Deployment Guide

RapidPro

1. Create a RapidPro account and get the API key for that account (you will need this key for the below provisioning steps).
2. Clone the appropriate flows from an existing RapidPro account and import them into your new account.
3. Within each flow, make sure to point the Webhooks to the appropriate EUMS hostname (which is specified below in the provisioning steps).
4. Make sure to apply the following labels to the corresponding flows (it is important to specify these correctly in order for the EUMS application to work):

Flow	Label Name
IP Flow	IMPLEMENTING_PARTNER
Middle Man / Sub-consignee Flow	SUB_CONSIGNEES
End User Flow	END_USER

EUMS

Environment Variables

The following environment variables need to be set in order for a successful deployment. Note that for deploying from the CI server, the 'Secure Variable?' column refers to whether the variable needs to be set in the Secure Variable section of the 'Environment Variables' tab in the top level section for the pipeline. If you are not deploying EUMS from the CI server, disregard that column.

Variable Name	Secure Variable?	Explanation
DEPLOY_USER	No	this is the deploy user you will set up in step 1 below
DEPLOY_HOST	No	this is the IP or hostname of the production server
EUMS_HOST	No	this will be the hostname of the production server
DJANGO_SECRET_KEY	Yes	this should be set to a unique, unpredictable value
RAPIDPRO_API_TOKEN	Yes	this is the token that corresponds to the appropriate RapidPro account that the production server will be talking to
EMAIL_PASSWORD	Yes	we are unsure if this is necessary so can put a random placeholder here for now
VISION_USER	Yes	this is the user name you will use to sync the vision data
VISION_PASSWORD	Yes	this is the password you will use to sync the vision data
VISION_BUSINESS_AREA_CODE	No	this is the business area code you will use to sync the vision data
TIME_ZONE	No	the time zone for your instance; you can find time zones here
MAP_LATITUDE	No	the latitude that represents the center latitude of your respective map; use this tool to find the center latitude
MAP_LONGITUDE	No	the longitude that represents the center longitude of your respective map; use this tool to find the center longitude
MAP_LEVEL	No	this is the zoom level for your respective map; use this tool to find the zoom level
ADMIN_PASSWORD	Yes	this is the password for the EUMS super user for logging into the EUMS system after a deploy

Deployment Steps

Below are the steps for deploying EUMS. Follow the appropriate steps depending on whether you are deploying EUMS using the Go CI server, or whether you are deploying from a separate machine.

1. (one-time only) Set up initial configuration for the production server.

• Create a deploy user with a home directory (no password necessary).
• Allow remote access via public / private keys.
  • Create or retrieve the public key for the machine you are deploying from.
  • Copy this public key to a 'authorized_keys' file within the the /home/<name-of-deploy-user>/.ssh/ directory on the production server.
• Allow this user to run sudo on any command without a password.
  • Run 'sudo visudo'
  • Add this line to the bottom of the file: 'deployuser ALL=(ALL) NOPASSWD:ALL' (without quotes)

2a. (Deploying from CI server) Set up a new pipeline for your production deploy.

• (one-time only) Clone a previous production-like pipeline. Make sure the name reflects your new production deploy (e.g. 'eums-prod-uganda').
• (one-time only) Update the environment variables in the pipeline's top level 'Environment Variables' tab. Refer to the above environment variables table. Save the new pipeline.
• (one-time only) Place the new pipeline within the 'eums-prod' environment. You can do this via the 'Environments' menu item a the top of the page.
• (one-time only) Un-pause the pipeline.
• Kick off the first stage of the pipeline, 'fetch-artifacts'. Wait for this stage and the 'packaging' stage to complete.
• Once the 'packaging' stage is complete, place the map in the appropriate directory.
  • ssh into the CI server. Switch to the go user (sudo su - go)
  • cd to the /var/lib/go-agent2/pipelines/<name of your new pipeline>/
  • Create a 'map' directory in this directory.
  • Within the 'map' directory, place your map GeoJSON file. This map GeoJSON file must be named 'districts.json'.
  • Verify your map environment variables are set correctly. This tool provides a way to find the appropriate latitude, longitude, and zoom level of your map for EUMS.
• Kick off the 'deploy-qa' stage. This should take roughly 10-15 minutes, due to the current size of the Docker image.

2b. (Deploying from non-CI server) Download the desired artifacts from the EUMS CI server to the machine from where you will deploy (which is different from the production server).

• Log in to http://41.210.128.38/, go to the desired eums-demo build, and go into the latest 'packaging' stage, and click on the 'packaging-job' job. There you will see a tab called 'Artifacts'.
• Download all the items within the 'build' directory. Note that you will need to download all the files individually. Make sure that when everything is downloaded, you create the same directory structure that existed on the CI server (i.e. there is a build/ directory with a /deployment directory within it, as well as two files, 'eums_docker_image.tar' and 'install-image-eums.sh', etc.).
• Make sure all the scripts are executable within the build/ and deployment/ directories.
• Now create a 'maps' directory at the same level as the build/ directory. Place your map GeoJSON file into this new map/ directory. This map GeoJSON file must be named 'districts.json'.
• Set up the appropriate environment variables and run the deploy script. Refer to the variables in the table in step #2.
• Once environment variables are set, copy the build/deployment/deploy.sh file to your current directory (deploy.sh should be at the same level as build/ directory).
• Run deploy.sh. This should take roughly 10-15 minutes, due to the current size of the Docker image.

Troubleshooting

Elastic Search is necessary for some of the report pages to function properly. If you find it is not running properly on the production server, this could be because it did not get re-indexed properly on the deploy. To fix this, ssh into the Docker container and follow these steps:

cd /opt/app/eums
source ~/.virtualenvs/eums/bin/activate
python manage.py shell_plus < eums/elasticsearch/run_sync.py