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:
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.
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 |
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 |
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.
https://hub.docker.com/_/mysql/
https://hub.docker.com/_/couchdb/
https://github.com/klaemo/docker-couchdb-lucene
https://hub.docker.com/r/rmohr/activemq/
https://gist.github.com/robcowie/3833088
Server for your App in 15 mins