We're glad you want to setup your machine for hitobito development 💃
Described below is the default, best supported Docker-based way to install hitobito locally, with minimal pre-requisites.
If instead you already have VSCode installed and want an easy to use quick start solution, you can use devcontainers and codespaces.
Warning
If you had hitobito/development set up before mid 2026 and are now coming back to it, you need to build new containers:
docker compose down && docker compose build
This ensures your project can be automatically migrated to the current structure.
You need to have Docker and docker compose installed on your computer. The free Docker Community Edition (CE) works perfectly fine. Make sure your user is part of the docker group:
usermod -a -G docker $USERYou probably have to log out and log in back again or run newgrp docker.
Additionally you need git to be installed and configured.
🐧 This manual focuses on Linux/Ubuntu. Hitobito development also runs on other platforms with some adjustments. Follow the prerequisites in section Windows preparation to set up a Windows platform for Hitobito development, before continuing below.
First declare a instance name: (e.g. generic, pbs)
read -p "Enter hitobito instance name: " INSTANCE_NAMEThen you need to clone this repository:
git clone https://github.com/hitobito/development.git $INSTANCE_NAME && cd $INSTANCE_NAME
git clone https://github.com/hitobito/hitobito.gitNow you need to add at least one wagon project.
If you want to run a generic demo instance of hitobito:
git clone https://github.com/hitobito/hitobito_generic.gitIf instead you want to run a PBS instance:
git clone https://github.com/hitobito/hitobito_pbs.git
git clone https://github.com/hitobito/hitobito_youth.git # pbs also requires the youth wagonYou can adapt the above commands as needed for the wagon(s) you want.
The final structure should look something like this:
$ ls -la
-rw-rw-r-- 1 ps ps 181 Mar 1 20:54 app.code-workspace
drwxrwxr-x 3 ps ps 4096 Mar 1 13:50 bin
drwxrwxr-x 2 ps ps 4096 Mar 1 14:07 doc
drwxrwxr-x 4 ps ps 4096 Mar 1 20:54 docker
-rw-rw-r-- 1 ps ps 3721 Mar 1 13:44 docker-compose.yml
drwxrwxr-x 2 ps ps 4096 Mar 1 20:54 dumps
drwxrwxr-x 18 ps ps 4096 Mar 1 20:59 hitobito
drwxrwxr-x 11 ps ps 4096 Mar 1 20:55 hitobito_generic
-rw-rw-r-- 1 ps ps 34523 Mar 1 20:54 LICENSE
drwxrwxr-x 3 ps ps 4096 Mar 1 20:54 nextcloud
-rw-rw-r-- 1 ps ps 584 Mar 1 20:54 nextcloud.yml
-rw-rw-r-- 1 ps ps 2116 Mar 1 13:44 README.md
drwxrwxr-x 2 ps ps 4096 Mar 1 20:54 sharedIf you did not so before, create new docker volumes for storing bundled gems and yarn packages:
docker volume create hitobito_bundle
docker volume create hitobito_yarn_cache⚡ If your user id is not 1000 (run id -u to check), you need to export this as env variable: export RAILS_UID=$UID before running any of the further commands. Maybe you want to add this to your bashrc.
To start the Hitobito application, run the following command in your shell:
docker compose upThis command might take a very long time on the first run, as the database needs to be seeded.
You will see the logs of all containers in your terminal.
If you press Ctrl+C, the application will be stopped.
If you don't want that, use docker compose up -d instead.
After the startup has completed (once you see Listening on http://0.0.0.0:3000 in the logs), you should be up and running.
You can check the status in a different terminal.
docker compose ps -aThe output should look something like this:
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
development-postgres-1 postgres:16 "docker-entrypoint.s…" postgres 23 hours ago Up 3 hours 5432/tcp, 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp
development-mailcatcher-1 ghcr.io/hitobito/development/mailcatcher "mailcatcher -f --ip…" mailcatcher 3 hours ago Up 3 hours 0.0.0.0:1080->1080/tcp, :::1080->1080/tcp
development-rails-1 ghcr.io/hitobito/development/rails "rails-entrypoint.sh…" rails 3 hours ago Up 3 hours 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp
development-rails_test_core-1 ghcr.io/hitobito/development/rails "rails-entrypoint.sh…" rails_test_core 21 hours ago Up About a minute
development-webpack-1 ghcr.io/hitobito/development/rails "webpack-entrypoint.…" webpack 3 hours ago Up About a minute 0.0.0.0:3035->3035/tcp, :::3035->3035/tcp
development-worker-1 ghcr.io/hitobito/development/rails "rails-entrypoint.sh…" worker 3 hours ago Up About a minute
Access the web application by browser: http://localhost:3000 and log in using hitobito@puzzle.ch (or in some wagons hitobito-pbs@puzzle.ch or similar) and password hito42bito. The correct email address to log in can be found in the file /config/settings.yml inside your wagon repository, in the field "root_email".
📧 All mails sent by your local development environment end up in mailcatcher. You can access these e-mails by visiting http://localhost:1080.
Congratulations! You are now ready to start changing hitobito.
You can simply edit the files in the hitobito/* folders with your preferred editor.
Those directories are mounted inside the containers. So every saved file is instantly available inside the containers.
💡 If you don't know where to begin changing something, have a look at our hitobito cheatsheet in English and German.
🤖 To use an AI coding agent, run bin/agent claude or bin/agent opencode — it starts the
agent inside the containers, where it has the whole application available and a sandbox to work in.
See AI coding agents.
For advanced development, see the development documentation.
The suggested approach for Hitobito development on Windows uses VSCode. VSCode provides extensions for integration of Docker and WSL 2. The next steps will prepare Windows for WSL 2, Docker and VSCode.
Install WSL 2 with Ubuntu using PowerShell running as administrator.
wsl --installConsider a look at Install Linux on Windows with WSL for troubleshooting.
Next, you will have to reboot your computer, before you are able to use WSL 2.
Open another PowerShell as administrator, and install Ubuntu:
wsl --install -d UbuntuAn Ubuntu terminal opens. If not, open Ubuntu using the Start menu.
You will be prompted to specify user name and password. Then, update and upgrade packages.
sudo apt update && sudo apt upgrade
⚡ Don't close the Ubuntu terminal yet.
Download and install Docker Desktop. The installation will promt you to enable WSL 2.
Open Docker Desktop using the Start menu. Select Settings > Generals and make sure the Use the WSL 2 based engine option is activated. If necessary, click Apply & restart.
Return to the Ubuntu terminal and confirm the installation.
docker --version
Version and build information should appear. That's it, terminate Ubuntu.
exit
See Get started with Docker remote containers on WSL 2 for a more detailed description.
Download and install VSCode.
Open VSCode using the Start menu.
Search for and install the following extensions:
- Remote Development (Microsoft)
- Dev Containers (Microsoft)
- Docker (Microsoft)
💡 You will find the Extensions menu on the left.
Start a remote Ubuntu session by clicking on the buttom left corner which should be highlighted in green, and select New WSL window.
A new VSCode instance opens with remote Ubuntu enabled. Confirm the button in the bottom left corner highlighted in green and indicating the Ubuntu session.
Start the terminal within VSCode, by clicking the Toggle panel button in the top right.
✨ Well done! You are set to follow the instructions of section Preparation, using the Ubuntu session within the VSCode terminal.
Hitobito has official support for nextcloud. You can start a nextcloud instance ready and set up for OIDC authentication via hitobito as follows:
docker compose -f docker-compose.yml -f nextcloud.yml upYou can then access your local nextcloud instance at http://localhost.
To test the hitobito Login part, you can then click on "Login with hitobito".
Alternatively, to manage the local nextcloud, you can use the credentials admin / hito42bito.
In case you get the following error:
Client-Autorisierung MKIM ist fehlgeschlagen: Unbekannter Client, keine Autorisierung mitgeliefert oder Autorisierungsmethode nicht unterstützt.
The reason is that the connection between hitobito and nextcloud is set up during hitobito's seeding process, and you probably already had a seeded database before, so no re-seed was done. To fix it, you first have to clear your database and then start again:
# Clear the database
docker compose -f docker-compose.yml -f nextcloud.yml down --volumes
# Start again
docker compose -f docker-compose.yml -f nextcloud.yml up
# Now it should work