Installing PL for local 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.

  • Step 2: Run PrairieLearn using the example course with:
docker run -it --rm -p 3000:3000 prairielearn/prairielearn
  • Step 4: When you are finished with PrairieLearn, type Control-C on the commandline where you ran the server to stop it.
  • Step 5: To use your own course, use the -v flag to bind the Docker /course directory with your own course directory (replace the precise path with your own) on Windows:
docker run -it --rm -p 3000:3000 -v C:\GitHub\pl-tam212:/course prairielearn/prairielearn

or on MacOS/Linux:

docker run -it --rm -p 3000:3000 -v /Users/mwest/git/pl-tam212:/course prairielearn/prairielearn

If you are using Docker for Windows then you will need to first give Docker permission to access the C: drive (or whichever drive your course directory is on). This can be done by right-clicking on the Docker "whale" icon in the taskbar, choosing "Settings", and granting shared access to the C: drive.

To use multiple courses, add additional -v flags (e.g., -v /path/to/course:/course -v /path/to/course2:course2). There are nine available mount points in the Docker: /course, /course2, /course3, ..., /course9.

If you're in the root of your course directory already, you can substitute %cd% (on Windows) or $PWD (Linux and MacOS) for /path/to/course.

If you plan on running externally graded questions in local development, please see this section for a slightly different docker launch command.

NOTE: On MacOS with "Apple Silicon" (ARM64) hardware, the use of R is not currently supported.

Upgrading your Docker's version of PrairieLearn

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

docker pull prairielearn/prairielearn

After this, run PrairieLearn using the same commands as above.

Running a specific older version of PrairieLearn

The commands above will always run the very latest version of PrairieLearn, which might be an unreleased development version.

The list of available versions is viewable on the hub.docker build page.

To run a specific older version (e.g., version 1.2.3) then you can do:

docker run -it --rm -p 3000:3000 [other args] prairielearn/prairielearn:1.2.3

Running PrairieLearn from a WSL2 instance

If you are using Windows with WSL2, you should be able to run Docker from another WSL2 instance. In order to that, you need to follow these instructions:

  • Open the Docker Dashboard, and click on Settings (the gear button at the top of the interface).

    • Under General, ensure the "Use the WSL2 based engine" option is selected.
    • Then, under Resources, select "WSL integration", and enable the option "Enable integration with my default WSL distro".
    • Also enable integration with any listed distros that you want to access docker from.
    • Click on "Apply & Restart" for the settings to apply.
  • On the shell of your WSL2 instance, make sure the instance has the docker command installed. The installation process may depend on your distribution, but most distributions provide a docker package.
  • Now you should be able to start PrairieLearn with the following command (assuming your course is stored under /mnt/c/Users/yourname/git/pl-tam212):
docker run -it --rm -p 3000:3000 -v /mnt/c/Users/yourname/git/pl-tam212:/course prairielearn/prairielearn

If you plan on running externally graded questions or workspaces in local development, please see the docker section in the external grading docs for a slightly different docker launch command.