CHT Local Environment Setup

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.

Required Resources

Before you begin, you need to have some useful software and tools that are required for things to work:

• nodejs version 12
• npm
• git or the Github Desktop
• docker and docker-compose.

Implementation Steps

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 cht-core.

Run the following command inside the directory that you saved the docker-compose.yml:

docker-compose up

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.

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://github.com/medic/pyxform.git@medic-conf-1.17#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-conf:

• Clone cht-core on your computer using the following command:

git clone https://github.com/medic/cht-core.git

• Navigate your terminal to the cht-core/config/default directory. This is where the reference application is stored.
• Run the following 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.

4. Create and Upload a Blank Project

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..

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:

./scripts/add-local-ip-certs-to-docker.sh

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.

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.

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

Related Content