OpenMRS SDK (latest version - 2.1, released on 2015/11/18) 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
- Examples of usage
- List of commands
- Server properties file
- Project Resources
Please help us improve SDK. We kindly ask you to report any problems in JIRA or in notes. Please include the output of openmrs-sdk:help in your problem description. In order to test SDK on your computer please go through the Step By Step instructions that you find below.
- 2.1 (released on 2015/11/18)
Key Summary T Assignee Reporter P Status Resolution SDK-76 Remove database with server remove Dmytro Trifonov Dmytro Trifonov Closed Fixed SDK-79 One should be able to upgrade to the same version Rafal Korytkowski Rafal Korytkowski Closed Fixed SDK-67 Add support for uiframework development mode Rafal Korytkowski Rafal Korytkowski Closed Fixed
- 2.0.3 (released on 21/09/2015)
Key Summary T Assignee Reporter P Status Resolution SDK-78 SDK falls on executing "setup" command Dmytro Trifonov Dmytro Trifonov Closed Fixed SDK-77 Y/N option should be shown with default option in caps Dmytro Trifonov Darius Jazayeri Closed Fixed
- 2.0.2 (released on 27/08/2015)
- all release notes...
1. Development Environment Check
Before we get started with the installation of the OpenMRS SDK you have to make sure that if you are planning on working in conjunction with GitHub, that you have
Git installed. For a howto on how to do that see here.
Once Git is installed, you have to make sure that you have the Apache Maven installed. To see if you do, open up a console/terminal and enter
You should see output like this:
SDK requires Maven 3+ and JDK 1.7+ installed. You can download Maven from here and install.
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 "-Xmx2048m -XX:MaxPermSize=1024m". It depends on your OS 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.
Once completed this, let's move onto setting up the sdk.
2. Setting up OpenMRS SDK
For setup the SDK you just need to open the terminal and execute:
Once it is finished, you can make sure the SDK works. To do so, open up a terminal/console and issue the following:
The output it gives, should be similar of that below:
If that is the case, you have successfully installed the SDK.
3. Upgrading OpenMRS SDK
If your SDK version isn't the latest version, you can update it using -U option with any SDK command.
For example, execute mvn openmrs-sdk:help -U, to be sure that you have the latest version installed.
Examples of usage
For all commands, you may not pass any attributes. In this case, all required parameters will be prompted in interactive mode.
Creating a module
OpenMRS Platform module
The SDK allow you, the user to create a basic module, with little effort! All that you have to do is, make sure you have a console/terminal window open and make sure you are
in a directory that you have write access to. If that is the case, you just issue the following:
This will now prompt you for various inputs, the default value/name is already assigned, which you can change if you input your own.
Once the creation process is finished, you can now start working on your module. Be sure that you initialize a git project and push it to
your Github account for easy development access.
OpenMRS Reference Application 2.x module
Similarly as creating OpenMRS 1.x module, you can create module for OpenMRS 2.x. For that, you can execute command:
Creating a server
OpenMRS Platform server
For running and testing OpenMRS modules we need to create and configure an OpenMRS server instance. For creating a OpenMRS platform server you can use setup-platform command.
NOTE FOR WINDOWS USERS
In windows, the command above may give a maven error stating POM.xml not found..build failed. To resolve this issue, avoid inserting the parameters. Instead, simply type in :
And you will be prompted for the parameters which you can enter manually. Same instructions go for setting up the Reference Application server as well.
You can pass server attributes for the server. To get full list of them, see setup-platform section of this documentation.
If command will executed without errors, server will be created in $HOME/openmrs/<serverId> directory.
OpenMRS Reference Application 2.x server
You need to have your own MySQL instance running to create a Reference Application server with the SDK. Specify your existing root password for the
-DdbPassword= argument below.
Similarly as create platform server, you can create OpenMRS Reference Application (RA) 2.x server, using setup command.
Note, that SNAPSHOT versions for RA based server also supported. For example, you can create OpenMRS 2.3-SNAPSHOT based server.
Creating server from properties file
During module development, sometimes we need to execute module on other machine (for example, on a remote server), but using the similar OpenMRS server instance (with a same configuration). Basically there are two ways to do that: move all server files to remote, or run setup command with required parameters, and install all required user modules. But you can move server much easier, using server properties file (see installation.properties).
For that, copy server properties file on remove server, and then execute:
The same server, as original for this properties file, will be created. The same option also will work for setup-platform command.
If any other option except file will be added, it will override options of a file. For example:
In this case, server will be created with a name "test3", even if other name selected in installation.properties file. In the same way you can override all available server attributes (see setup, setup-platform).
Installing module on server
To install module on selected server, just execute install task with required parameters (see install options). Note, that before installing a module on server you must install it lo local maven repo (launch mvn clean install for this)
Also you may not pass any module parameters for this command, for this you must execute install task directly from module folder, and current module will be installed (parameters will be fetched from module pom file)
Uninstalling module from server
To uninstall module from server, just execute uninstall command (see uninstall options)
Watching module for changes
Since SDK 2.1 it is possible to enable the uiframework development mode for modules. You can add any module to server's list of watched modules by going to modules source code main directory and typing:
You can also list watched modules for the given server typing:
If you want to stop watching a module type:
Running a server
OpenMRS 1.x instance with an embedded Database
Within the module that you just created, you can choose to run OpenMRS platform with an Embedded Database to test the module you are working on.
First, you need to create server:
Than you need to install you module to server. For that, execute next:
Plugin will ask you for a serverId of server, you must put the id of just created server. After that, you can execute it:
If you run this command from the server folder, the server will start immediately. Otherwise plugin will ask you for a serverId.
If the server starts successfully, you can access a fully running OpenMRS instance by going to http://localhost:8080/openmrs
If a previous install of OpenMRS did not happen, an automatic installation will be done. When the wizard is finished, the page will refresh and
you can login using:
The module you were working on, providing it was built without any error, should be visible on the administration page.
OpenMRS Reference Application 2.x instance with an external database
Steps for creating OpenMRS 2.x server, and starting, are mostly the same as for 1.x. First, setup 2.x server:
Besides serverId, you must put database driver class, database URI, login and pass for database user.
And finally, install module to server, and run selected server (These steps are absolutely the same as for OpenMRS 1.x)
Running a server from server folder
OpenMRS SDK 2 supports an option of running a server without passing any parameters (serverId). For this, you can execute run task directly from server folder.
After that, server <serverId> will be executed.
Running a server from module folder
During module development, we need to test how out module works. For that each time we need to install a module on server, and them run. SDK allows to do it much more simple. You can execute run task directly from module folder, and selected module will be installed on server before launching automatically.
As usually, you may not pass serverId as a parameter of run task, in this case serverId will be prompted in interactive mode.
Running a server on different ports
Basically OpenMRS instance launching on 8080 port, but you can choose any other port for executing. For this, you can pass jetty.port option for run task.
Reset server, with saving user modules
To return server to its default state (as it was after creating) you may use reset command. All user data (database data, except user modules) will be removed. See more details about reset.
You may remove current server, without passing serverId option. For this, please run reset from server folder.
Full reset, with removing user modules
To return server to default state, including user modules removing, you may pass a full option for reset task.
Upgrade platform based servers
For upgrading OpenMRS Platform server to later version, you may use upgrade-platform command. See more details about upgrade-platform.
Note, that you can't make upgrade to lower version of OpenMRS Platform, only to higher.
For upgrading current server, without passing serverId option, just execute command from server folder.
Upgrade Reference Application based server
For upgrading Reference Application server, you can use upgrade task.
Also you can upgrade platform server to Reference application server. For this, also use upgrade task as described above, no any additional options required.
Fixing errors on server upgrade
If upgrading server finished with an error (for example, if you tried update server to missing server version) you can return server to previous state, which was before running upgrade.
Server files wouldn't be removed, but you just need to remove "old.properties" file to "installation.properties".
For deleting server and all server files, use delete command. See details about delete. Please note that currently server data will not be removed from database after remove, so you need to remove this data manually. Database name for selected server you can find in installation.properties file.
List of commands
These commands are mainly used for working with an OpenMRS Module, however certain ones can come in handy if you are doing development on the OpenMRS core.
Each command can be executed by:
Each option must be passed with next format:
Here is an example of executing run task, with an option "serverId" which has a value "test":
All supported commands listed below:
|Displays all available commands and their information.||N/A|
|Creates module for OpenMRS 1.x||N/A|
|Creates module for OpenMRS 2.x||N/A|
|Runs previously created OpenMRS server|
|Creates OpenMRS 1.x server|
|Creates OpenMRS 2.x server|
|Installs module to selected server (you must install it to local repository before, using "mvn clean install")|
|Removes module from selected server|
|Adds module to the list of watched modules for the given server|
|Removes module from the list of watched modules of the given server|
|Displays information about the server including a list of watched modules|
|Upgrades OpenMRS platform server to selected version.|
|Upgrades OpenMRS 2.x server, or OpenMRS Platform server to 2.x. User modules will be saved|
|Updates server to default state (database data, configuration, and optionally user modules)|
|Remove selected server|
Note! All parameters, except "optional" are required, and will be prompted if user will no put them
Server properties file
Server properties file - is a file, used for saving server properties, which required while running OpenMRS instance. File name of this file is usually "installation.properties", both for platform and Reference Application types of server.
Installation.properties file usually placed in $HOME/openmrs/<serverId>/installation.properties
|connection.username||Username for database connection|
|connection.url||URL for database connection|
|server.id||Unique name of a server|
|connection.driver_class||Database driver class|
|connection.password||Password for database connection|
|admin_user_password||Default admin password (used for first launch)|
|user_modules||Comma-separated list of user modules.|
|add_demo_data||Add demo data to server (platform server only)|
|database_name||Database name for server (usually generated automatically)|
|openmrs.version||Web App version (non-platform server only)|
|OpenMRS 2.x SDK||https://github.com/openmrs/openmrs-contrib-sdk-maven-plugin|