System Administration


CommCare Sync deployments use an “infrastructure as code” philosophy which means all configuration is documented in code files. See the sections below to access everything needed to configure the system.


The complete list of services is available in the roles/commcare_sync/tasks/main.yml file.

The most important ones are summarized on the what’s installed page.

Common Tasks

Some of the common tasks needed to manage an environment.

Enabling/Disabling Public Sign Ups

Sign ups are currently configured via the Django ACCOUNT_ADAPTER setting. To enable anyone to sign up, you should set it to EmailAsUsernameAdapter. To disable public account creation, set it to NoNewUsersAccountAdapter. This behavior is controlled by the django_allow_public_signups Ansible variable.

If public sign ups are disabled, then only superusers can create new accounts, via the Django admin UI or command line.

Deploying Changes

You may wish to deploy updates to the server, for example to pull the latest changes from the CommCare Sync code.

The command to deploy updates is:

ansible-playbook -i inventories/yourapp commcare_sync.yml --vault-password-file /path/to/password/file -vv --tags=deploy

Changes can also be deployed from the CommCare Sync codebase itself by following the instructions in the README.

Accessing the Virtual Environment

To access the virtual environments for commcare sync and superset, run the following commands:

source <venv>/bin/activate
source <venv>/bin/postactivate

On most servers the commcare-sync is at ~/www/.virtualenvs/commcare-sync and the superset is at ~/www/.virtualenvs/superset.

The second command is required to set the project-specific environment variables to the correct values.

Other Useful commands

Task Command
See running supervisor processes sudo supervisorctl status
Restart a supervisor processes sudo supervisorctl restart [process name]
Connect to database sudo -u postgres psql
Restart Nginx `sudo service nginx restart

Checking for Stuck Exports

The logs for running exports don’t show up in the UI until they complete. The easiest way to see if an export is still running or if it is stuck/was killed is to login to the server and just run a command to see what “commcare-export” processes are running. E.g.

ps -ef | grep commcare-export

Database Management

Because CommCare Sync does not provide direct access to the underlying databases, it is common to have to perform database management tasks, for example, creating new databases, or dropping existing databases or tables.

Database management can be done by logging into the server and getting a postgres shell:

psql -U [postgres user] -h localhost -p 5432

You will need the postgres username and password from the secrets file, or by finding it on the server e.g. in the django commcare_sync/ file. You can also run ./ dbshell in the CommCare Sync virtual environment.