Docker Setup

Docker is a software containerization platform.

Docker containers wrap a piece of software in a complete filesystem that contains everything needed to run: code, runtime, system tools, system libraries – anything that can be installed on a server. This guarantees that the software will always run the same, regardless of its environment.

This is useful when running OpenSRP server because it requires mysql, couchdb, couchdb-lucene, activemq and openmrs services to be installed.

Before going through this setup, checkout the links below to install docker:

Note: Install docker CE or EE version. Docker CS is not supported and permission errors may be experienced if using Docker CS version.
Docker CS (Commercially Supported) is kind of the old bundle version of Docker EE for versions <= 1.13.

Steps for setting up OpenSRP docker container

Build the container and remember to pass your preferred server tag from the releases here. This argument is required.

docker build -t onaio/opensrp --build-arg opensrp_server_tag=your_preferred_server_tag .

Other build arguments are optional and the default values have been defined in the docker file. You can change the values by updating the docker file or by passing the value to replace using --build-arg option.
Checkout the documentation here here.

Below is the list of docker build arguments

ARG opensrp_server_tag

ARG catatlina_opts="-server -Xms512m -Xmx1024m" 

#openmrs settings
ARG openmrs_url="http:\/\/localhost:8080\/openmrs\/"
ARG openmrs_username=admin
ARG openmrs_password=Admin123

#couchdb settings
ARG couchdb_username
ARG couchdb_password
ARG couchdb_opensrp_db=opensrp
ARG couchdb_form_db=opensrp-form
ARG couchdb_atomfeed_db=atomfeed
ARG couchdb_mcts_db=opensrp-mcts
ARG couchdb_motech_db=motech-scheduletracking-api
ARG couchdb_error_db=opensrp-errortrace
ENV COUCHDB_USER $couchdb_username
ENV COUCHDB_PASSWORD $couchdb_password

#mysql settings
ARG mysql_opensrp_user
ARG mysql_opensrp_password
ARG mysql_opensrp_database=opensrp
ARG mysql_openmrs_user
ARG mysql_openmrs_password
ARG mysql_openmrs_database=openmrs
ARG mysql_motech_database=motechquartz
ARG mysql_reporting_database=report
ARG mysql_anm_database=anm_report
ARG mysql_opensrp_jdbc="jdbc:mysql:\/\/localhost:3306\/${mysql_opensrp_database}?createDatabaseIfNotExist=true"
ARG mysql_opensrp_jdbc_wo="jdbc:mysql:\/\/localhost:3306"
ARG mysql_motech_jdbc="jdbc:mysql:\/\/localhost:3306\/${mysql_motech_database}"

#redis settings
ARG redis_password

#postgres settings
ARG postgres_opensrp_user
ARG postgres_opensrp_password
ARG postgres_opensrp_database=opensrp
ARG postgres_opensrp_jdbc="jdbc:postgresql:\/\/localhost:5432\/${postgres_opensrp_database}"ARG demo_data_tag

The below arguments are mandatory and must be specified when building the docker container

ARG opensrp_server_tag

#couchdb settings
ARG couchdb_username
ARG couchdb_password

#mysql settings
ARG mysql_opensrp_user
ARG mysql_opensrp_password
ARG mysql_openmrs_user
ARG mysql_openmrs_password

#redis settings
ARG redis_password#postgres settings
ARG postgres_opensrp_user
ARG postgres_opensrp_password

To replace the default value using --build-arg option. Run the following command

docker build -t onaio/opensrp --build-arg opensrp_server_tag=your_preferred_server_tag \ 
--build-arg couchdb_username=rootuser --build-arg couchdb_password=adminpass \
--build-arg mysql_opensrp_user=opensrp --build-arg mysql_opensrp_password=opensrp \
--build-arg mysql_openmrs_user=openmrs --build-arg mysql_openmrs_password=openmrs \
--build-arg redis_password=reallylongreallylongpass --build-arg postgres_opensrp_user=opensrp_admin \
--build-arg postgres_opensrp_password=admin .

Note: You can add a build arg demo_data_tag so that the launched containers contains demo(seed) data for a particular project. The value should be either zeir, tbreach or uganda-hpv. If the build arg is set openmrs database, opensrp database and images will be downloaded from S3 bucket. Below is an example when specifying to build with demo data

docker build -t onaio/opensrp --build-arg opensrp_server_tag=your_preferred_server_tag \ 
--build-arg couchdb_username=rootuser --build-arg couchdb_password=adminpass \
--build-arg mysql_opensrp_user=opensrp --build-arg mysql_opensrp_password=opensrp \
--build-arg mysql_openmrs_user=openmrs --build-arg mysql_openmrs_password=openmrs \
--build-arg redis_password=reallylongreallylongpass --build-arg postgres_opensrp_user=opensrp_admin \
--build-arg postgres_opensrp_password=admin --build-arg demo_data_tag=your_preferred_demo_data_tag .

Create .entry_pont_env file to store variables and credentials. For example, create a file with the following details..

#!/bin/sh
POSTGRES_MAIN_PASSWORD=mainpassword
POSTGRES_OPENSRP_TABLESPACE_DIR=/opt/postgresql
MYSQL_ROOT_PASSWORD=mypassword

Run the container

docker run -d --name='opensrp' --env-file .entry_point_env  \
-v opensrp_migrations:/etc/migrations -v opensrp_couchdb:/usr/local/var/lib/couchdb -v opensrp_couchdb_lucene:/opt/couchdb-lucene/indexes \
-v opensrp_mysql:/var/lib/mysql -v opensrp_redis:/data \
-v opensrp_postgres:/var/lib/postgresql/data -v opensrp_postgres_tablespaces:/opt/postgresql \
-p 9090:8080 -p 9091:8081 onaio/opensrp

The docker run command given starts a container named 'opensrp' with the following variables and ports. This also mounts the data directories that stores data that needs to be persistent across container restarts e.g mysql data, postgres data.
Note:The last volume i.e opensrp_postgres_tablespaces:/opt/postgresql ; the mapped directory should have the value of the environment variable POSTGRES_OPENSRP_TABLESPACE_DIR passed to the container via env file .entry_point_env. POSTGRES_OPENSRP_TABLESPACE_DIR controls the directory that stores opensrp data in postgres database.

Variables https://docs.docker.com/engine/reference/run/#/env-environment-variables

ENV	Description
POSTGRES_MAIN_PASSWORD	password for postgres user
POSTGRES_OPENSRP_TABLESPACE_DIR	postgres directory where opensrp table spaces will be created
MYSQL_ROOT_PASSWORD	password for mysql root user

Ports https://docs.docker.com/engine/reference/run/#/expose-incoming-ports

Service	Host Port	Container Port
postgresql	Not configured	5432
mysql	Not configured	3306
couchdb	Not configured	5984
couchdb-lucene	Not configured	5985
activemq	Not configured	8161
activemq	Not configured	61616
redis	Not configured	6379
opensrp (tomcat7)	9090	8080
openmrs (tomcat7)	9091	8081

NB: Host ports can be changed i.e. if mysql is already installed in port 3306, host port 3306 can be changed to 3307.

Check the logs
```
docker logs -f opensrp
```
-f option follows log output.
No errors/exceptions should be displayed in the logs if the container has started successfully.
Test the services
Service Link Credentials
OpenSRP http://localhost:9090/opensrp
OpenMRS http://localhost:9091/openmrs admin/Admin123

Some useful commands

Command	Description
docker stop opensrp	Stops opensrp container
docker rm opensrp	Removes opensrp container
docker rmi onaio/opensrp	Removes onaio/opensrp image
docker exec -it opensrp bash	Go to opensrp container
docker ps -a (-a shows all containers)	List containers
docker images	List images
docker volume ls \| grep volume_name	list mounted volumes
docker volume rm volume_name	delete volume
docker volume rm opensrp_couchdb opensrp_couchdb_lucene \ opensrp_mysql opensrp_postgres opensrp_redis \ opensrp_postgres_tablespaces opensrp_migrations	Delete all opensrp volumes

Checkout Docker Compose Setup for an advanced docker setup.

Checkout Cloudant Sync Security Configuration especially step 8 for information on how to link lucene with a secure CouchDB. This can be helpful when COUCHDB_USER and COUCHDB_PASSWORD variables have been set.