Installation

Host CHT with Docker

Prerequisites for hosting CHT with Docker

Prerequisites

Be sure you have followed the requirements document including installing Docker. This guide assumes you’re using the ubuntu user and that it has sudo-less access to Docker.

Directory Structure

Create the following directory structure:

By calling this mkdir commands:

mkdir -p /home/ubuntu/cht/{compose,certs,upgrade-service,couchdb}

compose - docker-compose files for cht-core and CouchDB
certs - TLS certificates directory
upgrade-service - where docker-compose file for the upgrade-service
couchdb - the path for the docker-compose file of the upgrade-service (not used in multi-node)

Download required docker-compose files

The following 3 curl commands download CHT version 4.21.1 compose files, which you can change as needed. Otherwise, call:

cd /home/ubuntu/cht/
curl -s -o ./compose/cht-core.yml https://staging.dev.medicmobile.org/_couch/builds_4/medic:medic:4.21.1/docker-compose/cht-core.yml
curl -s -o ./compose/cht-couchdb.yml https://staging.dev.medicmobile.org/_couch/builds_4/medic:medic:4.21.1/docker-compose/cht-couchdb.yml
curl -s -o ./upgrade-service/docker-compose.yml https://raw.githubusercontent.com/medic/cht-upgrade-service/main/docker-compose.yml

Prepare Environment Variables file

Prepare a .env file by running this code:

sudo apt install wamerican uuid-runtime
uuid=$(uuidgen)
couchdb_secret=$(shuf -n7 /usr/share/dict/words --random-source=/dev/random | tr '\n' '-' | tr -d "'" | cut -d'-' -f1,2,3,4,5,6,7)
couchdb_password=$(shuf -n7 /usr/share/dict/words --random-source=/dev/random | tr '\n' '-' | tr -d "'" | cut -d'-' -f1,2,3,4,5,6,7)
cat > /home/ubuntu/cht/upgrade-service/.env << EOF
CHT_COMPOSE_PROJECT_NAME=cht
COUCHDB_SECRET=${couchdb_secret}
DOCKER_CONFIG_PATH=/home/ubuntu/cht/upgrade-service
COUCHDB_DATA=/home/ubuntu/cht/couchdb
CHT_COMPOSE_PATH=/home/ubuntu/cht/compose
COUCHDB_USER=medic
COUCHDB_PASSWORD=${couchdb_password}
COUCHDB_UUID=${uuid}
# <ADD_SERVERNAME_TO_HTTP_AGENT>: (optional, default: false, configures: api) Adds 'servername' to HTTP agent for certificate issues in receiving traffic when proxying HTTPS->HTTP in SNI environments with external TLS termination. 
# See 'tls.connect(options[, callback])' (https://nodejs.org/api/tls.html). May resolve 'ERR_TLS_CERT_ALTNAME_INVALID' error.
# ADD_SERVERNAME_TO_HTTP_AGENT=true
# <PROXY_CHANGE_ORIGIN>: (optional, default: false, configures: api) See http-proxy (https://www.npmjs.com/package/http-proxy#options). Sets 'changeOrigin' to 'true' for HTTP clients. For certificate issues in proxying HTTP->HTTPS
# PROXY_CHANGE_ORIGIN=true
EOF

Note that secure passwords and UUIDs were generated on the first four calls and saved in the resulting .env file. Uncomment optional items if required.

Launch containers

Important

This section has the first use of docker compose. If you get an error calling this, double check hosting requirements.

To start your CHT instance, run the following

cd /home/ubuntu/cht/upgrade-service
docker compose up --detach

Docker will start the upgrade service, which in turn pulls the required images and starts all the services as defined by the compose files in /home/ubuntu/cht/compose.

To follow the progress tail the log of the upgrade service container by running this:

docker logs -f upgrade-service-cht-upgrade-service-1

To make sure everything is running correctly, call docker ps and make sure that 7 CHT containers show:

CONTAINER ID   IMAGE                                                 COMMAND                   CREATED              STATUS              PORTS                                                                          NAMES
8fa9625929f2   public.ecr.aws/medic/cht-nginx:4.21.1                 "/docker-entrypoint.…"    About a minute ago   Up About a minute   0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcp   cht-nginx-1
8cffee82f5d0   public.ecr.aws/medic/cht-api:4.21.1                   "/bin/bash /service/…"    About a minute ago   Up About a minute   5988/tcp                                                                       cht-api-1
5b7fb45ec122   public.ecr.aws/medic/cht-sentinel:4.21.1              "/bin/bash /service/…"    About a minute ago   Up About a minute                                                                                  cht-sentinel-1
2ead8d40874f   public.ecr.aws/medic/cht-haproxy:4.21.1               "/entrypoint.sh"          About a minute ago   Up About a minute   5984/tcp                                                                       cht-haproxy-1
6e13a4abf21e   public.ecr.aws/medic/cht-haproxy-healthcheck:4.21.1   "/bin/sh -c \"/app/ch…"   About a minute ago   Up About a minute                                                                                  cht-healthcheck-1
fc5816b19336   public.ecr.aws/medic/cht-couchdb:4.21.1               "tini -- /docker-ent…"    About a minute ago   Up About a minute   4369/tcp, 5984/tcp, 9100/tcp                                                   cht-couchdb-1
953ff81ce484   public.ecr.aws/s5s3h4s7/cht-upgrade-service:latest    "node /app/src/index…"    About a minute ago   Up About a minute                                                                                  upgrade-service-cht-upgrade-service-1

This should show related to the CHT core are running

cht_nginx
cht_api
cht_sentinel
cht_couchdb
cht_healthcheck
cht_haproxy
cht-upgrade-service

Take note of the STATUS column and make sure no errors are displayed there. If any container is restarting or mentioning any other error, check the logs using the docker logs <container-name> command.

If all has gone well, nginx should now be listening at both port 80 and port 443. Port 80 has a permanent redirect to port 443, so you can only access the CHT using https.

To login as the medic user in the web app, you can find your password with this command:

grep COUCHDB_PASSWORD /home/ubuntu/cht/upgrade-service/.env | cut -d'=' -f2

TLS Certificates

See the TLS Certificates page for how to import your certificates.

Upgrades

During upgrades, the CHT upgrade service updates the docker-compose files located in /home/ubuntu/cht/compose/. This means that any and all changes made to the docker-compose files will be overwritten. If there is ever a need to make any changes to the docker-compose files, be sure to re-do them post upgrades or should consider implementing them outside of those docker-compose files.

Upgrading the cht-upgrade-service

The CHT Upgrade Service provides an interface between the CHT Core API and Docker to allow easy startup and one-click upgrades from the CHT Admin UI. Occasionally, the CHT Upgrade Service, itself, will need to be upgraded. If an upgrade is available, it is highly recommended that you install the upgrade for the CHT Upgrade Service before performing further upgrades on your CHT instance. This is done via the following steps:

Verify that the version of the cht-upgrade-service image in your ./upgrade-service/docker-compose.yml files is set to latest.
Pull the latest cht-upgrade-service image from Docker Hub and replace the current container by running the following command:
```
cd /home/ubuntu/cht/upgrade-service
docker compose pull
docker compose up --detach
```

Important

Upgrading the CHT Upgrade Service will not cause a new CHT version to be installed. The CHT Core and CouchDB containers are not affected.

Follow the Product Releases channel on the CHT forum to stay informed about new releases and upgrades.

Last updated on October 21, 2025

Did this documentation help you ?

TLS Certificates