Syncing local HQ instance with an Android Phone

No syncing or submitting, easy method

If you would like to use a url or barcode scanner to download the application to

your phone here is what you need to setup. You won’t be able to submit or sync

using this method, but it is easier.

Make sure your local django application is accessible over the network

The django server will need to be running on an ip address instead of localhost.

To do this, run the application using the following command, substituting your

local IP address.

./ runserver

Try accessing this url from the browser on your phone to make sure it works.

Make CommCare use this IP address

The url an application was created on gets stored for use by the app builder

during site creation. This means if you created a site and application

previously, while using a ‘localhost:8000’ url, you will have to make a code

tweak to have the app builder behave properly.

The easiest way to check this is to see what url is shown below the barcode on

the deploy screen.

If it is currently displaying a localhost:8000/a/yourapp/... url then open and set BASE_ADDRESS = "" substituting with your local IP address.

Try it out

With this set up, you should be able to scan the barcode from your phone to

download and install your own locally built CommCare application!

Submitting and syncing from your local HQ instance (harder method)

Install nginx

sudo apt-get install nginx or

brew install nginx

Install the configuration file

In /etc/nginx/nginx.conf, at the bottom of the http{} block, above any other site includes, add the line:

include /path/to/commcarehq/deployment/nginx/cchq_local_nginx.conf;

Start nginx

sudo nginx

Make sure your local django application is accessible over the network

./ runserver

Try accessing http://localhost/a/domain and see if it works. nginx should

proxy all requests to localhost to your django server.

Make Commcare use your local IP address

Set the BASE_ADDRESS setting in to your IP address (e.g., without a port.

Additionally, modify deployment/nginx/cchq_local_nginx.conf to replace localhost with your IP address as server_name. For example, set server_name as Then run sudo nginx -s reload or brew services restart nginx to reload configuration.

You should now be able to access http://your_ip_address/a/domain from a phone or other device on the same network.

Note: You’ll have to update these if you ever change networks or get a new IP address.

Rebuild and redeploy your application

You’ll have to rebuild and redeploy your application to get it to sync.

Directly Modifying App Builds (CCZ files)

During development, it’s occasionally useful to directly edit app files.

CommCare apps are bundled as .ccz files, which are just zip files with a custom extension.

See for utilities for unzipping, editing, and rezipping CCZ files. Doing this via the command line is often cleaner than doing it an in OS, which may add additional hidden files.

Adding CommCare Builds to CommCare HQ

Using a management command

  • ./ add_commcare_build –latest To fetch the latest released build from github

  • ./ add_commcare_build –build_version 2.53.0 To manually specify the build number to use

In the web UI

  • Go to http://HQ_ADDRESS/builds/edit_menu/

  • In the second section Import a new build from the build server

    1. In the Version field input the version in x.y.z format

    2. Click Import Build

  • In the first section Menu Options add the version to HQ to make sure the build is available in the app settings.