App Developer Hosting in CHT 4.x

Hosting the CHT when developing apps

Getting started

Be sure to meet the CHT hosting requirements first. To avoid conflicts, ensure that all other CHT 4.x instances are stopped. To stop ALL containers, you can use

docker kill $(docker ps -q)

After meeting these requirements, create a directory and download the developer YAML files in the directory you want to store them. This example uses ~/cht-4-app-developer as the directory:

mkdir  ~/cht-4-app-developer && cd ~/cht-4-app-developer
curl -s -o docker-compose.yml
curl -s -o cht-core.yml
curl -s -o cht-couchdb.yml

You should now have 3 compose files which we can check with ls:

cht-core.yml  cht-couchdb.yml  docker-compose.yml

To start the first developer CHT instance, run docker-compose, prepending the needed environment variables:


This may take some minutes to fully start depending on the speed of the internet connection and speed of the host. This is because docker needs to download all the storage layers for all the containers and the CHT needs to run the first run set up. After downloads and setup has completed, the CHT should be accessible on https://localhost. You can log in with username medic and password password.

When connecting to a new dev CHT instance for the first time, an error will be shown, “Your connection is not private” (see screenshot). To get past this, click “Advanced” and then click “Proceed to localhost”.

Running the Nth CHT instance

After running the first instance of the CHT, it’s easy to run as many more as are needed. This is achieved by specifying different:

  • port for HTTP redirects (CHT_HTTP)
  • port for HTTPS traffic (NGINX_HTTP_PORT)
  • directory for storing the compose files and CouchDB files

Assuming you want to start a new project called the_second and start the instance on HTTP port 8081 and HTTPS port 8443, we would first create a new directory and download the same files:

mkdir  ~/the_second && cd ~/the_second
curl -s -o docker-compose.yml
curl -s -o cht-core.yml
curl -s -o cht-couchdb.yml

Then, we would use the same docker-compose command as above, but this time specify the ports:


The second instance is now accessible at https://localhost:8444 and again using username medic and password password to login.

The .env file

Often times it’s convenient to use revision control, like GitHub, to store and publish changes in a CHT app. A nice compliment to this is to store the specifics on how to run the docker-compose command for each app. By using a shared docker-compose configuration for all developers on the same app, it avoids any port collisions and enables all developers to have a unified configuration.

Using the above the_second sample project, we can create a file ~/the_second/.env with this contents:


Now it’s easy to boot this environment:

cd ~/the_second
docker-compose up

Switching & concurrent projects

The easiest way to switch between projects is to stop the first set of containers and start the second set. Cancel the first project running in the foreground with ctrl + c and stop all the project’s services:

docker stop second_api_1 second_cht-upgrade-service_1 second_couchdb_1 second_haproxy_1 second_healthcheck_1 second_nginx_1 second_sentinel_1

Alternately, you can stop ALL containers (even non-CHT ones!) with docker kill $(docker ps -q). Then start the other CHT project using either the .env file or use the explicit command with ports and other environment variables as shown above.

To run projects concurrently open a second terminal and start the second project so you don’t have to cancel and stop the first project. Remember to avoid port conflicts!

To read more about how docker-compose works, be sure to read the helpful docker-compose commands page.

CHT Docker Helper for 4.x

The scripts downloads 3 compose files and builds an .env file used above. This greatly eases starting your first CHT instance with a simple text based GUI:

The script showing the URL and version of the CHT instance as well as number of containers launched, global container count, medic images downloaded count and OS load average. Finally a “Successfully started my_first_project” message is shown and denotes the login is “medic” and the password is “password”.

This script brings a lot of benefits with it:

  • You only have to download one bash script
  • It has been tested to work on Windows, macOS and Linux
  • All compose files and images will be downloaded automatically for you
  • All networks, storage volumes and containers will be created
  • A valid TLS certificate will be installed, allowing you to easily test on with CHT Android natively on a mobile device

Currently, the CHT Docker Helper for 4.0 is in beta, and comes with some caveats:

  • it is not yet available in master
  • it does not account for port conflicts, so you need to manually resolve them yourself by editing the *.env files
  • upgrades are not yet supported
  • concurrently running multiple instances is not yet supported

To get started using it:

  1. Clone the CHT Core repo
  2. Checkout the 7852-cht-4.x-docker-helper branch
  3. cd into the cht-core/scripts/docker-helper-4.x/ directory
  4. Run the script with ./

Here is a video of the beta version being run on 8 Nov 2022. The video references lazydocker which is a great way to monitor and control your local docker environment: