Description

Run openmrs reference application and mysql as disposable docker containers for demo server.

The docker image used was generated by OpenMRS SDK, and deployed to Docker hub (check https://hub.docker.com/r/openmrs/openmrs-reference-application-distro/

Setup Docker and Docker Compose on Ubuntu 18.04

$ sudo apt update
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
$ sudo apt update
$ apt-cache policy docker-ce
$ sudo apt install docker-ce
$ sudo systemctl status docker
$ sudo curl -L https://github.com/docker/compose/releases/download/1.21.2/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose
$ docker-compose --version

Getting the code

First clone the code:

git clone https://github.com/openmrs-indianaems/openmrs-docker-indianaems.git
cd openmrs-docker-indianaems

Next, perform one-time install of client-side git hooks to keep encrypted files safe:

conf/install-hooks.sh

NOTE: environment files for staging and production are encrypted using git-crypt. Your public gpg key must be registered within the repository before you can see the content of these encrypted files. We use two git hooks: (1) to issue warning to prevent accidentally pushing encrypted files in unencrypted state and (2) to make sure encrypted file permissions are limited to current user (removing read access for group or others).

Running the dev environment locally in a single instance

To start the containers in a detached mode:

$ cd app
$ docker-compose up -d

To see the logs:

$ docker logs -f app_openmrs-reference-application_1

Application will be eventually accessible on http://localhost:8080/openmrs.

Credentials on shipped demo data:

• Username: admin
• Password: Admin123

To stop the instance use:

$ docker-compose down

But to make sure to destroy containers to delete any left overs volumes and data when doing changes to the docker configuration and images use:

$ docker-compose down -v

Database backup

To backup:

docker exec [containerId] /usr/bin/mysqldump -u openmrs --password=[password] openmrs > backup.sql

To restore:

cat backup.sql | docker exec -i [containerId] /usr/bin/mysql -u openmrs --password=[password] openmrs

Installation in the production environment in a two environment setup

1. Start the Database on db server

$ cd db
$ ./production up -d

2. Start OpenMRS on app server

$ cd app
$ ./production up -d

Convenience scripts in the app and db folders:

Script	Equivalent to
./production	docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d.
./staging	docker-compose -f docker-compose.yml -f docker-compose.staging.yml up -d
./validation	docker-compose -f docker-compose.yml -f docker-compose.validation.yml up -d

NOTE: The first time the app is started, it can take around 5-10 minutes

Move to Step #3 after seeing the following page on the server:

3. Clear out concepts on db server

Open MySQL:

$ docker exec -it openmrs-mysql bash
# mysql -u $MYSQL_USER -p$MYSQL_PASSWORD

Switch to openmrs database:

use openmrs;

Void all synonyms:

update concept_name set voided=1, date_voided=now(), voided_by=1 where concept_name_type is null;

Create temp table of duplicate concept names:

create temporary table foo (
  select t2.concept_name_id from concept_name t1
  join concept_name t2
    on t1.concept_name_id != t2.concept_name_id and t1.name = t2.name and t1.concept_name_type = "FULLY_SPECIFIED"
  join concept t3 on t1.concept_id=t3.concept_id
  join concept t4 on t2.concept_id=t4.concept_id
  where
    t1.voided=0 and t2.voided=0 and t3.retired=0 and t4.retired=0
);

Void all duplicate concept names:

update concept_name set voided=1, date_voided=now(), voided_by=1
  where concept_name_id in (select concept_name_id from foo);

Add SNOMED US Concept Source:

INSERT INTO concept_reference_source VALUES (17,'SNOMED US','SNOMED CT US Extension',NULL,1,
  '2012-09-15 12:11:39',0,1,NULL,NULL,'17ADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD',NULL,NULL,1);

4. Initialize Metadata

First, start monitoring logs in a terminal on app server:

docker logs -f openmrs

Second, in the Reference Application user interface:

• Navigate to System Administration > Manage Modules
• Click on the ➕Add/Upgrade Modules button
• Click within the "Drag files here or click to upload" box and select the initializer module .omod file (available in this repository under app/modules/)
• Click on Upload Module to upload the module

NOTE: installing the module will being the CIEL dictionary import (concepts), importing ~52000 concepts, and can take 45 to 90 minutes to load all the concepts the first time.

5. Manual Steps

5.1 Secure the system

Change the super user password to a secure password

• Log in as admin with default password
• On home screen, click on "admin" username in header and select My Account. If the "My Account" popover does not appear when clicking on the admin username, navigate to Advanced Administration > Manage Modules and click on admin username there as a workaround.
• Choose Change Password
• Change the admin user password to a secure password and save that password securely for future reference
  • It should be at least 12 characters long
  • It should contain a mix of uppercase, lowercase, digits, and special characters

5.2 Change Identifier

NOTE: This should happen before adding any patients or it might lead to inconsistent behaviour

Go to System Administration > Advanced Administration > Manage Patient Identifier Sources

Click on Configure, makes these changes, and save them:

• First Identifier Source: 100
• Suffix: CE
• Min Length: 3

5.3 Add HTML Form

Go to System Administration > Advanced Administration > Manage HTML Forms

Click on New HTML Form

• Name: COVID-19 Note
• Version: enter the version from the parenthetical in the formName on this line
• Encounter type: COVID-19 Note
• Click on Save
• Replace the default HTML with this HTML form definition
• Check the box for Published
• Click on Save

Go to Home > Configure Metadata > Manage Forms

• Click on Add beside COVID-19 Note
• UI Location: Patient Dashboard - Current Visit Actions
• Click on Save

5.4 Manage Apps

Go to Home > System Administration > Manage Apps

• Click on Add App Definition button
• App ID: referenceapplication.registrationapp.registerIEMS
• Definition: Copy this JSON into definition

Stop the following apps (if you see a square ◾ to the right of any of these, click it to stop the app):

referenceapplication.registrationapp.registerPatient
registrationapp.basicRegisterPatient
coreapps.latestObsForConceptList
coreapps.obsAcrossEncounters
coreapps.obsGraph
coreapps.relationships
coreapps.awaitingAdmission
referenceapplication.personalRelationships
coreapps.conditionlist

NOTE: The apps listed above should all have a triangle ▶ to the right, indicating they are stopped.

5.5 Adding User Accounts

Add two users: clinicProvider and clinicAdmin

1. Navigate to System Administration > Manage Accounts
2. Click on Add New Account

• Family Name: Pop-up Clinic
• Given Name: Provider
• Gender: Female

3. In the USER ACCOUNT DETAILS section, check the "Add User Account?" box

• Username: clinicProvider
• Privilege Level: High
• Password: Create a secure password with at least 8 chars, at least one UPPERCASE letter, at least one digit (create a new password, don't use the admin password)
• Confirm Password: Re-enter password (save password securely so it can be communicated to approprriate users)
• Uncheck the "Force Password Change" checkbox
• Capabilities: Check A Standard User (first option)

4. In the PROVIDER DETAILS section, check the "Add Provider Account?" box

• Identifier: clinicProvider
• Provider Role: Clinical Doctor

5. Click the Save button
6. Click on Add New Account

• Family Name: Pop-up Clinic
• Given Name: Admin
• Gender: Female

7. In the USER ACCOUNT DETAILS section, check the "Add User Account?" box

• Username: clinicAdmin
• Privilege Level: Full
• Password: Create a secure password with at least 8 chars, at least one UPPERCASE letter, at least one digit (don't re-use a password used earlier)
• Confirm Password: Re-enter password (save password securely so it can be communicated to approprriate users)
• Uncheck the "Force Password Change" checkbox
• Capabilities: Check the first two options, A Standard User and Administers System

8. In the PROVIDER DETAILS section, check the "Add Provider Account?" box

• Identifier: clinicAdmin
• Provider Role: Clinical Doctor

9. Click the Save button

Future improvements

• Record and Remove duplicates in different loacales - Report to Andy Kanter and see if this can be improved in the CIEL dictionary itself.
• capture Idgen settings needed to automate the 5.1 Change Identifier step
• Use Metadata package folder and see if Covid_Form_-_All_Concepts-1.zip Can be loaded automatically to remove the manual step of add HTML Form
• See if Concept sources can be added to initializer module, this should automate the step of manually loading the sources througn MySQL