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 https://github.com/dimagi/commcare-sync-ansible.git
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 namehosts.local1.ansible_user
: username of your ansible userhosts.local1.ansible_host
: hostname/public IP where your ansible user lives
inventories/myproject/group_vars/commcare_sync/vars.yml
public_host
: your commcare-sync hostnamesuperset_public_host
: your superset hostnamesuperset_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))
print(key)'
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
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.