# Development environment setup This page introduces the development tools required for developing Kompassi, Edegal ([Conikuvat.fi/Larppikuvat.fi](http://Conikuvat.fi/Larppikuvat.fi)) and related services. :::info **Recent changes:** As of 2025-07-23, we use [uv](https://docs.astral.sh/uv/) for Python virtual environment management. You no longer need to run `code kompassi.code-workspace` to open the project in Visual Studio Code, but a simple `code .` should suffice. **Public documentation:** This page and its sub-pages are publicly shared and linked to from the [Kompassi repository README](https://github.com/con2/kompassi). ::: # Required tools ## Mac Both Intel and Apple Silicon Macs are supported. Please install these tools following their installation guides: * [Homebrew](https://brew.sh/) * [Docker Desktop](https://docs.docker.com/desktop/mac/install/) (`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](https://docs.microsoft.com/en-us/windows/wsl/install) (use the latest available version of Ubuntu as the distro) * [Docker Desktop](https://docs.docker.com/desktop/windows/install/) ## Linux :::info If you are using Linux via WSL2 on Windows, follow the *Windows (WSL2)* instructions above instead. ::: For native Linux machines: * Docker (recommended: [Docker Engine](https://docs.docker.com/engine/install/ubuntu/)) # Recommended tools Installing these tools will greatly enhance your development experience but are not strictly required. * [Visual Studio Code](https://code.visualstudio.com/) 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: ```json apt install python3.13 python3.13-venv ``` If you are not in luck, you can install it from the [Deadsnakes PPA](https://launchpad.net/\~deadsnakes/+archive/ubuntu/ppa): ```bash 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](https://github.com/nodesource/distributions#debian-and-ubuntu-based-distributions) 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](https://github.com/con2/kompassi) 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 for the v1 UI and for the v2 UI. You should be greeted with the front page of your own Kompassi development instance. The `README`[ of the Kompassi repository](https://github.com/con2/kompassi) 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 * Bilingual fi/en! Try changing the language from the upper right. * Admin * Set up in [setup_hitpoint2024.py](https://github.com/con2/kompassi/blob/2622588cd21a6750ed0560168dbc5ee752b0f7af/backend/events/hitpoint2024/management/commands/setup_hitpoint2024.py#L486-L533) using [larp-survey-fi.yml](https://github.com/con2/kompassi/blob/main/backend/events/hitpoint2024/forms/larp-survey-fi.yml) and [larp-survey-en.yml](https://github.com/con2/kompassi/blob/main/backend/events/hitpoint2024/forms/larp-survey-en.yml) * Hackathon 1/2024 feedback form * Admin * Set up in [setup_tracon2024.py](https://github.com/con2/kompassi/blob/2622588cd21a6750ed0560168dbc5ee752b0f7af/backend/events/tracon2024/management/commands/setup_tracon2024.py#L887-L914) using [hackathon-feedback.yml](https://github.com/con2/kompassi/blob/main/backend/events/tracon2024/forms/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]( https://marketplace.visualstudio.com/items?itemName=ms-python.python) and [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.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 :::tip **How do I know if this step is required?** If Visual Studio Code complains *Import* `django.db.models` *could not be resolved from source* or similar, you need to complete this step. ::: In order for Visual Studio Code to understand your code, a virtualenv is needed that has the requisite libraries available. We use [uv](https://docs.astral.sh/uv/) to manage virtualenvs. Install uv from wherever. ```sql brew install uv ``` Then set up the virtualenv as follows: ```sql 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 ```bash 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 ```javascript 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): ```javascript cd backend pip install pre-commit pre-commit install ``` Now you can run it locally: ```javascript 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](https://kompassi.eu/profile/privileges). ## 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](https://github.com/join), create an [SSH key pair](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) (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](/doc/git-conventions-RdVC4pJKXp). To be able to edit issues on backlogs, ask for membership in the kompassi-interest-group team. For more information, see [GitHub access](/doc/github-access-KXz1txfOS4).