Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A server-side tool to help manage community health workers, written in Django
Python HTML JavaScript CSS Shell ActionScript
Tree: 647a5ea62e

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

CommCare HQ

CommCare HQ is a server-side tool to help manage community health workers. It seamlessly integrates with CommCare mobile and CommCare ODK, as well as providing generic domain management and form data-collection functionality.

Key Components

  • CommCare application builder
  • OpenRosa compliant xForms designer
  • SMS integration
  • Domain/user/CHW management
  • Xforms data collection
  • Case management
  • Over-the-air (ota) restore of user and cases
  • Integrated web and email reporting

Basic Project Structure

  • submodules/ - submodule reference to the meat of the code (which lives in many other packages, particularly core-hq)
  • libs/ - Third party libs (presumably python) that you'll need to reference
  • scripts/ - Any helper scripts you'll want to write to deal with data and or other things. This stuff should probably run outside the scope of the python environment

Installing CommCare HQ

Please note, these instructions are targeted toward UNIX-based systems.


The following are necessary for the basic function of CommCare HQ.

Note on couchdb installation: Using aptitude or apt-get may not install the latest version. See other installation options if version < 1.0 is installed by using this method.

Configurations for postgres

It is recommended that you create the database commcarehq before continuing.

Configuration for CouchDB

It is recommended that you create the database commcarehq before continuing.

Setting up a virtualenv

A virtualenv is not required, but it may make your life easier.

To install:

sudo pip install virtualenv     # or sudo easy_install virtualenv
mkdir ~/.virtualenvs/
virtualenv ~/.virtualenvs/commcare-hq --no-site-packages

Run source ~/.virtualenvs/commcare-hq/bin/activate to enter your virtualenv.

libmagic is required by python-magic, which pip will install automatically. Unfortunately, on Mac OS X, pip doesn't install libmagic itself. To add it, just

 brew install libmagic

HQ Bootstrap Requirements

We use our own flavor of Twitter Bootstrap for our user interface. Please check the README on our HQ Bootstrap project page for requirements and instructions. Most notably, you will need lessc and uglify-js to compile HQ Bootstrap.

Install CommCare HQ

Once all the requirements are in order, please do the following:

git clone
cd commcare-hq
git submodule update --init --recursive
source ~/.virtualenvs/commcare-hq/bin/activate      # enter your virtualenv if you have one
pip install -r requirements.txt


Make the necessary edits to (database passwords, email configuration, etc.). Things to note:

  • Make sure the postgres settings match your expectations (for instance, the postgres user password likely needs to be changed from the ***** in the file)
  • Make sure the CouchDB settings match your expectations
  • Make sure the following lines are correct and that the directories exist and are accessible by your user. Feel free to change the paths to your liking. DJANGO_LOG_FILE = "/var/log/datahq/datahq.django.log" LOG_FILE = "/var/log/datahq/datahq.log"

Set up your django environment

Please make sure you're still in the root directory of commcare-hq and that you are inside the correct virtualenv (if you are using one).

./ syncdb
./ migrate
# this will do some basic setup, create a superuser, and create a project
./ bootstrap <project-name> <email> <password>
./ make_bootstrap # (if it fails add the 'direct-lessc' directive)
./ collectstatic

Don't forget to start up helper processes

memcached (a lightweight cacher)

memcached -d


Enable  Lucene settings in (to view  case list in the  Report section)

Celery (asynchronous task scheduler)

./ celeryd -v 2 -B -s celery -E

Get CommCare Binaries

In order to build and download a CommCare mobile app from your instance of CommCare HQ, you need to follow our instructions for how to download and load CommCare binaries from the Dimagi build server:

A Note about requirements.txt

If an import isn't working it may well be because we aren't specifying all versions in the requirements.txt and you have an old version. If you figure out this problem and figure out what version we should be using, feel free to add it to requirements.txt as ">" like so: couchdbkit>=0.5.2 (Use == for exact version instead of lower bound.)

Something went wrong with that request. Please try again.