This page introduces the development tools required for developing Kompassi, Edegal (Conikuvat.fi/Larppikuvat.fi) and related services.

Required tools

Mac

Both Intel and Apple Silicon Macs are supported.

Please install these tools following their installation guides:

• Homebrew

• Docker Desktop (brew install --cask docker-desktop)

Windows (WSL2)

Windows 10/11 Home and Pro are supported. Build 2004 or newer is required for WSL2 (see WSL2 installation instructions).

Please install these tools following their installation guides:

• WSL 2 (use the latest available version of Ubuntu as the distro)

• Docker Desktop

Linux

For native Linux machines:

• Docker (recommended: Docker Engine)

Recommended tools

Installing these tools will greatly enhance your development experience but are not strictly required.

• Visual Studio Code is used by most developers as the text editor / IDE.

  • You can use other IDEs such as JetBrains PyCharm or similar, but the instructions here assume Visual Studio Code.

• A local installation of Python is recommended for VS Code Python development tools to work.

  • As of 2024-12-12 the minimum supported version of Python is 3.13.

  • See below for installation instructions.

• A local installation of Node.js is recommended for VS Code Node.js development tools to work.

  • As of 2025-07-23, the minimum supported version of Node.js is 24.

  • You’ll need these mostly for frontend development of the V2 frontend.

  • See below for installation instructions.

Mac

brew install pango python@3.13 node@24 prek uv

Windows (WSL 2) / Linux (Debian/Ubuntu)

There might be a Python 3.12 available from your distribution:

apt install python3.13 python3.13-venv

If you are not in luck, you can install it from the Deadsnakes PPA:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
apt install python3.13 python3.13-venv

Similarly, you can try to apt-get install nodejs, and if you get a version that is too old, the NodeSource repository will get you a recent one.

Getting started

Get Kompassi running in Docker

To get started and validate your setup, you should

1. check out the Kompassi repository from GitHub using git clone git@github.com:con2/kompassi (if using Windows, do this under your WSL2 installation),

2. cd kompassi into the working copy you just cloned and execute docker compose up, and

3. open your web browser to http://localhost:8000 for the v1 UI and http://localhost:3000 for the v2 UI.

You should be greeted with the front page of your own Kompassi development instance.

The README of the Kompassi repository provides more detailed instructions for this step.

Cool things to try out!

As of 2024-01-18, the Surveys v2 app is the hottest when it comes to new features. There’s two surveys you can use to try it out:

• Hitpoint larp survey http://localhost:3000/events/hitpoint2024/surveys/larp-survey

  • Bilingual fi/en! Try changing the language from the upper right.

  • Admin http://localhost:3000/events/hitpoint2024/surveys

  • Set up in setup_hitpoint2024.py using larp-survey-fi.yml and larp-survey-en.yml

• Hackathon 1/2024 feedback form http://localhost:3000/events/tracon2024/surveys/hackathon-feedback

  • Admin http://localhost:3000/events/tracon2024/surveys

  • Set up in setup_tracon2024.py using hackathon-feedback.yml

The mahti user should have sufficient permissions to access the admin views by default.

Optional but recommended

Visual Studio Code Python support

From the Extensions panel to the left, install the Python and Ruff extensions. Visual Studio Code should recommend them to you when you open Kompassi in Visual Studio Code for the first time.

If the Python extension prompts you whether to use the Pylance language server, answer Yes.

Local backend deps for Visual Studio Code and admin commands

In order for Visual Studio Code to understand your code, a virtualenv is needed that has the requisite libraries available.

We use uv to manage virtualenvs. Install uv from wherever.

brew install uv

Then set up the virtualenv as follows:

uv sync
source .venv/bin/activate

Now run which python and copy the result to the clipboard. Then open Visual Studio Code in the kompassi directory (code .), hit Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows) to open the Command Palette, search for Python: Select Interpreter and select it, select select Enter interpreter path…, paste the path from clipboard and hit Enter.

Using this virtualenv to python manage.py runserver outside Docker is not recommended: you should use docker compose up instead. You can use it for commands not requiring the full configuration, however, including but not limited to

python manage.py kompassi_i18n -acv2
python manage.py makemigrations
python manage.py analyze_commits

Local frontend deps for Visual Studio Code

Similarly, for the frontend, while not strictly required, it’s a good idea to run

cd kompassi-v2-frontend
npm install

to install deps for the frontend locally so that VS Code will find and pick up them.

Pre-commit hooks

In our GitHub pipelines, there is a lint step that runs various checks on the code. To avoid this step failing, you can run the same checks locally or, better yet, configure Git to run them before commit. Provided you have the venv active (see above):

cd backend
pip install pre-commit
pre-commit install

Now you can run it locally:

pre-commit run --all-files

Now when you git commit, it should run the linters on changed files and interrupt the commit if it would fail in CI.

Required user accounts

Now that you have the technical requirements installed, it’s time to focus on the requirements for the process ie. participating in the development of Kompassi.

Con2 Slack

Please join us on the #kompassi channel in the Con2 Slack to get help and participate in the development. Get access to Con2 Slack via Kompassi.

GitHub

A GitHub account is required to make pull requests to the main repository. If you don’t yet have one, set up a GitHub user account, create an SSH key pair (under WSL2 if you use Windows) and add its public key to GitHub.

Use a personal fork to make pull requests. For more information, see Git conventions.

To be able to edit issues on backlogs, ask for membership in the kompassi-interest-group team. For more information, see GitHub access.