Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

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

Documentation

Skip to end of metadata
Go to start of metadata

Overview

OpenMRS SDK allows for rapid development of modules and the OpenMRS Platform code. It is an ever expanding project with a rich feature-set, outlined below. Operating System compatibility was also taken into account, allowing users to install the SDK and be up and running within a few minutes on Windows, Linux and Mac OS X.

Release Notes

Installation

Requirements

JDK 1.7 and/or JDK 1.8

To make sure that you have JDK 1.7 or JDK 1.8 installed properly, open up a console/terminal and enter:

on Windows:

on Linux/Mac:

It should say:

If you do not have similar output or the Java version does not start from 1.7 or 1.8, then you have to install JDK. Follow Oracle's guide.

Maven 3.x

To make sure that you have Apache Maven 3.x installed, open up a console/terminal and enter:

You should see:

If you do not have similar output, you are missing the Maven, please go ahead and install it.

Here are tutorials for WindowsMac OSXUbuntu.

Miscellaneous 

Although Git is not necessary for OpenMRS SDK to work, we recommended you to install it as well. See here.

You will also want to make sure that your maven has enough memory available for building code, running tests and servers. Please set the MAVEN_OPTS system property to "-Xmx768m -XX:MaxPermSize=512m". It depends on your OS on how you set it up. See http://stackoverflow.com/a/2820738 for Windows or http://unix.stackexchange.com/a/117470 for Unix/Linux.

If you are using an IDE for calling openmrs-sdk commands, please make sure to configure VM arguments in run configurations accordingly.

You will also need MySQL 5.6 for development of most OpenMRS modules. Please follow MySQL's guide.

Once completed, let's move on to setting up the SDK.

Setup

To setup the OpenMRS SDK you just need to open up a terminal/console and enter:

Once it is finished, you can make sure the OpenMRS SDK works by running the following command:

It should produce the following output:

If that is the case, you have successfully installed the SDK.

Upgrade

You can upgrade to the latest version of the OpenMRS SDK by running:

Basic usage

Let's start from creating a server to run the OpenMRS platform or a distribution. 

When asked specify server id, which you will later use to run your server. You can have as many servers as you want. Each server can run a different set of modules and use a different database.

Next type '1' to setup a distribution or '2' to setup the OpenMRS platform without any modules.

Note that for running a distribution you will most likely need to have MySQL 5.6 installed.

Answer all remaining wizard questions, which may include selecting a version of platform or distribution, database connection details, JDK path.

Next let's create a module.

You will need to choose what type of module you want to create. It is either a platform module, which can be run on any server or OpenMRS Reference Application module, which needs to be run on a server with the OpenMRS Reference Application distribution installed.

A new directory named after the artifactId (basicexample by default) will be created for you with all the initial code constituting any OpenMRS module.

Let's build, deploy and run the module on the server.

You will be asked to choose the server id, which you want this new module to be deployed to. If you do not want to be asked for the server id each time you run the module, just use:

When running the server for the first time, you will see:

You need to go to http://localhost:8080/openmrs/ to complete the setup. You should see a page with the installation progress. Once done you will be redirected to the login page. Use admin as the username and Admin123 as the password.

Documentation

The OpenMRS SDK consists of a number of commands. In this section we will cover different use cases for them. By default all OpenMRS SDK commands work in a wizard mode that is, if there are any parameters required, but not provided, you will be asked for them.

Setting up servers

The openmrs-sdk:setup command allows you to easily create instances of servers running OpenMRS. You can have as many servers on your machine as you wish. They are stored in ~/openmrs (Linux/Mac) or  %userprofile%\openmrs (Windows).

The OpenMRS SDK supports setting up a server with a plain platform or any distribution.

Databases

Servers can be configured to use H2 or MySQL 5.6 database. The H2 database is only supported by some modules. If you choose to install the Reference Application distribution, you must use the MySQL database.

The SDK comes with the H2 database so you do not have to install anything to use it. The MySQL 5.6 database needs to be installed prior to using it with the SDK. Please refer to installation instructions.

An H2 database is stored in a directory under ~/openmrs/server_id/database

A MySQL database is created, if it does not exist when running setup. If you include @DBNAME@ in a dbUri, it will be replaced with "server-your_server_id".

Distributions

The SDK supports setting up a server with a distribution. The OpenMRS distribution consists of a platform and a set of modules.

If your distribution is published as a maven artifact, you can make it work with SDK by simply adding openmrs-distro.properties file under src/main/resources. That way others will be able to setup your distribution by simply typing -Ddistro=package:artifactId:version. To setup such a distribution it is not even required to clone its repository as Maven will fetch the given artifact from a remote repository.

See here how it is done for the Reference Application distribution.

If you do not use maven to publish your distribution, you can also create openmrs-distro.properties file. The openmrs-sdk:setup command will have to be run from a directory, which contains the file or with -Ddistro=path/to/openmrs-distro.properties.

See here how it is done for the Concept Dictionary OWA server.

Examples

Examples are provided as batch commands whenever possible, which means parameters are specified explicitly and you should not be asked questions. If you skip the parameters, you should be able to achieve the same following wizard questions.

Setup OpenMRS Reference Application 2.3.1 on MySQL database
Setup OpenMRS Platform 1.11.5 on H2 database

Which JDK would you like to use to run this server?:
1) JAVA_HOME (currently: C:\Program Files\Java\jdk1.7.0_51)
2) Other...

Which one do you choose? [1/2]:

Answer: 1

The server will use JAVA_HOME system variable whenever starting up. It means that if the value is changed in the system, the server will start using the new value after restart.

Setup OpenMRS Platform 1.11.7-SNAPSHOT on MySQL database

Which JDK would you like to use to run this server?:
1) JAVA_HOME (currently: C:\Program Files\Java\jdk1.7.0_51)
2) Other...

Which one do you choose? [1/2]:

Answer: 1

Setup Concept Dictionary OWA distribution on H2 database

Setting up a new server...

You can setup the following servers:
1) OpenMRS Concepts OWA server 1.0 from current directory
2) Distribution
3) Platform
Which one do you choose? [1/2/3]:

Answer: 1

Would you like to use the h2 database (-DdbDriver) (note that some modules do not support it)? [Y/n]:

Answer: Y

Which JDK would you like to use to run this server?:
1) JAVA_HOME (currently: C:\Program Files\Java\jdk1.7.0_51)
2) Other...

Which one do you choose? [1/2]:

Answer: 1

Deleting servers

You can delete a server by running:

The command will delete the server as well as the database it used. If the command fails for some reason, you can delete the server manually by dropping ~/openmrs/mysever (Linux/Mac) or %userprofile%\openmrs (Windows) directory.

Creating projects

To create an openmrs module project in the current directory, use the openmrs-sdk:create-project command. The newly created project has basic structure and configuration files generated from an archetype. It is ready to be built and installed on an OpenMRS instance right after creation.

There are two types of projects: referenceapplication-module and platform-module. After you choose the module type, the SDK will run a wizard, where you will have to provide information about a module to create.

Example

Creating a module has always the same workflow. The example shows how to create the Reference Application module.

In a directory where you want to have a directory with a project, run:

The wizard will appear:

What kind of project would you like to create?:
1) Platform module
2) Reference Application module

Which one do you choose? [1/2]:

Answer: 2

Define value for property 'artifactId': : artifactId

artifact id must be all lowercase and start from a letter, allowed a-z, 0-9

Define value for property 'package':  org.openmrs.module.artifactId: :

package must follow java conventions for naming packages

Define value for property 'A-moduleName': : 

module name is a user friendly name of your module, by convention it is module id with spaces

Define value for property 'B-moduleDescription': :

a couple of words about functionality of your module

Define value for property 'C-moduleAuthor': : 

author of module

Define value for property 'D-moduleClassPrefix':  Basic: :

module class prefix should follow java conventions for naming classes

At the end confirm configuration by typing Y and hitting Enter.

Deploying projects

The openmrs-sdk:deploy command allows you to deploy module, Open Web App, Distribution an Platform to your OpenMRS server. 

Deploying module

OpenMRS SDK supports deloying modules in two ways. Either by running the command from the directory that contains module or by passing module artifactId, groupId and version.

Deploy OpenMRS Appui module from any directory

What would you like to deploy?:
1) Module
2) Open Web App
3) Distribution
4) Platform

Which one do you choose? [1/2/3/4]:

Answer: 1

Please specify 'groupId': (default: 'org.openmrs.module'): 

Answer: org.openmrs.module

Please specify 'artifactId':

Answer: appui

You can deploy the following versions of the module:
1) 1.6-SNAPSHOT
2) 1.5.1
3) 1.4
4) 1.3
5) 1.2.2
6) Other...

Which one do you choose? [1/2/3/4/5/6]:

Answer: 1

If the module is installed you will be asked if you want to upgrade it

Module is installed already. Do you want to upgrade it to version '1.6-SNAPSHOT'? [Y/n]:  

Answer: y

Deploy OpenMRS Appui module from it's directory

Would you like to deploy appui 1.6-SNAPSHOT from the current directory? [Y/n]: 

Answer: y

Deploying OWA

This example will show how to install Concept Dictionary OWA.

You have the following servers::
1) refapp
2) platform-1-11-7
3) test
4) conceptdictionary

Which one do you choose? [1/2/3/4]: 

Select server you would like to use.

What would you like to deploy?:
1) Module
2) Open Web App
3) Distribution
4) Platform

Which one do you choose? [1/2/3/4]:

Answer: 2

Which OWA would you like to deploy?:
1) openmrs-owa-conceptdictionary
2) Other...

Answer: 1

Which version would you like to deploy?:
1) 1.0.0-beta.6
2) 1.0.0-beta.3
3) 1.0.0-beta.1
4) 1.0.0-beta
5) Other...

Answer: 1 to select latest version.

If you don't have Open Web App Module on selected server, before deploying OWA, SDK will install its latest version.

If there is no default directory 'owa' on selected server, you will have either to confirm to create it, or pass absolute path to directory where you want to install OWAs.

There is no default directory 'owa' on server refapp, would you like to create it? (if not, you will be asked for path to custom directory) [Y/n]: y

It it recommended to agree by answering with Y.

Deploying Distribution 

You can upgrade your server's distribution version(to 2.1 and above) using the openmrs-sdk:deploy command. OpenMRS SDK supports openmrs-distro-properties files that contains all necessary information(modules, core version etc.).
The parameter responsible for distribution is -Ddistro. You can pass there:
1) Artifact information e.g referenceapplication:2.3.1
2) Path to openmrs-distro.properties file
You can also run openmrs-sdk:deploy command from directory that contains openmrs-distro.properties file. 

Deploy Refference Application 2.3.1 from any directory

You will see all updates and additions required to upgrade the distribution version

The Reference Application 2.3.1 introduces the following changes:
^ Updates openmrs-webapp 1.11.2 to 1.11.5
.
.
.
^ Updates htmlformentry-omod 2.5 to 2.6
+ Adds adminui-omod 1.0
Would you like to apply those changes to 'server4'? [Y/n]:

Answer: y

Deploy Refference Application 2.3.1 from directory with openmrs-distro.properties file

Would you like to deploy serverID OpenMRS Concepts OWA server from the current directory? [Y/n]: 

Answer: y

You will see all updates and additions required to upgrade the distribution version

The Reference Application 2.3.1 introduces the following changes:
^ Updates openmrs-webapp 1.11.2 to 1.11.5
.
.
.
^ Updates htmlformentry-omod 2.5 to 2.6
+ Adds adminui-omod 1.0
Would you like to apply those changes to 'server4'? [Y/n]:

Answer: y

Deploy Refference Application 2.3.1 with path to openmrs-distro.poperties file

You will see all updates and additions required to upgrade the distribution version

The Reference Application 2.3.1 introduces the following changes:
^ Updates openmrs-webapp 1.11.2 to 1.11.5
.
.
.
^ Updates htmlformentry-omod 2.5 to 2.6
+ Adds adminui-omod 1.0
Would you like to apply those changes to 'server4'? [Y/n]:

Answer: y

 

Deploying Platform 

Deploying platform replaces OpenMRS core on selected server. 

Deploy 1.12.0 platform to selected server

If you will try to downgrade server's platform, you will be asked to confirm this action with prompt:

Note that downgrades are generally not supported by OpenMRS. Please consider setting up a new server with the given version instead. Are you sure you would like to downgrade? [Y/n]

Watching projects

You can add a module as watched by the selected server executing the openmrs-sdk:watch command in module's project directory. 

UI changes (given UI Framework is used) in project's code will be automatically deployed to the running server.

Running and debugging servers

You can run any server with:

If you do not specify the serverId parameter, then you will be presented with a list of previously setup servers:

You have the following servers::
1) conceptdictionary
2) platform-1-11-7
3) platform-1-11-5

Which one do you choose? [1/2/3]:

By default a server is started on port 8080 so you should be able to access it opening up http://localhost:8080/openmrs in your browser. You can change the port by specifying -Dport=8081.

The SDK runs OpenMRS on embedded Tomcat 7.0.6, which you do not have to install, because it is bundled with the SDK. By default it uses -Xmx768m and -XX:MaxPermSize=512m for memory settings. You can increase those settings by defining MAVEN_OPTS="-Xmx768m -XX:MaxPermSize=512m" in your system properties or in a run configuration in your IDE. If you specify lower values, they will be increased to the default values as they are required to run OpenMRS.

If you execute the run command from a directory with a module or openmrs-core project, it will be automatically deployed before starting up the server. You can add the following run configuration to the IDE to build, deploy and run the project:

Debugging

You have 2 ways of debugging a server. First is by connecting to a running server by using a remote debugger configuration in your IDE. To run the server in remote debugging mode use:

By default the server listens for remote debuggers on port 1044. You can configure it to use a different port by setting -Ddebug=1045.

Alternatively, you can debug a server by running it in a debug mode straight from your IDE. It depends on your IDE, how to do it, but usually you just create a debug configuration and as the run command specify:

It is important to use -Dfork=false to disable forking a new process for Tomcat as it is not possible to debug a forked process that way (the debugger stays connected to the Maven process and not the Tomcat process).

Setting JDK

When setting up a server you are asked to select JDK. OpenMRS Platform 2.x requires JDK 1.8 whereas lower versions require JDK 1.7. The SDK prevents you from running a server using a wrong JDK. You should see the following message trying to do so:

The JDK 1.7.0_51 is not compatible with OpenMRS Platform 2.0.0-beta. Please use JDK 1.8 to run this server.

If you are running in a forked mode, correct the java.home property in C:\Users\Rafal\openmrs\platform\openmrs-server.properties

Following the message please correct the java.home property in openmrs-server.properties by pointing to the correct JDK version.

Feedback 

Please help us improve SDK. We kindly ask you to report any problems in JIRA. Please include the output of openmrs-sdk:help in your problem description.

Contributions

The SDK 1.x was developed by Chris Niesel mentored by Rafał Korytkowski as part of Google Summer of Code 2013 (GSoC 2013).

In GSoC 2015 the OpenMRS SDK was reworked by Dmytro Trifonov mentored by Rafal Korytkowski to support OpenMRS Reference Application 2.x and provide better integration with IDEs by the mean of a maven plugin.

In 2016 Soldevelo developers Adam GrzybkowskiPaweł GutkowskiTomasz Marzeion lead by Rafal Korytkowski worked on OpenMRS 3.0.0 and OpenMRS 3.1.0 release.

Resources

  1. Repo: https://github.com/openmrs/openmrs-sdk
  2. JIRA: https://tickets.openmrs.org/browse/SDK
  • No labels

13 Comments

  1. Why does openmrs-skd:help need to download anything at all?

  2. Does the SDK support building local versions of openmrs-core yet?

  3. To clarify SDK doesn't have any commands to build code. It does have commands to run it and yes you can run openmrs-core built localy by just specifying a SNAPSHOT version. For example mvn openmrs-sdk:setup-platform -Dversion=2.0.0-SNAPSHOT -o. Remember you need to run mvn clean install in openmrs-core first. Note the offline switch -o, which makes sure your local version is used and not a one built and deployed by our CI.

  4. The structure of this page is confusing if you're not sure what you're supposed to be using the SDK for.

    It would be very helpful to have a tutorial-style description of how to use the SDK to work on a ticket, and test out your changes. Do we already have this anywhere, or can it be added to this page?

  5. The SDK creates a database openmrs-<serverId>. If my serverId is let's say reference the database it creates is 'openmrs-reference'. Is this normal?

      1. Now that I look closely I see it does this for me too. I was surprised.

        It would make more sense if things the sdk does were prefixed by "sdk" or "openmrssdk" rather than just "openmrs". E.g. that it created me a ~/openmrs folder, and this database name prefix

        1. You mean, add to SDK possibility to set custom prefix (instead of default 'openmrs') ?

          1. I don't think this should be configurable.

            I'm saying that I would prefer if the default behavior were different. As an OpenMRS developer, I have lots of folders called "openmrs" in different places, and also lots of "openmrs" databases. For me it would be a lot more clear if the things that the SDK created were called "openmrssdk" instead of just "openmrs" so it would be obvious where something came from.

            (If I only used the SDK, I guess this would matter less.)

  6. How can I debug if we run the application using openmrs-sdk 

    mvn openmrs-sdk:run -DserverId=test

    1. For example, you can create debug configuration in your favorite IDE, with this command, and use IDE for debugging.
      In future, we will add support of popular IDE run configurations to SDK, to make possible create them automatically.

       

    2. Got debugging working 

      If you set MAVEN_OPTS 

      export MAVEN_OPTS="-Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000"

      and then run mvn openmrs-sdk:run -DserverId=test

      You can then attach a debugger on 8000 port. Let me know if you think I should add this information to the page as well instead of a comment

  7. As a feature request for SDK 3.0...the command names are not intuitive to me. It would be better if they were longer, but clearer.

    For example:

    • mvn openmrs-sdk:setup-server ...
    • mvn openmrs-sdk:install-module ...
    • mvn openmrs-sdk:run-server ...