Download and run the publicly available Docker image for CHT applications
CHT Local Environment Setup
This tutorial will take you through setting up a local environment to build and test CHT applications on CHT version 3.9.0. 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:
- View the login page to CHT webapp on localhost
- Upload default settings to localhost
Brief Overview of Key Concepts
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.
1. Create docker-compose.yml
Open your terminal and navigate to your working folder. Run the command:
curl -o docker-compose.yml https://raw.githubusercontent.com/medic/cht-core/master/docker-compose.yml
This will create a copy of the
docker-compose.yml file from
NoteYou can also copy the content of the docker-compose.yml file from this link.
Run the following command inside the directory that you saved the
Once the command is finished, navigate to https://localhost with the Google Chrome browser and login with the default username
medic and default 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.
2. Install cht-conf
Using npm and python on your terminal, install cht-conf and pyxform globally using the following commands:
npm install -g cht-conf sudo python -m pip install git+https://firstname.lastname@example.org#egg=pyxform-medic
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.
3. Upload Test Data
By default, the CHT will have the Maternal & Newborn Health Reference Application installed. To upload demo data you can use
cht-coreon your computer using the following command:
git clone https://github.com/medic/cht-core.git
- Navigate your terminal to the
cht-core/config/defaultdirectory. This is where the reference application is stored.
- Run the following
cht-confcommand 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.
4. Create and Upload a Blank Project
NoteThis step will erase the default Maternal & Newborn Health Reference Application.
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..
5. Optional: Install Valid TLS Certificate
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
medic-os container is running and make this call:
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:
Debug: Service 'medic-core/nginx' exited with status 143 Info: Service 'medic-core/nginx' restarted successfully Success: Finished restarting services in package 'medic-core' If no errors output above, certificates successfully installed.
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.
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:email@example.com. As well, you can now use this URL to test with the CHT Android app.
Frequently Asked Questions
- How do I upgrade to a higher version of the webapp?
- How do I access the instance remotely?
- Error ‘No module named pip’ when installing cht-conf
- CouchDB failed to start properly
- Enable adding contacts in a blank project
Notes for developing on Windows
Hosting the CHT on self run infrastracture
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.