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

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

Java is the language in which OpenMRS is written. The latest version of OpenMRS requires at least Java version 1.6. It is reported to compile and run fine on Java 1.7 (1.7.0_60) and we are working on making it compatible with Java 1.8. 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 in Eclipse, then navigate to Window -> Preferences -> Java -> Installed JRE's to check if the JDK has been set. If not, do so.

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 Luna 4.4.1 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, see instructions for older versions).

The latest release has all plugins you need to start OpenMRS development. There is one optional plugin we recommend to install that allows you to create tests from @should annotations. 

How to install Eclipse plugins

OpenMRS Behavior Test Generator (optional)

(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.)

22 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,

  14. The current version of openmrs (as of 11 May 2014) doesn't build from mvn unless you have the openmrs Nexus repo in your Maven settings.xml. There are several dependencies that are unavailable anywhere else, including simpleframework and the modified version of Hibernate.

    This example settings file has the repository settings in it.

  15. This page has not been updated for a while.  Is the warning about requiring JDK 1.6 still valid?  (The issue it references has been closed.)

  16. This installation instruction is so light years behind time. JDK 1.6 requirement is still necessary. Oracle is going to stop supporting JDK 1.7 in April or May, 2015. There is no available m2e connector for mavern-scm-plugin anywhere in marketplace or in Windows->Preference->Maven->OpenCatalog. So if I cannot install this scm plugin, there is no way I can install m2e-subclipse. These incompatibility issues probably did not exist prior to 2012. If you are new like me, this installation guide won't work for the latest eclipse. This is a work of frustration. If only some gurus can step up and install the whole workspace from scratch using the latest available eclipse, luna & update this page!!!

    1. I updated the page. Hope it helps.

  17. i tried run as maven build..-> clean install then i got the following error

    anyone please help.!

    [INFO] Scanning for projects...
    [INFO] ------------------------------------------------------------------------
    [INFO] Reactor Build Order:
    [INFO]
    [INFO] OpenMRS
    [INFO] openmrs-tools
    [INFO] openmrs-test
    [INFO] openmrs-api
    [INFO] openmrs-web
    [INFO] openmrs-webapp
    [INFO]
    [INFO] ------------------------------------------------------------------------
    [INFO] Building OpenMRS 1.12.0-SNAPSHOT
    [INFO] ------------------------------------------------------------------------
    [INFO]
    [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openmrs ---
    [INFO]
    [INFO] --- buildnumber-maven-plugin:1.1:create (default) @ openmrs ---
    [INFO] Checking for local modifications: skipped.
    [INFO] Updating project files from SCM: skipped.
    [INFO] ShortRevision tag detected. The value is '6'.
    [INFO] Executing: cmd.exe /X /C "git rev-parse --verify --short=6 HEAD"
    [INFO] Working directory: D:\openmrs-core\openmrs-core-master
    [INFO] Storing buildNumber: 0 at timestamp: 1436978170908
    [INFO] ShortRevision tag detected. The value is '6'.
    [INFO] Executing: cmd.exe /X /C "git rev-parse --verify --short=6 HEAD"
    [INFO] Working directory: D:\openmrs-core\openmrs-core-master
    [INFO] Storing buildScmBranch: UNKNOWN_BRANCH
    [INFO]
    [INFO] --- build-helper-maven-plugin:1.5:parse-version (parse-version) @ openmrs ---
    [INFO]
    [INFO] --- maven-jar-plugin:2.3.2:test-jar (default) @ openmrs ---
    [WARNING] JAR will be empty - no content was marked for inclusion!
    [INFO] Building jar: D:\openmrs-core\openmrs-core-master\target\openmrs-1.12.0-SNAPSHOT-tests.jar
    [INFO]
    [INFO] --- license-maven-plugin:2.6:check (default) @ openmrs ---
    [INFO] Checking licenses...
    [INFO]
    [INFO] --- maven-install-plugin:2.4:install (default-install) @ openmrs ---
    [INFO] Installing D:\openmrs-core\openmrs-core-master\pom.xml to C:\Users\Piyush\.m2\repository\org\openmrs\openmrs\1.12.0-SNAPSHOT\openmrs-1.12.0-SNAPSHOT.pom
    [INFO] Installing D:\openmrs-core\openmrs-core-master\target\openmrs-1.12.0-SNAPSHOT-tests.jar to C:\Users\Piyush\.m2\repository\org\openmrs\openmrs\1.12.0-SNAPSHOT\openmrs-1.12.0-SNAPSHOT-tests.jar
    [INFO]
    [INFO] ------------------------------------------------------------------------
    [INFO] Building openmrs-tools 1.12.0-SNAPSHOT
    [INFO] ------------------------------------------------------------------------
    [INFO]
    [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openmrs-tools ---
    [INFO] Deleting D:\openmrs-core\openmrs-core-master\tools\target
    [INFO]
    [INFO] --- buildnumber-maven-plugin:1.1:create (default) @ openmrs-tools ---
    [INFO]
    [INFO] --- build-helper-maven-plugin:1.5:parse-version (parse-version) @ openmrs-tools ---
    [INFO]
    [INFO] --- maven-resources-plugin:2.4:resources (default-resources) @ openmrs-tools ---
    [INFO] Using 'UTF-8' encoding to copy filtered resources.
    [INFO] Copying 7 resources
    [INFO]
    [INFO] --- maven-compiler-plugin:2.1:compile (default-compile) @ openmrs-tools ---
    [INFO] Compiling 1 source file to D:\openmrs-core\openmrs-core-master\tools\target\classes
    [INFO] -------------------------------------------------------------
    [ERROR] COMPILATION ERROR :
    [INFO] -------------------------------------------------------------
    [ERROR] Unable to locate the Javac Compiler in:
    C:\Program Files\Java\jre7\..\lib\tools.jar
    Please ensure you are using JDK 1.4 or above and
    not a JRE (the com.sun.tools.javac.Main class is required).
    In most cases you can change the location of your Java
    installation by setting the JAVA_HOME environment variable.
    [INFO] 1error
    [INFO] -------------------------------------------------------------
    [INFO] ------------------------------------------------------------------------
    [INFO] Reactor Summary:
    [INFO]
    [INFO] OpenMRS ............................................ SUCCESS [ 2.541 s]
    [INFO] openmrs-tools ...................................... FAILURE [ 0.422 s]
    [INFO] openmrs-test ....................................... SKIPPED
    [INFO] openmrs-api ........................................ SKIPPED
    [INFO] openmrs-web ........................................ SKIPPED
    [INFO] openmrs-webapp ..................................... SKIPPED
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD FAILURE
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 3.312 s
    [INFO] Finished at: 2015-07-15T22:06:12+05:30
    [INFO] Final Memory: 19M/355M
    [INFO] ------------------------------------------------------------------------
    [ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:2.1:compile (default-compile) on project openmrs-tools: Compilation failure
    [ERROR] Unable to locate the Javac Compiler in:
    [ERROR] C:\Program Files\Java\jre7\..\lib\tools.jar
    [ERROR] Please ensure you are using JDK 1.4 or above and
    [ERROR] not a JRE (the com.sun.tools.javac.Main class is required).
    [ERROR] In most cases you can change the location of your Java
    [ERROR] installation by setting the JAVA_HOME environment variable.
    [ERROR] -> [Help 1]
    [ERROR]
    [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
    [ERROR] Re-run Maven using the -X switch to enable full debug logging.
    [ERROR]
    [ERROR] For more information about the errors and possible solutions, please read the following articles:
    [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException
    [ERROR]
    [ERROR] After correcting the problems, you can resume the build with the command
    [ERROR] mvn <goals> -rf :openmrs-tools

    1. I'd recommend you sharing your problem on Ask OpenMRS to reach the largest number of people. Wiki page comments do not get much visibility and so you're unlikely to get support here. Good luck!