OpenMRS SDK 3.3.0 released!

I’m excited to announce the next major 3.3.0 release of OpenMRS SDK!

In this release we added full docker support for distributions.

You can now call openmrs-sdk:build-distro to create docker files for your distribution. The goal will download all modules and war file and put it inside a docker image. It will also create a docker-compose file to run mysql, mysql volume and openmrs container for you! After calling build-distro you are just a command away from running your distro in a production environment with ‘docker-compose up’.

We have used default settings for Tomcat and MySQL, but we are sure they can be tweaked to work faster with OpenMRS. We welcome any suggestions from people running OpenMRS in production.

We’ll showcase the use of that feature to startup a server for running UI tests in travis-ci. See

Thanks @gutkowski from Soldevelo for contributing the feature!


@gutkowski, I’ve just noticed the goal is not documented on the wiki at Would you mind adding some info there?

Sure, I will take care of it :slight_smile:

1 Like

@raff and @gutkowski Thanks for the excellent work, SDK makes OpenMRS development a pleasurable experience.

One interesting challenge we have is with deployment to a production server. Currently we have a separate distro-platform project that we use to build a WAR file containing all bundled modules what we push to a server. Is it possible to add a task to the SDK that can build a WAR file like this which removes the need for the distro-platform project (maybe the core OpenMRS can also use this when releasing).

@ssmusoke, I’d advise you to move on to Docker deployments. It’s extremely easy with the new goal openmrs-sdk:build-distro. It bundles all modules and war in a single image. I hope @gutkowski will document how to use it soon.

We could add a task to build just a war with modules, but I really think production deployments should be done with Docker these days. At some point we will improve Docker configs to easily scale up with multiple instances of OpenMRS and DBs. You will be able to benefit from such improvements going the Docker path.

Also you will benefit from any tweaks to Tomcat and MySQL we will make in the future to speed up OpenMRS.

@raff In Uganda our production environments are physical sites distributed across the country not connected to the Internet, so we do not have Docker running on those sites. The WAR file would provide an upgrade that would be manually delivered.

The built WAR file would also be added to an installer (Windows or Linux). Hence the reason for maintaining the distribution platform.

Documentation updated, do you think it’s sufficient?

@ssmusoke, Docker lets you store images in a file and move them around offline. You could exercise the following:

mvn openmrs-sdk:build-distro -Ddistro=referenceapplication:2.5-SNAPSHOT -Ddir=docker
cd docker
docker build -t openmrs-distro-referenceapplication:2.5-SNAPSHOT .
docker save -o openmrs-distro-referenceapplication-2.5-SNAPSHOT.tar openmrs-distro-referenceapplication:2.5-SNAPSHOT
docker save -o mysql-5.6.tar mysql:5.6

and then transfer the .tar files together with the docker-compose.yml file to another machine and run:

docker load -i mysql-5.6.tar
docker load -i openmrs-distro-referenceapplication-2.5-SNAPSHOT.tar
docker-compose up

It requires some changes in the way you deliver software, but I do believe it is superior than delivering just a war file and having to make sure that Java, Tomcat and MySQL are installed and configured separately.

The drawback is that those 2 docker files have almost 800 MBs, but we’ll cut that number down in some future release. Of course you do not have to load mysql-5.6.tar with your next update, which alone cuts the size by ~320 MBs.

That said, you can always request a feature you need (building the war with bundled modules for distro) by creating an issue in JIRA :slight_smile:

@gutkowski, thanks, looks good!

Hi @raff,

We are currently looking at the right way to automate the configuration and deployment of our OpenMRS production servers. I have a few questions about this new feature:

Each of our client uses his own set of module, so I would like to make sure that the SDK builds the right distro. Is it possible to build the docker image with my own distro (war + omods - distributed on Bintray for instance)?

Then, once my prod server is online, can this be used to deploy a module upgrade. Should I rebuild a new Docker image?

Hi @mksrom,

You can easily create your own distros. All it takes is creating the file for each distro. See examples at or

I would version such a file in git repo and then have a CI plan, which clones the repo and calls mvn openmrs-sdk:build-distro docker build and then pushes an image to docker registry like Bintray or Docker Hub.

Next you can configure your servers to simply pull images from docker registry and run containers. They can be configured to pull updated images automatically or on request and restart containers.

If there’s a module update you set the version in, build and push a new image to docker registry through the CI plan and then your server can pull it.

Thanks @raff.

Currently, we are hosting specific versions of pre-compiled modules (war + omods) in a binaries repository. Each client has his own repo of binaries. We do this because we use forked version of official modules and some of our own modules too. For instance one client uses our Visit Documents UI module which is not available on the OpenMRS repo.

Is there a way with the SDK to pull custom modules, based on a provided URL, and build the Docker image ?

@mksrom, do you store binaries in a maven repository? If yes, then you just have to update your maven settings.xml file to point to that repository and SDK will pull from there. If not, I’d recommend you to consider storing them that way.

Currently there’s no support for other repositories than maven.

Just wanted to let you know that you can see the build-distro feature in action at

@raff Our binaries are just a downloadable archive hosted on Bitbucket. I guess I’ll stick with that for now.

We will use our to CI override the ~/.OpenMRS/modules folder on the docker container. Thanks


@raff just bringing this back up on your radar, any chance of being able to build a WAR file with modules defined in a file as this will save the use of and maintenance of distro-platform projects

@ssmusoke, created an issue at

@ssmusoke Feature is implemented in and is available in version 3.4.5 of SDK :slight_smile:

1 Like

@tmarzeion Thanks for this tested out the feature. When I run the following command mvn openmrs-sdk:build-distro -Dbundled=true -Ddir=aijar -Ddistro=org.openmrs.module:aijar:1.0.15-SNAPSHOT

I see the following:

  1. A folder called AIJAR is created
  2. The WAR file is included along with docker image information
  3. Omods are copied to the modules folder

However what the ticket was about was to add the omods in the modules directory to the WEB-INF/bundledModules/ directory checkout this project to see an example of what I meant at

@ssmusoke, please make sure your SDK has been updated to 3.4.5. Just run:

mvn openmrs-sdk:setup-sdk -U

and try your command again.

@raff Thanks - my problem was that I was using the old command for updating the SDK `mvn openmrs-sdk:help -U’ so it was not updating at all.

I have also corrected the documentation on the wiki page to reflect the new command

Thanks @tmarzeion works like a charm

1 Like