Hosting the CHT on Amazon EC2
Self Hosting in CHT 3.x
Whether run on bare-metal or in a cloud provider, the Community Health Toolkit (CHT) core framework has been packaged into a docker container to make it portable and easy to install. It is available from dockerhub. To learn more how to work with docker you could follow the tutorial here and the cheat sheet here.
NoteBefore continuing, ensure all requirements are met.
Installing with a compose file
The CHT containers are installed using docker compose so that you can run multiple containers as a single service.
Start by choosing the location where you would like to save your compose configuration file. Then create the
docker-compose.yml file by
cding into the correct directory and running:
curl -s -o docker-compose.yml https://raw.githubusercontent.com/medic/cht-core/master/scripts/docker-helper/docker-compose-developer-3.x-only.yml
The install requires an admin password that it will configure in the database. You need to provide this externally as an environment variable. Before you run the compose file, you need to export this variable as shown below.
You can then run
docker-compose in the folder where you put your compose
docker-compose.yml file. To start, run it interactively to see all the logs on screen and be able to stop the containers with
sudo docker-compose up
If there are no errors, stop the containers with
c and then run it detached with
sudo docker-compose up -d
Note In certain shells,
docker-compose may not interpolate the admin password that was exported in
DOCKER_COUCHDB_ADMIN_PASSWORD. Check if this is the case by searching the logs in the medic-os dockers instance. If the
docker logs medic-os command below returns a user and password, then the export above failed, and you should use this user and password to complete the installation:
docker logs medic-os |grep 'New CouchDB Admin' Info: New CouchDB Administrative User: medic Info: New CouchDB Administrative Password: password
Monitor the logs until you get the
Setting up software (100% complete) message. At this stage all containers are fully set up.
Once containers are setup, please run the following command from your host terminal:
sudo docker exec -it medic-os /bin/bash -c "sed -i 's/--install=3.9.0/--complete-install/g' /srv/scripts/horticulturalist/postrun/horticulturalist" sudo docker exec -it medic-os /bin/bash -c "/boot/svc-disable medic-core openssh && /boot/svc-disable medic-rdbms && /boot/svc-disable medic-couch2pg"
The first command fixes a postrun script for horticulturalist to prevent unique scenarios of re-install. The second command removes extra services that you will not need.
Visit your project
If you’re running this on your local machine, then open a browser to https://localhost. Otherwise open a browser to the public IP of the host if it’s running remotely.
You will have to click to through the SSL Security warning. Click “Advanced” -> “Continue to site”.
Clean up and re-install
If some instructions were missed and there’s a broken CHT deployment, use the commands below to start afresh:
docker stop medic-os && docker stop haproxy
docker rm medic-os && docker rm haproxy
Clean data volume:
docker volume rm medic-data
docker-compose down -vwould do all the above 3 steps
docker system prune
After following the above commands, you can re-run docker-compose up and create a clean install:
docker-compose up -d
In case you are already running services on HTTP(80) and HTTPS(443),you will have to either remap ports to the medic-os container or stop the services using those ports.
To find out which service is using a conflicting port: On Linux:
sudo netstat -plnt | grep ':<port>'
On Mac (10.10 and above):
sudo lsof -iTCP -sTCP:LISTEN -n -P | grep ':<port>'
You can either kill the service which is occupying HTTP/HTTPS ports, or run the container with forwarded ports that are free. In your compose file, change the ports under medic-os:
services: medic-os: container_name: medic-os image: medicmobile/medic-os:cht-3.7.0-rc.1 volumes: - medic-data:/srv ports: - 8080:80 - 444:443
Turn off and remove all existing containers that were started:
sudo docker-compose down
Bring Up the containers in detached mode with the new forwarded ports.
sudo docker-compose up -d
Note: You can substitute 8080, 444 with whichever ports are free on your host. You would now visit https://localhost:444 to visit your project.
Data storage & persistence
NoteContainers that are already set up will lose all data when following the steps below to remap the
Docker containers are stateless by design. In order to persist your data when a container restarts you need to specify the volumes that the container can use to store data. The CHT app stores all its data in the
/srv folder. This is the folder that you need to map to your volume before you spin up your containers.
Ideally you should map this folder to a volume that is backed up regularly by your cloud hosting provider.
The example below shows how to map this folder in Ubuntu:
sudo mkdir /srv
Mount your volume to this folder:
sudo mount /dev/xvdg /srv. The attached volume number varies. Find your volume by running
Update your compose file so that the containers store data to this folder
services: medic-os: container_name: medic-os image: medicmobile/medic-os:cht-3.9.0-rc.2 volumes: - /srv:/srv ---- haproxy: container_name: haproxy image: medicmobile/haproxy:rc-1.17 volumes: - /srv:/srv
Alternatively, can create the
/srv folder on any drive with enough space that is regularly backed up. Then map the path to the folder in the compose file like this.
volumes: - /path/to/srv:/srv
Be sure to check the available storage space regularly and expand your volume when needed
Regular backups should be made of the
/srv directory to have holistic and easy to restore copies of all important data and the current CHT version installed. To backup just the data and not the CHT, make copies of
/srv/storage/medic-core/. This directory includes 4 key sub-directies:
To make backups of just CouchDB data outside of the CHT docker infrastructure, please see CouchDB’s Backup docs for 2.3.1. Please note:
- CouchDB data files are in
- Backing up via replication is discouraged as restored DBs can cause offline users to restart replication from zero. Use file backups instead.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.