Skip to content
Branch: master
Find file Copy path
Find file Copy path
3 contributors

Users who have contributed to this file

@SCdF @ngaruko @CescaGarrett
204 lines (129 sloc) 8.01 KB

Development Setup

These instructions are for developers who want to contribute to the Core Framework (this repository). If you only need to run the Framework (ie with a Reference App configuration), or you are a developer building configurations, you can follow the easy deployment instructions instead.

Before getting started, read about our development workflow and the architecture overview. With the setup instructions below the tools will run directly on your machine, rather than via Docker.

Supported Operating Systems

Developers are actively using both Linux and MacOS, so both of those platforms are well supported for development. We don't support Windows out of the box. However, you can try using the Windows Subsystem for Linux. See the Windows Subsystem for Linux notes for how the installation instructions differ.


You will need to install the following:

To run end-to-end tests you will also need:

  • Java JDK
  • Docker

Installation instructions for these tools differ heavily based on your operating system and aren't covered here.

Setup CouchDB on a single node

NB: multiple CouchDB nodes will be more complicated, but the general pattern outlined below will be the same.

Build the webapp

git clone
cd cht-core
npm ci

Enabling a secure CouchDB

By default CouchDB runs in admin party mode, which means you do not need users to read or edit any data. This is great for some, but to use your application safely we're going to disable this feature.

First, add an admin user. When prompted to create an admin during installation, use a strong username and password. Passwords can be changed via Fauxton. For more information see the CouchDB install doc.

Now, configure some security settings on CouchDB:

COUCH_URL=http://myAdminUser:myAdminPass@localhost:5984/medic COUCH_NODE_NAME=couchdb@ grunt secure-couchdb

After following these steps CouchDB should no longer allow unauthorised access:

curl http://myAdminUser:myAdminPass@localhost:5984 # should work
{"couchdb":"Welcome","version":"2.0.0","vendor":{"name":"The Apache Software Foundation"}}
curl http://localhost:5984 # should fail
{"error":"unauthorized","reason":"Authentication required."}

To be able to use Fauxton with authenticated users:

curl -X PUT "http://myAdminUser:myAdminPass@localhost:5984/_node/$COUCH_NODE_NAME/_config/httpd/WWW-Authenticate" \
  -d '"Basic realm=\"administrator\""' -H "Content-Type: application/json"

Required environment variables

Medic needs the following environment variables to be declared:

  • COUCH_URL: the full authenticated url to the medic DB. Locally this would be http://myAdminUser:myAdminPass@localhost:5984/medic
  • COUCH_NODE_NAME: the name of your CouchDB's node. This is likely to either be couchdb@127.0.0,1 or noname@nohost. You can find out by querying CouchDB's membership API
  • (optionally) API_PORT: the port API will run on. If not defined we use 5988
  • (optionally) CHROME_BIN: only required if grunt unit or grunt e2e complain that they can't find Chrome.

How to permanently define environment variables depends on your OS and shell (e.g. for bash you can put them ~/.bashrc). You can temporarily define them with export:

export COUCH_NODE_NAME=couchdb@
export COUCH_URL=http://myAdminUser:myAdminPass@localhost:5984/medic

Deploy the webapp

Webapp code is stored in CouchDB. To compile and deploy the current code, use grunt:


This will also watch for changes and redeploy as neccessary.

Start medic-api

API is needed to access the application.

Either start it directly with node:

cd ./api
node server.js

Or use grunt to have it watch for changes and restart as neccessary:

grunt dev-api

Start medic-sentinel

Sentinel is reponsible for certain background tasks. It's not strictly required to access the application, but many features won't work without it.

Either start it directly with node:

cd ./sentinel
node server.js

Or use grunt to have it watch for changes and restart as neccessary:

grunt dev-sentinel

Try it out

Navigate your browser to http://localhost:5988/medic/login.

Testing locally with devices

Follow the steps below to use an Android device with a development build of your application. This process is relevant when running v3.5.0 or greater of the Core Framework since it relies on service workers, which requires a valid HTTPS certificate. Use either serveo or ngrok to make your developer build accessible from your Android device by giving it a trusted URL.

  1. Start the api. This can be via docker, grunt, debug, horti, etc.
  2. Follow the instructions below to start serveo (preferred) or ngrok
  3. This will output a generated URL which you can enter into our android app or browser and connect to your local dev environment.


Proxying via serveo is generally more successful than ngrok so it is our preferred route. Sometimes it will be blocked by Chrome safe browsing however in which case you can try ngrok.

  • To connect to an API running via grunt or horti, execute ssh -R 80:localhost:5988
  • To connect to an API running via Docker, execute ssh -R 80:localhost:443

This will echo a URL which you can connect to.


ngrok sometimes fails due to connection throttling which can cause the service worker cache preload to fail. It's included here as an alternative in case serveo doesn't work for some reason.

  1. Create a ngrok account at
  2. Follow instructions on downloading and linking your computer to your ngrok account.
  3. Start ngrok
  • To connect to an API running via grunt or horti, execute ./ngrok http 5988
  • To connect to an API running via Docker, execute ./ngrok http 443


To fill your app with generated data, you can batch-load messages from a CSV file, with the load_messages.js script.

Use curl to submit a single message:

curl -i -u gateway:123qwe \
    --data-urlencode 'message=Test One two' \
    --data-urlencode 'from=+13125551212' \
    --data-urlencode 'sent_timestamp=1403965605868' \
    -X POST \


All text labels in the app are localized. See the translation documentation for more details on how to add new labels or modify existing ones.


Check out the Gruntfile for all the tests you can run.

Unit tests

They live in the tests directories of each app. Run them with grunt: grunt unit-continuous.

End to End tests

They live in tests. Run them with grunt: grunt e2e. Docker is required (it should be available on the command line as docker).

API integration tests

grunt api-e2e

Integration tests

Travis runs grunt ci every time some new code is pushed to github.

Build documentation

To build reference documentation into a local folder jsdoc-docs: grunt build-documentation

Automated Deployment on Travis

Code is automatically published via Travis CI to the staging server.

You can’t perform that action at this time.