Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

This tutorial will introduce you to OpenMRS SDK (Server Software Development Kit). It assumes that you have basic understanding of OpenMRS modular architecture (you can learn about it by reading Technical Overview).

To get started ensure that you have installed the latest version of OpenMRS SDK and Oracle JDK 8. You can find instruction how to do that on OpenMRS SDK wiki pages.

In this tutorial we will walk step by step through common use cases and scenarios.

Table of Contents

Why use the SDK

The question is why do I need to use the SDK for development, instead of installing Tomcat and using my own configuration.

The SDK is the tool for setting multiple self contained servers that can be run independently, at times at the same time by running each available server on a different port specifying the -Dport variable. You can even mix the servers, having those running JDK 1.7 for 1.11.x and JDK 1.8 2.x alongside each other.

The SDK creates an indpendent Tomcat instance with its own database. 

Setting up dev environment

To set up your dev environment, you have to execute 4 steps:

  1. Create server
  2. Add developed project to watched projects on server
  3. Create debugging configuration in IDE
  4. Run server

We will walk through these steps and create environment to develop and debug REST module on top of OpenMRS 2.0.0 platform.

To create server, run:

Code Block
mvn openmrs-sdk:setup -DserverId=webservices-dev -Dplatform=2.0.0

SDK will fetch artifacts, and prompt you for debug port:


Which database would you like to use?:
1) H2
2) MySQL 5.6 7 (requires pre-installed MySQL 5.67)
3) MySQL 5.6 7 in SDK docker container (requires pre-installed Docker)
4) Existing docker container (requires pre-installed Docker)


If you have properly configured JAVA_HOME, answer '1'. If not, you need to answer with '4' and type path to JDK on your machine. Please note that OpenMRS platform 2.x requres JDK 8 to run.

Now, when server is created you need to get source of REST module. To do that, in your workspace directory run: 


Code Block
mvn openmrs-sdk:run -DserverId=webservices-dev

And run remote debugging configuration from IDE Remote debugging has important advantage over running server from IDE - you can debug multiple projects with single server run (but only one at the same time), and run debugging only when you need to debug.

Alternatively, you can create direct Maven configuration in IDE to run:

Code Block
mvn openmrs-sdk:run -DserverId=webservices.-dev -Dfork=false

Steps to create debugging configuration depend on IDE you are using, but it should be quite easy to find.


This way you can set up development environment for any module and openmrs-core. Remember that you have to provide all required modules by currently developed module.

Developing with the Reference Application

You can easily develop/ debug modules with the Reference Application just like with the platform. The steps are as follows.

  1. Create a distribution server.
  2. Select Reference Application version.
  3. Set debug port.
  4. Connect with database.
  5. Add a module as watched in the selected server.

As before, create a server by running 

Code Block
mvn openmrs-sdk:setup

This will start the SDK in the wizard mode. When prompted, give a name to the server you're creating.

Next, you will be prompted to select server type.

Code Block
You can setup the following servers:
1) Distribution
2) Platform
Which one do you choose? [1/2]:

Make a Distribution server by entering 1. Next you'll be prompted to select the distribution version.

Code Block
You can deploy the following versions of distribution:
1) Reference Application 2.6-SNAPSHOT
2) Reference Application 2.5
3) Reference Application 2.4
4) Reference Application 2.3.1
5) Reference Application 2.2
6) Other...
Which one do you choose? [1/2/3/4/5/6]:

Select the latest Reference Application version by entering 1. The rest of the steps are the same as explained under Setting up dev environment. The watched modules will be built from source and deployed to the selected server every time you run that server.

Creating new distribution

OpenMRS distribution consist of platform and set of modules. SDK distribution is specified in properties file, by convention named Minimal valid distro file contains 3 fields:


name= OWA development
version= 1.0
war.openmrs= 2.0.0



Now, when we have our distro configuration file, you can setup server from this directory containing file with  with command:

Code Block
mvn openmrs-sdk:setup

You can see these steps executed on asciinema:

Image Added

Replicating environment for troubleshooting


To allow others to reproduce your server configuration, you have to create '' file  file with modules deployed on failing server. Since SDK 3.4.x you can go to your server directory `{user directory}/openmrs/{name of server}` and copy this file to share it with others. If you are using older version of SDK or standalone OpenMRS, you need to manually create this file as described in Creating new distribution


To create dump from dockerized MySQL database, you need to use mysqldump from within the container. We will show it on example of creating dump of MySQL database in SDK container. First, ensure that SDK container "openmrs-sdk-mysql-v3-2" is started:

Code Block
docker start openmrs-sdk-mysql-v3-2


Code Block
docker exec -it openmrs-sdk-mysql-v3-2 mysqldump -u root -pAdmin123 {name of database, equal to name of server} > dump.sql

Username 'root' and password 'Admin123' are standard credentials for MySQL instance in container created by SDK. Creating dumps from custom container looks analogously, you just have to replace container name and credentials.

After command execution, you will have dump.sql file in your working directory.


Now, if you want to replicate environment of other developer, and you are provided and dump.sql, you can do that in one step:


from directory where you have those 2 files. flag '-Drun' makes  makes SDK automatically run server after successful setup. Go to http://localhost:8080/openmrs/ to complete the setup.



Page properties

Related issues