Follow these steps if you’re installing Chap Core for the first time.
!!! warning We highly recommend you to have read the recommendation for server deployment before reading this guide.
chap-admin command, which adds models to Chapuv installs Python tools together with the Python version they need, so the host does not need a recent Python of its own. On Linux, install it with:
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
On macOS, use brew install uv. See the uv installation guide for other systems. Check that it works with uv --version.
git clone https://github.com/dhis2-chap/chap-core.git
cd chap-core
Fetch the available versions and checkout the version you want to install. Check the releases on GitHub to see what the latest release is.
# Fetch all tags
git fetch --tags
# List available versions
git tag -l
# Checkout a specific version
git checkout [VERSION] #Replace with your desired version, e.g. v2.4.0
For latest release go to: https://github.com/dhis2-chap/chap-core/releases
Copy the example environment file:
cp .env.example .env
This creates a .env file with default database credentials used by Docker Compose.
!!! tip “Production deployments”
For production, open .env and change at least POSTGRES_PASSWORD to a strong, unique value. The password is interpolated into a database URL, so keep it URL-safe – no @, :, /, ?, # or % – or set CHAP_DATABASE_URL to a full percent-encoded URL instead. You can optionally change POSTGRES_USER as well. These credentials are set permanently when the database volume is first created, so choose them before running docker compose up for the first time.
If Chap Core will be reachable from outside your internal network, also set `CHAP_API_TOKEN` to require an API token on every request. See [API Authentication](/chap-core/docs/webapi/api-authentication.html).
docker compose up -d
This command will:
compose.ghcr.yml uses pre-built images instead) and pull the other imagesThe Chap Core REST API will be available at http://localhost:8000 once all services are running. At this point Chap has only its built-in models.
!!! note
compose.yml and compose.ghcr.yml are alternatives — do not stack them.
Model services are installed from the CHAP Model Marketplace with chap-admin, which comes with the chap-core package. Install the same chap-core version as the Chap you checked out in step 2, since chap-admin uses REST API endpoints of that version. Then install every model with a verified stable version from the repository directory:
uv tool install chap-core==[VERSION] --python 3.13 # e.g. chap-core==2.4.0 (chap-admin needs 2.4.0 or later)
chap-admin install-all
This is a manual step, run once after the first docker compose up. For each model it starts the model service, waits for it to register with Chap, and adds the model’s verified configurations. The services are written into compose.marketplace.yml next to compose.yml. Add --platform linux/amd64 on machines that are not AMD64, such as Apple Silicon, since some models only publish AMD64 images. If you set CHAP_API_TOKEN in .env, export it in your shell first, since chap-admin does not read .env.
From now on, include compose.marketplace.yml in every Docker Compose command for this deployment:
docker compose -f compose.yml -f compose.marketplace.yml up -d
See Running marketplace models for installing, updating and removing single models.
You can verify that Chap Core is running correctly by:
Check the API documentation: Visit http://localhost:8000/docs in your browser to see the interactive API documentation
Check the health endpoint:
curl http://localhost:8000/health
curl http://localhost:8000/v1/crud/configured-models
docker compose logs -f
To stop all services (pass the same -f flags used to start them):
docker compose -f compose.yml -f compose.marketplace.yml down
This preserves your database data. To start again, run docker compose -f compose.yml -f compose.marketplace.yml up -d.
See Troubleshooting: Viewing Logs for how to inspect logs from the running services.