CHT Core Framework > Overview > Docker Use
Download and run the publicly available Docker image for CHT applications
This tutorial will take you through setting up a local environment to build and test CHT applications on CHT version 4.x. This includes setting up the necessary tools to download and run the CHT public docker image as well as a command line interface tool to manage and build CHT apps.
By the end of the tutorial you should be able to:
The CHT Core Framework makes it faster to build full-featured, scalable digital health apps by providing a foundation developers can build on. These apps can support most languages, are Offline-First, and work on basic phones (via SMS), smartphones, tablets, and computers.
CHT Project Configurer also known as cht-conf is command-line interface tool to manage and configure CHT apps.
Docker is a tool designed to make it easier to create, deploy, and run applications by using containers.
Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and deploy it as one package.
To read more about these concepts, see our Docker Setup guide.
Before you begin, you need to have some useful software and tools that are required for things to work:
Now that you have the dependent tools and software installed, you are ready to set up your CHT local environment.
Open your terminal and run these commands which will create a directory, download the three Docker Compose files and prepare the evironment variables file. You should just be able select all and paste on a command line:
mkdir -p ~/cht-local-setup/couch-data/ && mkdir -p ~/cht-local-setup/core-couch/ && mkdir -p ~/cht-local-setup/upgrade/
cd ~/cht-local-setup
curl -s -o ./core-couch/cht-core.yml https://staging.dev.medicmobile.org/_couch/builds_4/medic:medic:4.0.1/docker-compose/cht-core.yml && curl -s -o ./core-couch/cht-couchdb.yml https://staging.dev.medicmobile.org/_couch/builds_4/medic:medic:4.0.1/docker-compose/cht-couchdb.yml && curl -s -o ./upgrade/docker-compose.yml https://raw.githubusercontent.com/medic/cht-upgrade-service/main/docker-compose.yml
cat > ${HOME}/cht-local-setup/upgrade/.env << EOF
DOCKER_CONFIG_PATH=${HOME}/cht-local-setup/core-couch/
COUCHDB_DATA=${HOME}/cht-local-setup/data/couch-data
CHT_COMPOSE_PATH=${HOME}/cht-local-setup/core-couch/
COUCHDB_USER=medic
COUCHDB_PASSWORD=password
EOF
Run the following command to start your CHT instance using Docker Compose:
cd ~/cht-local-setup/upgrade/
docker-compose up
Note that the first time you run your CHT instance it may take a while. In case you run into issues running your docker file, ensure that the following setting in Docker is checked.
Settings » General » Use Docker Compose V2
Once the command is finished, navigate to https://localhost with the Google Chrome browser and login with the default username medic
and default password password
.
You might get an error “Your connection is not private” (see screenshot). Click “Advanced” and then click “Proceed to localhost”.
If you are using Mac you will not be able to find the “Proceed to localhost” link in Chrome, to bypass that error just click anywhere on the denial page and type “thisisunsafe”.
This error can be fixed in step 5 below.
If you encounter an error bind: address already in use
, see the Port Conflicts section in the Docker Setup guide.
This CHT instance is empty and has no data in it. While you’re free to explore and add your own data, in step 3 below we will upload sample data. Proceed to step 2 to install cht-conf
which is needed to upload the test data.
Using npm on your terminal, install cht-conf globally using the command below.
npm install -g cht-conf
Using python on your terminal, install pyxform globally using the command below.
sudo python -m pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic
If you encounter the error npm ERR! gyp ERR verb find Python Python is not set
while installing pyxform and are running macOS, see this troubleshooting section.
You can confirm that the installation was successful by typing cht
in your terminal.
If you have trouble installing cht-conf
, see the application’s GitHub repository for more information.
By default, the CHT will have the Maternal & Newborn Health Reference Application installed. To upload demo data you can use cht-conf
:
cht-core
on your computer using the following command:git clone https://github.com/medic/cht-core.git
cht-core/config/default
directory. This is where the reference application is stored.cht-conf
command to compile and upload default test data to your local instance:cht --url=https://medic:password@localhost --accept-self-signed-certs csv-to-docs upload-docs
With the test data uploaded, log back into your CHT instance and note the “Test Health Facility” and related data.
With cht-conf
you can also create a blank project. This provides you a template from which you can begin working on CHT. To do so, run the following commands:
mkdir cht-app-tutorials
cd cht-app-tutorials
cht initialise-project-layout
Then deploy the blank project onto your local test environment with the command:
cht --url=https://medic:password@localhost --accept-self-signed-certs
If the above command shows an error similar to this one ERROR Error: Webpack warnings when building contact-summary
you will need to install all the dependencies and libraries it needs, then you need to restart the docker-compose and try again.
npm ci
docker-compose restart
cht --url=https://medic:password@localhost --accept-self-signed-certs
accept-self-signed-certs
tells cht-conf that it’s OK that the server’s certificate isn’t signed properly, which will be the case when using docker locally.
Once you have run the above command it should complete with the message: INFO All actions completed.
.
With the blank project deployed to your CHT instance, you’re ready to start writing your first app. A big part of authoring an app is testing it on a mobile device, likely using the unbranded version of CHT Android. In order to test in the APK, your CHT instance needs a valid TLS certificate which the default docker version does not have.
To install a valid certificate, open a terminal in the cht-core
directory. Ensure the CHT instance is running and make this call:
./scripts/add-local-ip-certs-to-docker-4.x.sh cht_nginx_1
If add-local-ip-certs-to-docker-4.x.sh
is not in your scripts directory, be sure to use git
or GitHub Desktop to update your local repository with the latest changes. If you can’t update for some reason, you can download it directly.
To see what a before and after looks like, note the screenshot to the left which uses curl
to test the certificate validity.
The output of add-local-ip-certs-to-docker.sh
looks like this:
cht_nginx_1
If just container name is shown above, a fresh local-ip.co certificate was downloaded.
The IP of your computer is used in the URL of the CHT instance now. For example if your IP is 192.168.68.40
then the CHT URL with a valid TLS certificate is 192-168-68-40.my.local-ip.co
. See the local-ip.co site to read more about these free to use certificates.
When using cht-conf
you can now drop the use of --accept-self-signed-certs
. Further, update the URL to be based on your IP. Using the example IP above, this would be --url=https://medic:password@192-168-68-40.my.local-ip.co
. As well, you can now use this URL to test with the CHT Android app.
Download and run the publicly available Docker image for CHT applications
Notes for developing on Windows
Hosting the CHT on self run infrastructure
Hosting the CHT on Amazon EC2
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.