Page Comparison

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

To get started ensure that you have installed the latest version of OpenMRS SDK. 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

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 platform.

To create server, run:

mvn openmrs-sdk:setup -DserverId=webservices-dev -Dplatform=2.0

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

If you want to enable remote debugging by default when running the server,
specify the port number here (e.g. 1044). Leave blank to disable debugging.
(Do not do this on a production server) (default: 'no debugging'): 

Type default value '1044' and push enter. Specifying debug port is essential to setup remote debugging configuration. You will be asked what database you want to use:

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

In this tutorial we will use most simple solution: H2, so answer with '1'. Last prompt will ask you for path to JDK:

Which JDK would you like to use to run this server?:
1) JAVA_HOME (currently: /usr/lib/jvm/java-8-oracle/jre)
2) /usr/lib/jvm/java-7-oracle/jre
4) Other...

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.

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

mvn openmrs-sdk:clone -DgroupId=org.openmrs.module -DartifactId=webservices.rest

SDK will ask you for your GitHub credentials, then fork repository and clone it. Enter newly created 'openmrs-module-webservices.rest' directory and add project to watched projects with

mvn openmrs-sdk:watch -DserverId=webservices-dev

From now on, every time you run 'webservices-dev' server, SDK will automatically execute steps:

1. Build webservices.rest module with 'mvn clean install -DskipTests'

2. Deploy webservices.rest module to webservices-dev server, equivalent of manually running:

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

So you will always have module compiled from your sources on 'webservices-dev' server.

Now it's time to create debugging configuration in IDE. Recommended way is to create remote debugging configuration on adress 'localhost:1044' (1044 is debug port you specified during server creation). This way, you can run instance from command line:

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

And run remote debugging configuration from IDE when you need to debug.

Alternatively, you can create direct Maven configuration to run:

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.

Example screens of configurations for IDEA IntelliJ:

Remote debugging

Image Added

Direct debugging

Image Added

Creating new distribution

...

To sum up, our openmrs-distro.properties file will look like this:

name= OWA development
version= 1.0
war.openmrs= 2.0
omod.owa=1.6.2
omod.webservices.rest=2.17-SNAPSHOT 

SDK automatically assumes that modules Maven Group ID is 'org.openmrs.module', but you can declare another Group ID

...