CHT Local Environment Setup

Setting up a local environment to build and test CHT applications

This tutorial will take you through setting up a local environment to build and test CHT applications on CHT version 3.9.1. 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

CHT Core Framework The 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.

Medic Project Configurer a.k.a medic-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.

First off, install nodejs 8 or later and npm.

You also require Docker for your operating system:

Implementation Steps

Now that you have the dependent tools and software installed, you are ready to set up your CHT local environment.

1. Install medic-conf

Using npm and python on your command line, install medic-conf and pyxform globally using the following commands:

npm install -g medic-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 medic-conf in your command line.

If you have trouble installing medic-conf, see the application’s GitHub repository for more information.

2. Install the Core Framework

Download the docker-compose.yml file to a folder of your choice. Be sure to place it in a folder that’s easy to find on terminal or command line.

Open your terminal or command line and navigate to the folder where you have your docker-compose.yml file and run the command:

docker-compose up

Once the command is done running, navigate to https://localhost on a Google Chrome browser and login with the default username medic and default password password.

If you encounter an error bind: address already in use, see the Port Conflicts section in our Docker Setup guide

3. Create and Upload a Blank Project

With medic-conf you can create a blank project. This provides you a template from which you can begin working on CHT. Just run:

mkdir cht-app-tutorials
cd cht-app-tutorials
medic-conf initialise-project-layout

Then deploy the blank project onto your local test environment with the command:

medic-conf --url=https://medic:password@localhost --accept-self-signed-certs

accept-self-signed-certs tells medic-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..

4. Upload Test Data

By default the CHT will have the Maternal & Newborn Health Reference Application installed. To upload demo data you can use medic-conf:

Check out the cht-core respository to your local machine, either by using the Github Desktop app or by running the following command in the directory you want to check the code out into: git clone https://github.com/medic/cht-core.git. This will create a cht-core directory.
Navigate your terminal to the cht-core/config/default directory. This is where the reference application is stored.
Run the following medic-conf command to compile and upload default test data to your local instance: medic-conf --url=https://medic:password@localhost --accept-self-signed-certs csv-to-docs upload-docs.