LibreHealth Toolkit Development Guide

Installation and running with Docker

We have a repository which hosts docker compose and resource files required to build docker images and start containers that can be used by users and developers to test the latest code in the repository. The Docker container that is created uses standard tomcat7:jre8 and mysql:5.7 images.

The following is included:

  • the legacy-ui module

  • module

  • the owa module

  • demo database for Toolkit 2.1 SNAPSHOT

The tomcat:7-jre8 uses OpenJDK 8, which in turn uses Debian 8.1 (Jessie) base image. Thus the LH Toolkit is deployed on tomcat7. The MySQL 5.7 image is used for the database on which the 2.1 SNAPSHOT demo database is deployed. The main advantage of using standard images is that the updates to those are automatically available. The LH Toolkit.war is downloaded from the latest devbuilds that are uploaded to bintray, using Gitlab CI. Thus, the web application built from the master branch is available as part of this container. You only have to update the image and get the latest and greatest LH Toolkit that is available from the Continuous Integration.

Setting up your Integerated Development Environment (IDE)

The LibreHealth toolkit (LH Toolkit) is one of the projects under the LibreHealth group on GitLab. It contains some of the most important software and interfaces required to run efficiently and to coordinate with other projects of LibreHealth like LibreHealth-radiology and open-decision-framework. The table below can be referred to understand the repositories present in the LH Toolkit.


java and resource files for building the java api jar file.


Puppet scripts for local development and deployment.


Cucumber/selenium integration tests. Run daily against a running web app.


Maven project to share tools that are used for testing.


Meta code used during compiling and testing. Does not go into any released binary (like doclets).


java and resource files that are used in the web application.


jsp files used in building the war file.


Used to configure Gitlab CI. Each branch can have its own configuration.


Used by license-maven-plugin to check the license on all source code headers.


The main maven file used to build and package OpenMRS.

To have all models processed correctly, this project should be opened under Maven projects. Once the project is forked into the user’s profile successfully, it is cloned to the local system easily using the git clone command. Many IDE’s are available on the web but IntelliJ IDEA is preferred in this case considering its flexibility in handling complex projects like this.

Running the project

You can easily run the project locally by following the guide. You will need to set up an IDE and clone the project first.