Skip to content

Installing and running for local course development

This page describes the procedure to install and run your course locally within Docker. You can develop course content locally following the instructions below, or using the in-browser tools.

Why run ZJUI-Learn locally?

ZJUI-Learn provides the ability to create and update questions with a browser interface. While this interface is suitable for simpler questions, it is not ideal for complex cases such as:

Using the course repository with a local installation simplifies the process of updating the course content. This workflow allows instructors to test changes in the question code or assessment configuration without affecting the student experience. It also supports collaboration and coordination in courses with multiple staff members using Git workflows and pull requests.

Installation instructions

Regardless of which operating system you are using, you will need to install the appropriate version of Docker Desktop. For Windows users, you will also need to install WSL 2 and enable its integration with Docker Desktop. See the Additional instructions for Windows users section below for more details.

Cloning your course repository

If you are running ZJUI-Learn with the example course only, you may skip this section.

When you request your course, you will typically receive a GitHub repository URL to your course's content. You may use Git to clone (make a local copy of) this course content in your own computer. Make note of the directory you are cloning your course to. If you are working with multiple courses, you will need to store each course in a separate directory. For Windows users, it is recommended to store your course content inside the WSL 2 instance for better performance.

Running instructions

The following instructions must be executed in a terminal window. For MacOS and Linux, you can use the default terminal application. For Windows, use a terminal connected to a WSL 2 instance.

To run ZJUI-Learn using the example course only, open a terminal window and type the command:

docker run -it --rm -p 3000:3000 prairielearn/prairielearn

To use your own course, use the -v flag to bind the Docker /course directory with your own course directory. For example, if your course is stored in $HOME/pl-tam212, the command is:

docker run -it --rm -p 3000:3000 -v $HOME/pl-tam212:/course prairielearn/prairielearn

Make sure to replace the course path with your own course directory. To use multiple courses, add additional -v flags (e.g., -v /path/to/course1:/course -v /path/to/course2:/course2). You may use up to nine courses through this method, using the mount points: /course, /course2, /course3, ..., /course9.

After running the command above, you should see a message that says:

ZJUI-Learn server ready, press Control-C to quit

Once that message shows up, open a web browser and connect to http://localhost:3000/pl.

When you are finished with ZJUI-Learn, type Control-C on the terminal where you ran the server to stop it.

Support for external graders and workspaces

There are a few extra steps needed to run ZJUI-Learn locally with support for external graders and workspaces.

First, create an empty directory to use to share job data between containers. This directory can live anywhere, but needs to be created first and referenced in the Docker launch command. This directory only needs to be created once. If you are running Windows, the directory should be created inside the WSL 2 instance. You can create this directory using a command like:

mkdir "$HOME/pl_ag_jobs"

Now, we can run ZJUI-Learn with additional options to allow the external grading or workspaces features. For example, if your course directory is in $HOME/pl-tam212 and the jobs directory created above is in $HOME/pl_ag_jobs, the new command is as follows:

docker run -it --rm -p 3000:3000 \
  -v "$HOME/pl-tam212:/course" `# Replace the path with your course directory` \
  -v "$HOME/pl_ag_jobs:/jobs" `# Map the jobs directory into /jobs` \
  -e HOST_JOBS_DIR="$HOME/pl_ag_jobs" \
  -v /var/run/docker.sock:/var/run/docker.sock `# Mount Docker into container so it can spawn others` \
  --add-host=host.docker.internal:172.17.0.1 `# Ensure network connectivity` \
  prairielearn/prairielearn
Why is this necessary?

In production, ZJUI-Learn runs external grading jobs and workspaces on a distributed system that can efficiently run many jobs in parallel. When developing questions locally, you won't have access to this infrastructure, but ZJUI-Learn allows you to still run external grading jobs and workspaces locally. To do this, it needs extra Docker command line arguments to provide two key capabilities:

  • ZJUI-Learn needs a way of starting up Docker containers on the host machine from within another Docker container. This is achieved by mounting the Docker socket from the host into the Docker container running ZJUI-Learn; this allows it to run "sibling" containers.
  • ZJUI-Learn needs to get job files from inside the Docker container running ZJUI-Learn to the host machine so that Docker can mount them to either /grade in the grading container or the home directory in the workspace container. This is achieved by mounting a directory on the host machine to /jobs in the ZJUI-Learn container, and setting an environment variable HOST_JOBS_DIR containing the absolute path of that directory on the host machine.

Development

If you want to contribute improvements or features to ZJUI-Learn, you will need to start up ZJUI-Learn differently. See the local installation documentation for more details.

Troubleshooting the --add-host option and network timeouts

If you are an advanced Docker user, or if your organization's network policies require it, then you might have previously adjusted the address pool used by Docker. If this conflicts with the Docker defaults, you might get a network timeout error when attempting to launch a workspace locally. In that case, you might need to adjust the IP address for the --add-host= option. You can find more technical details here: PL issue #9805, moby/moby PR 29376, docker/docs issue 8663.

If you are using macOS, then you may be able to remove the --add-host option entirely without any problems.

Upgrading your ZJUI-Learn Docker image

To obtain the latest version of ZJUI-Learn at any time, make sure ZJUI-Learn is not running (Ctrl-C it if needed) and then run:

docker pull prairielearn/prairielearn

After this, run ZJUI-Learn using the same commands as above.

Running a specific version of ZJUI-Learn

The commands above will always run the very latest version of ZJUI-Learn, which might be an unreleased development version. If you would like to run the version that is currently deployed, use the appropriate tag for the server you're using:

  • For courses running under https://us.prairielearn.com/ use the tag us-prod-live;
  • For institutions with local installations of ZJUI-Learn, consult your local IT department.
docker run -it --rm -p 3000:3000 --pull=always [other args] prairielearn/prairielearn:us-prod-live

Tip

The command above uses the --pull=always option, which will update the local version of the image every time the Docker command is restarted. If you keep a long-running container locally, make sure to restart the container when updates in the production servers are announced in the ZJUI-Learn GitHub Discussions page.

Additional tags are available for older versions. The list of available versions is viewable on the Docker Hub build page.

Additional instructions for Windows users

We do not currently support a Windows environment without WSL 2, due to extreme performance issues, limitations related to file permissions in job folders, as well as issues associated to file formats. While there are ways to run ZJUI-Learn in this environment, it may not provide the same experience that a student would see in a production environment, and as such it is discouraged and not documented.

If you are using Windows, use WSL 2 to run ZJUI-Learn. WSL 2 provides a Linux environment that runs alongside Windows, and makes better use of modern CPU virtualization features. All examples in this page assume that, if Windows is in use, commands are executed and files are stored within the WSL 2 environment.

Here are the instructions to install WSL 2 and enable its integration with Docker:

Opening a WSL 2 shell on Windows

To run a WSL 2 shell, open the Windows Start menu, search for "WSL", and select the WSL 2 instance you installed. Alternatively, install the Windows Terminal application and select your WSL 2 instance from the dropdown menu.

Note that PowerShell, the Command Prompt, Git Bash, Cygwin, MinGW and other similar environments are not supported and may not work properly. You can check if you are using a WSL shell by typing echo $WSL_DISTRO_NAME in the terminal. If you see the name of the Linux distribution you installed in the previous step, you are using WSL. If you see nothing, or you see $WSL_DISTRO_NAME, you are not using WSL.

Storing your course content in WSL 2

While there are ways to store your course content in the Windows file system itself (e.g., in your Documents or Desktop folder, or elsewhere inside the C:\ drive) and to translate those paths to WSL mounted paths (e.g., via /mnt/c/... paths), these are not recommended due to performance concerns.

If you are using Windows, store your course content inside the WSL 2 instance. This option typically provides the best performance when running ZJUI-Learn locally. You can clone the repository using git commands inside your WSL shell. Note that, in this case, you will need to either update your files using WSL tools and editors, or access the files using the Linux file systems. Instructions to do so are listed here. In this case, keep track of the path used by your course inside WSL (e.g., $HOME/pl-tam212).