Introduction

Chap forecasts cases of climate-sensitive diseases such as dengue and malaria. It learns from past case counts together with climate data and population, scores how well each forecasting model would have done on the past, and predicts the coming months per district or province. It is often used together with DHIS2, through the Modeling App. Your first forecast in the Modeling App shows it end to end on demo data.

chap-devops deploys and manages Chap and the services around it, as Docker Compose deployments: chap-core, the forecasting model services published in the Chap model marketplace, Open Climate Service (OCS) with an S3-compatible object store, and DHIS2.

They deploy together or any of them on its own. A deployment is made of components (chap-core, OCS, the object store, DHIS2) plus the model services you enable. chap-core is on unless you leave it out, so the default is a Chap deployment. chap-devops init --only ocs,s3 is an OCS server, chap-devops init --only dhis2 a DHIS2, and chap-devops init --only none --models ID one model service answering on its own port. Use cases walks through each shape, and Components is the reference.

The name

chap-devops is the development and operations tool of Chap. The name says the two halves of the work it does:

• Operations: it deploys Chap and the services around it, keeps them up to date, backs them up, and says what is wrong when something stops (init, up, update, backup, status, doctor).
• Development: it makes and tests model projects, and runs the chap and chapkit CLIs with no Python or R on the machine (models new, models test, chap, chapkit).

The command has a short form: cdx is the same command as chap-devops. The install script puts it next to chap-devops.

What it does, in one screen

One command writes a self-contained deployment directory: the base services (chap-core, its worker, Valkey and PostgreSQL), one Compose overlay per enabled model, an .env file, and a .chap-devops/ directory that records exactly what the deployment is meant to be.

chap-devops init mychap --models chapkit_simple_multistep_model   # writes the deployment directory
cd mychap
chap-devops up                             # sync the compose files, docker compose up -d
chap-devops status                         # chap-core health and registered models
chap-devops ui                             # browse the marketplace, toggle models
chap-devops up                             # apply what the browser changed
chap-devops update                         # move the pins to what upstream publishes now
chap-devops restart                        # apply them to the services that are running

Other shapes:

chap-devops init mychap --with ocs         # Chap with Open Climate Service beside it
chap-devops init climate --only ocs,s3     # OCS alone, with no Chap

A new model:

chap-devops models new my-model            # a model project, from a template

After init, chap-devops is two things at once: a thin wrapper around docker compose that always passes the explicit -f list, and a model manager that can add or remove models without you hand-editing YAML.

Every command takes --json for machine-readable output, and every command ends with a line saying what it did or found. Empty output is a bug.

The three words to remember

• chap-devops up starts what is on disk. It renders the compose files from .chap-devops/, checks the host ports, and runs docker compose up -d. It never moves a pin. Only chap-devops up --pull downloads a newer build, and only for an image on a moving tag such as the main tag of OCS.
• chap-devops update fetches newer versions. It asks the marketplace and the chap-core release feed what they publish today, moves the pins that follow a channel or a release, and pulls the images. It never touches a container: it ends by naming the services that are now running something out of date.
• chap-devops restart applies them to the services that are running. It recreates the containers that no longer match the files and leaves the rest alone, and it changes no file and no pin.

Everything else follows from that split. chap-devops up, chap-devops restart, chap-devops models expose and chap-devops models unexpose are safe on a deployment running a build you do not want moved. chap-devops update, chap-devops models enable, chap-devops models add and chap-devops components enable --tag are the commands that move a version; see What moves a pin.

The pure server promise

A machine that runs Chap with chap-devops needs Docker and one binary. Nothing else: no Python, no uv, no checkout of chap-core, no build step on the server. The Linux releases are static musl builds, so the same file runs on any distribution.

The compose files chap-devops writes are plain Compose files with nothing chap-devops-specific in them, so

docker compose -f compose.yml -f compose.chap-devops.yml -f compose.marketplace.yml up -d

works on a machine that has never had chap-devops installed. That is the point of generating them rather than keeping the deployment inside the tool.

That is the list for chap-core and models. A component adds its own file before compose.marketplace.yml, for example -f compose.ocs.yml. A deployment without chap-core has no compose.yml or compose.chap-devops.yml.

Where to go next

• Install puts the binary on the machine.
• Quickstart walks a first deployment end to end.
• Your first forecast in the Modeling App uses one.
• Concepts explains the deployment directory, intent versus artifacts, and the pins.
• Commands is the tour; Command reference is the generated, complete list.

chap-devops is licensed under the AGPL-3.0, like chap-core. The full text is in LICENSE at the repository root.

For AI assistants

This page is written for an AI assistant that helps someone install and run something with chap-devops. If a person pointed you here, follow the steps below in order. Keep your answers short and concrete, and give one command at a time.

What Chap is

Use this when the person asks what they are installing, or seems unsure why they would want it.

Chap forecasts cases of climate-sensitive diseases such as dengue and malaria. It learns from past case counts together with climate data (rainfall, temperature) and population, and predicts the next months for each district or province. Before trusting a model it runs an evaluation: it pretends to stand at several past points in turn, forecasts the months after each, and scores how close each forecast came. Ministries of health use it together with DHIS2, the health information system where their case data already lives, through the Modeling App inside DHIS2.

chap-devops is the installer. It runs Chap, its forecasting models, a DHIS2 with demo data and the other pieces on one computer with Docker, so the person can use them without setting each one up by hand.

A few words the person will see:

How to help

1. Ask what they want to do, in one question, and match the answer to a group in The options. Do not show all nineteen options.

   • Learn Chap, try forecasting, see what it does (a student, an analyst, a public health person): option 1. It is the only one with a user interface they can click through. If their computer cannot give Docker 8 GB of memory, option 2 instead (6 GB).
   • Run Chap for a DHIS2 that already exists: option 5.
   • One piece on its own (climate data, one model, a DHIS2): options 6 to 10.
   • Develop a model, chap-core or DHIS2: options 11 to 18.
   • Two deployments at once: option 19.
   • Evaluate a model on their own data file, without DHIS2: option 20.

   If they are unsure, recommend option 1.

2. Check the machine with Before any option.

3. Give the commands for their option, in order, one block at a time. Wait for them to say it worked before giving the next block. Every option has an “It worked when” line: use it to decide.

4. When it works, say what to do next. Option 1 continues in the Modeling App, and so do options 3 and 4 when they added DHIS2: walk them through Your first forecast in the Modeling App. Option 2 continues with What to try next without DHIS2.

5. If something fails, ask them to paste the exact output. Then look for the first line that starts with error: or warning:. chap-devops puts the fix on the same line, usually a command in backticks: tell them to run that command. If that does not help, search Troubleshooting for the exact message. If chap-devops says it does not know a command or an option, the installed chap-devops is older than this page: chap-devops self update installs the newest release, and chap-devops <command> --help is always right for the installed one.

6. Never tell them to edit the compose*.yml files by hand (chap-devops rewrites them), and never ask them to paste the .env file (it holds passwords).

When an option has a “More” link, that page has the details. You only need it if the person asks for something the steps here do not cover.

If you run the commands yourself

If you have a shell on the person’s machine and run the commands rather than telling the person what to type:

• Run each block as written, top to bottom. Where an option shows alternatives, it says so and you pick one. Check its “It worked when” line yourself instead of waiting for the person to say it worked.
• If your shell does not keep its folder between commands, put -C mychap (the folder from chap-devops init) on every command in place of the cd: chap-devops -C mychap up.
• chap-devops status exits 0 only when everything the deployment declares is up and registered, and non-zero otherwise, so poll it by its exit code where a step says to run it every minute. A first DHIS2 start can take 20 minutes. chap-devops status --json gives the same report as one JSON document; every command takes --json.
• The first chap-devops up downloads the images that take most of the disk in Before any option. Give it a long timeout, or run it in the background, and do not start a second one while it runs. Running chap-devops up again after it has finished or timed out is safe: it continues from where it stopped.
• chap-devops dhis2 connect waits by itself for DHIS2 to start, up to 20 minutes; it prints a line on stderr while it waits.
• Nothing prompts you: without a terminal, a question becomes an error: with the flag that answers it. chap-devops self update is the exception: without a terminal it replaces the binary and does not ask, so ask the person before you run it. chap-devops up --replace stops another deployment holding the ports, chap-devops down --volumes --yes deletes data; ask the person before either.
• Credentials go in the .env file in the folder. Ask the person to add them there themselves, and do not print or read that file.
• Do not run chap-devops ui (an interactive screen), chap-devops up --attach or chap-devops logs -f (they never return). chap-devops logs SERVICE without -f prints and returns.
• chap-devops open NAME opens a browser on the machine it runs on. Run chap-devops open NAME --no-browser instead: it prints the address and opens nothing, and you give the person that address (or open it in your own browser tool). --json never opens a browser either.

Before any option

The person needs Docker: Docker Desktop on macOS and Windows, Docker Engine on Linux. On Windows, chap-devops runs inside WSL 2: Docker Desktop with its WSL integration turned on for the distribution, and every command below typed in the WSL shell. Check two numbers before they start:

Most of the disk is the model and worker images, which the first chap-devops up downloads: expect it to take a while on a slow connection. On Docker Desktop the memory is set under Settings, Resources. Then:

curl -fsSL https://raw.githubusercontent.com/winterop-com/chap-devops/main/install.sh | sh
chap-devops doctor

On Windows, run those two lines in the WSL shell, which installs the Linux binary; do not use the native Windows zip, which is published untested. See Install.

It worked when chap-devops doctor shows no fail lines, and its disk space line shows at least the number in the table above. chap-devops doctor passes with less, so compare the number yourself. On an Apple Silicon Mac a warn line about linux/amd64 and emulation is normal and can be ignored: the models run, only slower.

chap-devops doctor shows the memory line only in a folder with DHIS2. For an option with DHIS2, run chap-devops doctor again in the new folder after chap-devops init. Its memory line, for example 31.3 GB available to docker, must show at least 8 GB.

Every option below creates a new folder. Tell the person to run the commands from the folder where they want it created, and then to cd into it as shown. Several options use the same folder name (mychap): if one from an earlier option is still there, chap-devops init says it already contains a chap-devops deployment. Either pick another name in the chap-devops init line (and the cd), or remove the old one first as shown in Every option: stop, start, remove.

The options

1. Chap in DHIS2, with the Modeling App

Needs 8 GB of memory for Docker. The DHIS2 comes with demo data from Laos: weekly dengue cases for 2019 to 2024 in 18 provinces, with rainfall, temperature and population.

chap-devops init mychap --models chapkit_simple_multistep_model --with dhis2
cd mychap
chap-devops doctor
chap-devops up
chap-devops status

Before chap-devops up, check the memory line of chap-devops doctor: 8 GB or more. The first time, DHIS2 takes several minutes to start; the dhis2 line of chap-devops status says starting until DHIS2 answers, then up. Then:

chap-devops dhis2 connect
chap-devops open dhis2

chap-devops dhis2 connect waits for DHIS2 to finish starting, then takes about a minute: it connects DHIS2 to Chap, gives each model its configured models, installs the Modeling App and the Climate App, and prepares the data the Modeling App reads. Its last line is the Modeling App can reach Chap; open DHIS2 with `chap-devops open dhis2` . It worked when DHIS2 opens in the browser, the login admin / district works, and typing Modeling in the app menu (the grid icon at the top right) finds Modeling.

If chap-devops dhis2 connect says that a model is not registered with chap-core, wait a minute. Then run chap-devops status. When it shows the model as registered, run chap-devops models configs sync.

Next: Your first forecast in the Modeling App, which takes them from here to an evaluation and a forecast in about fifteen minutes.

More: Chap with a local DHIS2.

2. Chap with forecasting models

chap-core and one model, without DHIS2: less memory, but no user interface beyond chap-core’s API page.

chap-devops init mychap --models chapkit_simple_multistep_model
cd mychap
chap-devops up
chap-devops status

It worked when chap-devops status says chap-core is up and the line under the table says the models are registered (1 model registered, or all 2 models registered with more). Models can take a minute or two after chap-devops up: if some say not registered, wait a minute and run chap-devops status again. Then chap-devops open chap-core opens chap-core’s API page in the browser.

Next: What to try next without DHIS2.

More: Chap with forecasting models.

3. Chap with climate data

chap-devops init mychap --models chapkit_simple_multistep_model --with ocs,s3
cd mychap
chap-devops up
chap-devops status

It worked when chap-devops status shows chap-core and ocs as up. Some climate datasets need an account with Copernicus or the Earth Data Hub; the keys go in the .env file in the folder, where they are already listed, commented out. Add ,dhis2 to --with for the Modeling App as well (8 GB of memory), then continue as in option 1 from chap-devops dhis2 connect. OCS covers Laos, like the demo DHIS2, until the person changes it.

Next, when they want climate data: Getting climate data.

More: Chap with climate data from OCS.

4. Chap with every model

Like option 2, with every marketplace model. The model images are 1 to 7 GB each. chap-devops init pulls one of them to read its user, and the first chap-devops up pulls the others. Both can take many minutes on a slow connection.

chap-devops init mychap --models all
cd mychap
chap-devops up
chap-devops status
chap-devops models test --all

It worked when chap-devops status ends with all 4 models registered (one per marketplace model; all leaves out the two starters) and chap-devops models test --all ends with 4 of 4 models pass. When the marketplace has more models, the numbers are higher. The tests take one to two minutes. If some models say not registered, wait a minute and run chap-devops status again.

After a plain chap-devops up, the table shows each model as registered, not configured, and that is normal. chap-devops models test --all does not need a configured model, but a backtest and the Modeling App do. Run chap-devops models configs sync to create them. Then chap-devops status shows each model as registered.

Add --with dhis2 to the chap-devops init line to compare them in the Modeling App (8 GB of memory, then as in option 1 from chap-devops dhis2 connect, which also creates the configured models).

More: Chap with forecasting models.

5. Chap for a DHIS2 that already exists

The person needs the DHIS2 address, an admin account on it, and an address at which that DHIS2 can reach this computer (not localhost).

chap-devops init mychap --models chapkit_simple_multistep_model --api-token
cd mychap
chap-devops up
chap-devops dhis2 use https://THEIR-DHIS2 --chap-url https://ADDRESS-OF-THIS-MACHINE
chap-devops dhis2 connect

It worked when chap-devops dhis2 connect finishes without error:. It only sets the route on their DHIS2: its skipped: lines name the apps to install and the analytics run, which are for whoever runs that DHIS2 to decide (chap-devops dhis2 apps, chap-devops dhis2 analytics). The first time, chap-devops dhis2 use warns and chap-devops dhis2 connect stops with error: chap-devops has no credentials for this DHIS2. Then ask the person to put DHIS2_ADMIN_USERNAME and DHIS2_ADMIN_PASSWORD (or DHIS2_API_TOKEN) in the .env file in the folder, and run chap-devops dhis2 connect again. If --chap-url is an http:// address and the DHIS2 is 2.42 or later, it may say DHIS2 refused the route: whoever runs that DHIS2 has to add the --chap-url address, with no path, to route.remote_servers_allowed in its dhis.conf and restart it; the error line names the exact value.

If chap-devops dhis2 connect says that a model is not registered with chap-core, wait a minute. Then run chap-devops status. When it shows the model as registered, run chap-devops models configs sync.

More: Chap for a DHIS2 that runs elsewhere.

6. Climate data only

chap-devops init climate --only ocs,s3
cd climate
chap-devops up
chap-devops status
chap-devops open ocs

It worked when chap-devops status shows ocs as up and the browser opens OCS.

To put some data in (public rainfall data, no account needed):

curl -X POST http://localhost:8790/ingestions -H 'Content-Type: application/json' -d '{"dataset_id": "chirps3_precipitation_daily", "start": "2024-01-01", "end": "2024-01-03", "publish": true}'

It worked when the answer contains "status":"completed".

Next: Getting climate data.

More: An OCS server on its own.

7. One forecasting model only

No folder needed: from any directory that is not a deployment,

chap-devops run chapkit_simple_multistep_model

It worked when the last lines say running chapkit_simple_multistep_model on http://localhost:5001 (answered in ...) and name the chap-devops stop that stops it. With -a, chap-devops stays in the foreground and shows the model’s log, and Ctrl-C stops the model. The model’s API is at that URL, and its documentation at /docs under it. It is reachable from this machine only. A first run pulls the image, which can take several minutes; the command waits for it. Other models: chap-devops models list shows their ids, and chap-devops run takes any of them, a GitHub repository URL or a ghcr image the same way. chap-devops ps lists what runs, chap-devops top shows it live, and chap-devops stop chapkit_simple_multistep_model stops it.

More than one works the same way: one chap-devops run per model, each on its own port, and chap-devops ps lists them all. --group NAME keeps a set apart, and chap-devops stop --group NAME --purge removes that set with its data.

For a folder of its own instead, with chap-devops status and the rest:

chap-devops init onemodel --only none --models chapkit_simple_multistep_model
cd onemodel
chap-devops up
chap-devops status

It worked when chap-devops status shows the model as up. Its API is at the port in the REACH column, usually http://localhost:5001, and chap-devops open chapkit_simple_multistep_model opens its documentation.

More: Running one model, A chapkit model service on its own, Any number of model services, no folder.

8. DHIS2 only

Needs 8 GB of memory for Docker. The first start takes several minutes.

chap-devops init dhis --only dhis2
cd dhis
chap-devops up
chap-devops status

Run chap-devops status every minute until the dhis2 line says up, then chap-devops open dhis2. It worked when the login admin / district works. This is DHIS2 2.42 with the Laos demo data; for another version, see option 9.

More: A DHIS2 on its own.

9. A particular DHIS2 version

Needs 8 GB of memory for Docker. Each version starts with an empty DHIS2 (only 2.42 has demo data, see option 8). chap-devops init says so in a warning: chap-devops knows no DHIS2 demo dump line: that is expected. Run one of these, not all three: 2.43,

chap-devops init dhis --only dhis2 --dhis2-tag 2.43

2.41,

chap-devops init dhis --only dhis2 --dhis2-tag 2.41

or the next DHIS2, not released yet:

chap-devops init dhis --only dhis2 --dhis2-image dhis2/core-dev --dhis2-tag master

Then:

cd dhis
chap-devops up
chap-devops status

Run chap-devops status every minute until the dhis2 line says up, then chap-devops open dhis2. It worked when the login admin / district works. To have Chap with it, use option 1 with the same --dhis2-tag (and --dhis2-image) added to its chap-devops init line; without demo data there is nothing to forecast until they import some.

More: A DHIS2 on its own.

10. Climate data and DHIS2, no Chap

Needs 8 GB of memory for Docker.

chap-devops init lab --only ocs,s3,dhis2
cd lab
chap-devops up
chap-devops status

Run chap-devops status every minute until every line says up, then chap-devops open ocs and chap-devops open dhis2. It worked when both open, and the DHIS2 login admin / district works.

More: Combinations.

11. A new model of my own

For someone who wants to write a new model. Ask which language they use: Python or R. chap-devops models new makes the project. Docker builds it, so Python, uv and R are not necessary on their machine.

chap-devops models new my-model

For R, add --template shell-r. For a model in the MLproject format, use --template mlproject-py or --template mlproject-r.

It worked when the first line says created my-model in my-model. Then build the image in the new folder:

cd my-model
git init && git add . && git commit -m "feat: first version"
docker build --platform linux/amd64 --build-arg GIT_REVISION=$(git rev-parse HEAD) -t my-model:dev .

It worked when the build ends with no error. The first build pulls the base image, which takes some minutes. Then run it with chap-core:

cd ..
chap-devops init mychap --models none
cd mychap
chap-devops models add my-model:dev
chap-devops up --wait
chap-devops models test my_model --backtest

It worked when the last line says 1 of 1 model passes. The model is in main.py (the default type) or in the scripts/ folder. The README.md of the project lists the files.

After a change, raise version in main.py (or in MLproject) first: chap-core stores each version only once. Then commit, build the image again with the same docker build line, and run chap-devops restart and the chap-devops models test line in the mychap folder. If the test says is stored from revision, the version was not raised.

More: A new model project.

12. My own model

The model has to be a chapkit model whose GitHub repository publishes a public image on ghcr.io (most do, through their publish workflow). If chap-devops models add says the repository publishes no public image, use option 14 instead: build the image from their checkout and add that.

To try it, with no folder:

chap-devops run https://github.com/THEIR-ORG/THEIR-MODEL

It worked when the last lines say running ... on http://localhost:.... To keep it in a folder of its own:

chap-devops init mymodel --only none
cd mymodel
chap-devops models add https://github.com/THEIR-ORG/THEIR-MODEL
chap-devops up
chap-devops status

It worked when chap-devops status shows the model as up, on the port in its REACH column. A repository the marketplace already lists is enabled as that marketplace model, with its reviewed version; the line ... is the marketplace model ...; enabling that says so.

More: Models outside the marketplace.

13. My own model, while I work on it

For someone developing a chapkit model in its folder. chap-devops runs chap-core; they run the model from the folder.

chap-devops init mychap --models none
cd mychap
chap-devops up

Then, in the model’s folder (keep the single quotes):

export SERVICEKIT_ORCHESTRATOR_URL='http://localhost:8700/v2/services/$register'
export SERVICEKIT_HOST=host.docker.internal
export SERVICEKIT_PORT=8001
uv run uvicorn main:app --host 0.0.0.0 --port 8001

main:app is right for a model with main.py at the top of its folder, which is how chapkit models are laid out. If main.py is inside a package folder instead, use PACKAGE.main:app.

It worked when chap-devops status, run in the mychap folder, lists the model with the state unmanaged and a LAST PING of a few seconds (unmanaged because chap-devops did not start it, which is expected).

More: Your model from its checkout, with Chap.

14. A model image I built

In the model’s folder, which must be a git checkout:

docker build --platform linux/amd64 --build-arg GIT_REVISION=$(git rev-parse HEAD) -t my-model:dev .

GIT_REVISION gives the image the commit it was built from. chap-core needs it to store the model template. Without it, chap-devops models configs sync stops with answered HTTP 409 Conflict and is stored from revision None. Then:

chap-devops init mychap --models none
cd mychap
chap-devops models add my-model:dev
chap-devops up
chap-devops status

It worked when chap-devops status lists the model as registered. Usually it does not the first time:

1. Right after chap-devops up, the model is running, not registered. Wait a minute and run chap-devops status again.
2. The model registers under the id in its MLServiceInfo (in main.py), not as my-model. Then chap-devops status shows that id as unmanaged, next to my-model as running, not registered.
3. The line under the table gives the two commands that fix it: chap-devops models remove my_model, then chap-devops models add my-model:dev --service-id with the id from the unmanaged row. Run them, then run chap-devops up again.
4. When the model is registered, not configured, run chap-devops models configs sync.

If chap-devops status or chap-devops models configs sync says that the model reports no git revision, build the image again with the GIT_REVISION line above. Then run chap-devops restart and chap-devops models configs sync.

More: A model image you built yourself.

15. My own chap-core, with the models

For someone developing chap-core itself. They run chap-core from its folder, listening on 0.0.0.0:8000; chap-devops runs the models. Have them start their chap-core first: chap-devops init then sees whether it runs in Docker and configures the models to match.

chap-devops init models --chap-core-url http://localhost:8000 --models chapkit_simple_multistep_model
cd models
chap-devops up
chap-devops status

It worked when chap-devops status shows chap-core up and the model registered. Right after chap-devops up, the model is running, not registered; run chap-devops status again after some seconds. If the model is registered, not configured, run chap-devops models configs sync.

If chap-core was started after chap-devops up, the model stays running, not registered: it tries to register for about ten seconds only. Two minutes after chap-devops up, the line under the table gives chap-devops restart --all chapkit-simple-multistep-model. Run it.

registered, unreachable means chap-core cannot call the model back, usually because chap-core was not running during chap-devops init. If their chap-core runs in a container, the line under the table gives the two commands that fix it: chap-devops components enable chap-core with --models-host host.docker.internal, then chap-devops up.

More: chap-core from its checkout, with the models.

16. chap-core built from my checkout

For someone changing chap-core who wants to run their version with models. Replace the path with where they cloned chap-core:

chap-devops init mychap --source ~/dev/chap-core --models chapkit_simple_multistep_model
cd mychap
chap-devops up
chap-devops status

The first chap-devops up builds chap-core and takes several minutes (longer on an Apple Silicon Mac). It worked when chap-devops status shows chap-core up and the models registered. After changing the code, chap-devops up again rebuilds it.

More: chap-core built from its checkout.

17. My own DHIS2, with Chap

For someone who already runs DHIS2 on this machine (for DHIS2 or app work). Ask whether their DHIS2 runs in Docker. If it does not:

chap-devops init mychap --models chapkit_simple_multistep_model
cd mychap
chap-devops up
chap-devops dhis2 use http://localhost:8080 --chap-url http://localhost:8700
chap-devops dhis2 connect

If it runs in Docker, it reaches Chap through host.docker.internal:

chap-devops init mychap --models chapkit_simple_multistep_model
cd mychap
chap-devops up
chap-devops dhis2 use http://localhost:8080 --chap-url http://host.docker.internal:8700
chap-devops dhis2 connect

It worked when chap-devops dhis2 connect finishes without error:. If it says it has no credentials, put DHIS2_ADMIN_USERNAME and DHIS2_ADMIN_PASSWORD (or DHIS2_API_TOKEN) in the .env file and run it again. On a DHIS2 chap-devops did not start it sets only the route: if its skipped: lines say an app is missing, chap-devops dhis2 apps installs it, and chap-devops dhis2 analytics generates the tables the Modeling App reads.

On DHIS2 2.42 and later it can then say DHIS2 refused the route: their DHIS2 only proxies to the addresses its own dhis.conf allows. Tell them to add the --chap-url address, with no path (for example route.remote_servers_allowed = https://*,http://localhost:8700), to their DHIS2’s dhis.conf, restart their DHIS2, and run chap-devops dhis2 connect again. A value with a path, such as http://localhost:8700/**, stops DHIS2 from starting at all.

More: A DHIS2 you run yourself, with Chap from chap-devops.

18. A DHIS2, with my own chap-core

For someone developing chap-core who wants DHIS2 and the Modeling App in front of it. Their chap-core must listen on 0.0.0.0:8000. Needs 8 GB of memory for Docker.

chap-devops init lab --chap-core-url http://localhost:8000 --with dhis2
cd lab
chap-devops up
chap-devops status

Then, once chap-devops status shows chap-core up (chap-devops dhis2 connect waits for DHIS2 by itself):

chap-devops dhis2 connect
chap-devops open dhis2

It worked when chap-devops dhis2 connect finishes without error: and the login admin / district works.

More: A DHIS2 from chap-devops, with a chap-core elsewhere.

19. Two of these at the same time

Every option uses the same ports, so a second one needs its own. Create the second one with these added to its chap-devops init line, one flag per piece it has (--ocs-port only with OCS, --dhis2-port only with DHIS2; a flag for a missing piece is an error):

For example, a second option 2: chap-devops init second --models chapkit_simple_multistep_model --api-port 8701 --port-base 5101.

For a third, use 8702, 8792, 8782 and 5201, and so on. It worked when both folders’ chap-devops status say up. Running them one at a time needs none of this; see the note below.

More: Several deployments on one machine.

20. Evaluate a model on my own data

They have a dataset as a CSV, with a GeoJSON of the same name beside it. Do not install Python or uv for them. In the directory with the data:

chap-devops chap eval --model-name https://github.com/dhis2-chap/minimalist_example_r \
  --dataset-csv data.csv --output-file eval.nc
chap-devops chap plot-backtest eval.nc --output-file eval.html

Use their model’s GitHub URL in --model-name, or a marketplace id such as auto_arima_chapkit: chap-devops starts that model by itself, and they need no chap-devops up. Never give a localhost URL. The first run pulls an image of about 12 GB, so tell them it takes some minutes. If chap-devops stops with runs in docker, run the same command with chap-devops chap --docker and tell them that the flag gives the container control of docker. If the directory of an output file is not there, chap-devops creates it.

It worked when the last lines say chap finished; it wrote eval.nc and chap finished; it wrote eval.html. They open eval.html in a browser.

More: Evaluating a model on your own data, which goes from installing chap-devops to a comparison of two models, and The chap CLI.

21. Make my MLproject model a chapkit service

They have a model directory with an MLproject file. Do not install Python or uv for them. Make sure that the directory is in git, or that they have a copy: the migration moves files to _old/. In the directory above the model:

chap-devops chapkit mlproject migrate my-model --yes

It worked when the last lines say chapkit finished; it wrote ... and wrote my-model/uv.lock with `uv lock` in the same image. If the second line is a warning that chap-devops could not write uv.lock, the build fails; show them the warning.

If chapkit stops with No Python (.py) or R (.r/.R) scripts, run the command again with --base-image chapkit-py for Python. For R, use chapkit-r, chapkit-r-tidyverse or chapkit-r-inla.

Then build the image and test it:

cd my-model
docker build --platform linux/amd64 --build-arg GIT_REVISION=$(git rev-parse HEAD) -t my-model:dev .
chap-devops run my-model:dev
chap-devops -C ~/.local/share/chap-devops/run/default models test my_model

The build needs a git commit for GIT_REVISION. It worked when the last line says 1 of 1 model passes.

More: The chapkit CLI.

22. Serve my MLproject model, with no build

They have a model directory with an MLproject file. Do not install Python, R or uv for them. In the directory above the model:

chap-devops chapkit mlproject run my-model

It worked when the line says the MLproject service answers at http://localhost:PORT. The service runs in the foreground. Leave it running, and use a second terminal for the next steps. Ctrl-C stops it.

If the train job stops with No module named, the image does not have a package that the model needs. Run chap-devops chapkit --image, and show them the list. Then run the command again with --image NAME.

To evaluate it, give the same port at host.docker.internal:

chap-devops chap eval --model-name http://host.docker.internal:PORT \
  --dataset-csv laos_subset.csv --output-file my-model.nc

It worked when the line says chap finished; it wrote my-model.nc. For the data, see option 20.

To test it through chap-core, commit the model directory first. Then start it from a deployment directory, such as mychap from option 2, with chap-devops chapkit mlproject run ../my-model. In a second terminal, in that deployment directory:

chap-devops models configs sync my-model
chap-devops models test my-model --backtest

Use the name in MLproject as the id. It worked when the last line says 1 of 1 model passes.

More: An MLproject model, with no image to build.

What to try next without DHIS2

Option 2 has no user interface, but the same evaluation the Modeling App runs works from the terminal. In the mychap folder:

chap-devops models test --all --backtest
chap-devops jobs

The first line creates the configured models that chap-core needs, then makes every enabled model train, forecast and run an evaluation through chap-core on sample data the model generates itself, and prints the scores. Under each row, the line configured model: NAME (id N) names the configured model that the backtest used. For Simple Multistep it takes under a minute. If every model was skipped, it says warning: no model was tested and exits non-zero; the line under each row says why. chap-devops jobs lists what chap-core did. To see it in the Modeling App instead, add DHIS2 to the same folder (8 GB of memory for Docker):

chap-devops components enable dhis2
chap-devops up

then continue as in option 1 from chap-devops dhis2 connect. See Growing a deployment.

Getting climate data

For options 3, 6 and 10, once OCS is up. OCS covers Laos until the person changes the extent (the --ocs-name, --ocs-country and --ocs-bbox flags of chap-devops init). Six years of monthly rainfall, public, no account needed; it takes a few minutes and the command waits:

curl -X POST http://localhost:8790/ingestions -H 'Content-Type: application/json' -d '{"dataset_id": "chirps3_precipitation_monthly", "start": "2019-01", "end": "2024-12"}'

It worked when the answer contains "status":"completed". curl http://localhost:8790/data-sources lists every other dataset; temperature (era5land_temperature_monthly) needs a Copernicus account, whose key goes in .env. To get the values out per province as the CSV Chap reads, or as a NetCDF file, follow Getting it out step by step.

Every option: stop, start, remove

chap-devops down                    # stop everything; the data is kept
chap-devops up                      # start it again
chap-devops down --volumes --yes    # stop and delete all the data

After chap-devops down --volumes --yes the folder can be deleted.

All the options use the same ports, so only one of them runs at a time (option 19 is the exception). While another deployment is up, chap-devops init warns that a port is already in use on this machine. You can ignore that warning if you stop the other one before chap-devops up.

When chap-devops up says a port is used by another deployment and asks whether to stop it, answer y. The other one keeps its data, and chap-devops up in its folder starts it again. chap-devops up --replace is the same y given in advance. Without a terminal, chap-devops up does not ask. It stops with error: 1 host port this deployment needs is already in use; nothing was started and names chap-devops up --replace; ask the person before you run it.

While the other one is up, chap-devops status in this folder says this deployment’s chap-core is not running and names the one that is.

Install

The one-liner

On macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/winterop-com/chap-devops/main/install.sh | sh

Or, to get the binary and nothing else - into this directory as ./chap-devops, no PATH advice, no completion scripts, nothing written anywhere outside it:

curl -fsSL https://raw.githubusercontent.com/winterop-com/chap-devops/main/install.sh | sh -s -- --here

If the script printed ... is not on your PATH, add the export PATH=... line it printed to your shell profile and open a new shell.

Then run chap-devops doctor (./chap-devops doctor after --here): it checks in one pass that this machine has everything a deployment needs - Docker, Compose 2.24.4 or newer, disk, and a route to the hosts Chap pulls from - and says what to do about anything it did not find. See Doctor.

The script prints the release, the platform, the archive URL and the install path, then the steps. On macOS with --here it ends like this:

downloading chap-devops-universal-apple-darwin.tar.gz
verifying the checksum
unpacking

installed /Users/you/chap-devops-test/chap-devops
chap-devops 0.100.1

The script works out the platform from uname, downloads the release archive for it, checks the download against the release’s SHA256SUMS and installs the binary. It refuses to install anything it could not verify.

Next to chap-devops, it puts the link cdx, the short form of the command: cdx up is the same as chap-devops up. chap-devops self update replaces the binary, and the link then points at the new one. --here installs the binary alone, with no link.

If the install folder already has a cdx that is not this link, the script leaves it alone and says so. Two small tools also install a command named cdx: the cdx crate (text tools, with cargo install cdx) and the cdx package on PyPI (directory bookmarks). If you need one of them, delete the link and use chap-devops.

It goes into /usr/local/bin when that directory is writable and ~/.local/bin otherwise. It makes the directory if it is not there. If the directory is not on your PATH, it prints the export PATH=... line to add to your shell profile. Pipe it through sudo sh to take the first branch on a machine where /usr/local/bin needs root.

Without --here, the script also copies the completion scripts into the directories of bash, zsh and fish that already exist in your home (see Shell completions). This is also true with --dir. It prints a completions line for each file it wrote. Only --here writes nothing outside the current directory.

curl -fsSL https://raw.githubusercontent.com/winterop-com/chap-devops/main/install.sh |
  CHAP_DEVOPS_INSTALL_DIR="$HOME/bin" CHAP_DEVOPS_VERSION=v0.100.0 sh

The oldest release that has chap-devops archives is v0.100.0. For an older tag, the script stops with could not download ..., and chap-devops self update --version stops with an error that names the archive it did not find:

error: v0.2.1 has no chap-devops-universal-apple-darwin.tar.gz, so chap-devops cannot install it on aarch64-apple-darwin; pick a newer tag with --version, or run `chap-devops self update` for the newest

Use v0.100.0 or newer. Without --version, the error ends in download a build from https://github.com/winterop-com/chap-devops/releases. --here and --dir together are an error; use one of them.

Without --version the newest release is looked up through the GitHub API, and through the redirect of the releases/latest page when the API rate limit has been reached. Unauthenticated API calls are limited to 60 an hour per address, which a CI runner can exhaust.

Windows

On Windows, chap-devops runs inside WSL. Install WSL 2 and Docker Desktop, turn on Docker Desktop’s WSL integration for your distribution (Settings, Resources, WSL integration), then open the WSL shell and follow the Linux steps above: the one-liner installs the Linux binary, and chap-devops doctor checks that docker answers from inside WSL.

The release also carries native Windows builds (chap-devops-*-pc-windows-msvc.zip in the table below). They are published untested: CI runs on Linux and macOS only. WSL with the Linux binary is the supported way on Windows.

Which version

There are two series, and a binary knows which one it belongs to.

Stable is a vX.Y.Z tag: a release that was cut on purpose, with notes, and it never changes once published. It is what the one-liner installs, what chap-devops self update follows, and what the download links point at.

dev is the rolling build of main, republished under the single moving tag dev on every push. It is the same seven archives, built and signed the same way, from a commit that has passed CI and nothing more: no release notes worth the name, no promise that anything in it stays. It reports the version of the last tag, so chap-devops --version says chap-devops 0.100.1 on a dev build as well; chap-devops self version is what tells the two apart:

  version       v0.100.1
  revision      b95828a
  channel       dev
  target        aarch64-apple-darwin
  path          /usr/local/bin/chap-devops
  installed by  release archive

target is the slice that runs. A universal macOS binary on Apple silicon shows aarch64-apple-darwin.

channel is always printed, stable or dev, and is in --json under the same name. path is the chap-devops file itself, also when you run it through the link cdx. A binary built anywhere else, cargo install included, is stable.

Picking one with the installer:

# the newest stable release
curl -fsSL https://raw.githubusercontent.com/winterop-com/chap-devops/main/install.sh | sh
# the rolling build of main
curl -fsSL https://raw.githubusercontent.com/winterop-com/chap-devops/main/install.sh | sh -s -- --version dev
# one named release
curl -fsSL https://raw.githubusercontent.com/winterop-com/chap-devops/main/install.sh | sh -s -- --version v0.100.0

and with an installed chap-devops:

chap-devops self update                      # the newest build of the channel this one is on
chap-devops self update --version dev        # cross over to the rolling build
chap-devops self update --version v0.100.1   # go back to a stable release

chap-devops self update on a stable build follows releases/latest, which excludes pre-releases, so a stable install is never moved onto a dev build by itself. On a dev build the same command follows the dev release, and compares the commit it was built from rather than the version number, since the version does not move between two rolling builds. --version TAG always wins over both.

Downloading an archive

Each release attaches an archive per platform. These links always point at the newest release:

An archive is named after the platform alone, with no version in it: the release it belongs to is the one in the URL, so a link written down today still resolves after the next release. A release attaches these seven archives and one SHA256SUMS covering all of them, and nothing else.

An archive holds one directory, chap-devops-<version>-<target>/, containing the chap-devops binary, README.md, LICENSE and a completions/ directory. In a dev archive that version is dev-<short commit>, which is the one place the commit shows up without running the binary.

The Linux builds are static musl binaries, so one file runs on any distribution with no shared library to match. Linux and macOS ship as tar.gz, Windows as zip.

On macOS take the universal archive unless you have a reason to pick a single architecture: it carries the Apple silicon and Intel slices in one binary and runs on any Mac.

On macOS:

curl -fsSLO https://github.com/winterop-com/chap-devops/releases/latest/download/chap-devops-universal-apple-darwin.tar.gz
tar -xzf chap-devops-universal-apple-darwin.tar.gz
sudo install -m 0755 chap-devops-*-universal-apple-darwin/chap-devops /usr/local/bin/chap-devops

On a Linux server:

curl -fsSLO https://github.com/winterop-com/chap-devops/releases/latest/download/chap-devops-x86_64-unknown-linux-musl.tar.gz
tar -xzf chap-devops-x86_64-unknown-linux-musl.tar.gz
sudo install -m 0755 chap-devops-*-x86_64-unknown-linux-musl/chap-devops /usr/local/bin/chap-devops

On an arm64 server, write aarch64 in place of x86_64 in the three lines. The commands do not add the link cdx. To add it, run sudo ln -s chap-devops /usr/local/bin/cdx.

Verifying a download

Every release carries a SHA256SUMS file covering every archive:

Download it into the directory that has the archive, then check:

curl -fsSLO https://github.com/winterop-com/chap-devops/releases/latest/download/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing

It prints one line for the archive that is there:

chap-devops-universal-apple-darwin.tar.gz: OK

On Linux, use sha256sum -c SHA256SUMS --ignore-missing; many distributions have no shasum. The sha256sum of BusyBox (Alpine, small containers) has no --ignore-missing. There, check the one line of your archive:

grep ' chap-devops-x86_64-unknown-linux-musl.tar.gz$' SHA256SUMS | sha256sum -c -

The macOS binaries are signed with an Apple Developer ID certificate and notarized by Apple, so Gatekeeper lets them run: no right-click to open, no xattr -d com.apple.quarantine. To see who signed one:

codesign -dv --verbose=4 /usr/local/bin/chap-devops

The Authority=Developer ID Application: ... line names the signer. To see that Apple notarized it:

spctl -a -vvv -t install /usr/local/bin/chap-devops

It prints accepted and source=Notarized Developer ID.

Apple serves the notarization ticket online rather than it being stapled to the file, because a bare executable has nowhere to carry a ticket. The first run on a machine therefore wants to reach Apple once; after that the verdict is cached.

The native Windows binaries are untested and not signed, which would need an Authenticode certificate. SmartScreen may warn the first time chap-devops.exe runs; “More info” then “Run anyway” gets past it. There SHA256SUMS is the check that matters. Under WSL none of this applies: it is the Linux binary.

Keeping it up to date

chap-devops self update           # replace this binary with the newest release
chap-devops self update --check   # say whether there is one, change nothing
chap-devops self version          # version, revision, channel, target, path, install method

chap-devops self update looks up the release, downloads the archive built for this target (on macOS the universal one, whichever slice you installed), checks it against SHA256SUMS and renames the new binary over the running one. The installed file is never written through, so a download that fails or does not verify leaves what you have exactly as it was.

--version TAG installs a named release, going backwards included, and dev is a tag like any other. --yes skips the question replace ... with chap-devops vX.Y.Z? [y/N]. chap-devops does not ask under --json, or when stdin or stdout is not a terminal. --json reports the result as a document, with channel alongside current and latest. If the binary lives somewhere you cannot write, chap-devops says so and suggests sudo or an install directory of your own rather than half-replacing itself.

A successful update prints:

updated chap-devops: v0.100.0 -> v0.100.1

With -v, a hint names the file: hint: replaced /usr/local/bin/chap-devops.

--check on a binary that is up to date prints chap-devops v0.100.1 is up to date. With --version dev or another tag, --check reports that release:

chap-devops dev b95828a (2026-10-07) is available (you have v0.100.1)
hint: the download is chap-devops-universal-apple-darwin.tar.gz
hint: `chap-devops self update --version dev` installs it

The hints come with -v. They name the same --version TAG that was checked, because a plain chap-devops self update follows the channel of this build. The day of a dev build is the day it was built, from the release notes or the newest asset. If chap-devops finds no date, the line says chap-devops dev b95828a with no day.

Without --version, an update follows the channel this build is on: the newest tag for a stable build, the newest build of main for a dev one. See Which version.

Once a day, after a command that succeeded, chap-devops asks the release feed whether there is a newer version and prints one dimmed line on stderr if there is:

chap-devops v0.100.1 is available (you have v0.100.0): run `chap-devops self update`

On a dev build the same notice compares commits, because the version number does not move between two rolling builds:

a newer chap-devops dev build is available (commit 9f3a2c1, you have bff294c): run `chap-devops self update`

It stays quiet unless it can see that the commit moved, so a build with no recorded revision is never nagged about nothing.

The check has a two-second timeout, its answer is cached in self-update-check.json in the cache directory ($CHAP_DEVOPS_CACHE_DIR, else $XDG_CACHE_HOME/chap-devops, else ~/.cache/chap-devops, also on macOS), and any failure is ignored: it can never change what a command did or what it exited with. It is skipped under --json, under --offline, when stdout is not a terminal, and for chap-devops self itself. CHAP_DEVOPS_NO_UPDATE_CHECK=1 turns it off entirely.

A chap-devops installed with cargo install is replaced the same way, but cargo install --path . from an updated checkout is the more honest way to move that one on. installed by in chap-devops self version tells which one you have:

• release archive for a binary that the release workflow built, wherever it is now.
• cargo install for a local build in a .cargo/bin directory.
• cargo build for a local build in a target/release or target/debug directory.
• local build for a local build at any other path, also for make install and for cargo install --root DIR.

Shell completions

Every release archive ships the scripts for bash, zsh, fish and PowerShell under completions/ (chap-devops.bash, _chap-devops, chap-devops.fish, _chap-devops.ps1). The install script copies the first three into place when the directory a shell reads already exists:

• ~/.local/share/bash-completion/completions/chap-devops (or under $XDG_DATA_HOME)
• ~/.zsh/completions/_chap-devops
• ~/.config/fish/completions/chap-devops.fish (or under $XDG_CONFIG_HOME)

When the script adds the link cdx, it also writes the bash and fish script a second time under the name cdx (completions/cdx and cdx.fish). bash and fish load a completion file by the name of the command, so cdx then completes before chap-devops was completed once. zsh needs nothing more, because _chap-devops starts with #compdef chap-devops cdx.

chap-devops completions <shell> prints one to stdout for the cases it does not cover: a checkout, a different directory, or a shell that reads its completions from somewhere else. The shells are bash, zsh, fish, powershell and elvish. The scripts complete chap-devops and the link cdx.

bash, with the bash-completion package installed (on macOS, bash-completion@2 from Homebrew):

mkdir -p ~/.local/share/bash-completion/completions
chap-devops completions bash > ~/.local/share/bash-completion/completions/chap-devops
chap-devops completions bash > ~/.local/share/bash-completion/completions/cdx

zsh, into a directory that is on your fpath. If it is a new directory, add fpath=(~/.zsh/completions $fpath) before compinit in ~/.zshrc:

mkdir -p ~/.zsh/completions
chap-devops completions zsh > ~/.zsh/completions/_chap-devops

fish:

mkdir -p ~/.config/fish/completions
chap-devops completions fish > ~/.config/fish/completions/chap-devops.fish
chap-devops completions fish > ~/.config/fish/completions/cdx.fish

PowerShell, appended to your profile:

chap-devops completions powershell | Out-String | Invoke-Expression

elvish:

mkdir -p ~/.config/elvish/lib
chap-devops completions elvish > ~/.config/elvish/lib/chap-devops.elv

Then add use chap-devops to ~/.config/elvish/rc.elv.

The scripts are generated from the same command tree --help is rendered from, so they are current for the binary that printed them. Regenerate them after an update.

From a checkout

A checkout needs Rust 1.91 or newer. In the root of the checkout, run:

cargo install --path .

This builds the binary and puts it in ~/.cargo/bin (or $CARGO_HOME/bin). cargo build --release builds it into target/release/chap-devops and installs nothing.

Or build and install through the Makefile, which puts the binary in $PREFIX/bin with PREFIX defaulting to ~/.local:

make install

To install into another directory, set PREFIX, for example make install PREFIX=/usr/local.

On macOS make release builds a universal (arm64 plus x86_64) binary at bin/chap-devops first, and make install copies that. It needs the two Rust targets; if one is missing, it stops and prints the command to add it: rustup target add aarch64-apple-darwin x86_64-apple-darwin. On Linux it builds the host binary. make install also adds the link cdx, as the install script does; cargo install installs chap-devops alone. See Development for the rest of the targets.

chap-devops is released as binaries on GitHub, not on crates.io: publish = false in Cargo.toml makes a cargo publish fail at once.

Requirements

On the machine that runs Chap: Docker, with Compose v2.24.4 or newer. That version is where the !override YAML tag arrived, and every compose.chap-devops.yml chap-devops sync writes uses it to replace chap-core’s own port mapping rather than add to it; see Ports. The other requirement is older: include:, which chap-devops uses for the umbrella file that names one overlay per enabled model, arrived in 2.20.

Nothing else is required. No Python, no uv, no checkout of chap-core. This is also true for chap-core’s own chap CLI: chap-devops chap runs it in a container. See The chap CLI. The same is true for chapkit’s CLI: chap-devops chapkit runs it in the chap-core image. See The chapkit CLI.

chap-devops checks the installed Compose version and warns on stderr when it is older than 2.24.4 rather than failing, because an older Compose still runs most of Chap. Between 2.20 and 2.24.4 the model overlays load and the API ends up published on two ports, its own and the override’s; below 2.20 the model overlays are the part that will not load at all.

A note on the name

The binary is chap-devops, not chap, because chap-core’s own Python package already installs a console script called chap. The two never collide, so a machine can have both.

Quickstart

0. Check the machine

After installing, run:

chap-devops doctor

ok    docker cli           docker 29.8.2
ok    docker daemon        Docker Engine 29.8.2
ok    docker compose       v5.5.1
warn  os and arch          macos/aarch64; Chap images are linux/amd64 only, so they run under emulation
      nothing to do: Rosetta runs the amd64 images, they are only slower
ok    disk space           583.7 GB free on /srv
ok    leftovers            no volumes left by removed deployments
ok    network ghcr.io      reachable (HTTP 401)
ok    network marketplace  reachable (HTTP 200)
ok    network releases     reachable, newest chap-core is v2.4.0
ok    github api           reachable, 60 of 60 requests left this hour (no token; set GITHUB_TOKEN for 5000)
ok    chap-devops                v0.100.1, aarch64-apple-darwin, release archive

11 checks: 10 ok, 1 warn, 0 fail

There is one line per check: Docker, Compose, the CPU architecture, free disk, and the hosts Chap pulls from. A check that is not ok has a second line that tells you what to do. The run above is on a Mac, so the architecture check is a warn. Inside a deployment directory, doctor also checks the deployment. See Doctor.

1. Write the deployment directory

chap-devops init mychap --models chapkit_simple_multistep_model

created a deployment in /srv/mychap
components: chap-core
chap-core: v2.4.0, API on http://localhost:8700
enabled chapkit_simple_multistep_model v0.1.2 at http://localhost:8700/v2/services/chapkit-simple-multistep-model/run/
run `cd /srv/mychap && chap-devops up` to start the deployment

init writes the compose files, .env and the state in .chap-devops/, and starts nothing. With -v, it also names each file it wrote.

Model services publish no host port. chap-core reaches them over the compose network, and you reach them through chap-core at the URL on the enabled line. That route accepts only GET (and HEAD) requests, for example /api/v1/info. For anything else, chap-devops models expose ID publishes a port of the model’s own (step 5).

chap-devops init mychap --with ocs adds Open Climate Service beside chap-core, and --with ocs,s3 adds the object store with it. --with dhis2 adds a demo or development DHIS2 and a PostgreSQL of its own; its first start takes minutes rather than seconds, and DHIS2 says why and what else to know first. See Components.

--models chapkit_simple_multistep_model enables Simple Multistep on its stable channel, and --models a,b takes a list of marketplace ids. Without --models, init enables no model and says no models are enabled; run \chap-devops models enable ID` to add one. –interactiveopens the model browser instead of reading–models`.

A model the marketplace does not list yet is added from its repository or image: chap-devops models add https://github.com/my-org/chapkit_dengue_model (see Models outside the marketplace).

chap-core itself is pinned to the newest release, v2.4.0 in the run above, and init takes the compose.ghcr.yml that release publishes as the base of the deployment. --chap-tag picks another tag; see Updating.

The deployment above has no authentication: anything that can reach the port can use the API. chap-devops init mychap --models chapkit_simple_multistep_model --api-token generates a token and protects the API with it. chap-devops auth enable does the same to a deployment that already exists. See Authentication.

2. Start it

cd mychap
chap-devops up

...
 Container mychap-dabd2e-chapkit-simple-multistep-model-1 Started
started chap, chapkit-simple-multistep-model, postgres, redis, worker

The first up on a machine pulls the images: about 6 GB to download and about 20 GB on disk. The chap-worker image alone is 3 GB. On a slow line this can take close to an hour (47 minutes in one test run). Compose shows the pull progress while it works. A second deployment uses the same images and starts in seconds.

up renders the compose files from .chap-devops/ first, then checks that every host port Chap is about to publish is free, then calls docker compose up -d. The last line names the services it started; a recreated container counts as started. With -v, a hint also names the services it left alone.

up returns when compose has started the containers, not when chap-core answers. chap-devops up --wait returns only once chap-core, every model, OCS and DHIS2 answer. It also gives the models their configured models (step 3).

Every command that operates on a deployment finds its directory the way git finds .git: from the current directory (or -C DIR) upwards to the nearest .chap-devops/, so chap-devops up works from any subdirectory of the deployment.

3. Check it

chap-devops status

chap-core   up   http://localhost:8700   2.4.0   auth: off

MODEL                           STATE                       REACH          LAST PING
chapkit-simple-multistep-model  registered, not configured  via chap-core  1s ago

1 model registered
chapkit-simple-multistep-model: chap-core has no configured model for it, so nothing can run it; run `chap-devops models configs sync`

registered, not configured is the normal state after a plain chap-devops up. chap-core v2.4.0 makes no configured model when a model registers. A backtest and the Modeling App need one. Make them:

chap-devops models configs sync

chapkit_simple_multistep_model: created configured model monthly_climate
chapkit_simple_multistep_model: created configured model monthly_selfhistory

chap-devops up --wait does the same step for you. See Configured models. Now chap-devops status shows the model as registered:

chap-core   up   http://localhost:8700   2.4.0   auth: off

MODEL                           STATE       REACH          LAST PING
chapkit-simple-multistep-model  registered  via chap-core  7s ago

1 model registered

With -v, status also gives the route through chap-core and the next command to try:

hint: models without a host port are reachable through chap-core at http://localhost:8700/v2/services/<id>/run/
hint: run `chap-devops models test --all` to check it can run

A model can also be running, not registered or not running, and then status names the command that fixes it. A model that started a moment ago is running, not registered until it is ready (step 5 shows this).

On a deployment whose containers do not exist at all, status skips the table and says so:

Chap is not running; start it with `chap-devops up`

Status and output explains every column and every state.

4. Add a model

chap-devops ui

The browser shows the catalogue as one table, with a one-line summary of the selected row under it. space enables or disables, p publishes a host port, v switches channel, and s saves. Enter or i shows the full entry, and q quits. Nothing is written until you save. See The browser.

The same thing without the browser:

chap-devops models search arima
chap-devops models info auto_arima_chapkit
chap-devops models enable auto_arima_chapkit --channel stable

enable changes only the files:

enabled auto_arima_chapkit v1.0.2 at http://localhost:8700/v2/services/auto-arima-chapkit/run/
run `chap-devops up` to apply

The STATUS column of search tells you how ready a model is. No model in the marketplace is production yet. Simple Multistep is limited data: it shows promise, but needs careful evaluation. Auto-ARIMA is experimental. Read chap-devops models info before you enable a model for real work.

Start the model:

chap-devops up
chap-devops status

up says started auto-arima-chapkit. Right after it, the new model is not registered yet, and status exits with 1:

chap-core   up   http://localhost:8700   2.4.0   auth: off

MODEL                           STATE                    REACH          LAST PING
auto-arima-chapkit              running, not registered  via chap-core  -
chapkit-simple-multistep-model  registered               via chap-core  1s ago

1 of 2 models is not registered.
auto-arima-chapkit: started under two minutes ago and registers once it is ready; run `chap-devops status` again in a minute

In the test run, the model registered within 10 seconds. Then it is registered, not configured, as in step 3. Give it its configured models:

chap-devops models configs sync

auto_arima_chapkit: created configured model monthly
chapkit_simple_multistep_model: chap-core has a configured model of it already

chap-devops status now shows both models as registered:

chap-core   up   http://localhost:8700   2.4.0   auth: off

MODEL                           STATE       REACH          LAST PING
auto-arima-chapkit              registered  via chap-core  4s ago
chapkit-simple-multistep-model  registered  via chap-core  6s ago

all 2 models registered

If you run chap-devops models configs sync before the model registers, it says so and tells you to run it again later.

chap-devops models list shows the whole catalogue and what this deployment enabled:

ID                                SERVICE                           NAME                STATUS        STABLE  LATEST  PORT
chapkit_simple_multistep_model    chapkit-simple-multistep-model    Simple Multistep    limited data  0.1.2   0.1.2   via chap-core
auto_arima_chapkit                auto-arima-chapkit                Auto-ARIMA          experimental  1.0.2   1.0.2   via chap-core
chapkit_ghr_model                 chapkit-ghr-model                 GHRmodel            experimental  0.1.3   0.1.3   -
chapkit_rwanda_malaria_bym_model  chapkit-rwanda-malaria-bym-model  Rwanda Malaria BYM  not for use   0.1.3   0.1.3   -

4 listed, 2 enabled in this deployment

5. Reach a model from your own machine

Model services publish no host port of their own. Either go through chap-core, which accepts only GET (and HEAD) requests:

curl http://localhost:8700/v2/services/chapkit-simple-multistep-model/run/api/v1/info

or give the model a port:

chap-devops models expose chapkit-simple-multistep-model

exposed chapkit-simple-multistep-model on http://localhost:5001
run `chap-devops up` to apply

chap-devops up

up recreates the model container to publish the port. The model needs up to a minute before it answers on http://localhost:5001 and registers again. Until then, chap-devops status shows it as running, not registered:

1 of 2 models is not registered.
chapkit-simple-multistep-model: started under two minutes ago and registers once it is ready; run `chap-devops status` again in a minute

See Ports.

6. Back it up

chap-devops backup create

wrote /srv/mychap/chap-devops-backup-mychap-20261012-094057.tar.gz (19.0 KB gzipped, 195.6 KB of data)

One tar.gz in the deployment directory holds the deployment files, a pg_dump of the chap-core database and one tar per model data volume. The time in the file name is UTC. The archive holds .env with the database password, so keep it private. chap-devops backup restore ARCHIVE puts it back. See Backup and restore.

7. Move the pins forward

chap-devops update --dry-run    # the plan, writing nothing
chap-devops update              # move the pins, pull the images
chap-devops restart             # apply them to the services that are running

When nothing is newer, update gives one row per pin and one closing line:

  auto_arima_chapkit              v1.0.2 (sha-e9047d4)  unchanged
  chapkit_simple_multistep_model  v0.1.2 (sha-10b2bc7)  unchanged
  chap-core                       v2.4.0  unchanged, the newest release
already up to date

restart then shows the compose progress, and its last line is nothing needed a restart: every container matches its files.

chap-devops update never touches a container. When a pin moved, its closing line says what moved and which running services are now behind it, and chap-devops restart recreates exactly those. On a deployment that is not running there is nothing to restart; with -v, a hint says that chap-devops up starts it with the new versions. See Updating.

Running one model

chap-devops run starts one model service and prints where it answers. There is no chap-devops init first and no directory to keep: name the model, by marketplace id, GitHub repository or image, and use the URL.

chap-devops run chapkit_simple_multistep_model
chap-devops run https://github.com/chap-models/chapkit_ghr_model
chap-devops run ghcr.io/my-org/chapkit_dengue_model:sha-1eb8cf1
chap-devops run my-dengue-model:dev                 # built on this machine

starting chapkit-simple-multistep-model (chapkit_simple_multistep_model in /home/me/.local/share/chap-devops/run/default)
running chapkit_simple_multistep_model on http://localhost:5001 (answered in 4s)

With -v, two hints follow: the command that stops the model, and the command that shows its log:

hint: `chap-devops stop chapkit_simple_multistep_model` stops it
hint: `chap-devops -C /home/me/.local/share/chap-devops/run/default logs chapkit-simple-multistep-model` shows its log

The command returns once the model answers its own /health, so the URL works when the line is printed. With --no-wait, the line starts with started instead of running, and chap-devops ps shows when the model answers. A first run pulls the image, which takes a while for the R-INLA models; --timeout SECONDS (300 by default) is how long it waits before it fails naming the state the model was in.

In the foreground: -a

-a (also --attach or --foreground, as on chap-devops up) keeps chap-devops run in the foreground. After the URL, it shows the model’s log, and Ctrl-C stops the model:

running chapkit_simple_multistep_model on http://localhost:5001 (answered in 4s)
following the log of chapkit-simple-multistep-model; Ctrl-C stops it
...
stopped chapkit_simple_multistep_model; its data stays, and `chap-devops run chapkit_simple_multistep_model` starts it again with it

Ctrl-C takes the model out of its group, as chap-devops stop does. The model’s data volume stays, so the next run starts with the model’s trained state. --rm removes the data volume too, and the group when it has no model left (removed group default), as chap-devops stop --purge does. A second Ctrl-C exits at once. A model that ran before the command is not stopped: Ctrl-C then stops only the log. With --no-wait, you watch the model start in its log. --json always returns.

Ctrl-C during the start, with or without -a, takes back out what the start put in: a model that this run enabled goes back out of the group, as after a failed start. The command then exits with 130:

error: stopped by Ctrl-C; chapkit_simple_multistep_model is taken back out of /home/me/.local/share/chap-devops/run/default

Your own chap-core

A group has no chap-core of its own, so its models register nowhere. --chap-core URL makes them register with a chap-core that runs elsewhere, for example one from its own checkout:

chap-devops run -a --rm --chap-core http://localhost:8000 https://github.com/chap-models/chapkit_ghr_model

running chapkit_ghr_model on http://localhost:5001 (answered in 2s)
registered with http://localhost:8000

• chap-devops records the chap-core on the group, as chap-devops components enable chap-core --url does in a deployment. Every model of that group then registers with it. Use --group NAME for a group of its own.
• chap-devops decides where chap-core calls the models back. A chap-core in a container on this machine calls host.docker.internal, and a chap-core process calls localhost. --models-host HOST sets it.
• After the start, chap-devops asks chap-core whether it lists the model, and says registered with URL, or gives the warning not registered with URL. “Up” means chap-core answered, not only that the container started.
• A group that had another chap-core moves to the new one. Its models that run now register with the old one until they restart, and chap-devops says so.

In a deployment of your own, --chap-core is refused: set the chap-core there with chap-devops components enable chap-core --url URL.

What the model can be

A model that is already enabled is started as it is: a second chap-devops run of the same id does not move its version or its port. A run by the repository URL of an enabled marketplace model, or by its image at the tag of the enabled version, finds that model and starts it as it is. The same holds for a repository or an image: one added before, by an earlier chap-devops run or models add, is that entry again, enabled or not, so running the same URL twice starts one model, not two. An image counts as the same only at the same tag. --id names an added model (--id auto picks a free one), exactly as on models add; an --id other than the one the source was added under adds a second copy beside it.

A word with no :, / or @ is a marketplace id, never a local image (a local image always carries a tag), so chap-devops run does_not_exist says there is no such model and names chap-devops models search. A marketplace starter is refused like it is on models enable; --allow-starter starts it anyway.

When the container cannot be started - the image does not exist, the pull is denied, the port is taken - run says what compose said and takes the model it enabled back out, so chap-devops ps does not list it and the next chap-devops run of the same source starts afresh. The definition of an added model stays.

Where it runs: groups

Outside a deployment, chap-devops run keeps its models in a group: a deployment chap-devops owns under its data directory, run/<group>/. The data directory is $CHAP_DEVOPS_DATA_DIR, else $XDG_DATA_HOME/chap-devops, else ~/.local/share/chap-devops. --group NAME picks one; without it the group is default. The first chap-devops run into a group creates it, as chap-devops init --only none --models none would, so there is no chap-core and no component in it: only model services, each on its own host port.

Groups keep models apart. Each one is a compose project of its own, so its containers, volumes and network carry its name, and stopping a group touches nothing else. .chap-devops/project.yaml records the group as group: <name>, and every container in it carries the labels com.winterop.chap-devops.kind: run and com.winterop.chap-devops.group: <name>, so docker ps --filter label=com.winterop.chap-devops.group=trial lists one group’s containers (Container labels):

chap-devops run chapkit_simple_multistep_model                    # group default
chap-devops run auto_arima_chapkit --group trial
chap-devops run chapkit_ghr_model --group trial
chap-devops ps

GROUP    ID                              SERVICE                         STATE        URL
default  chapkit_simple_multistep_model  chapkit-simple-multistep-model  up           http://localhost:5001
trial    auto_arima_chapkit              auto-arima-chapkit              up           http://localhost:5002
trial    chapkit_ghr_model               chapkit-ghr-model               not running  http://localhost:5003

With -v, a hint after the table names the directory that holds the groups, for example hint: groups live in /home/me/.local/share/chap-devops/run.

--port auto takes the lowest port in 5001-5999 that nothing on the machine holds and no group has given to a model, running or stopped, so two groups never collide.

Inside a deployment of your own - the working directory, or -C DIR - run, ps and stop work on that deployment instead, and --group is refused, because the deployment is the group. So a tool that only wants “start this model and give me its URL” has one code path whether or not someone ran chap-devops init.

Only this machine

A group publishes every model port on 127.0.0.1, so a model chap-devops run started is reachable from this machine and not from the network: models have no login. --bind 0.0.0.0 publishes one on every address instead. Inside a deployment, run publishes as that deployment does. See Ports.

Listing and stopping

chap-devops ps lists every model in every group, or in one with --group, with the state chap-devops status would give it: up when its /health answers, running, not answering while it starts or when it failed to, not running when its container is gone.

When it finds no model, chap-devops ps says where it looked:

• there is no `chap-devops run` group X; `chap-devops ps` lists every group, for a --group X that does not exist.
• no model runs in a `chap-devops run` group, when the groups exist and have no model.
• nothing has been started with `chap-devops run` yet, when there is no group.

-C on a group that chap-devops stop --purge removed names the command that makes it again: the `chap-devops run` group X does not exist, or `chap-devops stop --purge` removed it; `chap-devops run <model> --group X` makes it again. chap-devops ps, chap-devops stop, chap-devops run, chap-devops chap, chap-devops logs and chap-devops status all give this error. A -C to another directory that is not a deployment, or to one that does not exist, gives DIR is not a chap-devops deployment. So chap-devops ps does not list every group, and chap-devops stop --all does not stop every model, because of a wrong -C.

chap-devops stop ID stops a model and takes its overlay away, in whichever group has it; when two groups do, it asks for --group. chap-devops stop --all stops every model in every group, and chap-devops stop --group NAME every model in one. The data volume stays, as with models disable, and so does the definition of an added model, so chap-devops run ID starts it again without asking GitHub. chap-devops stop prints one line for each model it stopped. With -v, hints say what became of the container and the volume, and how to start the model again:

$ chap-devops -v stop chapkit_simple_multistep_model
stopped chapkit_simple_multistep_model
hint: stopped and removed 2 containers (chapkit-simple-multistep-model, chapkit-simple-multistep-model-init); host port 5001 is free again
hint: kept volume default-1ab2c3_ck_chapkit_simple_multistep_model_data; remove it with `chap-devops -C /home/me/.local/share/chap-devops/run/default models disable chapkit_simple_multistep_model --purge` or `docker volume rm default-1ab2c3_ck_chapkit_simple_multistep_model_data`
hint: `chap-devops run chapkit_simple_multistep_model` starts it again

--purge takes the volume too, and the group it leaves with no model in it goes as well: its network, its directory and every volume compose made for it, including the volume of a model stopped earlier without --purge. Only that group: another group with no model left, emptied by an earlier plain stop, keeps its data. chap-devops stop --group NAME --purge empties and removes that one group, and chap-devops stop --all --purge every group. A volume docker will not remove keeps its group, so the same chap-devops stop --group NAME --purge can finish the job once the volume is free.

The deployment behind a group is an ordinary chap-devops deployment, so every other command works on it with -C: chap-devops -C ~/.local/share/chap-devops/run/default logs chapkit-simple-multistep-model, chap-devops -C ... status. Messages from inside a group name their commands that way.

For tools

Every one of the three takes --json and prints one document on stdout:

{
  "bind": "127.0.0.1",
  "enabled": true,
  "group": "default",
  "id": "chapkit_simple_multistep_model",
  "messages": [...],
  "ok": true,
  "port": 5001,
  "project_dir": "/home/me/.local/share/chap-devops/run/default",
  "service_id": "chapkit-simple-multistep-model",
  "url": "http://localhost:5001",
  "wait": {"ready": true, "waited_s": 4, "models": [...]}
}

Each document also has the messages list of every closing line with its level; see Output. chap-devops ps --json is {"models": [...]} with the same fields per model plus state; chap-devops stop --json lists what it stopped, the groups it removed and the volumes that went with them, removed_volumes. A failure is {"ok": false, "error": ..., "hint": ...} like every other command’s, a usage error included; see --json for scripts and tools. docker’s own progress, such as a pull, goes to stderr, so stdout is the one document.

Two chap-devops run started at the same time into one group wait for each other rather than writing over each other, and land on different ports; see One change at a time. That holds for a group neither of them has created yet, and for two runs of the same model, which start it once and both report it.

Watching everything: chap-devops top

chap-devops top shows every chap-devops deployment on this machine as one tree that keeps itself up to date: the deployments made with chap-devops init and the chap-devops run groups alike, each with its services under it - chap-core and its worker and databases, DHIS2, OCS, the object store and the models - and what each container is doing.

 chap-devops top  3 deployments  8/12 running  at 13:17:51 (every 2s)
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│DEPLOYMENT / SERVICE                                                  STATE                  CPU      MEMORY                 URL                              │
│▾ mychap  init                                                        6/9 running                                            /home/me/mychap                  │
│  ├─ chap                                                             running (healthy)      6.52%    442.9MiB / 31.29GiB    http://localhost:8700            │
│  ├─ postgres                                                         running (healthy)      0.02%    35.27MiB / 31.29GiB                                     │
│  ├─ redis                                                            running (healthy)      0.28%    12.56MiB / 31.29GiB                                     │
│  ├─ worker                                                           running (healthy)      0.79%    1.118GiB / 31.29GiB                                     │
│  ├─ dhis2                                                            running (healthy)      2.82%    1.982GiB / 31.29GiB    http://localhost:8780            │
│  ├─ dhis2-db                                                         running (healthy)      0.04%    71.71MiB / 31.29GiB                                     │
│  ├─ dhis2-dump                                                       exited                                                                                  │
│  ├─ dhis2-prep                                                       exited                                                                                  │
│  └─ chapkit-simple-multistep-model (chapkit_simple_multistep_model)  exited                                                 http://localhost:5001            │
│▸ run/default  run                                                    1/1 running                                            /home/me/.local/share/chap-devops/run/ │
│▾ run/trial  run                                                      1/2 running                                            /home/me/.local/share/chap-devops/run/ │
│  ├─ auto-arima-chapkit (auto_arima_chapkit)                          running (healthy)      0.43%    108.9MiB / 31.29GiB    http://localhost:5003            │
│  └─ chapkit-simple-multistep-model (chapkit_simple_multistep_model)  exited                                                 http://localhost:5001            │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 j/k move  enter fold  l logs  s stop model  r refresh  q quit

--interval SECONDS (2 by default, at most 3600) sets how often docker is asked. Docker is asked from a thread of its own, so a slow daemon never holds up a key.

How it finds them

Every container chap-devops starts carries labels that say what it is (see Container labels), so one docker ps -a --filter label=com.winterop.chap-devops.role finds them all, on any deployment, wherever its directory is. Compose’s own labels say which deployment and which service each one is, and the directory compose ran in; from that directory chap-devops top reads the deployment’s state for the URLs. A deployment whose directory is gone still shows, without them.

The deployment the command runs in, and every chap-devops run group with a model enabled, show even with nothing running: their enabled models are listed as not running. A group with no model is left out.

In a script

Off a terminal - piped, or under --json - chap-devops top prints one snapshot of the same tree and exits:

chap-devops top --json | jq '.deployments[] | {name, kind, services: [.services[] | {service, state, cpu}]}'

Each deployment has project (the compose project name), name, kind (init or run), group, dir and services; each service has service, role, model, state, health, cpu, memory and url. For the models of one deployment with their registration state, chap-devops ps and chap-devops status say more.

Your first forecast in the Modeling App

A walk from a fresh deployment to an evaluated model and a three-month dengue forecast, by clicking in the Modeling App. It takes about fifteen minutes, most of it waiting for the model. It starts where Chap with a local DHIS2 ends:

chap-devops init mychap --models chapkit_simple_multistep_model --with dhis2
cd mychap
chap-devops up
chap-devops status          # until the dhis2 line says up
chap-devops dhis2 connect
chap-devops open dhis2

chap-devops dhis2 connect points the DHIS2 route chap at chap-core, installs the Modeling App and the DHIS2 Climate App, and runs the DHIS2 analytics tables. It also makes the configured models that the Modeling App lists. It took about 40 seconds. Its last line is the Modeling App can reach Chap; open DHIS2 with `chap-devops open dhis2`.

Tested on 2026-10-19 with chap-devops v0.110.0, Modeling App 7.3.0, DHIS2 2.42.6 with the Laos demo database, chap-core v2.5.0 and Simple Multistep (chapkit) 0.1.2. Other versions of the Modeling App may name a button differently; the steps stay the same. chap-devops dhis2 show says which Modeling App version a deployment has.

What the demo data holds

The DHIS2 that chap-devops starts is seeded with a demo database from Laos:

for Lao PDR, its 18 provinces and their districts. The Modeling App adds the weekly cases up to months when an evaluation is monthly.

1. Open the Modeling App

Log in to DHIS2 with admin / district, open the app menu (the grid of squares at the top right), type Modeling in its search box and pick Modeling: the menu shows only a few top apps until you search. The dashboard is empty until the first evaluation.

2. Start an evaluation

An evaluation asks: had this model been used in the past, how close would its forecasts have come? It trains the model on the earlier data, forecasts the months after, and compares the forecast with what really happened, several times over.

In Evaluate, Overview, choose New evaluation. The page opens on the tab Use saved dataset, which needs a dataset saved before. Choose the tab Import from DHIS2 and fill in:

The list cuts long names short, for example Simple Multistep Model (chapkit) [Mont…. The panel on the right shows the full name of the entry you clicked, and Use this model picks that entry.

Leave the Backtest parameters as they are: 3 forecast periods, 7 splits, a step of 1, 1 training run, and the future-weather provider Seasonal climatology.

Simple Multistep Model (chapkit) is the model chap-devops started with --models chapkit_simple_multistep_model. It has two entries, one for each configuration in its marketplace entry: Monthly climate uses rainfall, temperature and relative humidity, and Monthly selfhistory uses only the case history. The list shows one entry for each configured model, as <model name> [<variant name>]. Each model enabled with chap-devops models enable adds its own entries. chap-core 2.4 and later does not make these entries itself: chap-devops up --wait, chap-devops dhis2 connect and chap-devops models configs sync make them. If a model is not in the list, run chap-devops status. If it shows the model as registered, not configured, run chap-devops models configs sync. To add an entry of your own with other option values, run chap-devops models configs add. See Adding. chap-devops models test --all makes each model train and predict. See Configured models.

Under each name, the list shows the author of the model. The list also holds models that chap-core ships configured on its own and runs inside its worker, such as CHAP-EWARS Model and Monthly CHAP-EWARS model. Some of them have the status Deprecated. From chap-core v2.5.0, it also has the three built-in baselines, Persistence, Global median and Seasonal median. chap-core runs them beside each evaluation, so you can compare a model with them. None of these are models that chap-devops started. The two (chapkit) entries have the status Limited.

3. Map the data

Configure sources asks which DHIS2 data each input of the model comes from. Search by name in each box:

A search for the dengue cases also finds the items CHAP Dengue Cases (Any) - Weekly Quantile ... and NCLE: 7. Dengue cases (any). The CHAP items hold forecasts, not cases. Pick Dengue Cases (Any) - Weekly exactly.

Save, then Start dry run. It checks the data without starting anything, and should say All 18 locations can be successfully imported.

Close it and choose Start import. The app moves to Jobs, where the evaluation runs. With Simple Multistep it took about 24 seconds on an Apple Silicon Mac (M2 Max), where the model runs under emulation. chap-devops jobs in the terminal shows the same job; its type is create_backtest_from_data.

4. Read the result

Back in Evaluate, Overview, open the evaluation. The chart shows the real cases (orange) and, for the period picked under Split period, the model’s forecast with its 50% and 80% prediction intervals. The list on the left switches between all of Laos and one province.

Evaluation metrics, lower on the right, scores the forecasts over every split and province: lower is better for CRPS (log1p), MAE and RMSE, and Coverage 10-90 should be close to its target of 0.8 (80% of the real values inside the 80% interval). Show all 13 metrics lists the others.

To compare two models, run a second evaluation on the same data:

1. On the first evaluation, choose Create new based on…. It asks which settings to copy; leave them all ticked and choose Create.
2. The copy has the name, provinces, model, data mapping and periods of the first, and its name ends in (Copy).
3. On the copy, Select model picks another model, for example Simple Multistep Model (chapkit) [Monthly selfhistory]. Then choose Start import.
4. In Evaluate, Compare, pick the first evaluation in the left box and the copy in the box beside it.

The evaluation of Monthly selfhistory took about 20 seconds. The comparison shows the two side by side, province by province; the box Location(s) starts with ten provinces selected. More marketplace models come with chap-devops models enable ID and chap-devops up (chap-devops models list shows the ids).

5. Make a forecast

On the evaluation, Create prediction setup keeps the model, the data mapping and the provinces under a name: type one in Setup name, leave Alert policy at No alert policy and Set default import mapping off, and Save. The app then opens the setup. Once the evaluation has a setup, the same button says Predict.

On the setup, choose Run prediction. The page fills in a name for the run. In Training period, set the last training period to the last month with case data: 2024 December for the demo data. Then choose Run prediction again. The app goes back to the setup, where the run shows as Running. The forecast covers the three months after that month.

The job took about 7 seconds in chap-devops jobs. The row in the app said Success within a minute, without a reload. Go to last run shows one chart per province: the real cases up to December 2024 and the forecast for January to March 2025.

Import, on the right of the forecast, opens a page that writes the forecast back into DHIS2 as data, where dashboards and maps can use it. It needs five data elements for the forecast’s quantiles. Each box is empty at first; open it, and it lists the elements of the demo database under Suggested. Pick CHAP Dengue Cases (Any) - Weekly Quantile High to ... Quantile Low.

Use alert outputs is on by default, and then the page also needs an Outbreak indicator: Clear and import does nothing until it has one, and the message is under the box, below the first screen. Pick CHAP Dengue Cases (Any) - Weekly Outbreak Alert; the box does not suggest it, so type Outbreak to find it. Or turn Use alert outputs off. Clear and import asks once more before it writes, then the app goes back to the setup. DHIS2 2.42.6 accepted the monthly values into those elements, but their data set is weekly. For a monthly forecast, create monthly data elements in DHIS2’s Maintenance app and pick those.

When something goes wrong

More on connecting DHIS2 and Chap: DHIS2. The Modeling App’s own guide is at chap.dhis2.org.

Use cases

Helping someone as an AI assistant? Start at For AI assistants, which turns these pages into a menu of options with the exact commands.

chap-devops deploys Chap, but Chap is only one of the shapes a deployment can take. The same directory layout, the same commands and the same chap-devops up / chap-devops status / chap-devops doctor loop work for any combination of:

--with adds components to chap-core. --only names the whole set, and chap-core is part of it only if you list it. Each page below is one shape people actually deploy: the command that creates it, what you get, and what to run next. They are not exclusive: a deployment can move from one shape to another later with chap-devops components enable / disable and chap-devops models enable / disable. See Growing a deployment.

Only one piece

Chap

• Chap with forecasting models: chap-core and the models it runs; the default, or every model in the marketplace.
• Chap with climate data from OCS: chap-core with Open Climate Service beside it.
• Chap with a local DHIS2 and the Modeling App: chap-core, models and a DHIS2 of the version you pick, connected.
• Chap for a DHIS2 that runs elsewhere: chap-core on a server, used by a DHIS2 someone else runs.
• Combinations: OCS and DHIS2 without Chap, a model beside OCS, everything at once.

Evaluating with the chap CLI

• Evaluating a model on your own data: chap-core’s chap eval on your CSV, through chap-devops chap, with no Python or uv.

Developing Chap, a model or DHIS2

• A new model of your own: chap-devops models new makes a model project in Python or R, and Docker builds it.
• An MLproject model, with no image to build: chap-devops chapkit mlproject run serves the directory, chap-core tests it, and migrate and export change it to a chapkit service and back.
• Your model from its checkout, with Chap: chap-devops runs chap-core; you run your model with uv run and it registers.
• A model image you built yourself: docker build a model and run it in Chap without publishing it.
• chap-core from its checkout, with the models: you run chap-core; chap-devops runs the models and registers them with it.
• chap-core built from its checkout: chap-devops builds chap-core from your clone and runs it with everything else.
• A DHIS2 you run yourself, with Chap from chap-devops: your DHIS2 and a chap-core from chap-devops, connected.
• A DHIS2 from chap-devops, with a chap-core elsewhere: a DHIS2 from chap-devops and your chap-core, connected.

More than one, and changing your mind

• Several deployments on one machine: taking turns on the default ports, or giving each its own.
• Growing a deployment: adding or removing chap-core, OCS, DHIS2 or models later.
• Taking over a chap-admin deployment: moving a server that runs chap-core’s compose files and chap-admin to chap-devops, with its database.

Which commands work where

Chap with forecasting models

The default, and what most deployments are: chap-core plus the models it runs.

chap-devops init mychap --models chapkit_simple_multistep_model
cd mychap
chap-devops up
chap-devops status                 # chap-core up, every model registered
chap-devops models test --all      # make each model train and predict once

It worked when chap-devops status shows chap-core up and every model registered:

chap-core   up   http://localhost:8700   2.4.0   auth: off

MODEL                           STATE                       REACH          LAST PING
chapkit-simple-multistep-model  registered, not configured  via chap-core  1s ago

1 model registered
chapkit-simple-multistep-model: chap-core has no configured model for it, so nothing can run it; run `chap-devops models configs sync`

and chap-devops models test --all says every model passes:

testing 1 model (model level; add --backtest to go through chap-core)
chapkit-simple-multistep-model    pass    5s   1 training, 1 prediction

1 of 1 model passes

registered, not configured is the normal state after a plain chap-devops up. chap-core v2.4.0 makes no configured model when a model registers, and the model level of chap-devops models test does not need one. A backtest and the Modeling App need one. The backtest below creates them, and so do chap-devops models configs sync and chap-devops up --wait. After that, chap-devops status shows the model as registered. See Configured models.

You get chap-core’s API on port 8700 and one service per model. The models register with chap-core over the compose network and publish no host port. You reach them through chap-core at http://localhost:8700/v2/services/<service_id>/run/.

To change the models later, use chap-devops ui, or chap-devops models enable ID and chap-devops models disable ID. disable stops the model at once. After enable, run chap-devops up to start the model.

Every model in the marketplace

all is every model the marketplace lists (starters aside), and a list of ids picks some. chap-devops models list prints them. Without --models, init enables no model.

This is a new deployment. It needs port 8700 too. If the deployment from the first section is still up, go to mychap and run chap-devops down --volumes --yes first, then cd ... chap-devops init then warns that mychap also uses port 8700. While mychap is down, you can ignore that warning.

chap-devops init allmodels --models all
cd allmodels
chap-devops up
chap-devops status                 # again, until every model is registered
chap-devops models test --all      # make each model train and predict once

The model images are large: four images of 1 to 7 GB each, all linux/amd64 only. chap-devops init already pulls one of them to read its user, and says asking ghcr.io/chap-models/chapkit_ghr_model:sha-dfb2e3f what uid `app` is (this pulls the image). The first chap-devops up pulls the others, which can take many minutes.

chap-devops up returns before the models register. Right after it, chap-devops status can show some or all models as not registered yet, and exits with 1:

MODEL                             STATE                    REACH          LAST PING
auto-arima-chapkit                running, not registered  via chap-core  -
...
chapkit-simple-multistep-model    running, not registered  via chap-core  -

4 of 4 models are not registered.
auto-arima-chapkit: started under two minutes ago and registers once it is ready; run `chap-devops status` again in a minute
...

If you see this, wait a minute and run chap-devops status again. On an M2 Max, all four models registered in less than a minute. It worked when chap-devops status ends with all 4 models registered, followed by one chap-core has no configured model for it line for each model, as in the first section. chap-devops models test --all then says:

testing 4 models (model level; add --backtest to go through chap-core)
auto-arima-chapkit                  pass   10s   1 training, 1 prediction
chapkit-ghr-model                   pass   24s   1 training, 1 prediction
chapkit-rwanda-malaria-bym-model    pass   20s   1 training, 1 prediction
chapkit-simple-multistep-model      pass    6s   1 training, 1 prediction

4 of 4 models pass

On an Apple Silicon Mac the models run under emulation; the four tests above took about 60 seconds on an M2 Max.

Test through chap-core

chap-devops models test --all --backtest tests each model through chap-core, the way the Modeling App does. It makes a dataset from the sample data of the model, runs a backtest on it and reads the scores. A backtest needs a configured model, so the command first creates the configured models from the marketplace entry of each model, as chap-admin install does. You make no API call yourself.

chap-devops models test --all --backtest

It worked when every model passes with its scores, and the closing lines name the configured models it created:

testing 4 models (through chap-core: a dataset, a backtest and its scores)
auto-arima-chapkit                  pass      18s   crps 3.4  mae 4.9  rmse 5.8
  configured model: monthly (id 14)
chapkit-ghr-model                   pass   1m 33s   crps 14.7  mae 21.8  rmse 23.8
  configured model: monthly_climate (id 15)
chapkit-rwanda-malaria-bym-model    pass      38s   crps 16.3  mae 21.5  rmse 26.5
  configured model: monthly (id 16)
chapkit-simple-multistep-model      pass      13s   crps 3.9  mae 5.3  rmse 6.8
  configured model: monthly_climate (id 17)

created configured models in chap-core for auto_arima_chapkit (monthly), chapkit_ghr_model (monthly_climate), chapkit_rwanda_malaria_bym_model (monthly), chapkit_simple_multistep_model (monthly_climate, monthly_selfhistory)
4 of 4 models pass

The four backtests took about three minutes on an M2 Max. The scores are not the same from one run to the next. A second run creates no configured models, so it has no created configured models line. After the first run, chap-devops status shows each model as registered.

Next: Models and the marketplace, Authentication before you put it on a network, Backup and restore.

All shapes: Use cases.

Chap with climate data from OCS

chap-core with an Open Climate Service beside it, so Chap has climate data to fetch from inside the same deployment.

chap-devops init mychap --models chapkit_simple_multistep_model --with ocs,s3
cd mychap
chap-devops up
chap-devops status                 # chap-core, ocs and s3 lines, then the models

The first chap-devops up pulls the images that are not on the machine yet: the chap-core images, the model image and the OCS image. The OCS image alone is about 3 GB on disk. With the chap-core and model images already present, the first chap-devops up took about a minute in one test run. It ends with one line:

started chap, chapkit-simple-multistep-model, ocs, postgres, redis, s3, worker

chap-devops status then shows this:

chap-core   up   http://localhost:8700   2.4.0   auth: off
ocs         up   http://localhost:8790   0 datasets   32.0 KB data
s3          up   internal

MODEL                           STATE                       REACH          LAST PING
chapkit-simple-multistep-model  registered, not configured  via chap-core  1s ago

1 model registered
chapkit-simple-multistep-model: chap-core has no configured model for it, so nothing can run it; run `chap-devops models configs sync`

registered, not configured is the normal state after a plain chap-devops up. A backtest and the Modeling App need a configured model. Make them:

chap-devops models configs sync

chapkit_simple_multistep_model: created configured model monthly_climate
chapkit_simple_multistep_model: created configured model monthly_selfhistory

chap-devops up --wait does the same step for you. See Configured models. Now chap-devops status shows the model as registered:

MODEL                           STATE       REACH          LAST PING
chapkit-simple-multistep-model  registered  via chap-core  2s ago

1 model registered

chap-core reaches OCS at http://ocs:9000 on the compose network, and you reach it at http://localhost:8790. chap-devops does not configure chap-core to fetch from OCS. chap-core has no setting for it: the two run side by side, and you connect them. See OCS.

init writes ocs/climate-service.yaml, which is yours to edit. chap-devops changes only its read_only and plugins_dir keys. It also puts the data source credentials into .env, commented out. ERA5-Land needs one or both of a Copernicus Climate Data Store account and an Earth Data Hub account. WorldPop and CHIRPS3 need no account.

It worked when chap-devops status shows chap-core, ocs and s3 as up and each model as registered.

Climate data in and out

To put climate data in and get it out, see Ingesting a first dataset and the sections after it. The same commands work here. Three days of CHIRPS3 took between 10 and 40 seconds, and one year of monthly CHIRPS3 between 30 seconds and one minute.

The per-district CSV in Getting it out reads the districts from a DHIS2 on port 8780. This deployment has no DHIS2. Do one of these:

• Give geometries a GeoJSON FeatureCollection of your own districts. The feature ids become the location column.
• Add the demo DHIS2 with chap-devops components enable dhis2, then chap-devops up. chap-devops up returns while DHIS2 still starts. Run chap-devops status again until dhis2 shows up. See Growing a deployment.

The extent is Laos, like the demo DHIS2, until you change it. chap-devops doctor warns about this on its components line, and tells you how to change it. See ocs/climate-service.yaml.

Next: OCS, and Data source credentials for which dataset needs which account.

All shapes: Use cases.

Chap with a local DHIS2 and the Modeling App

A complete local setup: chap-core, its models, and a DHIS2 seeded from the demo database, connected so the Modeling App in DHIS2 talks to this Chap. For development, demos and training.

chap-devops init mychap --models chapkit_simple_multistep_model --with dhis2
cd mychap
chap-devops up                     # the first start of DHIS2 can take minutes
chap-devops status                 # wait until the dhis2 line says up, not starting
chap-devops dhis2 connect          # the route to chap-core, the apps, analytics
chap-devops open dhis2

The first chap-devops up on a machine pulls the images. The Chap images are about 6 GB to download (see Quickstart), and DHIS2 adds 1 to 1.5 GB. When the images are on the machine, up returns in seconds. DHIS2 then restores the Laos demo database and migrates its schema. On an arm64 Mac, the dhis2 line of chap-devops status said up less than a minute after up returned. Under emulation, this can take 8 to 15 minutes. chap-devops logs dhis2 shows the progress.

chap-devops up does not connect DHIS2 to Chap; chap-devops dhis2 connect does. Until it has run once, up ends with this line, and status shows a shorter form:

chap-devops has not connected this DHIS2 to Chap; run `chap-devops dhis2 connect` once DHIS2 answers

If DHIS2 is still starting, chap-devops dhis2 connect waits for it, for at most 20 minutes. It logs in as admin / district, makes the chap route, installs the two apps from the App Hub, and generates the analytics tables. That took about 40 seconds on the demo database:

DHIS2 2.42.6 at http://localhost:8780, as `admin`
repointed the `chap` route at http://chap:8000/**; chap-core answered through it
installed Modeling App 7.3.0
installed DHIS2 Climate App 1.16.2
analytics finished in 36 seconds (job Xx1SH9cHGCV)
the Modeling App can reach Chap; open DHIS2 with `chap-devops open dhis2`

The demo database has a chap route already, so connect repoints it at this chap-core. On an empty DHIS2, that line starts with created instead.

It worked when:

• chap-devops dhis2 connect ends with the Modeling App can reach Chap.
• chap-devops open dhis2 opens DHIS2 on http://localhost:8780. Log in with admin / district.
• Typing Modeling in the app menu (the grid icon at the top right) finds Modeling, and its Models page lists the models.

Next, in the Modeling App: Your first forecast in the Modeling App evaluates a model on the demo data and makes a forecast with it.

To remove the deployment and its data, run chap-devops down --volumes --yes in mychap.

Another DHIS2 version

chap-devops init chap243 --models chapkit_simple_multistep_model --with dhis2 --dhis2-tag 2.43
chap-devops init chap241 --models chapkit_simple_multistep_model --with dhis2 --dhis2-tag 2.41
chap-devops init chapdev --models chapkit_simple_multistep_model --with dhis2 --dhis2-image dhis2/core-dev --dhis2-tag master

Each line makes a new deployment. If the directory already exists, init stops with already contains a chap-devops deployment; choose another directory, or use --force to overwrite it. Use a different name.

The deployments use the same ports (8700 and 8780), so only one of them can be up at a time. If another deployment is up, init tells you, for example:

warning: port 8780 is already in use on this machine (needed by dhis2); free it, or run `chap-devops components enable dhis2 --port 8781`

Before you start the new deployment, run chap-devops down in the old one.

The Laos climate demo database exists for 2.42 only, so these start with an empty DHIS2. init tells you so:

warning: chap-devops knows no DHIS2 demo dump for 2.43, so `dhis2_db` starts empty; name one with `seed:` in `.chap-devops/components.yaml` (a URL or a path) and run `chap-devops sync`

An empty DHIS2 still has the admin / district login, and dhis2 connect works the same. An empty DHIS2 has no data for the Modeling App to evaluate a model on.

Do not seed them with DHIS2’s Sierra Leone demo when you want Chap connected. Its admin is not a superuser, and dhis2 connect stops at the route:

error: DHIS2 refused to write the `chap` route as `admin` (HTTP 403, "You don't have the proper permissions to create this object."): that needs the F_ROUTE_PUBLIC_ADD authority; add it to one of that user's roles in DHIS2 (Users, User role), or name a superuser with `--user NAME`

See Picking the version and Picking the data in A DHIS2 on its own.

Next: DHIS2, especially Connecting the Modeling App to Chap and Memory.

All shapes: Use cases.

Chap for a DHIS2 that runs elsewhere

chap-core and its models on a server, used by an existing DHIS2 instance.

chap-devops init mychap --models chapkit_simple_multistep_model --api-token
cd mychap
chap-devops up                     # returns when the containers start
chap-devops status                 # run it again until the chap-core line says up
chap-devops dhis2 use https://dhis2.example.org --chap-url https://chap.example.org
chap-devops dhis2 connect

Replace the two URLs in chap-devops dhis2 use:

• https://dhis2.example.org is the URL of the DHIS2, as this machine reaches it.
• https://chap.example.org is the address of chap-core, as the DHIS2 server reaches it. The route points there.

--api-token protects chap-core’s API from the start. dhis2 use records the external DHIS2 and the address it reaches chap-core at. connect then creates the chap route on that DHIS2, or points an existing chap route at this chap-core. It puts chap-core’s token in the route, so the Modeling App reaches chap-core and never holds the token itself.

The first chap-devops up on a machine pulls the images: about 6 GB to download and about 20 GB on disk (see Quickstart). When the images are on the machine, up returns in seconds, and chap-core answers some seconds later.

The credentials

chap-devops has no default login for a DHIS2 it did not deploy. So the first chap-devops dhis2 use ends with this warning, and chap-devops dhis2 connect stops with the same text as an error::

warning: chap-devops has no credentials for this DHIS2, and did not deploy it, so there is no default to try; set `DHIS2_ADMIN_USERNAME` and `DHIS2_ADMIN_PASSWORD`, or `DHIS2_API_TOKEN`, in `.env`

.env has these three lines as comments at its end. To give chap-devops a login:

1. Remove the # from DHIS2_ADMIN_USERNAME and DHIS2_ADMIN_PASSWORD, and set the values of a DHIS2 superuser. Or set DHIS2_API_TOKEN to a personal access token of that user.
2. Run chap-devops dhis2 use again. Its login line ends with (accepted).
3. Run chap-devops dhis2 connect.

See The credentials.

What connect changes

On a DHIS2 that chap-devops does not run, connect changes the route and nothing else. The admin of that DHIS2 decides about the other two steps:

• chap-devops dhis2 apps installs the Modeling App and the Climate App.
• chap-devops dhis2 analytics generates the analytics tables. On a large instance this can take hours.

For a DHIS2 2.42 that has a chap route already and none of the apps, the first connect printed this:

external DHIS2 2.42.6 at https://dhis2.example.org, as `admin`
repointed the `chap` route at https://chap.example.org/**; chap-core answered through it
skipped: installing apps on a DHIS2 chap-devops does not run (the Modeling App is not installed, the Climate App is not installed); `chap-devops dhis2 apps` installs them if its admin agrees
skipped: generating analytics tables on a DHIS2 chap-devops does not run; `chap-devops dhis2 analytics` starts a run if its admin agrees
created configured models in chap-core for chapkit_simple_multistep_model (monthly_climate, monthly_selfhistory)
the Modeling App can reach Chap after the admin of this DHIS2 installs the Modeling App and the Climate App; `chap-devops dhis2 show` says when they are there

On a DHIS2 with no chap route, the second line starts with created. Only the first connect prints the created configured models line. It makes the configured models that the Modeling App lists.

It worked when:

• chap-devops dhis2 connect says chap-core answered through it.
• chap-devops dhis2 show lists the route as (healthy).
• When the two apps are installed, the last line of chap-devops dhis2 show and chap-devops dhis2 connect is the Modeling App can reach Chap; open DHIS2 with `chap-devops open dhis2` .
• The Models page of the Modeling App lists the models.

Until the admin installs the apps, chap-devops dhis2 show names each missing app on a missing: line.

If connect warns nothing answered through it, read the rest of the warning:

• If it says chap-core answers at, chap-core is up, but the DHIS2 server may not reach the --chap-url address. Set the correct address with chap-devops dhis2 use --chap-url URL. Then run chap-devops dhis2 connect again.
• If it says run `chap-devops status`, chap-core did not answer on this machine. Run chap-devops status.

See The route is there but nothing answers through it.

Until connect gets an answer from chap-core through the route, chap-devops up ends with this line:

chap-devops has not connected this DHIS2 to Chap; run `chap-devops dhis2 connect` once DHIS2 answers

On a DHIS2 that chap-devops does not run, the route is all that connect changes. So when chap-core answers through the route, connect records the connect in .chap-devops/components.yaml, and the line stops. The apps do not have to be installed for this.

The address of chap-core

--chap-url is the address at which the DHIS2 server reaches this machine:

• A DHIS2 on another server needs the name or IP address of this machine.
• localhost works only for a DHIS2 that runs directly on this machine. chap-devops dhis2 use warns about it.
• A DHIS2 in Docker on this machine uses http://host.docker.internal:8700.

chap-devops serves chap-core over http on port 8700. An https:// address needs a reverse proxy in front of it. If you use http://SERVER:8700, the DHIS2 admin must add that origin, with no path, to route.remote_servers_allowed in the dhis.conf of the DHIS2 server (DHIS2 2.42 and later).

Try it on one machine

A second chap-devops deployment can be the external DHIS2. It uses port 8790, so it does not conflict with chap-core. Start it before chap-devops dhis2 use. Run these commands in the directory that holds mychap, not in mychap:

chap-devops init ext-dhis2 --only dhis2 --dhis2-port 8790
cd ext-dhis2
chap-devops up
chap-devops status                 # run it again until the dhis2 line says up

DHIS2 answers after about a minute on a fast machine, and after some minutes on a slow one.

In mychap, use chap-devops dhis2 use http://localhost:8790 --chap-url http://host.docker.internal:8700. In The credentials, use the demo login admin / district. The demo database has a chap route already, so connect says repointed.

This DHIS2 is yours, so you are its admin. In mychap, chap-devops dhis2 apps installs the two apps in about ten seconds.

To remove the two deployments and their data, run chap-devops down --volumes --yes in mychap and in ext-dhis2.

Next: A DHIS2 that runs elsewhere, Authentication.

All shapes: Use cases.

An OCS server on its own

Open Climate Service and no Chap at all: a climate data server for anything that speaks STAC or openEO.

chap-devops init climate --only ocs,s3
cd climate
chap-devops up
chap-devops status
chap-devops open ocs

The first chap-devops up pulls the OCS image, about 3 GB. After that, a start takes some seconds. chap-devops status then shows:

ocs   up   http://localhost:8790   0 datasets   32.0 KB data
s3    up   internal

both components are up

You get OCS on http://localhost:8790, with the S3-compatible store beside it. OCS does not read the store yet: it keeps its data on its own ocs_data volume (The object store says why the store is there). Nothing Chap-specific is created: no compose.yml, and no chap-core release is looked up. It worked when chap-devops status shows ocs as up and chap-devops open ocs opens its web interface.

To leave out the object store, use this init instead of the first one. OCS works the same, on the same volume:

chap-devops init climate --only ocs

Ingesting a first dataset

CHIRPS3 rainfall is public and needs no account. Three days of it, over the instance’s extent:

curl -X POST http://localhost:8790/ingestions \
  -H 'Content-Type: application/json' \
  -d '{"dataset_id": "chirps3_precipitation_daily", "start": "2024-01-01", "end": "2024-01-03", "publish": true}'
curl http://localhost:8790/stac/collections/chirps3_precipitation_daily

The first command waits until the data is in, about 20 seconds. It worked when it answers with "status":"completed" and the second returns the collection; chap-devops status then counts one dataset:

ocs   up   http://localhost:8790   1 dataset   424.0 KB data

The data size can be a little different on your machine.

The extent is Laos until you change it, the country of the DHIS2 demo database chap-devops seeds, so data ingested here covers the provinces that DHIS2 holds case data for. Change it in ocs/climate-service.yaml, or at init with --ocs-name, --ocs-country and --ocs-bbox; curl http://localhost:8790/extent shows the one in use.

Which datasets there are

curl http://localhost:8790/data-sources

lists every data source OCS knows, and "ingestable": true marks the ones /ingestions takes. The ones Chap models use:

Data source credentials says where the two accounts go.

A range worth forecasting with

start and end are written in the dataset’s own period: YYYY-MM-DD for a daily one, YYYY-MM for a monthly one and YYYY for a yearly one. Six years of monthly rainfall, the years the demo DHIS2 has cases for:

curl -X POST http://localhost:8790/ingestions \
  -H 'Content-Type: application/json' \
  -d '{"dataset_id": "chirps3_precipitation_monthly", "start": "2019-01", "end": "2024-12"}'

The request waits until the ingestion is complete. For Laos that took between two and eleven minutes, as the download speed changes, and curl shows nothing in that time. With -H 'Prefer: respond-async' it answers 202 at once instead, with a Location of /ingestions/jobs/ID to poll. Leaving out end ingests up to the current period, and sending the same request again answers at once with the earlier ingestion rather than downloading it twice. curl 'http://localhost:8790/datasets?f=json' lists what has been ingested.

Getting it out

Values per district or province, as the CSV Chap reads: OCS averages the dataset over each area in a GeoJSON FeatureCollection whose feature ids become the location column. A DHIS2 hands out its org units in that shape, so with the demo DHIS2 beside OCS (chap-devops components enable dhis2, then chap-devops up; or --only ocs,s3,dhis2 at init, option 10 on the AI page). chap-devops up returns while DHIS2 still starts. Run chap-devops status again until dhis2 shows up, then run:

curl -u admin:district -o provinces.geojson \
  'http://localhost:8780/api/organisationUnits.geojson?level=2'
python3 - > request.json <<'PY'
import json
areas = json.load(open("provinces.geojson"))
print(json.dumps({"process": {"process_graph": {"agg": {
    "process_id": "aggregate_to_chap_csv",
    "arguments": {"dataset_id": "chirps3_precipitation_monthly",
                  "temporal_extent": ["2024-01-01", "2024-12-31"],
                  "geometries": areas, "method": "mean", "period_type": "month"},
    "result": True}}}}))
PY
curl -X POST http://localhost:8790/result \
  -H 'Content-Type: application/json' -d @request.json -o rainfall.csv

It worked when rainfall.csv starts with time_period,location,precip and has one row per province and month (216 for the 18 provinces over 2024). The values are what the dataset holds: CHIRPS3 is a rate in mm per day.

The whole grid over a bounding box, as NetCDF, for anything that reads it (xarray, QGIS, Panoply):

curl -X POST http://localhost:8790/result -H 'Content-Type: application/json' -o rainfall.nc -d '{
  "process": {"process_graph": {
    "load": {"process_id": "load_collection", "arguments": {
      "id": "chirps3_precipitation_monthly",
      "temporal_extent": ["2024-01-01", "2024-12-31"],
      "spatial_extent": {"west": 100.0, "south": 13.9, "east": 107.7, "north": 22.5}}},
    "save": {"process_id": "save_result",
      "arguments": {"data": {"from_node": "load"}, "format": "NetCDF"}, "result": true}}}}'

GET /datasets/ID/download answers 409 for data OCS keeps in its default storage; /result is the way out. Both calls above still work on a read-only instance, which refuses ingestion but not reading.

As a server

Two settings matter once other people use it:

chap-devops components enable ocs --read-only                          # refuse writes over HTTP
chap-devops restart ocs                                                # apply read-only
chap-devops components enable ocs --base-url https://ocs.example.org   # behind a proxy
chap-devops up                                                         # apply the base URL

--read-only changes ocs/climate-service.yaml. OCS reads that file only when it starts, so the command tells you to restart it:

ocs is now read-only
run `chap-devops restart ocs` to apply

chap-devops up does not apply this change. It leaves OCS as it is, and it prints this warning on stderr. Until you run chap-devops restart ocs, chap-devops status shows the same warning:

warning: `ocs/climate-service.yaml` changed after the ocs container started, so ocs may still use the old settings; run `chap-devops restart ocs` to apply it

chap-devops restart ocs returns before OCS answers again. Run chap-devops status until ocs shows up. It worked when this answers 403:

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:8790/ingestions -d '{}'

A read-write OCS answers 422 to the same request. The base URL is different: it is in compose.ocs.yml, so chap-devops up applies it. --base-url says what it set:

enabled ocs on http://localhost:8790
set the ocs base URL to https://ocs.example.org
run `chap-devops up` to apply

If you give the same base URL again, nothing changes, and the command prints no chap-devops up line:

ocs was already enabled on http://localhost:8790; nothing changed

It worked when the links in curl http://localhost:8790/stac/catalog.json start with the base URL.

Both have init spellings too, --ocs-read-only and --ocs-base-url. A read-only instance refuses every ingestion over HTTP, so ingest first.

Next: Standalone OCS, Data source credentials, Read-only instances, Behind a reverse proxy.

All shapes: Use cases.

A DHIS2 on its own

A DHIS2 instance and its database, nothing else: for trying a DHIS2 version, developing an app, or restoring a database dump to look at it.

chap-devops init dhis --only dhis2
cd dhis
chap-devops up                     # returns when the containers start
chap-devops status                 # run it again until the dhis2 line says up
chap-devops open dhis2

You get DHIS2 on http://localhost:8780, with its own PostgreSQL, and no chap-core, OCS or models.

chap-devops up prints started dhis2, dhis2-db when the containers start. The first chap-devops up also pulls the images, about 2 GB on disk, and downloads the demo database, about 7 MB. DHIS2 then needs more time before it answers: less than a minute on a fast machine, several minutes on a slow one. Until then, chap-devops status shows this and exits with 1:

dhis2   starting   http://localhost:8780

1 of 1 component is still starting; run `chap-devops status` again in a moment

It worked when chap-devops status shows this, and the login admin / district works in the browser:

dhis2   up   http://localhost:8780

dhis2 is up

DHIS2 needs about 4 to 5 GB of memory; give Docker 8 GB or more.

Picking the version

--dhis2-tag picks the DHIS2 version, and --dhis2-seed what its database starts from:

Each command makes a new deployment dhis, and so do the commands in the next section. If dhis already exists, init stops with already contains a chap-devops deployment; choose another directory, or use --force to overwrite it. Use a different name.

A full version such as --dhis2-tag 2.42.6 works too. chap-devops has a demo database for 2.42 only, so 2.42 and every 2.42.x get it. Every other version starts empty, and init tells you so:

warning: chap-devops knows no DHIS2 demo dump for 2.43, so `dhis2_db` starts empty; name one with `seed:` in `.chap-devops/components.yaml` (a URL or a path) and run `chap-devops sync`

An empty DHIS2 still has the admin / district login, as a superuser. A version that is not on the machine yet adds a pull of 1 to 1.5 GB to the first chap-devops up.

Picking the data

chap-devops init dhis --only dhis2 --dhis2-seed none                  # empty, whatever the version
chap-devops init dhis --only dhis2 --dhis2-seed dumps/mine.sql.gz     # your own dump, a path
chap-devops init dhis --only dhis2 --dhis2-seed dumps/mine.sql.gz \
  --dhis2-seed-password                                         # every user logs in with district
chap-devops init dhis --only dhis2 --dhis2-tag 2.43 \
  --dhis2-seed https://databases.dhis2.org/sierra-leone/2.43/dhis2-db-sierra-leone.sql.gz

A relative path is relative to the deployment directory, not to the directory you run init in. For the commands above, put the dump at dhis/dumps/mine.sql.gz before chap-devops up. Until the dump is there, init tells you:

warning: the dhis2 seed names dumps/mine.sql.gz, which is not in /path/to/dhis; copy the dump there before `chap-devops up`, or run `chap-devops components enable dhis2 --seed none`

The seed is applied once, when the database is first created; after that the database is DHIS2’s. DHIS2’s Sierra Leone demo is published for 2.41, 2.42 and 2.43 at that address pattern, and the first chap-devops up downloads about 90 MB for it. It has no climate data, and its admin is not a superuser: it cannot create the route the Modeling App uses, so pick it for a DHIS2 on its own, not for one you will connect to Chap.

A dump of a real DHIS2 keeps the passwords of its users. --dhis2-seed-password gives every user the password district, turns on every account and turns off two-factor login, so you can log in as any of them. See One password for every user.

Next

chap-devops dhis2 connect refuses here, since there is no chap-core to connect to:

error: chap-core is not a component of this deployment, so the route would point at a service that is not there; run `chap-devops components enable chap-core` first

chap-devops dhis2 show works here. Its target row says none (this deployment has no chap-core), and it names no chap-devops dhis2 connect. When the apps or the analytics tables are missing, its last line is:

run `chap-devops dhis2 apps` for the apps, then `chap-devops dhis2 analytics` for the analytics tables; the `chap` route needs chap-core; `chap-devops components enable chap-core` adds it

chap-devops components enable chap-core adds one, then chap-devops up starts it, and Chap with a local DHIS2 is that shape from the start. More: The seed, Changing the DHIS2 version, Memory.

All shapes: Use cases.

A chapkit model service on its own

One forecasting model, running and answering on its own port, with no chap-core in front of it. For developing or checking a model: calling its API directly, reading its /docs, running chapkit test against it, or putting it behind something other than chap-core.

The quickest way needs no folder at all:

chap-devops run chapkit_simple_multistep_model                    # a marketplace model
chap-devops run https://github.com/chap-models/chapkit_ghr_model  # by repository
chap-devops run ghcr.io/my-org/chapkit_dengue_model:sha-1eb8cf1   # by image: use your own
chap-devops ps
chap-devops stop chapkit_simple_multistep_model
chap-devops stop --all

The image line is an example: my-org does not publish it, so that chap-devops run stops with chapkit-dengue-model did not start: the registry answered `denied`. Put an image of your own there. See did not start: the registry answered denied.

Each of the other two commands prints a starting line, and one more line when the model answers:

starting chapkit-simple-multistep-model (chapkit_simple_multistep_model in ~/.local/share/chap-devops/run/default)
running chapkit_simple_multistep_model on http://localhost:5001 (answered in 4s)

chap-devops prints the full path of the group. The docker compose progress goes to stderr between the two lines. The repository line also says on stderr that the URL is the marketplace model chapkit_ghr_model, and it answers on http://localhost:5002.

chap-devops run keeps the model in a group under chap-devops’s data directory, publishes it on 127.0.0.1 only, and returns once it answers. A first run pulls the model image, and the pull can take some minutes. On disk, the image of Simple Multistep is about 1 GB, and the image of GHRmodel about 7 GB. -a keeps it in the foreground with its log, until Ctrl-C stops it. chap-devops stop ID stops one model, and chap-devops stop --all stops every model that chap-devops run started. Both keep the data volume of each model. To remove the volumes and the groups too, add --purge. See Running one model.

For a deployment directory of your own, with chap-devops status, chap-devops doctor and everything else:

chap-devops init multistep --only none --models chapkit_simple_multistep_model
cd multistep
chap-devops up --wait
chap-devops status
curl http://localhost:5001/health
chap-devops open chapkit_simple_multistep_model

chap-devops up --wait returns once the model answers its own /health:

waiting up to 300s for the model to answer
started chapkit-simple-multistep-model
ready in 4s
  chapkit-simple-multistep-model  up  http://localhost:5001

Without --wait, chap-devops up returns when the container starts, and for some seconds chap-devops status says running, not answering. Then chap-devops status shows:

MODEL                           STATE  REACH      LAST PING
chapkit-simple-multistep-model  up     port 5001  -

1 model up, answering on its own host port

The curl command gets the same /health that chap-devops status asks:

{"status":"healthy","checks":{"database":{"state":"healthy"},"registration":{"state":"healthy"}}}

chap-devops open chapkit_simple_multistep_model opens the model’s API documentation, at http://localhost:5001/docs, in a browser. With --no-browser, it prints the address instead:

the model's API documentation is at http://localhost:5001/docs

chap-devops open with no name opens nothing. It lists the components and each model with a host port, with the address of its /docs.

Your own model works the same way, from its repository or a published image:

chap-devops init mymodel --only none
cd mymodel
chap-devops models add https://github.com/my-org/chapkit_dengue_model   # adds and enables it
chap-devops up --wait

Replace the URL with your model’s repository. The repository must publish a sha-<commit> image on ghcr, as the model repositories’ publish workflow does. If the URL names a repository that does not exist, chap-devops models add stops with GitHub has no repository my-org/chapkit_dengue_model, or it is private. The chap-devops up --wait after it then says nothing to start. A repository that the marketplace lists is enabled as that marketplace model; add --id NAME to keep an entry of your own beside it. See Models outside the marketplace.

Without chap-core each model gets a host port when it is enabled (the first free one from 5001; --port N picks one), does not try to register anywhere, and is judged by chap-devops status and chap-devops doctor through its own /health. Near the start of its log, after Application startup complete, expect one registration.missing_orchestrator_url line at error level and a registration.skipped line. servicekit has nothing to register with, and the model continues to serve. See registration.missing_orchestrator_url in a model’s log.

chap-devops models test chapkit_simple_multistep_model (or --all) works here: it runs chapkit test inside the model’s own container:

testing 1 model (model level; add --backtest to go through chap-core)
chapkit-simple-multistep-model    pass    5s   1 training, 1 prediction

1 of 1 model passes

chap-devops models test --backtest and chap-devops jobs go through chap-core, so they refuse and name chap-devops components enable chap-core.

Next: Model services without chap-core, Models outside the marketplace.

All shapes: Use cases.

Several model services side by side

Two or more chapkit model services in one deployment directory, with no chap-core. Each model gets its own host port and its own data volume, and the models do not depend on each other. For one model, see A chapkit model service on its own.

chap-devops init models --only none --models chapkit_simple_multistep_model,auto_arima_chapkit
cd models
chap-devops up --wait
chap-devops status
chap-devops models list --enabled  # the PORT column says where each one answers

chap-devops init gives each model the next free port from 5001 up, and prints it:

created a deployment in /path/to/models
components: none
enabled chapkit_simple_multistep_model v0.1.2 on http://localhost:5001
enabled auto_arima_chapkit v1.0.2 on http://localhost:5002
run `cd /path/to/models && chap-devops up` to start the deployment

A first chap-devops up pulls the model images. On disk, the image of Simple Multistep is about 1 GB, and the image of Auto-ARIMA about 6 GB. The pull can take some minutes. The images are amd64 only, so on an arm64 machine they run under emulation.

chap-devops up --wait returns once each model answers its own /health. Without --wait, chap-devops up returns when the containers start, and for some seconds chap-devops status can say running, not answering. After compose’s own lines, chap-devops up --wait ends with:

waiting up to 300s for the 2 models to answer
started auto-arima-chapkit, chapkit-simple-multistep-model
ready in 4s
  auto-arima-chapkit              up  http://localhost:5002
  chapkit-simple-multistep-model  up  http://localhost:5001

Then chap-devops status shows:

MODEL                           STATE  REACH      LAST PING
auto-arima-chapkit              up     port 5002  -
chapkit-simple-multistep-model  up     port 5001  -

all 2 models up, each answering on its own host port

It worked when chap-devops status shows every model as up, each on its own port. Each model answers on http://localhost:<port>, with its API documentation at /docs. The ids for --models are in the ID column of chap-devops models list. That command also works outside a deployment directory.

Compose publishes these ports on every address of the machine, and the models have no login. To keep a model on this machine only, see Which address a model port is published on.

Without a folder, chap-devops run does the same one model at a time: Any number of model services, no folder.

All shapes: Use cases.

Any number of model services, no folder

One chapkit model or ten, each answering on its own port, with no chap-devops init, no deployment directory and no chap-core. For calling models’ APIs directly, comparing several side by side, or a tool (a UI, a notebook, a test harness) that only needs “start this model and tell me where it answers”.

From any directory that is not a deployment:

chap-devops run chapkit_simple_multistep_model
chap-devops run auto_arima_chapkit
chap-devops run https://github.com/chap-models/chapkit_ghr_model
chap-devops ps                     # every model, its state and its URL

Each chap-devops run returns once the model answers on its /health and prints where it answers. Between the two lines, docker compose shows its progress:

starting chapkit-simple-multistep-model (chapkit_simple_multistep_model in /home/me/.local/share/chap-devops/run/default)
...
running chapkit_simple_multistep_model on http://localhost:5001 (answered in 4s)

The first run of a model pulls its image. A marketplace model image is several gigabytes, so this can take many minutes; a later run starts in seconds.

The GitHub URL above is a model that the marketplace lists. Before the starting line, chap-devops says so, then reads the user of the image (this pulls the image), and then starts that marketplace model:

https://github.com/chap-models/chapkit_ghr_model is the marketplace model chapkit_ghr_model; enabling that (pass `--id <other>` to add it beside it instead)
asking ghcr.io/chap-models/chapkit_ghr_model:sha-dfb2e3f what uid `app` is (this pulls the image)

Each model gets the next free port from 5001 up, its own container and its own data volume, published on 127.0.0.1 only. The models do not depend on each other. A marketplace id, a GitHub repository URL, a ghcr image and a local name:tag are all accepted; see Running one model.

It worked when chap-devops ps lists every model as up, each with its own URL:

GROUP    ID                              SERVICE                         STATE  URL
default  auto_arima_chapkit              auto-arima-chapkit              up     http://localhost:5002
default  chapkit_ghr_model               chapkit-ghr-model               up     http://localhost:5003
default  chapkit_simple_multistep_model  chapkit-simple-multistep-model  up     http://localhost:5001

chap-devops top shows the same, live.

Starting many at once

--no-wait returns as soon as the container starts, so a whole set can start in parallel. Runs into the same group take turns where they have to and never step on each other; a run that waits for its turn says another chap-devops command is changing this deployment; waiting for it to finish.

for m in chapkit_simple_multistep_model auto_arima_chapkit chapkit_ghr_model; do
  chap-devops run "$m" --no-wait &
done
wait
chap-devops ps                     # `running, not answering` until each one is ready

With --no-wait, each run prints started in place of running. The runs take their turns in no fixed order, so the ports can go to the models in a different order each time. Read each URL from chap-devops ps or from --json.

Running a model that already runs starts nothing new: it reports the same id and port. A repository or image you ran before is that same model again, not a copy; --id auto adds a second copy beside it when you want one. A run by the GitHub URL of a marketplace model works as a run by its id: the second run does not read the image again, recreate the container, or move the port.

Keeping sets apart: groups

Without a folder, chap-devops keeps the models in a group under its data directory, default unless you name one. A group per experiment keeps sets apart, and every group can be listed and stopped on its own:

chap-devops run chapkit_simple_multistep_model --group dengue
chap-devops run auto_arima_chapkit --group dengue
chap-devops run chapkit_simple_multistep_model --group malaria   # one more, separate copy
chap-devops ps --group dengue

GROUP   ID                              SERVICE                         STATE  URL
dengue  auto_arima_chapkit              auto-arima-chapkit              up     http://localhost:5005
dengue  chapkit_simple_multistep_model  chapkit-simple-multistep-model  up     http://localhost:5004

The same model in two groups is two containers with two ports and two data volumes. Group names are lowercase letters, digits, - and _.

A group is an ordinary chap-devops deployment that chap-devops keeps for you, so the other commands reach it with -C. The starting line of chap-devops run names the group directory, and chap-devops -v run prints the full log command:

chap-devops -C ~/.local/share/chap-devops/run/dengue logs chapkit-simple-multistep-model

The path is the default data directory; $CHAP_DEVOPS_DATA_DIR or $XDG_DATA_HOME moves it (Where it runs: groups).

For a group that does not exist, chap-devops ps --group says there is no `chap-devops run` group X; `chap-devops ps` lists every group.

From a script

Under --json each command prints one JSON document on stdout, and docker’s progress goes to stderr:

chap-devops --json run chapkit_simple_multistep_model --group dengue

The fields a tool needs are url, port, id, group and project_dir; a failure is {"ok": false, "error": ..., "hint": ...} with a non-zero exit. See Running one model for every field and --json for scripts and tools.

Stopping

chap-devops stop chapkit_ghr_model                                # one model, in whichever group has it
chap-devops stop chapkit_simple_multistep_model --group malaria   # one model in one group
chap-devops stop --group dengue                                   # every model in one group
chap-devops stop --all                                            # every model in every group
chap-devops stop --group dengue --purge                           # and its data, and the group itself

An id alone works only when one group has that model. After the steps above, chapkit_simple_multistep_model runs in three groups, so chap-devops stop chapkit_simple_multistep_model stops nothing and says:

error: chapkit_simple_multistep_model runs in the groups default, dengue, malaria; name one with `--group default`

A stop keeps the model’s data volume, so the next chap-devops run of it continues with the same data. The port can be a different one. --purge deletes the data too, and removes a group it leaves empty: its network, its directory and every volume it had, including those of models stopped earlier. To remove every group and all its data, use chap-devops stop --all --purge.

In the order above, dengue has no running model when --purge comes, so chap-devops says:

nothing was running to stop
removed group dengue

chap-devops -v stop also names each volume that it removed.

When a folder is the better fit

If you often reach a group with -C, or want chap-core, OCS or DHIS2 next to the models, use a folder of your own instead: Several model services side by side.

To reach the models from other machines, start them with --bind 0.0.0.0.

All shapes: Use cases.

A new model of your own

For starting a new forecasting model: chap-devops models new makes the project, Docker builds its image, and a chap-devops deployment trains it, predicts with it and scores it through chap-core. Python, uv, R and the chapkit CLI are not necessary on the machine.

Make the project

chap-devops models new dengue-lags

created dengue-lags in dengue-lags (fn-py template, service id dengue-lags)
next: build the image as `dengue-lags/README.md` says, then run `chap-devops run dengue-lags:dev`

The default type, fn-py, is a chapkit service with the model in Python, in main.py. For a model in R scripts, add --template shell-r. For a model in the MLproject format, use --template mlproject-py or --template mlproject-r. The types lists all nine.

The example model predicts, for each location, the mean of disease_cases in the last window periods. Replace it with your model. README.md in the project lists the files to change.

Build the image

In the project:

cd dengue-lags
git init && git add . && git commit -m "feat: first version"
docker build --platform linux/amd64 --build-arg GIT_REVISION=$(git rev-parse HEAD) -t dengue-lags:dev .
cd ..

chap-core stores a model only if the image has a git revision, so build from a commit with GIT_REVISION. The first build pulls the base image, ghcr.io/dhis2-chap/chapkit-py. A rebuild takes some seconds.

Run it with chap-core

chap-devops init lab --models none
cd lab
chap-devops models add dengue-lags:dev
chap-devops up --wait
chap-devops status

chap-devops up --wait returns when the model has registered, and it creates the configured model default. chap-devops status then shows:

chap-core   up   http://localhost:8700   2.4.0   auth: off

MODEL        STATE       REACH          LAST PING
dengue-lags  registered  via chap-core  3s ago

1 model registered

Test it through chap-core

chap-devops models test dengue_lags --backtest --seed 7

testing 1 model (through chap-core: a dataset, a backtest and its scores)
dengue-lags    pass      16s   crps 35.5  mae 35.5  rmse 38.8
  configured model: default (id 14)

1 of 1 model passes

The test makes a dataset from the model’s own sample data, runs a backtest in chap-core, and prints its scores. --seed makes the data the same on every run, so two runs can be compared.

Give an option another value

window is an option of the model, with 3 as the default. A configured model gives it another value:

chap-devops models configs add dengue_lags --name long --set window=6
chap-devops models test dengue_lags --backtest --seed 7 --config long

created configured model long of dengue_lags
testing 1 model (through chap-core: a dataset, a backtest and its scores)
dengue-lags    pass      13s   crps 41.4  mae 41.4  rmse 43.2
  configured model: long (id 15)

1 of 1 model passes

The Modeling App shows long as a model to pick, next to default. See Configured models.

After a change

chap-core stores each version of a model only once. If you build a new commit under the same version, the model registers, but its backtests fail:

dengue-lags    FAIL       8s   ValueError: Model template 'dengue-lags' version '0.1.0' is stored from revision 'db139b6b09185e0be0971d31cafb39f126c910...

So, before you build again, raise version in main.py (in MLproject for an MLproject type), for example to 0.1.1. Then commit, and build with the same docker build line. In lab:

chap-devops restart
chap-devops models test dengue_lags --backtest --seed 7

dengue-lags    pass      13s   crps 39.5  mae 39.5  rmse 42.3
  configured model: default (id 16)

created configured models in chap-core for dengue_lags (default)
1 of 1 model passes

In this run, the change was window: int = 4 in main.py, so the score is different. The backtest created the configured model default of version 0.1.1. A configured model belongs to one version, so long is not there for 0.1.1: add it again with chap-devops models configs add.

To run the model service alone, with no deployment: chap-devops run dengue-lags:dev. To publish the image, push the project to GitHub: the workflow in .github/workflows/publish.yml builds it and publishes it to GHCR. Then chap-devops models add takes the repository URL, as in Models outside the marketplace.

These lines come from chap-devops 0.101.0 with this change, chap-core 2.4.0 and chapkit 2.3.1 on macOS (arm64, the image under amd64 emulation), on 2026-10-08.

More: A new model project.

All shapes: Use cases.

An MLproject model, with no image to build

For a model in the MLproject format: a directory with an MLproject file and the train and predict scripts. chap-devops chapkit mlproject run serves it as a chapkit service from the directory, so you can evaluate it, test it through chap-core and change it without a docker build. When the model is ready, chap-devops chapkit mlproject migrate makes it a chapkit service with an image of its own, and chap-devops chapkit mlproject export goes the other way. Python, uv, R and the chapkit CLI are not necessary on the machine.

mlproject run uses chapkit images of its own, so it works with chap-core v2.4.0 and later. export, --run-config.as-chapkit and the up-to-date migrate need chapkit 2.4.0 in the chap-core image, which chap-core v2.5.0 has.

Make or bring the model

A model from chap-models, or your own, works as it is. For a new one:

chap-devops models new rain-model --template mlproject-r
cd rain-model
git init && git add . && git commit -m "feat: first version"
cd ..

created rain-model in rain-model (mlproject-r template, service id rain-model)
next: run `chap-devops chapkit mlproject run rain-model` to serve it with no build, or build the image as `rain-model/README.md` says

For Python, use --template mlproject-py. The commit is not necessary to serve the model, but chap-core stores a model only with a git revision. See In a deployment.

Serve it

chap-devops chapkit mlproject run rain-model

serving /home/me/rain-model with `chapkit mlproject run` in ghcr.io/dhis2-chap/chapkit-r-tidyverse-cli:latest (from the train command `Rscript scripts/train.R --data {train_data} --model {model} --config {model_config}`; --image picks another)
starting it on http://localhost:5001; the logs follow, and Ctrl-C stops it
the MLproject service answers at http://localhost:5001

It worked when the last line says the MLproject service answers at. The service runs in the foreground, and the logs of chapkit follow. Leave it running, and use a second terminal for the next steps. Ctrl-C stops it:

stopped the MLproject service on http://localhost:5001

The train command selects the image: python or uv gets py-data, and Rscript gets r-tidyverse. A model that needs INLA gets --image r-inla. To see the images, run chap-devops chapkit --image:

NAME         IMAGE                                              PLATFORMS     LOCAL  WHAT IT HAS
py           ghcr.io/dhis2-chap/chapkit-py-cli:latest           amd64, arm64  yes    Python
py-data      ghcr.io/dhis2-chap/chapkit-py-data-cli:latest      amd64, arm64  yes    Python, numpy, pandas, scipy, scikit-learn, statsmodels, ...
r            ghcr.io/dhis2-chap/chapkit-r-cli:latest            amd64, arm64  no     R, renv, pak
r-tidyverse  ghcr.io/dhis2-chap/chapkit-r-tidyverse-cli:latest  amd64, arm64  yes    R, tidyverse, fable, tsibble, forecast, xgboost, ...
r-inla       ghcr.io/dhis2-chap/chapkit-r-inla-cli:latest       amd64         yes    R, tidyverse, INLA, sf, spdep, dlnm, ...

chap-devops does not install the packages that uv_env or renv_env names. If the model needs one that the image does not have, give an image that has it. See Serve an MLproject model.

Evaluate it

The chap CLI runs in a container, so it reaches the service at host.docker.internal, not at localhost:

chap-devops chap eval --model-name http://host.docker.internal:5001 \
  --dataset-csv laos_subset.csv --output-file rain-model.nc

model: http://host.docker.internal:5001 answers
chap finished; it wrote rain-model.nc
`chap-devops chap plot-backtest rain-model.nc --output-file rain-model.html` plots it

It worked when the line says chap finished; it wrote rain-model.nc. The data comes from Evaluating a model on your own data.

chap can also run the directory itself, without the service. With --run-config.as-chapkit, chap serves it with chapkit in its own container, and installs what uv_env or renv_env names:

chap-devops chap eval --model-name ./rain-model --run-config.as-chapkit \
  --dataset-csv laos_subset.csv --output-file rain-model.nc

In a deployment

In a deployment that runs chap-core, the service registers with chap-core, and the commands of the deployment use it by its id, the name in MLproject:

chap-devops init lab --models none
cd lab
chap-devops up --wait
chap-devops chapkit mlproject run ../rain-model

the MLproject service answers at http://localhost:5001; it registers with chap-core in this deployment, which reaches it at http://chap-devops-mlproject-18970-0:8000

In a second terminal, in lab:

chap-devops models configs sync rain-model
chap-devops models test rain-model --backtest

rain-model: created configured model default
testing 1 model (through chap-core: a dataset, a backtest and its scores)
rain-model    pass      13s   crps 31.4  mae 31.4  rmse 37.5
  configured model: default (id 21)

1 of 1 model passes

It worked when the last line says 1 of 1 model passes.

With DHIS2 in the deployment, the Modeling App shows the configured model while the service runs. Select model lists it by its name, with the commit that chap-devops gave chapkit:

An evaluation runs as for any other model. For rain-model, map only Disease cases, because the model has no covariates. See Your first forecast in the Modeling App. This was tested with Modeling App 7.3.0, DHIS2 2.42.6 and chap-core v2.5.0, after a chap-devops update from v2.4.0: the evaluation of the 18 provinces, 2019 to 2024, took 19 seconds.

chap-devops gives chapkit the git commit of the model directory, and chap-core stores the version of the model with it. After a change, commit it, and raise version in MLproject, before you serve the model again. If the directory has changes that are not committed, chap-devops warns.

chap-devops status lists the service as unmanaged, because chap-devops does not manage it:

MODEL                           STATE       REACH                                      LAST PING
chapkit-simple-multistep-model  registered  via chap-core                              11s ago
rm1                             unmanaged   http://chap-devops-mlproject-85595-0:8000  6s ago

Make it a chapkit service

When the model is ready to publish, make it a chapkit service with an image of its own. Commit first: the migration moves files to _old/. Then, in the model directory:

cd rain-model
chap-devops chapkit mlproject migrate . --yes
docker build --platform linux/amd64 --build-arg GIT_REVISION=$(git rev-parse HEAD) -t rain-model:dev .
chap-devops run rain-model:dev
chap-devops -C ~/.local/share/chap-devops/run/default models test rain_model

It worked when the last line says 1 of 1 model passes. chapkit finds the scripts in scripts/ through the train and predict commands, and picks the base image from them. chap-core v2.5.0 and older need --base-image. See Migrate an MLproject model.

And back to an MLproject

A chapkit service that runs scripts, such as one from the shell-py or shell-r template, can write the MLproject of the same model:

cd my-service
chap-devops chapkit mlproject export main.py -o MLproject
chap-devops chapkit mlproject run .

chapkit finished; it wrote MLproject

The exported MLproject runs with chap-devops chapkit mlproject run and with --run-config.as-chapkit, not with chap-devops chap alone. See Export a service as an MLproject.

What was tested

On chap-core master before v2.5.0 (chapkit 2.4.0), macOS arm64, each row was served with chap-devops chapkit mlproject run and evaluated with chap-devops chap eval. On v2.5.0, the mlproject-py template was migrated and tested again, and the shell-r template was exported, served and evaluated again, with no --tag:

Your model from its checkout, with Chap

For developing a chapkit model: chap-devops runs chap-core, and you run the model from its own checkout on this machine (with uv run, a debugger, hot reload), registered with that chap-core like any deployed model. Nothing about the model has to be built into an image.

chap-devops init mychap --models none
cd mychap
chap-devops up --wait
chap-devops status

chap-devops up --wait returns once chap-core answers. Without --wait, chap-devops up returns when the containers start, and for some seconds chap-devops status says starting. Then chap-devops status shows chap-core up and no models yet:

chap-core   up   http://localhost:8700   2.4.0   auth: off

no models enabled; run `chap-devops models enable ID` to add one

Start the model

Then, in the model’s checkout, start it on a port of its own and tell it where chap-core is and where chap-core can call it back:

export SERVICEKIT_ORCHESTRATOR_URL='http://localhost:8700/v2/services/$register'
export SERVICEKIT_HOST=host.docker.internal
export SERVICEKIT_PORT=8001
export GIT_REVISION=$(git rev-parse HEAD)
uv run uvicorn main:app --host 0.0.0.0 --port 8001

main:app is the app in a main.py at the top of the checkout, which is the layout chapkit models use; a model whose main.py is inside a package runs as PACKAGE.main:app instead. The first uv run in a checkout makes its .venv and installs the dependencies of the model.

• SERVICEKIT_ORCHESTRATOR_URL is where the model registers. It runs on this machine, so localhost and the API port reach chap-core. The single quotes keep the shell from reading $register as a variable.
• SERVICEKIT_HOST and SERVICEKIT_PORT are the address the model registers itself under, which is where chap-core calls it. chap-core runs in a container, where localhost is the container itself; host.docker.internal is this machine. The chap-core compose file maps that name for the chap-core containers on Linux too.
• GIT_REVISION is the commit the model reports as its git_revision. chap-core v2.4.0 stores the model template only for a service that reports a revision. Without it, the model registers, but chap-core has no template for it. chap-devops status warns: SERVICE_ID: it reports no git revision, so chap-core stores no model template for it; set `GIT_REVISION` where it runs, then start it again. chap-devops models configs sync fails with answered HTTP 409 Conflict and gives the same way out. The chap-core log (chap-devops logs chap) says is stored from revision None, but its source now reports revision None.
• --host 0.0.0.0 makes the model listen on more than the loopback, which is what a call from a container arrives on.

It worked when chap-devops status lists the model’s service id with a recent LAST PING. For the minimalist example in ~/dev/chap-models, the status is:

chap-core   up   http://localhost:8700   2.4.0   auth: off

MODEL                          STATE      REACH                             LAST PING
chapkit-minimalist-example-py  unmanaged  http://host.docker.internal:8001  7s ago

no models enabled here; the unmanaged one above registered from outside this deployment

Its state is unmanaged, because this deployment did not start it; that is expected.

chap-core stores one template for each model version, with the revision it had at the first registration. Changes you do not commit keep the revision, so hot reload needs nothing more. If you commit and export GIT_REVISION again, the revision changes. chap-core then refuses the backtest with is stored from revision '...', but its source now reports revision '...'. The backtest row shows the start of that reason, and chap-devops jobs logs JOB_ID shows all of it. chap-devops status warns: SERVICE_ID: chap-core stores its model template VERSION from another git revision and refuses to run it; set a new version in the model, then start it again. To continue:

1. Set a new version in the MLServiceInfo in main.py.
2. Start the model again.
3. Run chap-devops models configs sync SERVICE_ID again.

The configured model from before belongs to the old version, and chap-core does not run it. Without step 3, chap-devops status warns: SERVICE_ID: chap-core has configured models of it of other versions only, not of VERSION; run `chap-devops models configs sync SERVICE_ID`. The backtest skips with chap-core has no configured model for SERVICE_ID VERSION.

Test it through chap-core

The model level of chap-devops models test (chapkit test in a container) is for models that chap-devops runs. For this model, chap-devops models test SERVICE_ID skips, names --backtest, and exits with status 1:

testing 1 model (model level; add --backtest to go through chap-core)
chapkit-minimalist-example-py    skip    0s   chap-devops does not run it, so there is no container to test it in
  run `chap-devops models test chapkit-minimalist-example-py --backtest` to test it through chap-core

0 pass, 1 skipped
warning: no model was tested, because every one was skipped; the line under each row says why

A backtest uses a configured model: a template with a set of option values. chap-core v2.4.0 makes no configured model from a registered service, so make one. Replace SERVICE_ID with the id that chap-devops status shows:

chap-devops models configs sync SERVICE_ID
chap-devops models test SERVICE_ID --backtest

chap-devops models configs sync stores the template of the service and makes one configured model, default, with the defaults of the service. chap-core names it SERVICE_ID:

SERVICE_ID: created configured model default

If the model has options, or reads covariates that it does not declare, make the configured model through the API instead (this example uses jq):

TEMPLATE_ID=$(chap-devops api GET /v1/crud/model-templates | jq '.[] | select(.name == "SERVICE_ID") | .id')
chap-devops api POST /v1/crud/configured-models --data "{\"name\": \"dev\", \"modelTemplateId\": $TEMPLATE_ID, \"additionalContinuousCovariates\": [\"rainfall\", \"mean_temperature\"]}"

chap-core names that configured model SERVICE_ID:dev. Add the options as "userOptionValues". If the template id is empty, chap-core has no template for the model; make sure that GIT_REVISION was set when the model started. The backtest uses the configured model SERVICE_ID if there is one, and else SERVICE_ID:dev. To test dev when both exist, add --config dev. The line under the backtest row names the configured model that the backtest used.

It worked when the backtest passes and prints its scores:

testing 1 model (through chap-core: a dataset, a backtest and its scores)
chapkit-minimalist-example-py    pass      13s   crps 16.7  mae 16.7  rmse 18.0
  configured model: default (id 15)

1 of 1 model passes

The scores change from run to run, because the sample data is random. Add --seed N to get the same data each time.

Without the configured model, the backtest skips with chap-core has no configured model for SERVICE_ID VERSION, and names chap-devops models configs sync. The backtest uses only a configured model of the version that the model registered with.

A registration key

If the deployment has a registration key (chap-devops auth show says Registration key on), export SERVICEKIT_REGISTRATION_KEY before you start the model. Its value is the line of that name in the deployment’s .env:

export $(grep '^SERVICEKIT_REGISTRATION_KEY=' /path/to/mychap/.env)

Without the key, chap-core answers 401 Unauthorized. The model log shows registration.attempt_failed five times, then registration.failed, and the model does not try again until you start it again. chap-devops status does not list the model.

Restarts

The model keeps its registration alive with a ping every 10 seconds. chap-core keeps the registrations in redis, so a restart of chap alone keeps them. If chap-core loses the registration, for example when redis restarts too, the model log shows keepalive.service_not_found. The model registers again 30 seconds after that, so about 40 seconds after the restart, with nothing to do on your side. When you are done with the model, the image route is Models outside the marketplace.

All shapes: Use cases.

chap-core from its checkout, with the models

For developing chap-core: you run chap-core from its own checkout on this machine, and chap-devops runs the model services around it, registered with your chap-core instead of one of its own.

1. Start chap-core from its checkout as you normally do. Make sure that it listens on 0.0.0.0:8000, so that the model containers can reach it.

2. Make the deployment and start the models:

   chap-devops init models --chap-core-url http://localhost:8000 --models chapkit_simple_multistep_model
   cd models
   chap-devops up
   

--chap-core-url leaves out chap-devops’s own chap-core, with its worker, Valkey and PostgreSQL. Your chap-core uses the database and the Valkey that you give it. chap-devops records the URL of your chap-core, so:

• Each model registers with your chap-core. Its overlay sets SERVICEKIT_ORCHESTRATOR_URL to your URL, with localhost turned into host.docker.internal, which is this machine from inside a container.
• Your chap-core calls each model back on its host port. Every model gets one (5001 up), and registers itself as localhost:<port>, which is right for a chap-core running on this machine. chap-devops reads each image’s command, so the host port reaches the app: an image that starts on --port 8000 gets its host port mapped to 8000, and one that reads PORT is told the host port. Every marketplace model registers in this shape.
• The chap-core commands talk to yours. chap-devops status asks it for its health and the registered models, and chap-devops jobs, chap-devops api and chap-devops models test --backtest send their requests there. chap-devops models test without --backtest tests each model inside its container, and does not need chap-core.

chap-devops status                 # your chap-core, and the models registered with it

chap-core   up   http://localhost:8000   2.5.0.dev0   auth: off

MODEL                           STATE                       REACH      LAST PING
chapkit-simple-multistep-model  registered, not configured  port 5001  6s ago

1 model registered
chapkit-simple-multistep-model: chap-core has no configured model for it, so nothing can run it; run `chap-devops models configs sync`

It worked when chap-devops status shows chap-core up at your URL and the models registered. The version is the one that your checkout reports. A model registers some seconds after chap-devops up. Until then, chap-devops status shows it running, not registered and says started under two minutes ago; run chap-devops status again in a moment.

registered, not configured is the normal state after a plain chap-devops up. chap-core makes no configured model when a model registers. A backtest and the Modeling App need one. To make them in your chap-core, run chap-devops models configs sync:

chap-devops models configs sync
chap-devops models test --all

chapkit_simple_multistep_model: created configured model monthly_climate
chapkit_simple_multistep_model: created configured model monthly_selfhistory

testing 1 model (model level; add --backtest to go through chap-core)
chapkit-simple-multistep-model    pass    6s   1 training, 1 prediction

1 of 1 model passes

After that, chap-devops status shows the model as registered, and 1 model registered. The configured models are in the database of your chap-core, so they stay when you restart it. See Configured models.

Start chap-core before chap-devops up. A model tries to register five times in its first seconds, and then it stops. If chap-core starts after that, the model stays running, not registered. After two minutes, the first line under the summary of chap-devops status gives the way out:

chapkit-simple-multistep-model: restart it with `chap-devops restart --all chapkit-simple-multistep-model`

To make every model of the deployment register again, run chap-devops restart --all. A restart of chap-core needs nothing more. Each registered model pings chap-core about every 15 seconds. If chap-core does not know the model, the model registers again, in about a minute. See A model is running but not registered.

Without a deployment directory, chap-devops run --chap-core does the same for one model at a time:

chap-devops run -a --rm --chap-core http://localhost:8000 https://github.com/chap-models/chapkit_ghr_model

If the image is not on this machine, the first run pulls it, and that can take some minutes: this image is about 7 GB.

running chapkit_ghr_model on http://localhost:5002 (answered in 2s)
registered with http://localhost:8000
following the log of chapkit-ghr-model; Ctrl-C stops it

It worked when the lines after the start say registered with http://localhost:8000. Ctrl-C stops the model, and --rm also removes its data: chap-devops prints stopped chapkit_ghr_model, and removed its data, then removed group default when the group has no other model. See Running one model.

To point an existing deployment at your chap-core, or back:

chap-devops components disable chap-core                            # stop chap-devops's own, if it has one
chap-devops components enable chap-core --url http://localhost:8000
chap-devops components list                                         # chap-core: external
chap-devops up

chap-devops components disable chap-core                            # forget it again
chap-devops components enable chap-core                             # or run chap-devops's own again

chap-devops components disable chap-core stops and removes the containers of chap-core and of the models. The next chap-devops up starts the models again. It also gives each model a host port, because your chap-core calls the models there. When chap-devops runs its own chap-core again, the models keep that port. chap-devops components enable chap-core says so:

the models keep their host ports (chapkit_simple_multistep_model on http://localhost:5001); `chap-devops models unexpose ID` removes one

The REACH column of chap-devops status then shows the port, not via chap-core. To remove the port, run chap-devops models unexpose ID.

If your chap-core is itself a container (another compose project, which is what make restart in chap-core’s checkout starts), it cannot call the models at localhost. The models must register as host.docker.internal. chap-devops init --chap-core-url and chap-devops components enable chap-core --url find this themselves if a container publishes the port of the URL at that time. chap-devops init and chap-devops components enable tell it in a warning, for example:

warning: chap-core at http://localhost:8700 is the container `own-dd1b2e-chap-1`, so it calls the models back at host.docker.internal; if it is a process on this machine instead, run `chap-devops components enable chap-core --url http://localhost:8700 --models-host localhost`

If chap-devops did not find it, do these steps:

1. Run chap-devops components enable chap-core --url URL --models-host host.docker.internal.
2. Run chap-devops up.

Without --models-host, the models still register, and chap-devops status shows them registered, unreachable, with this command on the line under the table. If chap-core runs on another machine, run chap-devops components enable chap-core --url URL --models-host HOST, with HOST the name or address that machine reaches this one at.

If your chap-core requires a registration key or an API token, do these steps:

1. If your chap-core checks an API token, run chap-devops auth enable --token TOKEN with its token. If not, run chap-devops auth enable.
2. In .env, set the line SERVICEKIT_REGISTRATION_KEY to the key of your chap-core.
3. Run chap-devops up.

For a chap-core elsewhere, chap-devops auth enable says what it does not do:

API authentication is on
run `chap-devops up` to restart the models with authentication
chap-devops does not change the chap-core at http://localhost:8000; set `SERVICEKIT_REGISTRATION_KEY` in `.env` to its registration key

After that, chap-devops status shows auth: on. This means that chap-devops sends a token. It does not mean that your chap-core checks it.

chap-devops auth enable writes an API token and a registration key to .env, and every overlay then passes SERVICEKIT_REGISTRATION_KEY from .env. chap-devops sends the API token to your chap-core in chap-devops status, api, jobs and models test --backtest. If authentication is already on, chap-devops auth enable --token with another token stops with --token was not used: API authentication is already on with another token, and changes nothing. To give a different token, run chap-devops auth disable, then chap-devops auth enable --token TOKEN. The registration key in .env stays. See Authentication.

More: A chap-core elsewhere.

All shapes: Use cases.

chap-core built from its checkout

For testing a chap-core change the way it will ship: chap-devops builds the chap-core and worker images from your checkout and runs them with everything else it normally runs (PostgreSQL, Valkey, the models, and OCS or DHIS2 if you add them with --with).

Replace ~/dev/chap-core with the path of your chap-core checkout:

chap-devops init mychap --source ~/dev/chap-core --models chapkit_simple_multistep_model
cd mychap
chap-devops up                     # builds both images from the checkout, then starts them
chap-devops status

The images are linux/amd64, so on an Apple Silicon Mac the build runs under emulation. The first chap-devops up pulls the base images and builds both images, which took two to five minutes on an Apple Silicon Mac. It prints the full docker build log, and ends with the services it started:

started chap, chapkit-simple-multistep-model, postgres, redis, worker

chap-core   up   http://localhost:8700   2.5.0.dev0   auth: off

MODEL                           STATE                       REACH          LAST PING
chapkit-simple-multistep-model  registered, not configured  via chap-core  1s ago

1 model registered
chapkit-simple-multistep-model: chap-core has no configured model for it, so nothing can run it; run `chap-devops models configs sync`

It worked when chap-devops status shows chap-core up and the model registered. The version is the one that your checkout reports.

registered, not configured is the normal state after a plain chap-devops up. chap-core makes no configured model when a model registers. A backtest and the Modeling App need one. To make them, run chap-devops models configs sync. After that, chap-devops status shows the model as registered. See Configured models.

• compose.yml comes from the checkout’s own compose.ghcr.yml, re-read on every chap-devops sync, so the services match the code you are building.
• Every chap-devops up builds the checkout as it is now. compose.chap-devops.yml gives chap and worker a build: from the checkout and pull_policy: build. Docker’s layer cache makes a build with nothing changed take some seconds, and chap-devops up then says already running: .... After a change in the code, the build installs the dependencies again (about a minute on an Apple Silicon Mac), and chap-devops up recreates only what moved: started chap, worker.
• The images are <project>-chap:checkout and <project>-worker:checkout, named after the deployment’s compose project (such as mychap-77c0c2-chap:checkout), so a build never overwrites a released ghcr.io/dhis2-chap/... tag on this machine, and two deployments built from two checkouts never overwrite each other’s. The worker image is about 12 GB.
• There is no pin. chap-devops update still moves the models and components, and refuses --chap-tag: check out the version you want in the checkout instead.

The checkout has to have Dockerfile, Dockerfile.worker and compose.ghcr.yml, which every chap-core clone does; anything else is refused before a file is written (see is not a chap-core checkout).

Go back to a released chap-core

.env and the data are kept. Do these steps in the deployment directory:

1. Stop the deployment:

   chap-devops down
   

2. Run init again without --source, with the same --with and --models values you used:

   chap-devops init . --force --models chapkit_simple_multistep_model
   

   init keeps .env, and moves its CHAP_IMAGE_TAG line from checkout to the released tag. It says so, and prints that tag:

   created a deployment in /home/me/mychap
   moved CHAP_IMAGE_TAG in the kept .env from checkout to v2.4.0
   components: chap-core
   chap-core: v2.4.0, API on http://localhost:8700
   enabled chapkit_simple_multistep_model v0.1.2 at http://localhost:8700/v2/services/chapkit-simple-multistep-model/run/
   run `cd /home/me/mychap && chap-devops up` to start the deployment
   

3. Start the deployment:

   chap-devops up
   

It worked when chap-devops status shows the released version, such as 2.4.0. Some seconds after chap-devops up, chap-devops status can show the model as running, not registered and exit with 1. If it does, run chap-devops status again in a minute. If the checkout added a database migration, the released chap-core may not start on that data.

The images built from the checkout stay on this machine. To get the disk space back, remove them with docker image rm <project>-chap:checkout <project>-worker:checkout. <project> is the name: line in compose.chap-devops.yml, such as mychap-77c0c2.

More: chap-core from its checkout, with the models runs chap-core as a process instead, without building images.

All shapes: Use cases.

A DHIS2 you run yourself, with Chap from chap-devops

For DHIS2 or Modeling App development: you run DHIS2 your own way on this machine (from its source, or its own compose project), and chap-devops runs chap-core and the models. chap-devops dhis2 connect points the chap route of your DHIS2 at this chap-core.

chap-devops init mychap --models chapkit_simple_multistep_model
cd mychap
chap-devops up                     # returns when the containers start
chap-devops status                 # run it again until the chap-core line says up

The first chap-devops up on a machine pulls the images: about 6 GB to download and about 20 GB on disk (see Quickstart). When the images are on the machine, up returns in seconds, and chap-core answers some seconds later.

The login

chap-devops has no default login for a DHIS2 it did not start. .env has the three lines as comments at its end. Before you record your DHIS2:

1. Remove the # from DHIS2_ADMIN_USERNAME and DHIS2_ADMIN_PASSWORD.
2. Set the login of a DHIS2 superuser. For a local dev DHIS2, this is often admin and district.

Or set DHIS2_API_TOKEN to a personal access token of that user. Without a login, chap-devops dhis2 use ends with this warning, and chap-devops dhis2 connect stops with the same text as an error::

warning: chap-devops has no credentials for this DHIS2, and did not deploy it, so there is no default to try; set `DHIS2_ADMIN_USERNAME` and `DHIS2_ADMIN_PASSWORD`, or `DHIS2_API_TOKEN`, in `.env`

Record your DHIS2 and connect

Run one of the two use lines, then connect. If your DHIS2 does not use port 8080, change 8080 to its port.

# DHIS2 runs as a process on this machine (a dev server, Jetty, Tomcat):
chap-devops dhis2 use http://localhost:8080 --chap-url http://localhost:8700

# DHIS2 runs in a container of its own compose project:
chap-devops dhis2 use http://localhost:8080 --chap-url http://host.docker.internal:8700

chap-devops dhis2 connect

The first URL is where chap-devops reaches DHIS2; --chap-url is where DHIS2 reaches chap-core, which is what the chap route points at:

• A DHIS2 process on this machine reaches chap-core at localhost and the API port. dhis2 use gives a warning about localhost. Here DHIS2 runs directly on this machine, so the address is correct:

  warning: http://localhost:8700 is right for a DHIS2 running directly on this machine; one running in Docker reaches chap-core at `http://host.docker.internal:8700` instead
  

• A DHIS2 container has its own localhost; host.docker.internal is this machine. On Linux, give that container extra_hosts: ["host.docker.internal:host-gateway"] in its own compose file.

For a DHIS2 2.42 in a container, with the chap route of the demo database and no apps, connect printed this:

external DHIS2 2.42.6 at http://localhost:8080, as `admin`
repointed the `chap` route at http://host.docker.internal:8700/**; chap-core answered through it
skipped: installing apps on a DHIS2 chap-devops does not run (the Modeling App is not installed, the Climate App is not installed); `chap-devops dhis2 apps` installs them if its admin agrees
skipped: generating analytics tables on a DHIS2 chap-devops does not run; `chap-devops dhis2 analytics` starts a run if its admin agrees
the Modeling App can reach Chap once it is installed; open DHIS2 with `chap-devops open dhis2`

On a DHIS2 with no chap route, the second line starts with created.

The allowlist in dhis.conf

DHIS2 2.42 and later only proxy to origins that its dhis.conf allows. The DHIS2 default is https://*, which refuses both http:// addresses above. Add the --chap-url origin, with no path, to route.remote_servers_allowed:

route.remote_servers_allowed = https://*,http://host.docker.internal:8700

Then restart DHIS2. If DHIS2 refuses the route, chap-devops dhis2 connect names the setting. For the process address, it printed:

error: DHIS2 refused the route: version 42 and later only allow the origins `route.remote_servers_allowed` lists, and http://localhost:8700 has to be one of them; add it, with no path (DHIS2 will not start with one), to that line in the `dhis.conf` of the DHIS2 server and restart DHIS2 there

DHIS2 checks the allowlist when chap-devops writes the route. If the route already points at this chap-core, chap-devops writes nothing. Then a refusal shows only as a warning, and chap-core can be up:

warning: the `chap` route is in place but nothing answered through it: HTTP 503 Service Unavailable; run `chap-devops status` to see whether chap-core is up

If chap-devops status says chap-core is up, check the allowlist line.

The apps and the analytics tables

connect sets only the route on a DHIS2 chap-devops did not start. On your own dev DHIS2, install the Modeling and Climate apps, and generate the analytics tables:

chap-devops dhis2 apps
chap-devops dhis2 analytics
chap-devops dhis2 connect

apps needs the network: DHIS2 downloads the apps from the App Hub. On the demo database, analytics took 30 seconds; a larger database can take hours. The second connect records the connect in .chap-devops/components.yaml. Until then, chap-devops up ends with this line:

chap-devops has not connected this DHIS2 to Chap; run `chap-devops dhis2 connect` once DHIS2 answers

It worked when chap-devops dhis2 connect says chap-core answered through it, and chap-devops dhis2 show lists the route as (healthy) and both apps:

external DHIS2 2.42.6 at http://localhost:8080, as `admin`
route      http://host.docker.internal:8700/** (healthy)
target     http://host.docker.internal:8700/**
analytics  2026-10-08 01:14 (a run finished on this deployment)
apps       Modeling App 7.3.0, DHIS2 Climate App 1.16.2
the Modeling App can reach Chap; open DHIS2 with `chap-devops open dhis2`

chap-devops dhis2 use --clear forgets your DHIS2 again. The chap route stays in DHIS2.

To try this with no DHIS2 of your own, start one as a second chap-devops deployment: see Try it on one machine.

More: A DHIS2 that runs elsewhere.

All shapes: Use cases.

A DHIS2 from chap-devops, with a chap-core elsewhere

For chap-core development with the Modeling App in front of it: chap-devops runs a DHIS2 (and any models), and chap-core runs somewhere else, usually from its own checkout on this machine.

1. Start chap-core and make sure that it answers at http://localhost:8000.

   • From its checkout: make it listen on 0.0.0.0:8000, not only on the loopback.
   • From a second chap-devops deployment: run the commands below.

   chap-devops init core --only chap-core --models none --api-port 8000
   cd core
   chap-devops up
   chap-devops status                 # wait for the chap-core line to say up
   cd ..
   

2. Make the DHIS2 deployment and connect it to that chap-core:

   chap-devops init lab --chap-core-url http://localhost:8000 --with dhis2
   cd lab
   chap-devops up
   chap-devops status                 # wait for the dhis2 line to say up
   chap-devops dhis2 connect
   chap-devops open dhis2
   

If chap-core is a container (the second deployment above, or make restart in the chap-core checkout), init gives this warning:

warning: chap-core at http://localhost:8000 is the container `core-f380cb-chap-1`, so it calls the models back at host.docker.internal; if it is a process on this machine instead, run `chap-devops components enable chap-core --url http://localhost:8000 --models-host localhost`

The warning is about models only. chap-devops found the container, so the models register with the correct address. A deployment with no models can ignore it.

chap-devops up returns after some seconds, before DHIS2 answers. The first chap-devops up pulls the DHIS2 images, about 2 GB, and downloads the seed dump. Then DHIS2 needs some seconds to some minutes before it answers. Until then, chap-devops status shows dhis2 starting.

With --chap-core-url, init enables no model unless you name one. Add --models ID,ID to start models that register with that chap-core. If a model cannot register with a chap-core elsewhere, init gives a warning that names it.

--chap-core-url records the chap-core elsewhere (see chap-core from its checkout, with the models), and for the DHIS2 beside it:

• The route goes to that chap-core as the DHIS2 container reaches it. A localhost URL becomes host.docker.internal, and the DHIS2 service maps that name to the host gateway.
• dhis2/dhis.conf allows it. A scaffolded file allows every http and https target in route.remote_servers_allowed, so the chap-core elsewhere is covered wherever it runs.
• chap-core has to listen on more than the loopback (0.0.0.0), since the route arrives from a container. A chap-core in a container publishes its port on all addresses already.

On the seed database, chap-devops dhis2 connect printed this:

DHIS2 2.42.6 at http://localhost:8780, as `admin`
repointed the `chap` route at http://host.docker.internal:8000/**; chap-core answered through it
installed Modeling App 7.3.0
installed DHIS2 Climate App 1.16.2
analytics finished in 20 seconds (job AyL1NbEW3ot)
the Modeling App can reach Chap; open DHIS2 with `chap-devops open dhis2`

The seed database has a chap route already, so the second line says repointed. On a DHIS2 with no chap route, it says created.

If chap-core does not answer, connect still sets the route, but it gives a warning and ends with another line:

warning: the `chap` route is in place but nothing answered through it: HTTP 500 Internal Server Error: finishConnect(..) failed with error(-111): Connection refused: host.docker.internal/192.168.65.254:8000; run `chap-devops status` to see whether chap-core is up
...
run `chap-devops dhis2 show` to see what is still missing

If you see this warning, start chap-core and run chap-devops dhis2 connect again. See The route is there but nothing answers through it.

chap-devops open dhis2 opens DHIS2 in the browser; with --no-browser, it prints the address. Log in as admin with the password district. The Modeling App is Modeling in the apps menu.

It worked when chap-devops dhis2 connect says chap-core answered through it and ends with the Modeling App can reach Chap. In the Modeling App, the Settings page then shows the chap-core version and Connected.

More: DHIS2, A chap-core elsewhere.

All shapes: Use cases.

A model image you built yourself

For testing a model the way it will really run: build its image on this machine and run it in a chap-devops deployment, registered with chap-core, without publishing it anywhere first.

For a new model, chap-devops models new creates a project that builds in this way, and its README.md has these commands with the names filled in. See A new model project.

In the model’s checkout:

docker build --platform linux/amd64 --build-arg GIT_REVISION=$(git rev-parse HEAD) -t my-model:dev .

The GIT_REVISION build argument puts the commit in the image. The model reports it when it registers, and chap-core 2.4 refuses to store the model template of a service that reports no revision. Without it, the model stays registered, not configured and nothing can run it.

The first build pulls the model’s base image, such as ghcr.io/dhis2-chap/chapkit-py or ghcr.io/dhis2-chap/chapkit-r-inla. The R-INLA base is about 1.4 GB, and its pull can take ten minutes or more. A rebuild uses the cached base and takes some seconds.

The model registers with chap-core under the id in its MLServiceInfo (in main.py for a chapkit model). Find that id before you add the image:

grep -A1 'MLServiceInfo(' main.py

Then make a deployment with chap-core, or use one that you have:

chap-devops init lab --models none
cd lab

Add the image with that id as --service-id, and start it:

chap-devops models add my-model:dev --service-id chapkit-minimalist-example-py
chap-devops up --wait
chap-devops status
chap-devops models test my_model

Replace chapkit-minimalist-example-py with the id of your model. The model id, my_model, comes from the image name. chap-devops models add prints:

added my_model (chapkit-minimalist-example-py)
enabled my_model dev at http://localhost:8700/v2/services/chapkit-minimalist-example-py/run/
the service must register with chap-core as `chapkit-minimalist-example-py`; if its own MLServiceInfo.id differs, `chap-devops status` shows it as unmanaged - run `chap-devops models remove my_model`, then add it again with `--service-id <that id>`
run `chap-devops up` to apply

chap-devops up --wait returns when the model has registered, and it then creates the configured model that chap-core needs to run it. A plain chap-devops up returns when the containers start; chap-devops status then says running, not registered for some seconds, and registered, not configured until chap-devops models configs sync runs. After chap-devops up --wait, chap-devops status shows:

chap-core   up   http://localhost:8700   2.4.0   auth: off

MODEL                          STATE       REACH          LAST PING
chapkit-minimalist-example-py  registered  via chap-core  3s ago

1 model registered

chap-devops models test my_model runs chapkit test in the model’s container:

testing 1 model (model level; add --backtest to go through chap-core)
chapkit-minimalist-example-py    pass    9s   1 training, 1 prediction

1 of 1 model passes

Without --service-id, the service id is the image name, here my-model. If the model registers under a different id, chap-devops status shows its row as unmanaged and names the commands that correct it:

MODEL                          STATE                    REACH                     LAST PING
my-model                       running, not registered  via chap-core             -
chapkit-minimalist-example-py  unmanaged                http://a75691bfa55d:8000  10s ago

1 of 1 model is not registered.
my-model: its container registered as `chapkit-minimalist-example-py`, the unmanaged row above; run `chap-devops models remove my_model`, then `chap-devops models add my-model:dev --service-id chapkit-minimalist-example-py`

A reference with no registry host (my-model:dev, me/my-model:dev) is read as an image in the local image store:

• It has to be there already. models add reads the user and data directory from the local image. If the image is missing, it refuses and gives the build command: error: nope-model:dev is not in the local image store for linux/amd64; build it with ....
• It is never pulled. The overlay says pull_policy: never, so chap-devops up starts what is in the store, and chap-devops update shows it as pinned, skipped.
• --platform linux/amd64 matches the platform every model overlay pins. On an Apple Silicon Mac the build runs under emulation and takes longer.
• Rebuilding with the same tag and running chap-devops restart starts the new build. chap-devops restart prints recreated chapkit-minimalist-example-py.

A local build of a marketplace model

If the model is one the marketplace already lists (you are working on it), give the local build the marketplace model’s service id, so it registers under the name chap-core expects. Build the image in the model’s checkout, for example chapkit_simple_multistep_model:

docker build --platform linux/amd64 --build-arg GIT_REVISION=$(git rev-parse HEAD) -t multistep:dev .

Then, in the deployment:

chap-devops models disable chapkit_simple_multistep_model          # if it is enabled
chap-devops models add multistep:dev --service-id chapkit-simple-multistep-model
chap-devops up

The two cannot run at the same time. If the marketplace model is enabled, chap-devops models add refuses:

error: the marketplace model chapkit_simple_multistep_model is enabled as the compose service `chapkit-simple-multistep-model`; disable it with `chap-devops models disable chapkit_simple_multistep_model` to run this local build in its place

In the same way, chap-devops models enable chapkit_simple_multistep_model refuses while the local build holds the service, and names chap-devops models disable multistep. To go back to the published image:

chap-devops models remove multistep
chap-devops models enable chapkit_simple_multistep_model
chap-devops up

chap-devops models disable and chap-devops models remove keep the model’s data volume and print the docker volume rm command that removes it. chap-devops down --volumes also removes that volume, because it has the compose project label of the deployment. It warns about each volume with the deployment prefix that it did not remove.

More: Models outside the marketplace.

All shapes: Use cases.

Combinations

Components and models combine freely: --only names exactly the components you want (and chap-core only if you list it), --with adds components to chap-core, and --models names the model services either way.

Each example below makes a deployment with its own name. Run each chap-devops init from the directory where you keep your deployments, not from inside another deployment. All three use the default host ports, so only one of them can be up at a time. chap-devops init warns about this, and chap-devops up offers to stop the other deployment. To run them side by side, see Several deployments on one machine.

Climate data and a DHIS2, no Chap

OCS with its object store beside a DHIS2, for work on climate data in DHIS2 without Chap in the picture:

chap-devops init lab --only ocs,s3,dhis2
cd lab
chap-devops up                     # DHIS2's first start takes several minutes
chap-devops status                 # run it again until every line says up
chap-devops open ocs
chap-devops open dhis2

The first chap-devops up pulls the images that are not on the machine yet: OCS (about 3 GB on disk), DHIS2 (about 1.2 GB) and PostGIS (about 0.8 GB). With the images already present, chap-devops up took 14 seconds and DHIS2 answered about 25 seconds later. While DHIS2 starts, chap-devops status ends with 1 of 3 components is still starting; run `chap-devops status` again in a moment. Then it shows:

ocs     up   http://localhost:8790   0 datasets   32.0 KB data
s3      up   internal
dhis2   up   http://localhost:8780

all 3 components are up

To wait in one command instead, run chap-devops up --wait --timeout 1200. It first says waiting up to 1200s for ocs and dhis2 to answer. It returns only when OCS answers its health check and DHIS2 answers /api/ping, and ends with:

started dhis2, dhis2-db, ocs, s3
ready in 17s
  ocs    up  http://localhost:8790
  dhis2  up  http://localhost:8780

The 17 seconds count from the end of the compose step. A first start of DHIS2 can take longer than the default 300 seconds, so keep --timeout 1200.

It worked when chap-devops status shows ocs, s3 and dhis2 as up. OCS is on http://localhost:8790 and DHIS2 on http://localhost:8780 (login admin / district). Inside the deployment, DHIS2 reaches OCS at http://ocs:9000. To put climate data into OCS and get it out per DHIS2 org unit, see Getting it out.

chap-devops dhis2 connect refuses, because this deployment has no chap-core:

error: chap-core is not a component of this deployment, so the route would point at a service that is not there; run `chap-devops components enable chap-core` first

To add Chap later, do these steps in the deployment directory:

chap-devops components enable chap-core
chap-devops up
chap-devops status                 # run it again until the chap-core line says up
chap-devops dhis2 connect

For about 10 seconds after chap-devops up, the chap-core line says starting. chap-devops dhis2 connect took about 30 seconds, most of it for analytics.

chap-core comes without models: chap-devops status says no models enabled; run `chap-devops models enable ID` to add one. Its image tag is latest, not a release. If the chap-core images are not on the machine, the first chap-devops up pulls about 15 GB. See Growing a deployment for the tag and how to pin a release.

A model beside OCS, no Chap

chap-devops init ocs-model --only ocs --models chapkit_simple_multistep_model
cd ocs-model
chap-devops up --wait
chap-devops status

The first chap-devops up pulls the model image (about 1 GB on disk) and the OCS image (about 3 GB) if they are not on the machine. chap-devops up --wait returns once the model answers on its own host port and OCS answers its health check. Then chap-devops status shows:

ocs   up   http://localhost:8790   0 datasets   32.0 KB data

MODEL                           STATE  REACH      LAST PING
chapkit-simple-multistep-model  up     port 5001  -

1 model up, answering on its own host port
ocs is up

If the ocs line says starting, run chap-devops status again in a moment. The model answers on http://localhost:5001, as in A chapkit model service on its own, and OCS on http://localhost:8790.

Everything

chap-devops init full --models chapkit_simple_multistep_model --with ocs,s3,dhis2
cd full
chap-devops up --wait --timeout 1200
chap-devops status
chap-devops dhis2 connect          # the route to chap-core, the apps, analytics

chap-core, its models, OCS with the object store and a DHIS2, all in one deployment. The images take about 28 GB on disk, so a first chap-devops up that pulls them all can take a long time. The running deployment used about 5 GB of memory; give Docker 8 GB or more.

chap-devops up --wait returns only when chap-core, OCS, DHIS2 and the model answer. DHIS2 answers when /api/ping returns 200. A first start of DHIS2 can take longer than the default 300 seconds, so the command sets --timeout 1200. With the images already present, the command took 31 seconds and ended with:

ready in 13s
  chap-core                       up          http://localhost:8700
  chapkit-simple-multistep-model  registered  http://localhost:8700/v2/services/chapkit-simple-multistep-model/run/
  ocs                             up          http://localhost:8790
  dhis2                           up          http://localhost:8780
created configured models in chap-core for chapkit_simple_multistep_model (monthly_climate, monthly_selfhistory)

The 13 seconds count from the end of the compose step. Then chap-devops status shows:

chap-core   up   http://localhost:8700   2.4.0   auth: off
ocs         up   http://localhost:8790   0 datasets   32.0 KB data
s3          up   internal
dhis2       up   http://localhost:8780

MODEL                           STATE       REACH          LAST PING
chapkit-simple-multistep-model  registered  via chap-core  10s ago

1 model registered
chap-devops has not connected this DHIS2 to Chap; run `chap-devops dhis2 connect`

If you use chap-devops up without --wait, run chap-devops status again until the component lines say up. The model line then says registered, not configured, because chap-devops up without --wait makes no configured models. chap-devops dhis2 connect makes them, and so does chap-devops models configs sync. chap-devops models configs lists them.

chap-devops dhis2 connect took about 35 seconds, most of it for analytics. It worked when chap-devops dhis2 connect ends with the Modeling App can reach Chap; open DHIS2 with `chap-devops open dhis2`. Follow Chap with a local DHIS2 for the DHIS2 side, and Chap with climate data from OCS for the OCS side.

Settings any of these take

--dhis2-tag (see Picking the version) and --dhis2-seed (see Picking the data) for DHIS2, --ocs-read-only and --ocs-base-url for OCS, and --api-port, --ocs-port, --dhis2-port for ports other than the defaults (see Several deployments on one machine).

All shapes: Use cases.

Several deployments on one machine

Each chap-devops init directory is a deployment of its own, with its own containers, data and ports. Any number of them can live on one machine. They share only the host ports, and by default every deployment asks for the same ones: chap-core on 8700, DHIS2 on 8780 and OCS on 8790 (models from 5001 up). There are two ways to work with that.

One deployment at a time

Keep the default ports and run one deployment at a time. For example, compare a DHIS2 2.42 with a 2.43:

chap-devops init d242 --only dhis2
chap-devops init d243 --only dhis2 --dhis2-tag 2.43   # warns: 8780 is also used by d242
cd d242 && chap-devops up
cd ../d243 && chap-devops up

The second init gives two warnings:

warning: port 8780 is also used by d242 (/home/me/d242), which is not running; run only one of them at a time, or run `chap-devops components enable dhis2 --port 8781`
warning: chap-devops knows no DHIS2 demo dump for 2.43, so a new `dhis2_db` starts empty; name one with `chap-devops components enable dhis2 --seed URL` (a URL or a path)

init warns when another deployment that it can see uses the same port. It sees a deployment in a directory beside the new one, and a deployment that Docker started before. If the port is in use now, the warning is the plain port 8780 is already in use on this machine (needed by dhis2) line and names no deployment. The warning names a free port. init refuses nothing: two deployments on one port can take turns. The second warning is about the data: chap-devops has a demo database for 2.42 only, so d243 starts with an empty DHIS2.

chap-devops up returns when the containers are started. DHIS2 needs more time to answer: chap-devops status shows starting until it does, then dhis2 is up.

chap-devops up checks every port before it starts anything. When the port belongs to another chap-devops deployment that is running, chap-devops up names it. At a terminal, it prints the lines of the refusal below, then asks:

d242 is using these ports. Stop it and start this deployment instead? Its data is kept. [y/N]

If you answer y, chap-devops runs chap-devops down on the other deployment, then starts this one:

stopping d242 (/home/me/d242) to free its ports; `chap-devops -C /home/me/d242 up` starts it again
...
started dhis2, dhis2-db

chap-devops deletes nothing. chap-devops up in the other directory starts it again, with its database. In a script, there is no one to answer. chap-devops up then refuses and names each way out:

error: 1 host port this deployment needs is already in use; nothing was started
  port 8780 (needed by dhis2) is in use, and d242 (/home/me/d242) publishes it too; stop it with `chap-devops -C /home/me/d242 down`, or move this one: run `chap-devops components enable dhis2 --port 8781`
  or run `chap-devops up --no-preflight` to hand the conflict to Docker
  or run `chap-devops up --replace` to stop d242 first

chap-devops up --replace gives the answer y before the question:

chap-devops up --replace

Only a running deployment is named, and only a running one is stopped by --replace. A stopped deployment that publishes the same port holds nothing, so chap-devops up starts this one. If the port is in use for another reason, the line is the plain port 8780 is already in use on this machine (needed by dhis2) line, and there is no --replace line.

When a program that is not a chap-devops deployment holds the port, chap-devops only reports it and does not stop that program. chap-devops up names the port and the setting that moves this deployment to a different port.

All deployments at the same time

Give each deployment its own ports. At init:

chap-devops init a --with ocs,dhis2
chap-devops init b --with ocs,dhis2 --api-port 8701 --ocs-port 8791 --dhis2-port 8781 --port-base 5101

Both deployments also get chap-core, with no model. If d242 and d243 from the section above are in the same directory, init a also warns about port 8780. Stop them before you start a. init b prints the ports it uses:

chap-core: v2.4.0, API on http://localhost:8701
OCS: http://localhost:8791
DHIS2: http://localhost:8781

--port-base moves the range that model services get host ports from. It has an effect only on models with host ports: models in a deployment without chap-core, and models that chap-devops models expose publishes. In b above, the model is reached through chap-core, so it has no host port.

On a deployment that already exists:

If the deployment has the port already, the command changes nothing, says so, and gives no chap-devops up line:

ocs was already enabled on http://localhost:8791; nothing changed
chapkit-simple-multistep-model is already exposed on http://localhost:5101; nothing changed

The two lines come from two commands. With -v, the ocs line has the hint if it is not running, `chap-devops up` starts it. A model keeps its own port: the port that its running container publishes does not count as a port in use.

You do not have to find a free port. When a port is in use, the warnings of chap-devops init and the refusal of chap-devops up name the next free port in the line to copy.

Inside each deployment, the services keep their container ports (http://chap:8000, http://ocs:9000). Thus a change to a host port does not change how the services reach each other. Memory is the other limit: each DHIS2 can use 4 to 5 GB.

Which deployment a command uses

Each command works on the deployment in the current directory, or on the one that -C DIR names:

chap-devops -C d242 status
chap-devops -C d243 down

chap-devops status in each directory shows what that deployment runs and where.

More: Ports, The preflight, A host port is already in use.

All shapes: Use cases.

Growing a deployment

Nothing about the first init is final. Components go on and off with chap-devops components enable NAME / disable NAME, models with chap-devops models enable ID / disable ID, and chap-devops up applies the change.

The move people make most is from a standalone piece to Chap: a model service or an OCS that was running alone gets chap-core added beside it. The examples here start from a model on its own (see A chapkit model service on its own):

chap-devops init multistep --only none --models chapkit_simple_multistep_model
cd multistep
chap-devops up

Add chap-core:

chap-devops components enable chap-core
chap-devops up
chap-devops status                 # the models now register with chap-core

chap-devops components enable chap-core prints enabled chap-core on http://localhost:8700, a line that says the models keep their host ports, and run `chap-devops up` to apply. Model services read the orchestrator URL on that chap-devops up and register. Registration takes up to a minute after the start, so the first chap-devops status can show running, not registered and the line started under two minutes ago and registers once it is ready. If it does, run chap-devops status again in a minute:

chap-core   up   http://localhost:8700   2.4.0   latest: running f80b66f755ef, revision 7c95b2a7df62   auth: off

MODEL                           STATE                       REACH      LAST PING
chapkit-simple-multistep-model  registered, not configured  port 5001  11s ago

1 model registered
chapkit-simple-multistep-model: chap-core has no configured model for it, so nothing can run it; run `chap-devops models configs sync`

registered, not configured means chap-core has the model but no configured model of it yet. chap-devops models configs sync, or chap-devops up --wait, creates them. See Configured models.

The host ports they were given while standalone stay published until you chap-devops models unexpose ID. The chap-core compose file comes from the copy built into chap-devops, and the image tag is latest, a moving tag: the latest: running ... cell in chap-devops status names the build that runs. chap-devops update --pin-chap-core moves it to the newest release, which is what chap-devops init with chap-core records.

The other direction works too: chap-devops components disable chap-core keeps the models, publishes a host port for each one that had none, and says where each one now answers:

$ chap-devops components disable chap-core
disabled chap-core
stopped and removed 6 containers (chap, chapkit-simple-multistep-model, chapkit-simple-multistep-model-init, postgres, redis, worker); host ports 5001, 8700 are free again
run `chap-devops up` to apply

A model that had no host port (after chap-devops models unexpose) gets one more line, for example chapkit_simple_multistep_model now registers nowhere and is published on http://localhost:5001. The disable stops the model containers too, so run chap-devops up to start the models again without chap-core.

chap-core’s own volumes are kept either way. While chap-core is enabled, chap-devops down --volumes removes them. After the disable it does not, because the deployment no longer has the compose file that names them. To remove them, run chap-devops components enable chap-core first, then chap-devops down --volumes.

It worked when chap-devops status shows the new pieces: chap-core up and the models registered after adding chap-core, or each model up on its own port after taking it away.

The same goes for any other piece: chap-devops components enable ocs, chap-devops components enable dhis2 or chap-devops models enable ID, then chap-devops up. A DHIS2 added this way runs the default version unless you name one: chap-devops components enable dhis2 --tag 2.43 (or --image dhis2/core-dev --tag master for the unreleased one), or v on its row in chap-devops ui (see Changing the DHIS2 version). Only the default version has a demo database. Another version starts empty, and the enable says so in a warning: line. If the deployment has chap-core, run chap-devops dhis2 connect once DHIS2 answers (see Connecting the Modeling App to Chap).

All shapes: Use cases.

Taking over a chap-admin deployment

A Chap server that runs chap-core’s own compose files, with models installed by chap-admin, can move to chap-devops. chap-devops init --adopt writes a new deployment directory that uses the same database. The old directory is read and never written, so you can go back to it.

What comes over

Each model comes over the way it ran:

• A marketplace model at the stable version follows the stable channel, as chap-admin update-all moved it.
• A marketplace model at an older version stays at that version. Run chap-devops models enable ID --channel stable to follow the marketplace.
• A model the marketplace no longer lists, such as CHAP-EWARS, is added with chap-devops models add at the image it ran.
• A custom image (chap-admin install --image) is added with chap-devops models add, under the template name it registered with.

The data volume of each model is copied to the name chap-devops uses, <project>_ck_<id>_data. The old volume stays. Chap itself keeps its model templates and configured models in the database, so the models are configured as they were.

Other settings of the old .env do not come over. The command names each one, so that you can copy the line into the new .env.

Steps

1. Stop the old deployment. down removes the containers and keeps the volumes:

   cd /srv/chap
   docker compose -f compose.yml -f compose.marketplace.yml down
   

2. Write the new deployment:

   chap-devops init /srv/chap-devops --adopt /srv/chap
   

   took over the deployment in /srv/chap (compose project chap)
   copied the data of chapkit_simple_multistep_model from chap_marketplace-chapkit-simple-multistep-model-data to chap_ck_chapkit_simple_multistep_model_data
   

3. Start it, and check it:

   cd /srv/chap-devops
   chap-devops up
   chap-devops status
   

It worked when chap-devops status shows chap-core up and each model registered. The Modeling App shows the same models and the same backtests and predictions as before.

To go back, run chap-devops down in the new directory, then start the old deployment again with its own compose command. Both use the same database.

What it refuses

• A deployment that still has containers: the two would use one database. Run the docker compose -p <project> down command in the message.
• A project name with no <project>_chap-db volume: chap-core would start with an empty database. If the deployment ran under another name, set COMPOSE_PROJECT_NAME in the old .env to that name.
• --models, --interactive, --source, --chap-core-url, --api-token, --fresh-env and --no-env: the takeover decides those itself.
• A target directory that is a deployment already.

If docker cannot be asked, init --adopt writes the deployment, copies no model data, and says so. Stop the old deployment before chap-devops up.

Evaluating a model on your own data

This guide goes from an empty machine to a comparison of two forecasting models on one dataset. It uses chap-core’s own command line, chap, through chap-devops chap. You do not install Python, uv or R: chap-devops chap runs chap in a container.

At the end you have:

• two evaluations (.nc files), one for each model;
• a plot of an evaluation (.html) that you open in a browser;
• a table that compares the two models (.csv).

All of these files are in your working directory, and they belong to your user.

What you need

• Linux or macOS. On Windows, use WSL with the Linux binary.

• Docker, and it must run. On macOS, start Docker Desktop.

• About 20 GB of free disk space, for the images that the steps download:

  Image	Size on disk	Step
  ghcr.io/dhis2-chap/chap-worker	about 12 GB	4, the model from GitHub
  ghcr.io/dhis2-chap/chap-core	about 2.4 GB	5 to 7, only if you have no chap-worker
  ghcr.io/chap-models/auto_arima_chapkit	about 6.2 GB	6, the marketplace model

  chap-devops says before each run when it must download an image first. chap-devops uses the tag of the newest chap-core release, v2.5.0 when this guide was tested. On a slow network, download the images in advance:

  docker pull --platform linux/amd64 ghcr.io/dhis2-chap/chap-worker:v2.5.0
  

• A connection to the internet for the first run.

The first run of each step takes some minutes, because Docker downloads the images. On an Apple silicon Mac, Docker runs the images under emulation, so each step is slower than on Linux. After the first run, an evaluation of the example data takes less than a minute.

Step 1: Install chap-devops

curl -fsSL https://raw.githubusercontent.com/winterop-com/chap-devops/main/install.sh | sh
chap-devops --version

It worked when chap-devops --version prints a version, for example chap-devops 0.100.1. See Install for other ways to install.

Step 2: Check the machine

chap-devops doctor

It worked when the docker cli, docker daemon and docker compose lines start with ok. A warn on the os and arch line of an Apple silicon Mac is correct: it only tells you that the images run under emulation. If a line starts with fail, do the fix that it names, then run chap-devops doctor again.

Step 3: Make a working directory and get data

Make a directory for this work, and go into it:

mkdir -p ~/chap-eval
cd ~/chap-eval

Download chap-core’s example data. It is monthly dengue cases, with rainfall, temperature and population, for districts of Laos:

curl -fsSO https://raw.githubusercontent.com/dhis2-chap/chap-core/master/example_data/laos_subset.csv
curl -fsSO https://raw.githubusercontent.com/dhis2-chap/chap-core/master/example_data/laos_subset.geojson

It worked when ls shows laos_subset.csv and laos_subset.geojson.

To use your own data instead, put your CSV and its GeoJSON in this directory. They must have the same name, for example mydata.csv and mydata.geojson. Use the same columns as the example file:

time_period,rainfall,mean_temperature,disease_cases,population,location
2010-01,37.965,20.04,1.0,75049.56,Bokeo

Each location must be a feature in the GeoJSON. In the steps below, change laos_subset.csv to the name of your CSV.

Step 4: Evaluate a model from GitHub

This model is a small R model from chap-core’s examples:

chap-devops chap eval \
  --model-name https://github.com/dhis2-chap/minimalist_example_r \
  --dataset-csv laos_subset.csv \
  --output-file minimalist_r.nc \
  --backtest-params.n-splits 3 \
  --backtest-params.n-periods 3

What the options do:

chap-devops writes some lines of its own before chap starts:

running `chap eval` in ghcr.io/dhis2-chap/chap-worker:v2.5.0; the first run pulls it, about 12 GB
files: chap reads and writes in /home/me/chap-eval

Then chap writes its own log lines. At the end, chap-devops writes:

chap finished; it wrote minimalist_r.nc
`chap-devops chap plot-backtest minimalist_r.nc --output-file minimalist_r.html` plots it

It worked when you see chap finished; it wrote minimalist_r.nc.

chap-devops selected the large chap-worker image because a model from GitHub can need R. chap clones the model again for each run. chap-devops keeps the R packages of a model in its cache, so the second run does not install them again. This small model has no packages to install, so each run takes about the same time: about 40 seconds on an Apple silicon Mac, when the image is there.

Step 5: Plot the evaluation

Run the command that the last line of step 4 gave you:

chap-devops chap plot-backtest minimalist_r.nc --output-file minimalist_r.html

It worked when chap-devops writes chap finished; it wrote minimalist_r.html. Open the file in a browser:

open minimalist_r.html        # macOS
xdg-open minimalist_r.html    # Linux

The plot shows the real cases and the forecasts of each split, one panel for each location.

Step 6: Evaluate a second model, from the marketplace

A model from the marketplace is a model service: a container with an HTTP API. Give its id to --model-name, and chap-devops starts it for you:

chap-devops chap eval \
  --model-name auto_arima_chapkit \
  --dataset-csv laos_subset.csv \
  --output-file auto_arima.nc \
  --backtest-params.n-splits 3 \
  --backtest-params.n-periods 3

chap-devops starts the model, waits until it answers, and then runs chap. After the first line, Docker Compose writes the lines of the network, the volume and the containers that it makes:

starting auto-arima-chapkit (auto_arima_chapkit in /home/me/.local/share/chap-devops/run/default)
...
running `chap eval` in ghcr.io/dhis2-chap/chap-worker:v2.5.0
files: chap reads and writes in /home/me/chap-eval
model: auto_arima_chapkit at http://auto-arima-chapkit:8000 answers
...
chap finished; it wrote auto_arima.nc
`chap-devops chap plot-backtest auto_arima.nc --output-file auto_arima.html` plots it
auto_arima_chapkit keeps running for the next run; `chap-devops stop auto_arima_chapkit` stops it, and `--stop` stops it after a run

It worked when you see chap finished; it wrote auto_arima.nc. The first time, Docker downloads the image of the model, which takes some minutes.

chap only talks HTTP to a model service, so the smaller chap-core image is enough. chap-devops uses an image that is already on this machine, so the run downloads no chap image. After step 4, that is chap-worker. If the chap-core image at the same tag is also on this machine, chap-devops uses chap-core, and the first line names it.

The model keeps running, so a second evaluation of it starts at once. chap-devops ps lists it. Find more ids with chap-devops models list.

Step 7: Compare the two models

chap-devops chap export-metrics minimalist_r.nc auto_arima.nc --output-file comparison.csv

It worked when chap-devops writes chap finished; it wrote comparison.csv. chap can write some RuntimeWarning lines about log1p before that. They do not stop the run.

comparison.csv has one row for each model. Open it in a spreadsheet. Some of the columns:

Step 8: Clean up

Stop the model service, and remove its data:

chap-devops stop auto_arima_chapkit --purge

It worked when chap-devops writes:

stopped auto_arima_chapkit
removed volume default-662918_ck_auto_arima_chapkit_data
removed group default

The number in the volume name is different on your machine. The group default held only this model, so chap-devops removes it too.

Your .nc, .html and .csv files stay in ~/chap-eval. To get the disk space of the caches back, delete chap-devops’s chap directory:

rm -rf ~/.local/share/chap-devops/chap

To remove the images too, list them, then remove each one with docker image rm:

docker image ls 'ghcr.io/dhis2-chap/*'
docker image ls 'ghcr.io/chap-models/*'
docker image rm ghcr.io/dhis2-chap/chap-worker:v2.5.0

If something goes wrong

More messages are in Troubleshooting.

Next

• To evaluate the models of a deployment, run chap-devops chap in a subdirectory of it (mkdir eval && cd eval), and give the model id: chap-devops chap eval --model-name auto_arima_chapkit .... The deployment does not need to run: chap-devops starts only that model, without chap-core.
• To use another chap-core version, add --tag, for example chap-devops chap --tag master eval ....
• For chap’s own options, run chap-devops chap eval --help.
• The chap CLI tells how chap-devops chap mounts your files, selects the image and keeps its caches.

Concepts

The project directory

chap-devops init writes a directory you own; nothing outside it is touched.

mychap/
  .chap-devops/
    project.yaml               intent: schema version, chap-core tag and compose
                               source, the compose project name, registry URL,
                               API port, whether the two auth secrets are in
                               use, the -f list, the model port range, and
                               which root files sync wrote
    models.yaml                intent: the enabled models (image, pinned version,
                               channel, host port or none, data dir, user and
                               where it was read from, platform, overlay name)
    models-manual.yaml         intent: the models this deployment defines itself,
                               added by `chap-devops models add`; only present when it
                               has added one
    components.yaml            intent: which components this deployment is made of
                               (chap-core, ocs, s3, dhis2) and their settings
    compose.chap-core.<tag>.yml
                               chap-core's own compose.ghcr.yml at the pinned tag,
                               exactly as downloaded; compose.yml is rendered from it
  compose.yml                  artifact: the base services, from the file above
  compose.chap-devops.yml            artifact: chap-devops-owned overrides on top of it: the
                               compose project name, the API's host port and the
                               registration key chap-core checks
  compose.ocs.yml              artifact: the ocs component, when it is enabled
  compose.s3.yml               artifact: the s3 component, when it is enabled
  compose.dhis2.yml            artifact: the dhis2 component, when it is enabled
  compose.marketplace.yml      artifact: include: list, one line per enabled model
  compose.<service_id>.yml     artifact: one overlay per enabled model
  ocs/climate-service.yaml     the OCS instance configuration; scaffolded once by
                               chap-devops, which changes only two keys in it
  dhis2/dhis.conf              the DHIS2 instance configuration; likewise, and DHIS2
                               does not start without it
  .env                         written once by init; only pins, the two auth
                               secrets and the component settings are ever added

Intent and artifacts

.chap-devops/ is the intent. It is what models enable, models disable, components enable, components disable, the browser and update edit, and it is small enough to read and to diff.

The compose files at the project root are artifacts rendered from it by chap-devops sync. They are plain Compose files with nothing chap-devops-specific in them, so

docker compose -f compose.yml -f compose.chap-devops.yml -f compose.marketplace.yml up -d

works without chap-devops installed, which is the point of generating them.

compose.yml is an artifact too. init downloads chap-core’s own compose.ghcr.yml at the tag it pinned, keeps the raw copy as .chap-devops/compose.chap-core.<tag>.yml and records its URL and SHA-256 in project.yaml; sync renders compose.yml as two header lines plus that copy, byte for byte. Rendering from the copy rather than the network keeps sync offline and deterministic, and it is why a hand edit of compose.yml is drift that chap-devops sync undoes. Edit the copy in .chap-devops/ instead, and sync will follow it, and say that the checksum no longer matches. When the copy is missing, sync leaves compose.yml alone rather than guessing.

One change at a time

Every command that changes .chap-devops/ takes an exclusive lock on .chap-devops/lock before it reads the state and keeps it until it has written it back: models enable, disable, add, remove, expose, the components commands, sync, update, restore, auth, dhis2 use, down, and up while it renders the compose files. A second such command on the same deployment waits for the first, and says so on stderr:

another chap-devops command is changing this deployment; waiting for it to finish

So two models enable --port auto started together, from two terminals or from a tool that runs chap-devops for its users, end with both models enabled on different ports. up lets go of the lock once the files are written, so a long image pull does not hold up the next models enable. Commands that only read - status, models list, logs - never wait. The operating system releases the lock when the command exits, however it exits, so there is no stale lock file to clear; .chap-devops/lock is left in place and is not part of a backup.

chap-devops sync

chap-devops sync

in sync: 0 written, 5 unchanged, 0 removed

With -v, a hint line names each file:

$ chap-devops -v sync
hint: compose.yml is unchanged
hint: compose.chap-devops.yml is unchanged
hint: compose.auto-arima-chapkit.yml is unchanged
hint: compose.chapkit-simple-multistep-model.yml is unchanged
hint: compose.marketplace.yml is unchanged
in sync: 0 written, 5 unchanged, 0 removed

chap-devops up runs sync before docker compose up, so the intent and the artifacts never drift in normal use. Rendering is deterministic and every file is compared before it is written, so a second sync reports everything as unchanged.

• chap-devops sync --check reports drift without writing, for CI or a pre-commit hook, and exits non-zero when anything would change. It names each file that would change (would write compose.yml) without -v.
• A plain chap-devops sync re-creates a deleted overlay or picks up a hand edit of models.yaml.
• Sync only ever removes overlays it wrote itself; project.yaml keeps the list. A hand-written compose.custom.yml next to them is left alone. Add it to the umbrella by hand if you want it included.

Orphans

Removing a definition does not stop a container: compose only knows about the services the -f list names, and a container it no longer finds a definition for is an orphan. chap-devops owns the whole -f list, so an orphan in one of its projects is exactly that - the container of a model or a component that was disabled, still running and still publishing its host port.

So chap-devops up and chap-devops restart both pass --remove-orphans, and models disable and components disable go further: they stop and remove the container of the service they are taking away there and then, while compose still has the definition to name it by, and say so in their closing line. The port is free the moment the command returns, rather than at the next chap-devops up.

The flip side is the rule for hand-written compose files. A container is only an orphan of the compose project it belongs to, and chap-devops renders its -f list from .chap-devops/, so a service of your own is only at risk if you started it under this deployment’s project name - which is what

docker compose -f compose.yml -f compose.chap-devops.yml -f compose.marketplace.yml \
               -f compose.custom.yml up -d

does, because the name: comes from the chap-devops files in that list. The next chap-devops up does not have compose.custom.yml in its own list, so it takes those containers with it. Run a hand-written file as a compose project of its own (its own directory, or -p) and nothing chap-devops does touches it.

The compose project name

Compose puts a project name in front of every container and every named volume it creates, and unless a file says otherwise that name is the directory name. Two deployments in directories both called demo therefore share demo_chap-db, demo_logs and the rest - on different paths, and even when one of them was deleted months ago. A fresh chap-devops init demo && chap-devops up then starts chap-core against a PostgreSQL volume created with a password it has never seen, the container never becomes healthy, and up ends on

dependency failed to start: container demo-chap-1 is unhealthy

So chap-devops init generates a name of its own and records it:

compose_project: demo-1ab2c3

chap-devops sync renders it as the top-level name: of the files it owns (compose.chap-devops.yml and compose.marketplace.yml - compose takes the name: of the last -f file that sets one, and the umbrella is the one file always in the list). Containers become demo-1ab2c3-chap-1 and volumes demo-1ab2c3_chap-db, which no other deployment can be holding.

The name never changes once it is written. chap-devops init --force keeps the one it finds, because a new name would leave the running deployment’s containers and its data behind under the old one.

chap-devops status --json, chap-devops doctor and the closing line of chap-devops down all name the project.

COMPOSE_PROJECT_NAME in the environment still wins over the name: key, as it does for any compose project.

Container labels

Every container chap-devops starts carries labels under com.winterop.chap-devops, so a tool can find them all on a machine without knowing where any deployment lives:

docker ps --filter label=com.winterop.chap-devops.role

lists every chap-devops container, of every deployment and every chap-devops run group, and chap-devops top finds its containers the same way. The one-shot containers of chap-devops chap and chap-devops chapkit have no role label; label=com.winterop.chap-devops.kind finds it too.

The model and component files carry the labels themselves. chap-core’s services get theirs from compose.chap-devops.yml, since compose.yml is upstream’s file byte for byte and compose merges labels across the -f files; a chap-core built from a checkout is labelled the same way.

Nothing in a label depends on the chap-devops version or the time, because a changed label makes compose recreate the container: an upgrade of chap-devops renders the same labels, and chap-devops up leaves running containers alone.

Pins

A deployment is reproducible because everything it runs is pinned.

• Models are pinned to an image tag, which for marketplace images is a sha-<short commit> build: image: <repo>:${<ID>_IMAGE_TAG:-sha-24d58c0}. A model that follows a channel records both the channel and the version the channel resolved to; one enabled with --version records the version alone and never moves.

• chap-core is pinned to a release tag. init resolves the default --chap-tag latest to the release it points at today, v2.3.1 say, and writes that into .env and .chap-devops/project.yaml, so a deployment is reproducible rather than following a tag that changes under it. --chap-tag master or dev keeps a moving tag on purpose.

• OCS and the object store follow a moving tag, because neither publishes a release feed: ${OCS_IMAGE_TAG:-main} and ${S3_IMAGE_TAG:-latest}. Set either variable in .env to pin a build of your own; chap-devops update says which of the two is in force. DHIS2 is pinned to a minor line instead, ${DHIS2_IMAGE_TAG:-2.42}, so a patch release arrives with a pull and moving to another line is a deliberate edit - DHIS2 migrates its schema forward only. See Components and DHIS2.

Model pins only move in two ways: chap-devops models enable ID (with --channel or --version) and chap-devops update. Nothing else, up, restart, expose and unexpose included, changes the version a model runs. update moves the pins and pulls; chap-devops restart applies what it fetched to the services that are running. See Updating.

The .env contract

.env is the one file that is written once and then left alone. init writes it when the directory has none, and never rewrites it afterwards: a second init keeps the file it finds, --force included, sync only appends missing pin comments and update only moves the pin comments of models it changed. One line is the exception. When init --force keeps the file, it moves the active CHAP_IMAGE_TAG line to the new tag if that line holds the tag that the deployment recorded (or checkout), as chap-devops update --chap-tag does. It says moved CHAP_IMAGE_TAG in the kept .env from checkout to v2.4.0. A line with another value is kept, with a warning that names the line to set.

That is deliberate. The file holds the database password the PostgreSQL volume was created with, plus the API token and the registration key, and a rotated password leaves chap-core unable to authenticate against its own data.

Because of what it holds, .env is readable by its owner only (mode 600), and every write goes to a temporary file that is renamed over it, so a crash or a full disk never leaves half a file. If a restored or hand-made .env is readable by everyone, the next chap-devops sync or chap-devops up closes it.

Those two secrets are the one exception to “written once”, and a narrow one. chap-devops init --api-token fills them in as it renders the file; chap-devops auth enable, disable and rotate rewrite exactly those two lines afterwards, leaving every other line, every comment and every blank line byte for byte as it found them:

CHAP_API_TOKEN=d1f0...                 the whole API, as `Authorization: Bearer`
SERVICEKIT_REGISTRATION_KEY=9a3c...    what each model sends when it registers

Commented out, as the generated file ships them, means no authentication at all. The values live only here: .chap-devops/project.yaml records two booleans under auth and never a secret, so the state directory stays safe to commit and to paste into a bug report. See Authentication.

Enabling a component appends its own section the same way sync appends a model’s pin: a commented OCS_IMAGE_TAG, and for the object store a generated S3_ACCESS_KEY and S3_SECRET_KEY. DHIS2 brings the longest section - a generated DHIS2_DB_PASSWORD and DHIS2_ENCRYPTION_PASSWORD, plus commented DHIS2_IMAGE_TAG, DHIS2_DB_DUMP_URL and DHIS2_JAVA_TOOL_OPTIONS carrying the values the rendered compose file already defaults to. Every generated value there is written once and never rewritten, for the same reason the database password is: the volume was created with them.

init --fresh-env is the explicit override: it renders a new .env with a new password, so an existing volume has to be dropped with

chap-devops down --volumes

(or the role changed with ALTER USER) before Chap will start again. init --no-env writes no .env at all.

What .env holds

Every line is optional except the ones init writes as active assignments; a commented placeholder means “not set”, which is the default the compose files already carry.

Compose reads .env automatically, so ${CHAP_IMAGE_TAG:-latest} and the per-model ${<ID>_IMAGE_TAG:-sha-xxxxxxx} pins can be overridden there without regenerating anything. Because Compose reads .env last, a line in it wins over what .chap-devops/ records; CHAP_API_PORT is the case that matters most, and Ports covers it.

How chap-devops reads it

By Compose’s rules, because Compose is the only thing that acts on the file:

• the last active assignment of a variable wins, so a file carrying two CHAP_API_TOKEN= lines is protected by the second one;
• export KEY=value assigns the same thing as KEY=value;
• a value wrapped in matching single or double quotes does not include them;
• a line whose first non-blank character is # assigns nothing, and an empty KEY= sets nothing (which is how a commented-out token and CHAP_API_TOKEN= both mean “no authentication”).

Writing follows the same rules, so the line chap-devops writes is always the line Compose reads back: chap-devops auth enable, disable and rotate rewrite the variable’s first active assignment and remove every later duplicate of it, leaving exactly one active line. A file with two CHAP_API_TOKEN= lines comes out of chap-devops auth rotate with one, holding the new token.

Context-sensitive help

chap-devops --help adapts to where you are. Outside a deployment directory it lists only the commands that can work there:

Commands:
  init         Create a deployment directory: compose files, .env and .chap-devops/
  run          Start one model and print where it answers
  ps           List the models that run, and where each one answers
  stop         Stop a model and remove its compose overlay; its data stays
  top          Watch every chap-devops deployment on this machine as a live tree
  models       Browse and manage marketplace models
  registry     Inspect and refresh the marketplace registry
  update       Move the pins to what upstream publishes now, and pull
  api          Send one authenticated request to chap-core's API
  chap         Run the chap CLI in a container, with no Python or uv installed
  chapkit      Run the chapkit CLI in the chap-core image, with no Python installed
  doctor       Run a checklist over this machine and this deployment
  cleanup      Delete what deployments whose directory is gone left in docker
  self         Update chap-devops itself, and report what this build is
  completions  Print a shell completion script for chap-devops
  help         Print this message or the help of the given subcommand(s)

Inside one, the deployment commands are listed too: up, down, logs, restart, status, sync, ui, components, docker, backup, auth, jobs, open and dhis2. The hiding runs both ways, so init drops out of that listing: the deployment it would create is already here. It still runs there - chap-devops init --force is how the API port or the components of a deployment are rewritten, see How the API port is set, and chap-devops init sub creates a second deployment in a subdirectory of the first.

The hidden commands still run if you type them; they just tell you there is no project. A group command typed on its own says the same thing rather than listing subcommands that cannot run either, so chap-devops components outside a deployment is the missing-project error, not the components help. chap-devops models is split the same way: list, search and info browse the marketplace and work anywhere, while add, remove, enable, disable, expose, unexpose and test need a deployment and are hidden outside one. The command reference lists all of them, because it is rendered from the static command tree rather than from where you happen to be.

Project discovery

Every command that operates on a project finds it the way git finds .git: from the current directory, or from -C DIR, upwards to the nearest .chap-devops/. So chap-devops up works from any subdirectory of the deployment, and chap-devops -C /srv/mychap status works from anywhere at all.

The wrappers then always run

docker compose -f <dir>/compose.yml -f <dir>/compose.chap-devops.yml -f <dir>/compose.marketplace.yml ...

with one -f per enabled component before the umbrella (and without compose.yml and compose.chap-devops.yml when chap-core is not a component), from the project directory, so they behave the same whatever your shell’s working directory is, and they exit with Compose’s own exit code.

Commands

chap-devops [--json] [-C DIR] [--registry-url URL] [--offline] [--cache-dir DIR] <command>

The groups below are the shape of the tool. The Command reference is generated from the --help texts and lists every command, every flag and every default.

Running one model

See Running one model.

The everyday verbs

chap-devops up starts what is on disk, chap-devops update fetches newer versions, and chap-devops restart applies them to the services that are running. That is the whole distinction, and it is why up and update are both safe to run at any time. See Updating.

chap-devops jobs and chap-devops api are the two that talk to the API rather than to Docker. A job is one unit of slow work chap-core handed to its worker, and a failed one says why in chap-devops jobs logs <id> and nowhere else; chap-devops api is what starts a job from a terminal in the first place. See Jobs and the API.

chap-devops doctor is the one to run first on a machine you have not deployed on before, and first again when something is wrong: it asks in one pass what the other commands assume. It exits non-zero only when a check failed. See Doctor.

chap-devops down --volumes is the reset that takes the data with it (docker compose down -v --remove-orphans): it lists the volumes docker holds under this deployment’s name - with how much the OCS data volume holds next to it, when that can be measured - asks before removing them and ends with the ones that are gone, by name. -y (--yes) is how a script says it meant it, and is required where there is nothing to ask at - a stdin that is not a terminal, or --json - rather than the question being skipped. Compose removes the volumes its files still declare, so a volume left over from a disabled model survives; chap-devops doctor finds those, and chap-devops models disable <id> --purge removes them. There is no -v for this: -v is the global --verbose flag, so a -v that reaches the passthrough (chap-devops down -- -v) is refused and told to use --volumes, rather than being passed on to compose or quietly dropped.

Models

list, search and info read the catalogue and work outside a project. The rest need a project; of them, only test, configs list and configs export change nothing. Registration is a heartbeat, so chap-devops status and chap-devops doctor can be green while a model cannot predict at all - chap-devops models test is the check that settles it. See Testing a model. add is the only one that needs the network for something other than the catalogue: it reads GitHub and ghcr to resolve what it was given. See Models and the marketplace.

Components

A component is a service (or a small group) that chap-devops sync renders one compose file for: chap-core, which is Chap itself and is on unless you turn it off, ocs (Open Climate Service), s3 (the object store OCS will use) and dhis2 (a demo or development DHIS2 with its own database). The set lives in .chap-devops/components.yaml. chap-devops init --with ocs,s3, --without chap-core and --only ocs,s3 set it at creation time. chap-devops open NAME opens one of them in a browser, and o does the same from the browser’s components page. See Components, Reaching a component from a browser and DHIS2.

DHIS2

For a deployment with the dhis2 component, or with an external DHIS2 recorded by chap-devops dhis2 use. Apart from use, which records a DHIS2 in .chap-devops/components.yaml, and connect, which records when it ran in the same file, nothing here touches Docker or a file: every verb is requests to DHIS2’s own API.

Every one of them is idempotent: a second run repoints nothing, reinstalls nothing and says so. All of them take --user NAME and --wait SECONDS (how long to wait for DHIS2’s API: 20 minutes by default for the dhis2 component, because a first start takes minutes, and 60 seconds for an external DHIS2). The credential comes from DHIS2_API_TOKEN or DHIS2_ADMIN_USERNAME/DHIS2_ADMIN_PASSWORD in .env, else CHAP_DEVOPS_DHIS2_TOKEN or CHAP_DEVOPS_DHIS2_PASSWORD in the environment, else the seed password, else admin/district (only on a DHIS2 that chap-devops deployed). See The credentials. There is no --password flag, because a password on a command line is in the shell history. chap-devops up does none of this and the chapter says why - so chap-devops up and chap-devops status each end by naming chap-devops dhis2 connect until one has been recorded in .chap-devops/components.yaml. That record suppresses the hint and is never evidence that the route is right; chap-devops dhis2 show is what asks DHIS2. See Connecting the Modeling App to Chap and connected_at, and what it is not.

Authentication

All four touch only those two .env lines, and none of them restarts anything: chap-core and the models read .env when Compose creates them, so chap-devops up has to follow. chap-devops init --api-token does the same thing at creation time. See Authentication.

The chap CLI

You need no Python, uv or R for it. See The chap CLI.

Registry

Docker

The Docker plumbing you only reach for when you already know what Docker is doing lives under chap-devops docker, so the top-level list stays readable if you have never used Compose.

chap-devops docker config is what Docker actually reads after the -f list, the include: and the .env substitutions have been applied, which is the fastest way to find out why a setting is not taking effect.

Backup

See Backup and restore.

chap-devops itself

The two commands that are about the CLI rather than about a deployment. Both work anywhere, inside a deployment or not.

chap-devops update moves a deployment’s pins; chap-devops self update replaces the chap-devops binary. Nothing in the first touches the second. See Install for both of these and for the once-a-day notice that a newer release exists.

Global options

They are accepted before or after the subcommand, on every command, and the reference lists them with their defaults. The last three are the registry options. The help lists them under “Registry options” only for the commands that use them; Global options names those commands. On the other commands they change only the once-a-day notice that a newer release exists.

--json for scripts and tools

Under --json every command prints exactly one JSON document on stdout, and everything meant for a person - progress, notes, warnings - goes to stderr. A tool that drives chap-devops reads stdout and branches on one field:

• Success of a command that changes something (models enable, disable, add, remove, expose, unexpose, up, models test) carries "ok": true. The read-only commands (status, models list, models info) print their report as it is; status says how things are in its own exit code.

• Failure of any command is

  {"ok": false, "error": "...", "hint": "run `chap-devops ...`", "causes": []}
  

  hint is the way out: the message’s last clause when that clause names a command or a flag to use instead (pass \–id auto` … to add this one beside it), and nullwhen the message has no way out to give.erroris the message up to that clause, so the two never say the same thing; the terminal shows them together aftererror:. A message of several lines, for example the port check with more than one busy port, stays whole in error, with hint: null, because each line has its own way out. A usage error - an unknown flag, a missing argument - is the same document, with clap's message as errorand the command's–helpashint`, and exits 2.

• models enable and models add list what they enabled under models, one object per model with id, service_id, port, bind and url (the model’s own port, else chap-core’s proxy to it, else null), next to the full change report.

• up prints api_url, the compose services running and the ones this run started, every enabled model the same way, and under --wait what the wait found: wait.ready, wait.waited_s and each model’s state and url.

• models test prints {"ok": ..., "models": [...]}, one object per model with its result (pass, fail or skip), the summary and the detail that says why and what to do.

• models configs sync prints {"ok": ..., "models": [...]}, one object per model with id, service_id and its state: created (with the names in configured), already-configured, not-registered or failed (with the reason in error).

• models configs list prints {"models": [...]}, one object per model with id, service_id and configs. Each configured model has id, name, variant, archived, version, covariates, values and source.

• models configs add prints {"ok": true, "model": ..., "configured": [...]}, with the rows that chap-core created.

• models configs update prints model, changed, configured (the new row) and archived (the old row). If nothing changed, changed is false.

• models configs archive prints {"ok": true, "model": ..., "archived": ...}.

• models configs export prints model, configurations (the block, as JSON) and prediction_periods_from, which says where each prediction_periods comes from.

The exit code agrees with ok: 0 for true, non-zero for false. Two commands print "ok": false rather than an error and still exit non-zero: models test, when a model failed or every model was skipped, and models configs sync, when a model could not be configured.

Command reference

Generated from the --help texts by make docs-reference; edit src/cli.rs and run that target rather than editing this file.

Every command accepts the options listed under chap-devops, --json included. The registry options (--registry-url, --offline, --cache-dir) show only in the help of the commands that use them, and each such command names them below. Commands that need a deployment directory are hidden from chap-devops --help outside one, but they are all listed here.

chap-devops

deploy Chap (climate-informed disease forecasting) and its services.

Usage: chap-devops [OPTIONS] <COMMAND>

Subcommands: chap-devops init, chap-devops components, chap-devops models, chap-devops registry, chap-devops sync, chap-devops update, chap-devops auth, chap-devops dhis2, chap-devops up, chap-devops down, chap-devops restart, chap-devops status, chap-devops logs, chap-devops open, chap-devops ui, chap-devops run, chap-devops ps, chap-devops stop, chap-devops jobs, chap-devops api, chap-devops chap, chap-devops chapkit, chap-devops backup, chap-devops doctor, chap-devops docker, chap-devops top, chap-devops cleanup, chap-devops self, chap-devops completions

chap-devops init

Create a deployment directory: compose files, .env and .chap-devops/.

Usage: chap-devops init [OPTIONS] [DIR]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops components

Show and change what this deployment is made of.

Usage: chap-devops components [OPTIONS] <COMMAND>

Subcommands: chap-devops components list, chap-devops components enable, chap-devops components disable

chap-devops components list

List every component and whether this deployment has it.

Usage: chap-devops components list [OPTIONS]

chap-devops components enable

Enable a component, or change the settings of an enabled one.

Usage: chap-devops components enable [OPTIONS] <NAME>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops components disable

Disable a component and remove its compose file.

Usage: chap-devops components disable [OPTIONS] <NAME>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models

Browse and manage marketplace models.

Usage: chap-devops models [OPTIONS] <COMMAND>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

Subcommands: chap-devops models list, chap-devops models search, chap-devops models info, chap-devops models test, chap-devops models configs, chap-devops models new, chap-devops models add, chap-devops models remove, chap-devops models enable, chap-devops models disable, chap-devops models expose, chap-devops models unexpose

chap-devops models list

List marketplace models.

Usage: chap-devops models list [OPTIONS]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models search

Search the marketplace by id, name or summary.

Usage: chap-devops models search [OPTIONS] <QUERY>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models info

Show everything known about one model.

Usage: chap-devops models info [OPTIONS] <ID>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models test

Make a model train and predict, and say whether it could.

Usage: chap-devops models test [OPTIONS] [ID]...

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models configs

List, add, archive and sync the configured models of each model.

Usage: chap-devops models configs [OPTIONS] [ID]
       chap-devops models configs <COMMAND>

Subcommands: chap-devops models configs list, chap-devops models configs add, chap-devops models configs update, chap-devops models configs archive, chap-devops models configs export, chap-devops models configs sync

chap-devops models configs list

List the configured models chap-core has of each enabled model.

Usage: chap-devops models configs list [OPTIONS] [ID]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models configs add

Add a configured model of a model to chap-core.

Usage: chap-devops models configs add [OPTIONS] <ID>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models configs update

Change the values of a configured model of a model.

Usage: chap-devops models configs update [OPTIONS] <ID> <NAME>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models configs archive

Archive a configured model of a model.

Usage: chap-devops models configs archive [OPTIONS] <ID> <NAME>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models configs export

Write the configured models of a model in the marketplace format.

Usage: chap-devops models configs export [OPTIONS] [ID]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models configs sync

Create the configured models that chap-core needs to run each model.

Usage: chap-devops models configs sync [OPTIONS] [ID]...

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models new

Create a model project from a template.

Usage: chap-devops models new [OPTIONS] <DIR>

chap-devops models add

Add a model the marketplace does not list.

Usage: chap-devops models add [OPTIONS] <SOURCE>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models remove

Remove a model that was added with models add.

Usage: chap-devops models remove [OPTIONS] <ID>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models enable

Enable a model and write its compose overlay.

Usage: chap-devops models enable [OPTIONS] <ID>...

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models disable

Disable a model and remove its compose overlay.

Usage: chap-devops models disable [OPTIONS] <ID>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models expose

Publish a host port for an enabled model.

Usage: chap-devops models expose [OPTIONS] <ID>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops models unexpose

Remove the host port of an enabled model.

Usage: chap-devops models unexpose [OPTIONS] <ID>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops registry

Inspect and refresh the marketplace registry.

Usage: chap-devops registry [OPTIONS] <COMMAND>

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

Subcommands: chap-devops registry update, chap-devops registry show

chap-devops registry update

Fetch the registry from the network and refresh the cache.

Usage: chap-devops registry update [OPTIONS]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops registry show

Show where the registry was loaded from and what it holds.

Usage: chap-devops registry show [OPTIONS]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops sync

Render the compose files from .chap-devops/.

Usage: chap-devops sync [OPTIONS]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops update

Move the pins to what upstream publishes now, and pull.

Usage: chap-devops update [OPTIONS]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops auth

Enable or disable API authentication, and show the token.

Usage: chap-devops auth [OPTIONS] <COMMAND>

Subcommands: chap-devops auth show, chap-devops auth token, chap-devops auth enable, chap-devops auth disable, chap-devops auth rotate

chap-devops auth show

Say whether the API is protected, and by which token.

Usage: chap-devops auth show [OPTIONS]

chap-devops auth token

Print the API token alone, for a script to capture.

Usage: chap-devops auth token [OPTIONS]

chap-devops auth enable

Enable authentication: write both secrets and sync.

Usage: chap-devops auth enable [OPTIONS]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops auth disable

Disable authentication; keep both values as comments.

Usage: chap-devops auth disable [OPTIONS]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops auth rotate

Replace both secrets with new generated ones.

Usage: chap-devops auth rotate [OPTIONS]

Registry options: --registry-url <URL>, --offline, --cache-dir <DIR> (see chap-devops).

chap-devops dhis2

Let the DHIS2 Modeling App reach this deployment’s Chap.

Usage: chap-devops dhis2 [OPTIONS] <COMMAND>

Subcommands: chap-devops dhis2 show, chap-devops dhis2 route, chap-devops dhis2 analytics, chap-devops dhis2 apps, chap-devops dhis2 connect, chap-devops dhis2 use

chap-devops dhis2 show

Say what DHIS2 has: the chap route, analytics and the apps.

Usage: chap-devops dhis2 show [OPTIONS]

chap-devops dhis2 route

Point DHIS2’s chap route at this deployment’s chap-core.

Usage: chap-devops dhis2 route [OPTIONS]

chap-devops dhis2 analytics

Generate DHIS2’s analytics tables and wait for them.

Usage: chap-devops dhis2 analytics [OPTIONS]

chap-devops dhis2 apps

Install the Modeling and Climate apps from the App Hub.

Usage: chap-devops dhis2 apps [OPTIONS]