OpenMRS Server Configuration

OpenMRS acts as the back end system for user management, auditing and reporting. This page provides the steps necessary to configure a fresh OpenMRS server. Note that the docker setup and docker compose setup instructions include a pre-configured OpenMRS server. Start there if you're just trying to stand up a demo.

We currently depend on OpenMRS Platform v1.11.x which depends on Java 7, Tomcat7 and MySQL 5.5.

OpenMRS Modules

The following modules are required for the OpenMRS server. Note that all of these modules are available for download as a single tarball from Source Forge.

Module name	Minimum Version	Source Code	Download Link or Build from Source	Description
atomfeed	3.0.1a	OpenSRP GitHub	Build from Source	This module provides an atom feed for every patient and encounter transaction in the system
calculation	1.1	OpenMRS GitHub	modules.openmrs.org	This is the standard OpenMRS calculation module.
cohort	2.0	OpenSRP GitHub	Build from Source	This module allows you to define a cohort of patients within OpenMRS
dhislocation	0.1-SNAPSHOT	OpenSRP GitHub	Build from Source	This module pulls the location information from DHIS2 so we don't have to manage the locations in OpenMRS
dhisreport	2.1-SNAPSHOT	OpenMRS GitHub	Build from Source	This module allows us to push aggregate information from the OpenMRS server to DHIS2.
htmlformentry	2.5	OpenMRS GitHub	modules.openmrs.org	This module allows us to easily define html forms in OpenMRS.
htmlwidgets	1.6.7	OpenMRS GitHub	modules.openmrs.org	This module displays the widgets within the HTML forms that we define in the htmlformentry module.
idgen	3.2	OpenMRS GitHub	modules.openmrs.org	This module allows you to generate identifiers within OpenMRS.
idgen-webservices	1.1-SNAPSHOT	Bahmni GitHub	Build from Source	This module allows you to access the ids that were generated through an API, which allows us to create unique identifiers across all components from a single source.
reporting	0.9.8.1	OpenMRS GitHub	modules.openmrs.org	This is the standard OpenMRS reporting module.
reportingrest	1.5	OpenMRS GitHub	modules.openmrs.org	This module allows us to access reports through a REST API.
scheduletracker	0.1-SNAPSHOT	OpenSRP GitHub	Build from Source	This module allows us to upload a patient alert schedule into OpenMRS and view those who enroll in automated alerts in OpenSRP.
serialization.xstream	0.2.7	OpenMRS GitHub	modules.openmrs.org	This module allows OpenMRS to serialize XML objects.
sync	1.2	OpenMRS GitHub	modules.openmrs.org	This module allows OpenMRS to sync with parent and child servers.
teammodule	0.1.0A	OpenSRP GitHub	Build from Source	This module allows us to assign team members to a particular location and share patients.
uiframework	3.3.1	OpenMRS GitHub	modules.openmrs.org	This module provides the user interface framework for other modules.
webservices.rest	2.12.0	OpenMRS GitHub	modules.openmrs.org	This module is the standard REST API for OpenMRS

OpenMRS Setup Script

This script allows you to install OpenMRS on Ubuntu 14.04. After running the script, you need to navigate to http://localhost:8080/openmrs and continue the OpenMRS setup process.

OpenMRS Setup for OpenSRP

# Notes:
# - This script builds on top of this GIST: https://gist.github.com/craigappl/6e54abfb8a59c5a28a63d2a6179cd506
# - This script was informed by the docker-builds repo: https://github.com/OpenSRP/docker-builds
# - This script installs OpenJDK7, MySQL 5.5, Tomcat7 to the default directories for Ubuntu 14.04 using sudo apt-get install
# - You can set the Tomcat7 memory environment variable to whatever you choose. Currently, 512MB RAM is allocated with a max of 1GB.
# - Install locations:
#   - OpenMRS Home Directory: /usr/share/tomcat7/.OpenMRS
#   - Tomcat7 Webapps: /var/lib/tomcat7/webapps/
#   - Tomcat7 Log: /var/log/tomcat7/catalina.out
#   - Tomcat7 Environment Variables: /var/lib/tomcat7/bin/setenv.sh

#!/bin/bash

#Run apt-get update
sudo apt-get update

#Install openjdk-7 (java 7 development kit)
echo "Installing OpenJDK7"
sudo apt-get install -y openjdk-7-jdk

#Install tomcat7
echo "Installing Tomcat7, stopping the service and setting the catalina environment variable to max 1GB RAM"
sudo apt-get install -y tomcat7
sudo service tomcat7 stop
echo 'CATALINA_OPTS="-Xms512m -Xmx1024m"' | sudo tee --append /usr/share/tomcat7/bin/setenv.sh

#Install MySQL Server (You will be prompted for a root password during this step, which is required for )
echo "Installing MySQL Server. You will be prompted for a password."
sudo apt-get install -y mysql-server

#Install curl to be able to get the .war files
echo "Installing curl"
sudo apt-get install -y curl

#Download the .war file
echo "Downloading the OpenMRS Platform v1.11.7 .war file"
curl -O -L -J "https://sourceforge.net/projects/openmrs/files/releases/OpenMRS_Platform_1.11.7/openmrs.war/download"
sudo cp openmrs.war /var/lib/tomcat7/webapps/openmrs.war

#Make a .OpenMRS home directory in /usr/share/tomcat7/
echo "Creating OpenMRS directory in /usr/share/tomcat7/.OpenMRS"
sudo mkdir /usr/share/tomcat7/.OpenMRS

#Download the OpenSRP modules
echo "Downloading the OpenSRP modules to configure OpenMRS"
curl -O -L -J "https://sourceforge.net/projects/keymane/files/opensrp/opensrp_openmrs_modules.tar.gz/download"
sudo tar xzvf opensrp_openmrs_modules.tar.gz -C "/usr/share/tomcat7/.OpenMRS/"

#Change permissions on tomcat7 folders
echo "Setting tomcat7 permissions to all tomcat directories"
sudo chown -R tomcat7:tomcat7 /usr/share/tomcat7
sudo chown -R tomcat7:tomcat7 /var/lib/tomcat7

#Start tomcat and navigate to http://localhost:8080/openmrs to complete setup
echo "Starting Tomcat"
sudo service tomcat7 start
echo "Navigate to http://localhost:8080/openmrs to continue the OpenMRS setup process."

Configuring OpenMRS

After setup, we need to create locations, users and teams to ensure the user can login:

Setup a location within openmrs under Administration>Locations tab>Manage Locations.
Create a new User(s) in Administration>Manage Users>Create User.
Create a team under the Team management module.
Assign the user to the Team that was created.
To verify whether the user is authenticated, within the browser type "localhost:8080/opensrp/security/authenticate" and fill in the user credentials created in openmrs. A JSON file should appear indicating the user details.
Make sure the logged in user has the ability to get identifiers from the OpenMRS idgen module. This can be achieved under the Manage patient Identifier sources to Auto-Generations Options and set the Location in line with the one set initially, then the Source to Auto-generate From and set it to "OPENMRS_OPENSRP" as well as selecting all the options below and then save.
With all that in place, open up the client App in the settings tab change the URL to that of your local machine for example "http://10.0.2.2:8080/opensrp".