These instructions are designed to help you run or develop on the Core Framework, a technical resource of the Community Health Toolkit (CHT) contributed by Medic Mobile.

Medic Mobile is a nonprofit organization on a mission to improve health in the hardest-to-reach communities through open-source software. Medic Mobile serves as the technical steward of the Community Health Toolkit.

For the latest changes and release announcements see our release notes. Our exact support matrix (including older app versions) can be found in our docs.

• Overview
• Easy deployment
• Development setup
• Tests
• Configuring the standard application
• Contributing
• License

The CHT's Core Framework is a software architecture that makes it faster to build full-featured, scalable digital health apps that equip health workers to provide better care in their communities. To learn more about building an application with the Core Framework, visit our guide for developing community health apps.

The Core Framework addresses complexities like health system roles and reporting hierarchies, and its features are flexible enough to support a range of health programs and local care provider workflows.

Mobile and web applications built with the Core Framework support a team-based approach to healthcare delivery and management. Health workers can use SMS messages or mobile applications to submit health data that can then be viewed and exported using a web application. These web applications are fully responsive with a mobile-first design, and support localization using any written language. They can be installed locally or in the cloud by setting up the individual components or as a Docker container.

For more information about Medic Mobile's architecture and how the pieces fit together, see Architecture Overview. For more information about the format of docs in the database, see Database Schema. For more information about the SMS exchange protocol between webapp and gateway, see Message States.

To get up and running quickly, you can use Docker. You can then create your own custom application, or set up the standard application by running the Medic Configurer on the ./config/standard directory.

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.

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.

Currently, the latest versions of Chrome, Chrome for Android and Firefox are functionally supported. We do not support Safari (unreliable implementations of necessary web APIs) and the generic android browser (unreliable implementations in general). Our webapp code, which includes any code written as configuration, is still ES5. Our exact support matrix (including older app versions) can be found in our docs.

You will need to install the following:

• Node.js 8.11.x and above
• npm 6.x.x and above (to support npm ci)
• grunt cli
• CouchDB v2.x

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

git clone https://github.com/medic/medic
cd medic
npm ci

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 [email protected] 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"

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 [email protected],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 [email protected]
export COUCH_URL=http://myAdminUser:myAdminPass@localhost:5984/medic

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

grunt

This will also watch for changes and redeploy as neccessary.

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

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

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

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. These steps will make your developer build accessible from your Android device by giving it a trusted URL created by ngrok.

1. Create a ngrok account at https://ngrok.com/
2. Follow instructions on downloading and linking your computer to your ngrok account.
3. Start the webapp. This can be via docker, grunt, debug, horti, etc....
4. Run ngrok and forward it towards the port you are running the webapp on.
   • EX: For running webapp in docker locally using the docker instructions above $ ./ngrok http 443. This will forward the traffic from your ngrok url on https to 443 on your local machine.
     
   • EX: For running via horti, or grunt where the api starts on port 5988. $ ./ngrok http 5988 This will forward the traffic from your ngrok url on https to 5988 on your local machine.
   • Example output from ngrok: Forwarding https://1661304e.ngrok.io -> http://localhost:5988
5. You can then enter the ngrok generated url(https://1661304e.ngrok.io) into our android app or browser and connect to your local dev environment.

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 \
    http://localhost:5988/api/v1/records

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.

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

They live in tests. Run them with grunt: grunt e2e.

grunt api-e2e

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

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

This app is highly configurable and can be modified to suit your needs. Read the guide for developing community health applications if you would like to customize your application further.

This repo includes a standard configuration as a useful starting point. It is located at ./config/standard.

Configuration is performed using Medic Configurer. medic-conf expects a particular structure (seen in the standard config above). It compiles forms and configuration into the required formats, as well as uploading that configuration and performing other tasks.

To import the standard configuration:

1. Install medic-conf: npm install -g medic-conf
2. Navigate to the configuration you want to import: cd <medic-repo>/config/standard
3. Ensure the app/api is running. Specifically on localhost for these instructions.
4. Import the config: medic-conf --url=http://username:password@localhost:5988

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

The Core Framework of the Community Health Toolkit is powered by people like you. We appreciate your contributions, and are dedicated to supporting the developers who improve our tools whenever possible.

First time contributor? Issues labeled help wanted are a great place to start.

Looking for other ways to help? You can also:

• Improve documentation. Check out our style guide here
• Find and mark duplicate issues
• Try to reproduce issues and help with troubleshooting
• Or share a new idea or question with us!

The easiest ways to get in touch are by raising issues in the medic Github repo or joining our Slack channel. You can even request access to our community forum.

For more information check out our contributor guidelines.

Builds brought to you courtesy of Travis CI.

Copyright 2013-2018 Medic Mobile, Inc. [email protected]

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.