Medic Mobile
These instructions should help you get setup to run or develop on Medic Mobile. For latest changes and release announcements see our change log.
Overview
Medic Mobile combines messaging, data collection, and analytics for health workers and health systems in hard-to-reach areas with or without internet connectivity.
The medic
repository is the core tool of the Medic Mobile stack. When health workers submit data โ using text messages (SMS), our mobile applications, or our SIM applications โ the web app confirms data submission, generates unique IDs, and schedules automated reminder messages based on user-defined configurations. All information submitted by mobile users can be viewed, filtered, verified, and exported using the reports tab in the web application.
The web app is fully responsive with a mobile-first design, and supports localization using any written language. It can be installed locally or in the cloud by setting up the individual components or as a Docker container.
Currently, we functionally support the latest versions of Chrome, Chrome for Android and Firefox. We do not support Safari (unreliable implementations of web APIs we need) 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.
For more information about Medic Mobile's tools, visit http://medicmobile.org/tools. 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.
Easy Deployment
If you want to get up and running with no fuss, you can use Docker.
Once up and running you can create your own custom application, or set up the standard application by running the Medic Configurer on the ./config/standard directory.
If you want to develop against the underlying framework of Medic and set up components individually, follow the Development Setup below.
Development Setup
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.
Dependencies
You will need to install the following:
Setup CouchDB on a single node
NB: multiple CouchDB nodes will be more complicated, but the general pattern outlined below will be the same.
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 Medic 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 that's done, we must 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"
Build and run
Build the webapp
git clone https://github.com/medic/medic
cd medic
npm ci
Deploy all the apps
Create a .env
file in the app directory with the following contents
COUCH_URL=http://myAdminUser:myAdminPass@localhost:5984/medic
COUCH_NODE_NAME=couchdb@localhost
Then do an initial deploy of the webapp:
grunt dev-webapp
# or just
grunt
Once this is complete you can close it, and from now on you can just run:
npm start
which will start the webapp, api, and sentinel, and watch for changes in each app.
Deploy apps individually
If npm start
is not to your taste for whatever reason, the apps can be deployed individually.
Deploy the webapp
grunt dev-webapp
will build and deploy the webapp, then watch for changes and redeploy when necessary.
Start medic-sentinel
cd sentinel
npm ci
export COUCH_NODE_NAME=couchdb@localhost
export COUCH_URL=http://myAdminUser:myAdminPass@localhost:5984/medic
Then run either node ./server.js
from the sentinel directory or grunt dev-sentinel
from the repository directory (which will watch for changes).
Start medic-api
cd api
npm ci
export COUCH_NODE_NAME=couchdb@localhost
export COUCH_URL=http://myAdminUser:myAdminPass@localhost:5984/medic
Then run either node ./server.js
from the api directory or grunt dev-api
from the repository directory (which will watch for changes).
Try it out
Navigate your browser to http://localhost:5988/medic/login
.
Data
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
Localization
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.
Tests
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
.
API integration tests
grunt api-e2e
Integration tests
Travis runs grunt ci
every time some new code is pushed to github.
Configuring Medic
We ship with one "standard" configuration, which can be a useful basis to start with. 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:
- Install medic-conf:
npm install -g medic-conf
- Navigate to the configuration you want to import:
cd config/standard
- Import the config:
medic-conf --url http://username:password@localhost:5984
Automated Deployment on Travis
Code is automatically published via Travis CI to the staging server.
Contributing
At Medic Mobile we are the technical steward of the Community Health Toolkit. We welcome and appreciate contributions, and support new developers to use the tools whenever possible. If you have an idea or a question we'd love to hear from you! The easiest ways to get in touch are by raising issues in the medic Github repo or joining our Slack channel. For more info check out our contributor guidelines.
Build Status
Builds brought to you courtesy of Travis CI.
Copyright
Copyright 2013-2018 Medic Mobile, Inc. [email protected]
License
The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.