Skip to main content

Installation

Kelvin relies on several runtime services, so some setup is required before use.

Install System dependencies​

apt-get install libsasl2-dev libgraphviz-dev graphviz gcc libxml2-dev libxslt1-dev libffi-dev \
  libz-dev curl

Install Python dependencies​

Create a Python virtual environment and install Kelvin’s dependencies. The easiest way of doing that is to use uv, which manages the dependencies of this project. If you don't have uv, you can install it using some supported approach, for example:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then, use uv to create a virtual environment and install the necessary dependencies into it:

uv sync
info

If you have unsupported python version, use uv python install 3.12 with following uv sync --python 3.12

Building the frontend​

For building the frontend, you'll need npm. Again if you don't have it installed, follow these official instructions.

cd frontend
npm ci
# Perform a production build:
npm run build
# Perform a development build with live-reload:
npm run dev

The frontend build will store JS and CSS files into web/static.

Prepare environment​

Application needs to work with services like postgres, redis, nginx, etc. Therefore, it's required to prepare .env file, that contains variables used by runtime services. Then modify by your liking.

cp .env.example .env

Preparing the database​

PostgreSQL is required to storage application data. You can either provide it yourself, or use the provided docker-compose.yaml file (recommended).

Running PostgreSQL with Docker​

To start postgres dockerized, docker server is required. If not already installed, use instalation guide, and then start a PostgreSQL database using docker-compose:

docker compose up db
info

Note that docker compose will load the DB (and other) configuration options from the .env file, same as Kelvin, so they should match.

Running migrations​

Once you have a working connection to the DB, you should run migrations on it:

uv run manage.py migrate

Creating superuser​

To be able to log in into Kelvin, you firstly need to create superadmin user. Create it by using:

uv run manage.py createsuperuser

Seeding database​

For the ease of use, you can seed some example data into your database by using init_db command. If you want you can specify username to match your created superuser. Otherwise it will create a user with username: teacher and password admin.

python manage.py init_db [--username <username>]

Running the server​

Once you built the frontend, installed Python dependencies and configured the database, you can start a local development server using this command:

uv run manage.py runserver 8000

And then you should be able to find the application on http://localhost:8000.

Optional enhancements​

Git pre-commit (prek) hooks​

To enable hooks with their installation:

uv run prek install

Deploying workers​

To perform code plagiarism checks or evaluate code submits, you'll also need to deploy Redis and start RQ workers. You can start Redis using the provided docker-compose.yml file:

docker compose up redis
info

Note that the Redis instance does not store data persistently.

You also need to compile the Docker images used for evaluation:

cd evaluator/images
uv run build.py

Then you can start a worker with the following command (in kelvin root folder):

uv run manage.py rqworker default evaluator --with-scheduler