Install CommCare Sync for Production

This page outlines the process you need to follow in order to set up a CommCare Sync instance on a production machine.

Choose a location for the control

While it is possible to run the ansible playbooks from anywhere, it is recommended to run them on the server you are setting up. This will ensure consistency and also streamline the install process.

These instructions assume a set up where the ansible control and playbooks are run on the server being set up.

Install Ansible

From the Ansible Installation Guide, run the following on your control machine.

sudo apt-add-repository ppa:ansible/ansible
sudo apt-get update
sudo apt-get install ansible

Install CommCare Sync

Set up user accounts

On the server, create an account for the ansible user to use. This can be done with the following command, answering the prompts.

sudo adduser ansible

Clone the repository

git clone

Prepare your environment

Initialize Inventory Folder

Production environments live in the inventories/ folder. First create a new inventory folder for your environment (we’ll use myproject as an example). This is where your project-specific configuration will live.

mkdir -p inventories/myproject
cp -r inventories/example/* inventories/myproject

Update Inventory Files

Edit the following files with your project-specific changes:

  • inventories/myproject/hosts.yml

    • vars.env: your environment name

    • hosts.local1.ansible_user: username of your ansible user

    • hosts.local1.ansible_host: hostname/public IP where your ansible user lives

  • inventories/myproject/group_vars/commcare_sync/vars.yml

    • public_host: your commcare-sync hostname

    • superset_public_host: your superset hostname

    • superset_enabled: specifies whether Superset should be installed

Ansible Vault

Production environments should use Ansible Vault to manage secrets. That page has lots of details about editing and using files with Vault.

The example environment includes a vault file which you should remove:

rm inventories/myproject/group_vars/commcare_sync/vault.yml

Initial Vault Setup

The following one-time setup is used to generate keys / files for Ansible Vault.

Generate Vault Key

openssl rand -base64 2048 > ~/myproject-ansible-vault

Create Vault Vars File

ansible-vault create --vault-password-file ~/myproject-ansible-vault ./inventories/myproject/group_vars/commcare_sync/vault.yml

Add your secrets here, e.g.

# My Project Vault File

vault_default_db_password: <secret1>
vault_django_secret_key: <secret2>
vault_mapbox_api_key: <secret3>
vault_django_secret_key: <secret4>

(You can generate a good random key from a command line:)

$ python3 -c 'import string
import secrets
chars = string.ascii_letters + string.digits
key = "".join(secrets.choice(chars) for x in range(64))

You run the following to edit the file later:

ansible-vault edit --vault-password-file ~/myproject-ansible-vault ./inventories/myproject/group_vars/commcare_sync/vault.yml

SSH access

Assuming you are running on AWS, Copy the AWS private key to ~/myproject.pem on your local machine.

You may also need to change permissions on it.

chmod 400 ~/myproject.pem

Test it’s working:

ssh -i ~/myproject.pem ubuntu@my.server.ip

Set hostname

On the remote server

sudo hostnamectl set-hostname myproject-server

Run the installation scripts

ansible-galaxy install -r requirements.yml
ansible-playbook -i inventories/myproject commcare_sync.yml --vault-password-file ~/myproject-ansible-vault -vv

Settting up HTTPS

HTTPS set up is currently not supported by this tool. To set up SSL, login to your machine and install certbot:

sudo apt install certbot python3-certbot-nginx

Then run:

sudo certbot --nginx

and follow the prompts.

You’ll need to repeat this process for each site (e.g. commcare-sync and superset). You may also need to open up port 443 on AWS or your firewall.

After setting up HTTPS you should set ssl_enabled=yes and superset_ssl_enabled=yes in your vars.yml file, otherwise running a full ansible-playbook will undo the changes!

You can set ssl_enabled=yes and superset_ssl_enabled=yes to prevent this from happening after enabling SSL support.