Have you implemented OpenMRS? Please participate in the Implementation Site Survey. If you already have, thank you!
Page tree
Skip to end of metadata
Go to start of metadata
Table of Contents

Checkout Source and Create Project

  1. File → New → Project → Checkout Maven Projects From SCM

  1. For SCM, choose 'svn' and browse to the project (http://svn.openmrs.org/openmrs/trunk)

  1. In older versions of the m2eclipse Eclipse plugin (prior to 0.11.0), you have an option to place all modules within a single project; this feature is deprecated as of m2eclipse 0.11.0.
    Click Advanced, and uncheck "separate projects for modules" (if that doesn't exist, change m2eclipse setting in Window → Preferences → Maven → Support multiple maven modules)
  2. Click Finish to download and create the Maven project(s).

Note: If you get the following error while trying to check out the code, switch the SVN URL from http to https. (i.e. https://svn.openmrs.org/openmrs/trunk)

checkout http://svn.openmrs.org/openmrs/trunk -r HEAD --depth=infinity --force
RA layer request failed
svn: REPORT of '/!svn/vcc/default': Could not read status line: connection was closed by server (http://svn.openmrs.org)

Develop with Maven

There are five projects shown in the workspace: openmrs, openmrs-api, openmrs-test, openmrs-tools, openmrs-web, and openmrs-webapp. The openmrs project is a parent project. When we run any maven goal on the parent project, it will run the same goal on its children, according to the dependency order. A Maven menu item is added on the context menu, which lets you modify the pom.xml, manage dependencies and plugins, etc. Common maven goals are also added on the menu items Run As and Debug As. You can also create your own Maven Run Configurations.

How to run the build

  • Right click the openmrs project to bring up the context menu, select "Run as → Maven build..." (notice the "..." at the end)

  • Enter the Goals: clean install
  • Make sure the Maven Runtime at the bottom is correct for your installation (Configure for Embedded/External as necessary)
  • Select Apply, then Run

  • The build output will be displayed in the Console.
  • The output contains links to the results of each test.

To re-run the build, right click the root project to bring up the context menu, select "Run as -> Maven build."  If you have multiple configurations, select the "clean install" one to run.

To manage these configurations, right click the root project to bring up the context menu, select "Run as -> Run configurations...".  Select the configuration under the Maven Build section.

How to run Junit

If you want to run all tests across modules, select Openmrs project and right click to bring context menu, select "Run As → Maven test"

If you want to run all tests in one module, select that project and right click to bring context menu, select "Run As → Maven test"

If you want to run a single test class,right click on test class and select "Run As → Junit test"

How to Run Web Application

Create a run configuration by click "Run → Run Configurations", select Maven Build and click "New launch configuration", type Name "OpenMRS", select working directory to be the root of webapp project, type goal "jetty:run" and save. Now you select "OpenMRS" and run or debug it.

On the JRE tab, in the VM parameters box, you will want to put in your memory parameters, e.g.

-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512m -XX:NewSize=128m

If on running, you get error messages including this: "java.net.BindException: Address already in use", most likely the default 8080 port is in use. You may want to change to any other different port for jetty. For instance if you want to change to port 8081, then on the JRE tab, in the VM parameters box, add something like this: -Djetty.port=8081

See Troubleshooting Memory Errors or Performance Tuning or Increasing Memory for Maven

Jetty is currently configured to reload static resources like jsp, javascript files, etc. Changes to Java classes will require recompiling and restarting Jetty. (run maven:compile goal (if auto build is not enabled) and restart Jetty).

How to Profile Web Application with YourKit

Set up a run configuration as specified in "How to Run Web Application" but in the JRE tab, set the -agentpath VM option as specified in the YourKit docs. Common values:

  • Linux x86, 32-bit Java: -agentpath:<profiler directory>/bin/linux-x86-32/libyjpagent.so
  • Mac OS X: -agentpath:<profiler directory>/bin/mac/libyjpagent.jnilib
  • Windows, 32-bit Java: -agentpath:<profiler directory>\bin\win32\yjpagent.dll

(This assumes you have YourKit installed already.)

How to Debug Web Application

Jetty plugin can pick up any changes of static resources, so changes of jsp, property or css files don't require a restart. However changes of java class will have to restart. The following solutions could help in some situations.

JVM Hotswap

Not yet documented.

Hot Deploy

Not yet documented.

Use JRebel

Here is how you configure JRebel to work with OpenMRS

  1. Download JRebel and install it. http://www.zeroturnaround.com/jrebel/current/
  2. Install JRebel plugin for Eclipse and restart.
  3. Configure JRebel plugin for Eclipse.
    Specify location of JRebel installation

Tick "Use Step filters" and also add com.zeroturnaround.* and org.zeroturnaround.* to the filters Tick "filter synthetic fields"

  1. Configure JRebel Agent Setting provided by JRebel installation
    Untick "Spring Framework Plugin"
  2. Change "OpenMRS" Run configuration to increase Permgen and enable JRebel.
  3. Run or Debug "OpenMRS"

When you change any java classes, just wait for eclipse auto build to finish, reload the web page, and JRebel will reload the class for you.


  1. I got the following error while in the step "Checkout Source and Create Project":

    "Eclipse is running in a JRE, but a JDK is required Some Maven plugins may 
    not work when importing projects or updating source folders."

    It can be solved including the following two lines in the eclipse.ini:


    Replacing "C:/Java/jdk1.6.0_24/bin/" by the path of your JDK's javaw.exe

    It is important to separate it into two lines (i.e. "-vm C:/Java/jdk1.6.0_24/bin/"  doesn't work)

  2. I have 64 bit Windows 7, I ran into a bunch of errors when trying to set up my development environment, including the one mentioned in the previous comment.  Here is how I fixed them all.

    At one point I didn't get Java HL working.  So when I went to Window -> Preferences and then Team -> SVN, the SVN Interface: Client was blank.  I discovered that the SubVersion was 1.6 and the JavaHL was 1.7.  According to the list 1.7 only works with 1.8 of SubVersion.  So my first attempt to fix was to put in the newer version of SubVersion (1.8).  But then I discovered that Maven doesn't support the newer version.  What I did to get this fixed was to download eclipse and start from scratch (I was unable to uninstall and then reinstall the correct versions).  After getting a clean version of Eclipse, I clicked on the link to about how to download Java HL.  The link for 64 bit windows was to http://www.sliksvn.com/en/download.  The trick though is to not install the version that it displays.  You have to click on the link for "Old Versions Are Available Here" which takes you to http://www.sliksvn.com/pub/

    Then I installed the 64 bit (I have windows 7) version of "Slik-Subversion-1.6.17-x64.msi".  This worked with the 1.6 version of SubClipse which is the default (as of Feb 2012) in the Eclipse Market Place. 

    The next error that I got was the one about the JRE.  What I needed to do was download a JDK.  If you read the instructions, it says you need a JDK, instead of a JRE.  After installing the 1.6 JDK (off of Sun / Oracle we site), I set eclipse to use it via Windows -> Preferences then Java -> Installed JREs.  I clicked the Add button and added the JDK for 1.6 (by choosing the directory that it got installed to - for me that was C:\Program Files\Java\jdk1.6.0_30) and then clicked the checkbox for it (mine was JDK1.6.0_30).  That fixed the error that you mentioned about the JRE.

    The 3rd error that I got had to do with the fact that when I was trying to run the Jetty:Run that I set up via the instructions. I didn't put the base directory that they have in the picture.  You need to change it to that exactly.

    If I had had this comment when I did my set up, it would have saved me a ton of time.  I hope this helps other developers using 64 bit windows 7.

  3. I am getting the following error while checking out source : 

    Checkout error; RA layer request failed
    svn: OPTIONS of 'https://svn.openmrs.org/openmrs/trunk': Could not resolve hostname `svn.openmrs.org': No address associated with hostname (https://svn.openmrs.org)

    First i used http and then https but it's giving error on both.

    Any way to get this correct ?

    1. Sounds like a DNS or network connectivity problem. Try using a different DNS server, or otherwise making sure you can access https://svn.openmrs.org/ before checking out the code.

  4. I trying to check out the code source by the give address "http://svn.openmrs.org/openmrs/trunk", but this address dose not work,I can not connect to the IP, the error sayed"the server can not be connected". anybody know this error and how to handle this error.thank you very much!

    1. Sounds like a DNS or network connectivity problem. Try using a different DNS server, or otherwise making sure you can access https://svn.openmrs.org/ before checking out the code.

  5. I am also having problems checking out these projects the error is a follow : 'Checking out Maven' has ecncountered a problem SVN "Checking out AS operation finining with error", anybody who have had a similer problem help out please.

  6. Hi,

    when i compile the openmrs-core the build fails at the api, therefore i separately gave the "clean install" command for the api without skipping the tests, but the tests fail and it gives an error

    Running org.openmrs.util.OpenmrsUtilTest
    Tests run: 47, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.932 sec
    Running org.openmrs.api.VisitServiceTest
    [INFO] ------------------------------------------------------------------------
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 2:20.329s
    [INFO] Finished at: Sat May 18 18:46:32 EDT 2013
    [INFO] Final Memory: 31M/167M
    [INFO] ------------------------------------------------------------------------
    [ERROR] Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.5:test (default-test) on project openmrs-api: There are test failures.


  7. I am blocked on the step "Checkout Source and Create Project" in second screenshot. I have integrated maven with eclipse but the SCM URL type (the dropdown) is inactive. Any help there.

    Thanks in advance,