All OpenMRS ID accounts have been reset.

Read more and change your password before signing in.
Icon

EXTENDED: OMRS14 Proposals due 30 April! Read more and submit a proposal at OpenMRS Talk.

Skip to end of metadata
Go to start of metadata
Icon

Below is a listing of software applications that you will need to install in order to develop in the OpenMRS codebase. The installation process may vary somewhat for Windows, Linux (Step By Step Instructions), or Mac OS X platforms. Still, OpenMRS depends mostly on Java which runs the same across those systems. This list will try to describe the software which you should install to start work on any development computer.

See also http://notes.openmrs.org/OpenMRS-University-2012-12-19 where you can find videos showing the same steps. 

Dependencies to install

Java 1.6

Java is the language in which OpenMRS is written. The latest version of OpenMRS requires at least Java version 1.6. If you plan to edit the source, you will need the JDK; if you plan just to run OpenMRS, you will only need the JRE.

If using a JDK, then navigate to Window -> Preferences -> Java -> Installed JRE's to check if the JDK has been set. If not, do so.

Icon

There are tests failing when run on JDK 1.7 so please use JDK 1.6 until TRUNK-3142 is resolved.

MySQL

MySQL is the database software most people use for the OpenMRS database. You should know your MySQL root password, or have a database ready with username and password to install OpenMRS into.

Eclipse 4.2.x (Juno) Instructions

Eclipse IDE for Java EE Developers is the recommended Java development environment. Get the latest stable release (though OpenMRS should still function on older versions that can use Maven integration). Eclipse 4.2.2 includes support for Git, but not for Maven so it must be added via plugins. Some OpenMRS modules are still in SVN instead of Git, so if you need to access them, you will want to install SVN plugins as well.  We recommend Eclipse 4.2 (Juno). However, the following installation instructions would also work on Eclipse 3.7 (Indigo) - just pay attention to which plugins you need with which version (and note there's a "shortcut" described below if you have a clean 3.7 install and want to just get all the additonal plugins in one go). If you are already running Eclipse 3.6 (Helios) and want to do OpenMRS development from there, see our old instructions.

 

How to install Eclipse plugins

Points of Interest

  • When installing the plugins, please follow the order specified below.
  • You should restart Eclipse as prompted after installing each component.
Installing the maven plugin (needed with all versions of eclipse)
  • Navigate to Help -> Eclipse Marketplace
  • search for "maven" via the search box.
  • select Maven Integration for Eclipse by Eclipse.org, EPL from the retrieved options
  • Install with all sub-options selected
  • Install
Install the git plugin (needed if you do not have 4.2, required for checking out the core OpenMRS code. Recommended for OpenMRS module development)
  • Navigate to Help -> Eclipse Marketplace
  • search for "git" via the search box.
  • select EGit - Git Team Provider by Eclipse.org, EPL from the retrieved options
  • Install with all sub-options selected
Install the Subversive plugin (Only needed for older projects still stored on svn.openmrs.org)
  • Navigate to Help -> Eclipse Marketplace
  • search for "subversive" via the search box.
  • select Subversive - SVN Team Provider by eclipse.org, EPL from the retrieved options
  • Install with all sub-options selected
Install an Subversive connector for the Subversive plugin (Only needed if you installed the above subversive plugin)
  • Once you restart Eclipse following the installation of Subversive, you will be automatically be prompted to install an Subversive connector.
  • From the options displayed by Subversive Connector Discovery, select SVN Kit 1.3.7
  • Install
Install the scm connector plugin (Only needed if you installed the above subversive plugin)
  • Navigate to (Window ->) Preferences -> Maven -> Discovery
  • choose Open Catalog
  • search for "scm" via the search box.
  • select m2e connector for maven-scm-plugin
  • select m2e-subversive
  • Install
OpenMRS Behavior Test Generator (optional)
Install Eclipse plugins Automatically, if you have a clean install of 3.7 (Indigo)

This method is supposed to be used with a clean Eclipse 3.7 (Indigo) installation (just downloaded from eclipse.org) and not one that has some plugins already installed by you.

  1. Download this file.
  2. Extract the zip file to the eclipse/dropins directory.

Congratulations, if the above steps were successful, then Eclipse has been configured and is ready for use.

(Optional) Tomcat

Jetty, a development-oriented J2EE server, is automatically provided with OpenMRS 1.8+, via Maven, and it integrates nicely with Eclipse's Run and Debug workflows. It is perfectly sufficient for most developer purposes.

Tomcat is a J2EE server on which OpenMRS can be deployed. Most production installations of OpenMRS run on tomcat, so if you want to test against the most common environment, you should install tomcat. You will want the core that matches your system specs the closest: probably 32-bit zip or 64-bit zip or bz2 on Linux.

Check out the core from Git Hub

Most importantly, you need to get the OpenMRS core code from GitHub: https://github.com/openmrs/openmrs-core

See Using Git for the overall docs.

For specific instructions for using Egit and Maven tools you have installed above, see Git IDE Integration.

If you are contributing to the main OpenMRS codebase, you want to check out "openmrs-core". If you want to contribute to a module, you should check out the release branch for the module's lowest required OpenMRS version (e.g.1.8.x or 1.9.x). OpenMRS began using Maven in 1.8.x, so for modules that run on earlier OpenMRS versions, you may find it easier to just check out1.8.x and test against that.

Compiling OpenMRS

Use Maven to compile and generate source files.

Go to the most outer project directory and run:

It will compile, run tests, build all artifacts and install them to your local repo.

Running OpenMRS

Before trying to run OpenMRS ensure you have MySQL running. Also, it is highly recommended to increase the memory available by following the steps in the Maven setup, or see Troubleshooting Memory Errors

You can now run OpenMRS by deploying the built WAR file into a J2EE container such as Tomcat or Jetty, or you can run it directly from the source code using the Maven Jetty plugin. The latter method is easier for developers as you can launch it from your IDE. However, if running this way for the first time, you will need to first manually install the core logic module. To do this, download the logic omod and copy it to your modules directory. Then you you start OpenMRS as follows: move into the "webapp" directory and execute following command

Wait for the [ INFO ] Started Jetty Server message and open the web browser at http://localhost:8080/openmrs. Follow the instructions.

(Optional) Module development

To contributing to an existing module, you need to check out its code.

If the module's source code is in Git, follow the Using Git instructions. If the module's source code is in subversion and the module is mavenized (i.e. it has a pom.xml file) then you should follow the same process described for the core code.

Older modules may be in subversion, and not yet mavenized (i.e. they have no pom.xml file). To check these out do New -> Checkout project from SVN.

To create a new module, we recommend Using Git and Using the Module Maven Archetype.

After you cloned a module you need to build it with mvn clean install.

To install a module, start OpenMRS and go to Administration -> Manage modules -> Add or upgrade module. You need to upload here an omod file, which you can find under cloned_module/omod/target.

Known issues

Once checked out, the pom file of each OpenMRS module will display the following error in Eclipse -
"Plugin execution not covered by lifecycle configuration: org.codehaus.mojo:build-helper-maven-plugin:1.5:parse-version (execution: parse-version, phase: initialize)"

This has no affect on the operation of the application, and can be safely ignored. (You may also choose "quick fix" and install the scm connector for this plugin.)

16 Comments

  1. I've noticed that once I have OpenMRS trunk installed into Eclipse, I see many pages marked with errors.  I understand that these are JSP fragments that Eclipse cannot fully understand and that these errors can be ignored.

  2. The comments on the 2 sets of eclipse configuration for maven are quite confusing. I think the focus should be on the market place as a source of teh plugin...quite quick i must say

    Anyway the m2 extras gave me a problem during installation, and several errors, but a reference to this previous discussion in the developer list was helpful....

    MSG

    Hi Rowan,

    I installed Eclipse Indigo + Maven today and I could successfuly install
    the SVN connector.

    I following these steps:
    1) Install Eclipse Indigo JEE
    2) Install m2eclipse via update site
    http://download.eclipse.org/technology/m2e/milestones/1.0
    3) Start "Check out Maven Projects from SCM" wizards and click on "Find
    more SCM connectors in the m2e Marketplace"
    4) select m2e-subversive and install it
    5) Restart

    Tests:
    Check out as Maven project - OK
    Run As > Maven targets - OK

  3. Setting things up on OSX 10.7 (Lion) ...

    I read about setting up JavaHL for OSX, unfortunately it recommends openCollabNet downloads and there isn't one for Lion (10.7) yet. :( 

    Macports ftw!

    After the installation completed, I restarted eclipse and the JavaHL option was available! (tongue) I don't know if I got 32-bit or 64-bit JavaHL (the openCollabnet notes suggested they might be 32-bit)... but it seems to be working for now.

    Trying to install m2e extras fails with the message:

    Solved: the solution is to use Maven's marketplace to add extra features (Preferences → Maven → Discovery → Open Catalog → m2e maven-scm-plugin).  I've edited the instructions above.

    1. Did you install m2e through the newer Eclipse Marketplace, rather than the older Install New Software?

      I did this (in Eclipse 3.7 on Snow Leopard) and I didn't get that dependency error:

      • Help → Eclipse Marketplace
      • "Maven Integration for Eclipse" (by Eclipse.org, EPL)
    2. Actually you don't need JavaHL bindings.. It's like ancient.. Select SVNKit api usage from the software updates for Subclipse, after you restart your Eclipse, it'll give you an option to pick SVNKit instead of JavaHL interface from Team -> Subversion under preferences..

      After this, u r ready to rock.

      Cheers,

      Isa

  4. I have 64 bit windows 7, and I ran into a bunch of errors when trying to set up my development environment.  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 about the JREs.

  5. I was installing plugins for eclipse indigo(Ubuntu 11.10) and while installing maven SCM handler for Subclipse plugin, i ran into the following error :

    An error occurred while collecting items to be installed
    session context was:(profile=epp.package.jee, phase=org.eclipse.equinox.internal.p2.engine.phases.Collect, operand=, action=).
    No repository found containing: osgi.bundle,org.sonatype.m2e.subclipse,0.13.0.201107071330
    No repository found containing: org.eclipse.update.feature,org.sonatype.m2e.subclipse.feature,0.13.0.201107071330
    An error occurred while collecting items to be installed

    session context was:(profile=epp.package.jee, phase=org.eclipse.equinox.internal.p2.engine.phases.Collect, operand=, action=).

    No repository found containing: osgi.bundle,org.sonatype.m2e.subclipse,0.13.0.201107071330

    No repository found containing: org.eclipse.update.feature,org.sonatype.m2e.subclipse.feature,0.13.0.201107071330

    How do i fix it ?

  6. On Win7 64 bit, I was also tripped up by JavaHL 1.6 not being added to the system path, as I had done the install from a limited user account and given it an administrator password to use. I had to reboot to get the path updated, a fact that took me more than hour to figure out :)

  7. I try to setup the dev environment again for all the latest Eclipse Indigo, I'm on Mac OS X Lion as well. I followed Burke's advice to install JavaHL via macports, and the "port install subversion-javahlbindings" completed successfully - however, I run into the following error at the end, when I try to checkout the code.  
    > Incompatible JavaHL library loaded.  1.6.x or later required.
    I try to setup the dev environment again for all the latest Eclipse Indigo, I'm on Mac OS X Lion as well. I followed Burke's advice to install JavaHL via macports, and the "port install subversion-javahlbindings" completed successfully (and both system and Eclipse restarted) - however, I run into the following error at the end, when I try to checkout the code.  

    > Incompatible JavaHL library loaded.  1.6.x or later required.
    

  8. Having problems with Subclipse and Maven SCM Handler. The version of Subclipse in the Indigo marketplace is 1.8, but the Maven SCM Handler "requires" 1.6 and refuses to install with anything higher (see http://dev.eclipse.org/mhonarc/lists/m2e-users/msg02496.html)

    Have to remove Subclipse 1.8 and then install Subclipse 1.6 manually from it's update site: http://subclipse.tigris.org/update_1.6.x

    Also not having much luck getting JavaHL to work on Windows 7 machines - using SVNKit instead

  9. I just set up on an Ubuntu 32-bit VM, and I installed subversive and its svnkit plugin, instead of subclipse. Seems to be working fine so far.

  10. I was getting errors on the class  ShouldTaglet.java about importing the packages:

    import com.sun.tools.doclets.Taglet;
    import com.sun.javadoc.*;import com.sun.tools.doclets.Taglet;
    import com.sun.javadoc.*;
    import com.sun.tools.doclets.Taglet;
    import com.sun.javadoc.*;

    And I think there are missing steps. This is what I did:

    Window->Preferences->Java->Installed JREs
    Standard VM
    Added JDK 1.6 by browsing to it's directory
    Add extenal JAR's
    Selected tools.jar located under JDK\lib. Pressed Finish
    Clicked on the checkbox marking it's active.

    After that, no more errors

  11. These instructions need some serious reworking. (dev list thread)

    I just did a new install on OSX of Eclipse 3.8 plus the plugins, and here are the notes I took while doing it. (Everything seems to be working without a hitch.)

    Eclipse Juno (3.8)
    Marketplace

    • "maven"
      • "Maven Integration for Eclipse" by Eclipse.org, EPL
      • (left both options checked)
      • restart
    • "subversive"
      • "Subversive - SVN Team Provider" by eclipse.org, EPL
      • (left all options checked)
      • restart
      • Subversive Connector Discovery: SVN Kit 1.3.7
    • "git"
      • "EGit - Git Team Provider" by Eclipse.org, EPL
      • (left both options checked)

    Preferences -> Maven -> Discovery

    • "scm"
      • choose "m2e connector for maven-scm-plugin" and "m2e-subversive"
    • also (found this later via Markers, Maven Problems) "m2e connector for build-helper-maven-plugin"

    (I reused my previous workspace, but I had to manually do Configure -> Convert to Maven Project on everything.)

    1. I was able to successfuly replicate all at my end.

      May i also suggest that eclipse references in the wiki should point to Juno rather than Indigo

  12. Manual installation of plugins appears to be broken at the moment. Latest m2e plugin version is at 1.1.0.2~ but the m2e-subversive plugin only supports up to 1.1.0. You can still use the p2f file for automatic installation but you definitely need to uncheck "Install latest versions" as the instructions say

  13. Read somewhere that Open JDK worked, but I got tag lib compile errors when doing so.  The code was referencing Sun's JRE.  Installed the latest sun jdk and got a clean compile,