Skip to content

Running natively

This page describes the procedure to install and run ZJUI-Learn fully natively without using Docker. Certain features, such as external graders and workspaces, still require Docker. ZJUI-Learn supports native execution on macOS, Linux, and Windows inside WSL 2.

Installation

Most of these prerequisites can be installed using the package manager of your OS:

On Ubuntu, use apt for the main prerequisites:

sudo apt update
sudo apt install git gcc g++ make libc6-dev graphviz libgraphviz-dev redis postgresql-common
# Configure Postgres repository
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install postgresql-17 postgresql-17-pgvector
# Optional; needed only for some example questions that use LaTeX
sudo apt install texlive texlive-latex-extra texlive-fonts-extra dvipng

Make sure you start Postgres:

sudo systemctl start postgresql.service

If the command above shows an error like System has not been booted with systemd as init system or Failed to connect to bus, the command above can be replaced with:

sudo service postgresql start

Install uv using the standalone installer:

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env  # Add uv to PATH for current shell

Node.js 24 is not available in the default Ubuntu repositories -- you can install it through nvm.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc # or your shell's equivalent
nvm install 24

Install pnpm:

npm install -g pnpm

d2 can be installed through the install script:

curl -fsSL https://d2lang.com/install.sh | sh -s --

The pgvector Postgres extension can be enabled with the following script:

sudo -u postgres psql postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"

On macOS, ensure you have installed the XCode command line tools:

xcode-select --install

The main prerequisites can be installed with Homebrew:

brew install git graphviz postgresql@17 redis uv d2 node pgvector

# Optional; needed only for some example questions that use LaTeX
brew install texlive

You may want to start up the postgresql server on boot, and add binaries to your path:

brew services start postgresql@17
brew link postgresql@17

Install pnpm:

npm install -g pnpm

  • Clone the latest code:

    git clone https://github.com/PrairieLearn/PrairieLearn.git
cd ZJUI-Learn

  • Install Python dependencies (this will automatically create a virtual environment at .venv if needed):

    make python-deps
    Error on pygraphviz for newer versions of gcc

    For some newer versions of gcc, the pygraphviz package may fail to install. If you encounter this error, you can try this command:

    CFLAGS="-Wno-error=incompatible-pointer-types" make python-deps

    This error should only happen the first time you install pygraphviz. For following calls to make python-deps, you should not need to set the CFLAGS environment variable.

  • Install all dependencies and transpile local packages:

    make deps
make e2e-deps

    The above command installs everything. Alternatively, you can run each step individually:

    pnpm install
make build
make python-deps
make e2e-deps

  • Make sure the postgres database user exists and is a superuser (these might error if the user already exists):

    sudo -u postgres createdb postgres
sudo -u postgres psql postgres -c "CREATE USER postgres;"
sudo -u postgres psql postgres -c "ALTER USER postgres WITH SUPERUSER;"

  • Ensure that your local postgres installation allows for local connections to bypass password authentication. First find the authentication configuration file with the command:

    sudo -u postgres psql postgres -c "SHOW hba_file;"

    The command above will list the path to a file named pg_hba.conf or something equivalent. As either root or the postgres user, edit the file listed by the command above, such that lines that correspond to localhost connections are set up with the trust method (do not change the other lines). If the last two lines already say "trust", no modifications are needed. This will typically be shown as:

    # TYPE  DATABASE        USER            ADDRESS                 METHOD
...
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 trust

    You may need to restart the PostgreSQL server after changing the file above.

Configuration

If you have your own ZJUI-Learn course repository, you will need to create the file ZJUI-Learn/config.json with the path of your local course repository. If you need support for the in-browser file editor or file uploads, you should set filesRoot. If you need support for workspaces, you should provide a path to a directory into which temporary files will be saved. Here is a sample configuration:

config.json
{
  "courseDirs": ["/Users/mwest/git/pl-tam212", "exampleCourse"],
  "filesRoot": "../filesRoot",
  "workspaceHostHomeDirRoot": "/tmp/workspace",
  "workspaceHomeDirRoot": "/tmp/workspace"
}

More information about the config.json can be found in the server configuration documentation.

Development

More information on the development workflow can be found in the development quickstart documentation.