Install Backend OpenMRS system

Requirements

The Vxnaid™ backend application runs as a self-contained docker image with a connection to an external database. The installation requires:

• Running MySQL 5.7 server
• General purpose server with Docker Engine and Docker Compose installed

MySQL server configuration details

• The server must listen on 3306 port
• The SQL server must be accessible from the Docker host server
• In case of AWS RDS, the log_bin_trust_function_creators variable must be set to 1
• There must be a user and schema created for an OpenMRS application:
  • There are no requirements for username, but openmrs is preferred
  • Schema name must be openmrs
  • Character set must be utf8
  • For collation utf8_unicide_ci is preferred

Preparation

Before installation of the Vxnaid™ backend application can happen, you need to obtain the Vxnaid™ package. This can be found here. You can either download the ready-made package which consists of a Docker image file, docker-compose.run.yml configuration file and .env file with example runtime configuration or you can build them by yourself using publicly available sources (link above).

Building package

Building package requires Docker Engine and Docker Compose to be installed.

1. Download the openmrs-distro-vxnaid GIT project from the publicly available J&J repository.
2. Check the included cfl/README.md file and follow instructions from the Production section.
3. After performing steps described in th README, you should get a Docker Image file openmrsvxnaid_X.Y.Z.tar.gz, where X.Y.Z is the current version of the package.

Installation

The Vxnaid™ backend application is packaged as a Docker image. Together with an image file (tar.gz archive) a docker-compose.run.yml file and .env file are distributed.

Startup process

When using an empty database, the first startup is considered as Initial Startup. During the Initial Startup the database tables are created, and the initial data is loaded – this includes an import of CIEL Concept Directory package maintained by Open Concept Lab (OCL) initiative. The Initial Startup must be explicitly configured and takes considerable amount of time – depending on machine from 15 minutes to couple of hours.

Following application restarts can be performed using regular Docker commands.

Updating application requires loading a new version of Docker image.

All commands must be executed from the root directory of the distribution package:

<root-directory>/
├── .env
├── docker-compose.run.yml
└── openmrsvxnaid_X.Y.Z.tar.gz

Loading an image

The Docker image must be loaded first, to do this run following command:

docker load < openmrsvxnaid_X.Y.Z.tar.gz

Where X.Y.Z is a version of the distribution package.

Verification of the loaded image can be done by running following command:

docker images

The result should be a list of all images in your local Docker, expected result should look similar to the following:

REPOSITORY	TAG	IMAGE ID	CREATED	SIZE
openmrsvxnaid	1.1.6	3d70715b03e6	41 minutes ago	816MB

Environment configuration using .env

The .env file contains configuration specific for each environment. The following table explains each property in detail. Once the system has started the file can be deleted.

Property Name	Example value	Description
INITIAL_STARTUP	False	Configures whether the next startup is the Initial Startup.
TOMCAT_PORT	80	The HTTP port of the Docker host machine which is going to be used by the application.
DB_HOST	myDatabase.abc123.eu-west-1.rds.amazonaws.com	The host name or IP address of the MySQL database server. Must be accessible from Docker host.
DB_USERNAME	openmrs	The database username for the application to use. This user must have full access to openmrs schema.
DB_PASSWORD	S3cretP4$$w0rd	The database user password. Once the system has started it must be removed.
BIOMETRIC_ENABLE	true	Whether the Biometric functions should be enabled.
BIOMETRIC_SERVER_HOST	127.0.0.1	The host name or IP address of Biometric server.
BIOMETRIC_SERVER_ADMIN_PORT	24932	The admin port of Biometric server.
BIOMETRIC_SERVER_CLIENT_PORT	25452	The client port of Biometric server.
BIOMETRIC_SERVER_MATCHING_THRESHOLD	40	The matching threshold.
BIOMETRIC_DB_HOST	127.0.0.1	The host name or IP address of Biometric database server.
BIOMETRIC_DB	iris_newpoc	The name of Biometric database.
BIOMETRIC_DB_PORT	1433	The port of Biometric database server.
BIOMETRIC_DB_USERNAME	cfl_demo_iris	The Biometric server user used by the application to access the Biometric
BIOMETRIC_DB_PASSWORD	S3cretP4$$w0rd	The password for the Biometric server user.
BIOMETRIC_DB_FETCH_SIZE	1000	The JDBC statement fetch size to be used by Biometric module when reading Biometric database.

Initial Startup of the Connect for Life™ Application

Verify that:

• Database is configured as required, is running and is accessible from Docker host.
• The .env file contains proper configuration.
  • Especially verify if Initial Startup property is set to true.

Run following command to start loaded image using .env configuration.

docker-compose -f docker-compose.run.yml up -d web

Optionally, inspect log output by running following command. It will print new log entries as they appear. Be cautious that during the Initial Startup the application will print huge amount of log entries during import of OCL Concepts.

docker logs -f --tail 500 cfl_web_1

After initial Startup

The Initial Startup should be performed only once. To ensure that, once the Initial Startup is complete you should perform following steps:

• Set INITIAL_STARTUP property in the .env file to false.
• Run command:
  • docker-compose -f docker-compose.run.yml up -d web

From now on, you can use regular docker commands to stop, start or restart application container:

To simply restart application container run:

docker restart cfl_web_1

Application update

To update the running application to the new version of the Vxnaid™ distribution, you need the Docker image of the new version and new docker-compose.run.yml.

The image contains the new version of the application and the YML file contains configuration which tells Docker to use the new version.

The .env file should stay the same unless explicit information is provided with the new version.

The new image has to be loaded into Docker.

docker load < openmrsvxnaid_X.Y.Z.tar.gz

Where X.Y.Z is a new version of the distribution package.

Listing all images in Docker should show image with a new version and any previous version:

docker images

Example result:

REPOSITORY	TAG	IMAGE ID	CREATED	SIZE
openmrsvxnaid	1.1.6	3d70715b03e6	41 minutes ago	816MB
openmrsvxnaid	1.1.5	2d69615b03c5	2 days ago	816MB

During update, the INITIAL_STARTUP property in the .env file must be false - which already should be if the Initial Startup steps has been followed.

Run following command to stop running the application and start a new version.

docker-compose -f docker-compose.run.yml up -d web

Optionally, inspect log output by running following command.

docker logs -f --tail 500 cfl_web_1