Setting up development environment for LibreHealth Radiology using Docker


The LibreHealth Radiology Module provides features of a Radiology Information System powered by LibreHealth Toolkit. It’s a spring framework application that uses JSP for it’s UI. There is a new UI in development that uses Angular 2/4 and communicates with the backend via REST but that UI is not production ready yet. To develop on the module you need a server running LibreHealth Toolkit(lh-toolkit). But good for you that has been dockerized.

We have a demo website you can visit if you just want to have a feel of the features. The link to the demo is and username and password is admin/Admin123

This tutorial is for those wanting to develop the backend. So it does not demonstrate setting up development environment for the Angular 2/4 UI. That will be in another blog post.


To complete this tutorial, you need the following installed. Please see their respective documentations on how to install these on your platform.

  • Java 8
  • Maven
  • Git
  • IDE of your choice. I use Idea
  • Docker

LibreHealth Radiology runs on Java8 and uses Maven to build. Git is used to get the code and Docker packages the module in a docker image making deployment easy.


Get the code

If you plan to make contributions to this module, you’d need to fork the repo on GitLab

Go to and fork the repo.

Clone your fork

git clone

Add a remote repository pointing to the original repo on LibreHealth

cd lh-radiology

git remote add upstream

Fetch all branches

git fetch --all

Build your code

Make sure you are in the root directory of the project (lh-radiology)

mvn clean package docker:build

mvn clean package will compile your code to a .omod file which is just a custom file extension designed by OpenMRS for it’s modules. That is the file you’d have to deploy to a running toolkit server. But with introduction of docker you don’t have to worry about that.

docker:build builds a docker image from the contents of the compiled module. This docker image contains a Toolkit server, REST webservices, legacyui and your newly built radiology module all installed.

Run your application

mvn docker:start

Your application will be running on http://localhost:8080/lh-toolkit, default username and password is admin/Admin123

You should see this

Screen Shot 2017-09-26 at 10.43.27 AM

You may notice that this a little different from the demo website. In the demo website the green bar is orange. That is easy to fit

Go to Administration under the maintenance section, click on settings

Screen Shot 2017-09-26 at 10.50.03 AM.png

You’ll see a setting for theme. Enter orange and safe.

Screen Shot 2017-09-26 at 10.51.38 AM.png

Your application should now look like below

Screen Shot 2017-09-26 at 10.52.18 AM


Import your code into an IDE(Optional)

This step is optional and can be done at any point after getting the code. Must not be done after deploying the application. But I always chose to do it last or at least after building the code with mvn. This is because depending on your IDE, it maybe intelligent enough to identify this project as a maven project during import and while importing the module, your IDE may try to download all dependencies specified in the pom.xml of the project. This tends to take a while with some IDEs and sometimes fail even if it’s the first time these dependencies are been fetched. That is why I like building first because all the dependencies will now be cashed in your local maven repo and when importing into an IDE it won’t take much time.



There are a number of IDEs you can choose from. You may already have one you are using that like and that’s ok. I will not be showing how to do this with every possible IDE but with just the one I’m using InteliJ IDEA. If you use something else, please see it’s documentation on how to import maven projects.

Launch IDEA and select import project

Screen Shot 2017-09-26 at 11.00.24 AM.png

Select your project directory and hit next. Now select import from external model and make sure it is set to Maven

Screen Shot 2017-09-26 at 11.07.54 AM.png

Take next, next, next

When you asked to select and SDK, use Java 8. If you have not already setup an SDK, click on the plus sign to add and SDK then look for your java8 installation folder.

Click finish and your code will be imported by IDEA

Screen Shot 2017-09-26 at 11.11.12 AM.png


You can now make changes to the module. Every time you make a change, you have to redeploy the module but that is every easy. From the terminal, execute the following commands in the project folder

# first stop the already running application

mvn docker:stop

# then build again

mvn clean package docker:build

# and deploy

mvn docker:start


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s