Overview

The xlsform server runs https://xlsform.getodk.org. This repo describes how to setup that machine.

1. Provision a remote machine

We currently use a small (2 GB, 2 CPU, 20 GB) box running Ubuntu 18 LTS on Digital Ocean. We connect via SSH on port 22 with a private key. Passwords are disabled for remote root login.

You will need to create a user called ubuntu for Ansible to use. To ensure the ubuntu user can run passwordless sudo, run sudo visudo and add this on the last line.

ubuntu  ALL=(ALL) NOPASSWD: ALL

You'll also need to setup create a RSA key pair on the remote machine. Once you do:

1. Copy the ~/.ssh/id_rsa file to xlsform-server/secrets/id_rsa on the local machine.
2. Add id_rsa.pub to ~/.ssh/authorized_keys on the remote machine.

2. Install software on your local machine

1. Install ansible v2.2.0 or later.

3. Run ansible to configure remote machine

1. Clone or download this repo.
2. Read over playbook.yml and the files in roles/ to understand behavior.
3. Ensure the correct fully qualified hostname (not IP) to the machine is in hosts file.
4. Ensure id_rsa is in secrets/.
5. In xlsform-server/, run ansible-playbook -i provisioning/hosts provisioning/playbook.yml.

4. Running regular updates

To upgrade the operating system, run the following commands as root:

sudo apt-get update;
sudo apt-get upgrade -y;
sudo apt-get dist-upgrade -y;
sudo apt-get auto-remove -y;
sudo apt-get clean -y;

To upgrade pyxform, run the following commands as root:

/home/ubuntu/xlsform/xlsform_env/bin/pip3 install --upgrade pyxform;
systemctl restart gunicorn;
systemctl restart nginx;

To discard local changes and upgrade the site to the xlsform-online repo, run the following commands as root:

cd /home/ubuntu/xlsform/xlsform_src;
git clean --force;
git fetch origin;
git reset --hard origin/master;
systemctl restart gunicorn;
systemctl restart nginx;

Notes

You may wish to configure ansible to disable host checking and disable retry files.

If file transfers over SSH/SCP/SFTP fail for unexplainable reasons, try switching to paramiko