Developer Installation Guide

Installation Guide

Introduction
Security considerations
Install Docker and Docker Compose
Install CfL distribution
Download the distribution files
Stop the CfL distribution
Backup the distribution data
Update the distribution data
Delete the distribution data
Login into server container
Manage the docker containers
Configure Message Deliveries Job
Sources

Introduction

The main purpose of this document is to describe the process of installation of the CFL distribution and process of maintaining this distribution.

The CFL distribution recommended using the docker to host and maintain the distribution. Docker gives the possibility to easily install and maintain the distribution through using the unit of software called a docker container. The whole distribution can be hosted as a unit based on specific docker containers (an example of docker infrastructure can be found on image 1). More information about docker can be found here: https://www.docker.com/resources/what-container

Example of dockerized architecture:

Docker is a multiplatform tool in which you should be able to execute this installation guide on your operating systems (if you have an issue with some of the docker commands please check docker documentation. For instance there is information about how to use docker on Windows OS https://docs.docker.com/docker-for-windows).

Security considerations

The default installation of Connect for Life™ serves the application over HTTP protocol. The HTTP is simple to use as it doesn't require to setup encyption certificates, but it's not secure. It is highly recommended to setup Web Application Firewall before the application host server and to expose the Connect for Life™ application over WAF's HTTPS connection to the internet.

Install Docker and Docker Compose

Running Docker on local environment

Installation of Docker looks different according to the operating system. To install Docker choose the platform and follow the instructions placed on the official page: https://docs.docker.com/get-docker

After installation of Docker you should be able to install docker-compose which also depends on the operating system. The installation process is distributed on the following page: https://docs.docker.com/compose/install

Running Docker on remote cloud

Instruction how to install Docker on AWS can be found here: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/docker-basics.html

Instruction how to use Docker on digitalocean can be found here: https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04

Installation Docker offline

If the target environment requires installation offline (missing or unstable internet connection) you can use the Docker Trusted Registry. More information can be found here: https://docs.docker.com/datacenter/dtr/2.0/install/install-dtr-offline

Additionally, in that case it will be required to extract and transfer Docker images using some physical memory like pen drive. To do so first you will need to download all required components on devices with stable internet connection. To extract the Docker images the following command will be useful: https://docs.docker.com/engine/reference/commandline/save

To load this image on the target environment the following command will be useful: https://docs.docker.com/engine/reference/commandline/load

Install CfL distribution

CFL is installed as a unit and this is the reason why the Docker tool was chosen. The main goal of this is to minimize the number of required steps that need to be performed to install the CFL distribution.

To perform the installation process you will need the following things:

Get the docker-compose.yml file (described in the ‘Docker compose file’ section)
Execute the following command: docker-compose up (described in the ‘Set up distribution’ section).

More information about that will be described in the following subsections.

Download the distribution files

The distribution files are available under the following link: https://github.com/johnsonandjohnson/openmrs-distro-cfl/archive/refs/heads/main.zip

Docker compose file

In the CFL distribution files (cfl/ directory) you can find the main docker-compose.yml which is used to create required distribution modules.

version: '2'

services:
	web:
		build: web
		image: openmrscfldemodistro:1.0.0
		environment:
			DB_DATABASE: openmrs
			DB_HOST: ${DB_HOST}
			DB_USERNAME: ${DB_USERNAME}
			DB_PASSWORD: ${DB_PASSWORD}
			DB_CREATE_TABLES: 'false' # change to 'true' if using an empty database
			DB_AUTO_UPDATE: 'false' # change to 'true' if using an empty database
			MODULE_WEB_ADMIN: 'true' # allow web admin on OpenMRS
			COPY_CFL_MODULES: 'false'
		volumes:
			-web-data:/usr/local/tomcat/.OpenMRS
			-~/.cfl-dev/modules:/usr/local/tomcat/.OpenMRS/modules/
			-~/.cfl-dev/owa:/usr/local/tomcat/.OpenMRS/owa/
volumes:
	web-data:

The CFL distribution is based on the reference application distribution. That’s why the configuration is similar to the configuration of refApp distribution. For the distribution several docker compose profiles, which can be used based on preferred configuration, are prepared. Those profiles are defined by the following docker-compose files:

Docker-compose.db.yml - used to host the database in a local environment. Note: important if you don’t intend to use external database
Docker-compose.dev.yml - used to run distribution with development mode. More info: https://wiki.openmrs.org/display/docs/Using+the+UI+Framework+in+Your+Module
Docker-compose.module-reload.yml - used to reload CFL specific modules
Docker-compose.override.yml - default port mapping and mode used during development
Docker-compose.prod.yml - port mapping recommended for production mode

Docker image file

In the “cfl/web/” directory a file can be found used to prepare the CFL web application docker image.

Environment variable - configuration

Most of the environment variables are defined in the “cfl/web/.env” file. Example of values can be found below:

MYSQL_DEV_PORT=3306
TOMCAT_DEV_PORT=8080
TOMCAT_DEV_DEBUG_PORT=1044
TOMCAT_PORT=80
DB_HOST=db
DB_USERNAME=openmrs
DB_PASSWORD=Admin123
DB_ROOT_PASSWORD=Admin123
DEV_MODE_DIR=/home/user/cfl
DEV_MODE_MODULES=messages

Note: By default the distribution is prepared to work with dockerized Database. In order to change that you have to change the following environment variables:

DB_HOST
DB_USERNAME
DB_PASSWORD

To run distribution with RDS

In order to run distribution with RDS you have to change the following environment variables:

DB_HOST
DB_USERNAME
DB_PASSWORD

Set up distribution

Follow the steps below to set up the cfl distribution:

Go to downloaded CFL distribution directory
Go to cfl directory
```
 cd cfl/
```
Make sure that environment variables are set properly (in file “cfl/web/.env”)
Run the following command:
```
 docker-compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.module-reload.yml up --build -d
```
Note: If you want to use dockerized database, then you have to run the appropriate profile and add “-f docker-compose.db.yml”
(optional) if you want to show the server logs, run the following command:
```
 docker-compose logs -f --tail 100
```
All required images should be downloaded and build, after that CFL distribution should be accessible under the: http://localhost/openmrs

Run in development mode

Follow the steps below to set up the cfl distribution:

Go to downloaded CFL distribution directory
Go to cfl directory
```
 cd cfl/
```

Run the following command:

 docker-compose -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.db.yml -f docker-compose.module-reload.yml -f docker-compose.dev.yml up --build -d

(optional) if you want to show the server logs, run the following command:
```
 docker-compose logs -f --tail 100
```
All required images should be downloaded and build, after that CFL distribution should be accessible under the: http://localhost:8080/openmrs

Note: You can also use a prepared bash script (“runInDevMode.sh” ) in order to run the environment in development mode. Script is located in: “cfl/runInDevMode.sh”.

Stop the CfL distribution

Execute the following command to stop the distribution:

docker-compose stop

Backup the distribution data

The script placed below can be used to create the dump of the database and to copy the OpenMRS configuration files (from .OpenMRS directory). Database user and password can be placed on the top variables.

#!/bin/bash
DB_USER=root
DB_PASSWORD=Admin123
webId=`docker ps --filter "name=cfl_web*" -q`
dbId=`docker ps --filter "name=cfl_db*" -q`

echo "Web container id:  $webId"

BACKUP_DIR_PREFIX=backup
ROOT_BACKUP_DIR=./backups
BACKUP_DIR=$ROOT_BACKUP_DIR/$BACKUP_DIR_PREFIX-$(date +%F)

rm -rf $BACKUP_DIR
mkdir -p $BACKUP_DIR

echo "Backuping to dir: $BACKUP_DIR"

docker cp $webId:/usr/local/tomcat/.OpenMRS $BACKUP_DIR

echo "DB container id:  $dbId"
ADDRESS_IP=`docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $dbId`
mysqldump --routines -u $DB_USER -p$DB_PASSWORD -h $ADDRESS_IP openmrs > $BACKUP_DIR/cfl_db.sql

echo "Backup completed"

Update the distribution data

In order to update the CFL distribution follow the steps below:

Download the latest version of distribution files (as described in the section above)

Run the following command:

 docker-compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.module-reload.yml up --build -d

Delete the distribution data

Note: Following instruction will remove all data related to distribution docker containers including configuration files and database.

To delete the distribution data execute the following command:

docker-compose down -v

Because of the CFL distribution copied modules and related OWA apps into ~/.cfl-dev directory, this directory should be removed. The following line can be used:

sudo rm -rf ~/.cfl-dev/

Login into server container

In order to login into the server you need to know the docker container name or container id. The following command can be used to determine that value:

docker ps --filter "name=cfl_web*" -q

Next, the following command can be executed:

docker exec -it ${container_id_or_name} bash

where “${container_id_or_name}” needs to be replaced by response from the first command. For instance:

docker exec -it bd28d1a0a94d bash

Commands above can also be concatenated:

docker exec -it $(docker ps --filter "name=cfl_web*" -q) bash

Manage the docker containers

More useful information (and commands) related to docker can be found in the official documentation: https://docs.docker.com/engine/reference/commandline/docker

Configure Message Deliveries Job

Connect for Life platform is largely focused on messaging interaction with patients like sending different types of reminders to them. To schedule such reminders Message Deliveries Job is used. In a typical production environment this job runs once every day (usually in the night hours) and schedules reminders for whole day. It is good and reasonable approach in production environments but it does not make sense on any testing envrionment (e.g we would have to wait all day to check if we got the message or call correctly).

In that case it is highly recommended to change interval of this job to up to few minutes at most e.g. 5 minutes. To do it go to the 'System Adminstration' -> 'Advanced Administration -> 'Manage Scheduler' -> Find 'Message Deliveries Job Task' and click it -> Go to 'Schedule' tab -> Set 5 minutes in 'Repeat interval' field -> Click 'Save' button.

Important thing here is that this change is valid only during current application runtime. When app is restarted then repeat interval value is set to default value which is defined in messages.messageDeliveryJobInterval global property, so the best will be setting this property to correct value after the application is launched for the first time.

Another related GP is messages.messageDeliveryJobStartTime - it determines start time (24-hour format in system timezone) of job. This time is set within each server restart as well.

Sources

Home

ADMIN GUIDE

Configuration

Modules

FAQ

FAQ

USER GUIDE