Setting up a development environment for LibreHealth Radiology without Docker

The recommended way of setting up development environment for LibreHealth Radiology  is using Docker. See this blog posts for instructions on how to use docker for your development environment. See blog post here Development environment with Docker.

But some people have been having some timeout issues with mysql using the docker setup. So this is an alternative way to setup your environment. But I’d recommend you try with the docker setup first.


  • Java 8
  • Tomcat
  • mysql
  • git
  • maven
  • IDE

Please see their respective documentations for instructions on how to install them.


Setup Toolkit

LibreHealth Radiology is just a module that runs on a LibreHealth Toolkit server. So to setup radiology you need to first setup a toolkit server.

Clone the toolkit code from GitLab

git clone

Now build the code

cd lh-toolkit

mvn clean package

You might encounter a test failure during the build. I did. You should skip the tests using

mvn clean package -DskipTests

Now you need to deploy the generated .war file to tomcat. But the build generated an openmrs.war file instead of lh-toolkit.war. This is because toolkit is a fork from openmrs and the build still generates an openmrs.war instead. That is easy to fix. We’ll just rename the file to lh-toolkit.war. For that run the following code

cd /webapp/target/

mv openmrs.war lh-toolkit.war

Now you need to copy this .war file to the tomcat webapps folder. My tomcat installation directory is /Library/Tomcat. You need to replace that in the command below with your actual tomcat directory

mv lh-toolkit /Library/Tomcat/webapps/

Now you restart tomcat and open your browser to http://localhost:8080/lh-toolkit/

You’ll be presented with an installation wizard to complete the installation of toolkit.


Screen Shot 2017-09-27 at 9.55.04 PM.png

Select your language and take next

Screen Shot 2017-09-27 at 9.56.10 PM.png

Make sure simple install is selected and move forward

Screen Shot 2017-09-27 at 9.57.04 PM.png

Enter your mysql root password and move forward.

Screen Shot 2017-09-27 at 9.58.43 PM

Scroll to the bottom of this page and take note of the directory where the file is kept.

Screen Shot 2017-09-27 at 10.01.10 PM.png

For me it’s in /Users/larry/.OpenMRS/lh-toolkit/ it might be different for you. Take note of it and move forward.

Screen Shot 2017-09-27 at 10.02.10 PM.png

Wait for installation to complete.

Screen Shot 2017-09-27 at 10.03.29 PM.png

If your output is like mine above that means you have successfully installed toolkit. The OpenMRS name there is a bug. I’ll create an issue for it. Now you need to install a user interface since as from 2.0 of toolkit the user interface was removed and it’s just an api server now. You are free to build which ever user interface you want to work interact with it.

For Radiology, we’ll be using the legacyui module. You have to clone and build it too then install the module. For that Follow the instructions below.

Install a User Interface

We’ll first clone the legacyui module from gitlab using

git clone

Now build a .omod file

cd lh-toolkit-legacyui/

mvn clean package

Once the build is done and successful, do

ls omod/target

And you’ll see a file called legacyui-1.2-SNAPSHOT.omod the version number may differ from this depending on when you doing the setup.

Remember the directory I told you to take note of, the directory containing the file?

Yes. That one. For me it was /Users/larry/.OpenMRS/lh-toolkit. There is a  subdirectory called modules. You have to copy the .omod file to that directory. For that do

cp omod/target/legacyui-1.2-SNAPSHOT.omod  /Users/larry/.OpenMRS/lh-toolkit/modules

Don’t forget to replace this /Users/larry/.OpenMRS/lh-toolkit/modules with the equivalent on your machine

Now restart tomcat and visit http://localhost:8080/lh-toolkit/

You should see this

Screen Shot 2017-09-27 at 10.58.38 PM.png

Instead of the page above you may see the error below

Screen Shot 2017-09-27 at 10.47.51 PM.png

Try restarting tomcat one or two times again and see.

You may notice that home page is 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

Now we are going to deploy the radiology module.

Deploy Radiology Module

The radiology module has dependencies on OpenMRS REST module and Open Web Apps module. You have to download those and install first before proceeding with deploying radiology. To get these modules visit and search for open web apps to download the open web apps module. You should endup with a file named owa-1.7.0.omod. The version may differ depending on the time you do the download.

Search `rest webservices` to get the webservices module. You may see to versions like below. Don’t take the extension. See the screenshot below, the second one is the right one

Screen Shot 2017-09-28 at 12.57.04 AM.png

You’ll end up with a file like and you can now install these omods just like you installed the legacyui module. But I’ll show you another method below how to do it graphically. This just so you know that this method is also available. In the future you are free to either us command line or this method.

While logged in to toolkit, go to Administration

Screen Shot 2017-09-28 at 1.01.59 AM.png

Click on manage modules

Screen Shot 2017-09-28 at 1.04.34 AM.png

Click on the Add or Upgrade Module button

Screen Shot 2017-09-28 at 1.05.44 AM.png

Now choose the omod files of the module you want to install and click upload

Screen Shot 2017-09-28 at 1.07.41 AM.png

Now proceed with radiology

Since you’ll be contributing to the radiology module, you should fork the repo.

Clone your fork

git clone

cd lh-radiology

Add a remote pointing to the original repo

git remote add upstream

Fetch all branches

git fetch --all

Pull latest changes

git pull --rebase upstream master

Then build code

mvn clean package

That will generate a .omod file and you are free to deploy it using any of the methods see fit. You final home page should look like this, note the link to Radiology on the navbar

Screen Shot 2017-09-28 at 1.12.31 AM.png

Please leave feedback in the comment sections below.










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