OpenMRS Docker Images

The OpenHMIS team is currently in the process of setting up some long-needed integration tests and, as part of that effort, have created some docker images for some of the recent platform and reference application releases. These images can be found at

The README file explains the various tags that are available as well as how to get an instance up and running but I’ll mention the basics here. First, our tags use the following naming convention: <Omrs Platform Version>_<Ref App Version>. For images without the reference application the second version is left off. For example, tag ‘1.11.5_2.3.1’ will be an image with OpenMRS Platform 1.11.5 with the Reference Application 2.3.1 while tag ‘1.11.3’ is an image with just the OpenMRS Platform 1.11.3.

Our images require a separate MySQL image (or accessible mysql server) to be used. To start up a MySQL docker instance execute the following command (replacing <LOCAL_PATH> with a path on the host machine where the mysql data will be stored):

docker run --name openmrs-mysql -v <LOCAL_PATH>:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=test -d -p=3306:3306 mysql/mysql-server:5.6

With that mysql instance running, you can start an OpenMRS instance:

docker run --name openhmis-test --link openmrs-mysql:mysql -it -p 9999:8080 -e DEMO_DATA=1 -e DB_USER=‘root’ -e DB_PASS=‘test’ openhmis/openmrs-docker:latest

This will download the ‘latest’ tag (currently ‘1.11.5_2.3.1’), load the OpenMRS and OpenHMIS demo data, copy the current OpenHMIS modules, and then start up OpenMRS, making it available on port 9999. Our docker hub page has a complete list of configurable environment variables but let me highlight a couple:

  • DB_NAME: The name to use for the OpenMRS database. If not defined this will be set to the default database name for the image selected. If a database with the specified name already exists it will not be updated and the specified OpenMRS user will be given access to it.
  • EXCLUDE_OPENHMIS: Tells the script to not download and install the OpenHMIS modules and data. This parameter simply needs to be set to something, the value does not matter.

We would love to get feedback from the community on these images including requests for additional tags, the tag naming convention, and any optimizations that can be done. Lastly, we have two questions:

  1. We currently manually create the sql file for the demo data (using mysqldump after loading the demo data during the omrs installation process). Do sql scripts of the demo data for each released version exist somewhere so that we can download it instead of manually creating it?
  2. When creating the file we are entering the username and password in plaintext because I am not aware of a program to generate the correct encryption vector, key, and then the associated encrypted username and password from the terminal. Is there a way to easily encrypt this information from the terminal? We’re not too worried about this given that the file is within the docker image and (should) not be generally accessible but we would like to improve this if possible.

Thanks @ibewes, these look great. If anyone is looking for other examples, I’ve also created platform and refapp instances using docker-compose.


people really should be using docker-compose to link containers

One problem with docker-compose is that you can’t neatly publish your linked containers to DockerHub like @ibewes did so nicely above.

You’re really supposed to make multiple containers – AUFS can only handle so many layers before it just won’t work. docker-compose isn’t for that – docker-compose is for tying it altogether. The problem it’s solving is connecting all these separate containers together

Awesome @pascal! Thanks for sharing the links, I’ll try and create one for our images.

1 Like

@r0bby Is there a generally accepted method for distributing docker-compose scripts? Should I create one and put it in the root of our github openmrs-docker repository?

1 Like

@ibewes – yeah throw a docker-compose file in the root directory. Great work – I’m not in any way saying this isn’t amazing

1 Like

The issue is that if you want nice versioning and public hosting on DockerHub, where do you keep the docker-compose configuration, and how do you reference the containers? By their public IDs? I’m not aware of a currently accepted best practice around this.

You reference them by tags – use git branches/tags to manage this in git

And do you keep the docker-compose config file in the repo with each referenced container? Or do you choose one container as the primary and keep the config file with just that one?

I would keep a version in each branch personally

Hi all!

just wanted to share what Ive been doing, thanks to your guys work :slight_smile:

So setup of was a pain and I wanted to make it easy and faster for everyone.

Docker images I built docker images for OpenMRS 2.0.0 MySQL db and OpenMRS 2.0.0. Builds are automatically done on docker hub (and tagged according to git tags).

Maven integration I added maven plugin to the radiology module so you can build the module and deploy it locally using one command mvn clean package docker:build docker:start :fireworks:

How it works: i define docker images in the pom.xml, can define links between images (so openmrs <–> db), how they are built and run. Have a Dockerfile for the radiology module which is based on the OpenMRS 2.0.0 image, contains and deploys its dependencies to tomcat and deploys the built radiology module .omod as well.

An extensive documentation of this awesome maven docker plugin is at

Its also possible to override some settings like the tomcat port or its JAVA_OPTS from the command line which would look like

mvn docker:start -Dtomcat.env.java_opts="-Dfile.encoding=UTF-8 -server -Xms256m -Xmx1024m"

Interesting One thing Ive seen that @pascal said is tricky and I also ran into. Is that if you tie the DB image and the tomcat image together via docker-compose, it does honor the order but doesnt wait for the DB to be really ready for connections.

I thus found

which I can use to tell it to wait for a tcp connection on the DB port. Also it provides templates :slight_smile: So I created templates for the openmrs runtime properties and the tomcat This enable me to expose some ENV variables which can be changed according to the docker image users needs. This is how the JAVA_OPTS can be set from outside.

One caveat still exists, the docker CMD doesnt do expansion of variables, so the DB hostname and port are hard coded :frowning: but only for now, I am sure well find a way to improve that as well!

Am interested in your thoughts!

And also maybe somebody wants to join forces :rocket: and set up an official docker image for OpenMRS which we could also integrate into the openmrs-core repo and its deployment process. (+ in future integration tests against multiple DBs can be automated this way :slight_smile:

1 Like

I’m using to do this now. You can see how it’s done for the Mozambican distribution images here:

1 Like

Another one similar to is dockerize – I’ve used it for ID dashboard and a rails app I worked on

1 Like

I also use dockerize, first tried but dockerize also brings in templates which is why I went for it :slight_smile:

I have a problem running the docker image. It seems the DB is not initialized. Here is a part of the output from mvn docker:start:

06:20:57.484 DB> /usr/local/bin/ running /docker-entrypoint-initdb.d/openmrs-platform-database.sql
06:20:57.487 DB> Warning: Using a password on the command line interface can be insecure.
[ERROR] DOCKER> [teleivo/openmrs-platform-mysql:2.0.0] "db": Timeout after 60019 ms while waiting on log out 'MySQL init process done. Ready for start up.'
[ERROR] DOCKER> Error occurred during container startup, shutting down...
[INFO] DOCKER> [teleivo/openmrs-platform-mysql:2.0.0] "db": Stop and remove container d7ff92058781
[ERROR] DOCKER> [teleivo/openmrs-platform-mysql:2.0.0] "db": Timeout after 60019 ms while waiting on log out 'MySQL init process done. Ready for start up.'
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] Radiology ......................................... SUCCESS [1.471s]
[INFO] Radiology API ..................................... SUCCESS [0.723s]
[INFO] Radiology OMOD .................................... FAILURE [1:02.928s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1:05.759s
[INFO] Finished at: Fri Aug 26 06:21:40 CEST 2016
[INFO] Final Memory: 32M/315M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal io.fabric8:docker-maven-plugin:0.15.11:start (default-cli) on project radiology-omod: [teleivo/openmrs-platform-mysql:2.0.0] "db": Timeout after 60019 ms while waiting on log out 'MySQL init process done. Ready for start up.' -> [Help 1]

never mind, I installed a new server based on ubuntu 16.04 and started from scratch. The installation there works. The previous errors were on a ubuntu 14.04 based system (just fyi)

1 Like

dear @mkauzlar I just see a fraction of the log (also dont know the command you executed) but it says that the maven docker plugin error is due to it reaching a timeout. You might have to increase the timeout. Duration depends on the environment you run this.