This document will walk you through the process of updating the CommCareHQ code on your server using
Ensure that you have a working version of
commcare-cloud which is configured to act on your monolith or fleet of servers. You can find more information on setting up
commcare-cloud in the installing
If you don’t yet have a server with CommCareHQ, you can try setting up a monolith.
All commands listed here will be run from your control machine which has
We first want to pull the latest code for
commcare-cloud to make sure it has the latest bugfixes by running:
This command will update the
commcare-cloud command from GitHub and apply any updates required. You can see exactly what this command does in this file.
CommCareHQ is deployed using
fabric, which ensures only the necessary code is deployed to each machine.
deploy command by running:
$ commcare-cloud <env> deploy
where you will substitute
<env> for the name of the environment you wish to deploy to.
The first step in deploy is what we call a
preindex, which updates any CouchDB views and Elasticsearch indices. This only runs when changes need to be made, and may take a while depending on the volume of data that you have in these data stores. You may need to wait for this process to complete in order to complete deploy.
If your server has email capabilities, you can look out for an email notification with the subject:
[<env>_preindex] HQAdmin preindex_everything may or may not be complete. This will be sent to the
SERVER_EMAIL email address defined in the Django settings file.
You can also try running:
$ commcare-cloud <env> django-manage preindex_everything --check
If this command exits with no output, there is still a preindex ongoing.
Once deploy has completed successfully, the script will automatically restart each service, as required. You can check that the system is in a good state by running:
$ commcare-cloud <env> django-manage check_services
This will provide a list of all services which are running in an unexpected state.
You may also wish to monitor the following pages, which provide similar information if you are logged in to CommCareHQ as a superuser:
The following commands may be useful in certain circumstances.
When there are changes that require a reindex of some database indexes it is possible to do that indexing prior to the deploy so that the deploy goes more smoothly.
Examples of change that woud result in a reindex are changes to a CouchDB view, or changes to an Elasticsearch index.
To perform a pre-index:
$ commcare-cloud <env> fab preindex_views
If something goes wrong and the deploy fails part way through you may be able to resume it as follows:
$ commcare-cloud <env> deploy --resume
You may also wish to revert to a previous version of the CommCareHQ code if the version you just deployed was not working for some reason. Before reverting, you should ensure that there were no database migrations that were run during the previous deploy that would break if you revert to a previous version.
$ commcare-cloud <env> fab rollback
In addition to the regular deploy, you must also separately deploy the service that backs Web Apps and App Preview, called formplayer. Since it is updated less frequently, we recommend deploying formplayer changes less frequently as well. Doing so causes about 1 minute of service interruption to Web Apps and App Preview, but keeps these services up to date.
commcare-cloud <env> deploy formplayer
Internally at Dimagi the main cloud environment is deployed every weekday.
However, for locally hosted deployments, we recommend deploying once a week (for example, every Wednesday), to keep up to date with new features and security patches.
Since CommCareHQ is an Open Source project, you can see all the new features that were recently merged by looking at the merged pull requests on GitHub.
In addition to the regular deploy, we recommend deploying formplayer once a month.