Installing Chap Core for use with the Modeling app

This guide covers installing and running Chap Core using Docker Compose. This is necessary if you want to run the modeling app. Note: For only using chap-core command line interface to run models locally, simply installing chap with pip install chap is sufficient.

Prerequisites

  • Docker and Docker Compose installed on your system

  • Git for cloning the repository

Fresh Installation (New Users)

Follow these steps if you’re installing Chap Core for the first time.

1. Clone the Chap Core Repository

git clone https://github.com/dhis2-chap/chap-core.git
cd chap-core

2. Checkout the Desired Version

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 (e.g., v1.0.17)
git checkout v1.0.17

To use the latest development version instead, stay on the master branch (skip the checkout step). Note that this branch is unstable and gets frequent changes.

3. Start Chap Core

docker compose up

This single command will:

  • Pull all required Docker images

  • Start the PostgreSQL database

  • Start the Redis cache

  • Start the Chap Core API server

  • Start the Celery worker for background jobs

  • Automatically create and initialize your database

The Chap Core REST API will be available at http://localhost:8000 once all services are running.

4. Verify the Installation

You can verify that Chap Core is running correctly by:

  1. Check the API documentation: Visit http://localhost:8000/docs in your browser to see the interactive API documentation

  2. Check the health endpoint:

    curl http://localhost:8000/health

  3. View service logs:

    docker compose logs -f

Upgrading Existing Installation

Follow these steps if you already have Chap Core installed and want to upgrade to a newer version.

2. Update the Repository

# Navigate to your chap-core directory
cd chap-core

# Fetch the latest tags and updates
git fetch --tags

# List available versions
git tag -l

# Checkout the new version you want to upgrade to
git checkout v1.0.18  # Replace with your desired version

3. Upgrade Chap Core

# Stop all containers first
docker compose down 

# Spin the containers up with --build to get new changes
docker compose up --build

This will:

  • Pull any updated Docker images

  • Automatically migrate your database to the new schema

  • Start all services with the new version

The database migration happens automatically - you do not need to run any manual migration commands. In the compose.yml file, we pin postgres to a major version (17). Note that between upgrades, there might be minor incompatibilities, such as collation issues. Feel free to handle these by pinning the postgres version further, or handle the database separately.

4. Verify the Upgrade

Check that the upgrade was successful, by checking the health endopint of chap locally:

curl http://localhost:8000/health

5. Restore from Backup (If Needed)

If you encounter issues and need to restore from your backup:

# Stop the services
docker compose down

# Remove the database volume to start fresh
docker compose down --volumes

# Start only the database
docker compose up -d postgres

# Wait for postgres to initialize, then restore the backup

cat backup_20241023_120000.sql | docker compose exec -T postgres psql -U root chap_core

# Start all services
docker compose up --build

Common Operations

Stopping Chap Core

To stop all services:

docker compose down

This preserves your database data. To start again, simply run docker compose up.

Viewing Logs

To view logs from all services:

docker compose logs -f

To view logs from a specific service:

docker compose logs -f chap
docker compose logs -f worker
docker compose logs -f postgres

Next Steps