Environment Setup

If you intend to develop code for OpenMRS then you would be needing a development environment for OpenMRS. This page will give you a detailed explanation of How-To-Setup-A-Development environment-For-OpenMRS.

Lets break the process into steps :

Step 1 : Setting up Java:

If your have have JDK 1.6 setup in your System, you can skip this step.

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.  Right now, I would advise you to download the 1.6 version as installing 1.7 will result in some test failures in OpenMRS (and believe me as a new developer you don’t want that).

It might be a little time consuming to search for the 1.6 version as 1.7 is released so, here is the link where you can download a 1.6 version of JDK . If you just scroll down a little in the site, you will see a section “Java SE development Kit 6u45“, under the section download the appropriate version for your operating system. Run the file and JDK will be installed in your computer.

Now, you must also make sure that javac(java compiler) runs in your command prompt. For that, in your environmental variables, you will have a “Path” system variable, open that and append the path to your javac.exe file(If you are using windows then the path will most likely be C:\Program Files\Java\jdk1.6.0_45\bin).  now, open up your command prompt and just type javac and hit enter, if it doesn’t return a list of options then there is something that you missed in the above process.

If you would prefer a guide with pictures for this process you can follow this link.

There are two other system variables you must make sure are set correctly , if not then I advise you to create them and set them.

1.Variable = JAVA_HOME ( Value =C:\Program Files\Java\jdk1.6.0_45)

2. Variable = JRE_HOME ( Value =C:\Program Files\Java\jre6)

You’re done with setting up JDK in your system!

Step 2 : Setting up 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.

You can download the MySQL community server from this link.

I would advise you to download the installer as it would install all the components and connectors etc. This installation will also install MySQL Workbench which provides a great GUI for viewing and editing the databases.

While installing MySQL it will prompt you to enter a password for your root user(a user with all privileges). Please remember this password for future reference.

Step 3 : Setting up Maven

Maven is a software project management and comprehension tool to support building OpenMRS software. You can download maven from this link. If you scroll down a little in the download page there are clear instructions to install maven in your system depending on your OS.

Just as a check, try running mvn –version in your command prompt and it should print something like this

Apache Maven 3.0.11 (r01de14724cdef164cd33c7c8c2fe155faf9602da;
 2013-02-19 14:51:28+0100)
Maven home: D:\apache-maven-3.0.5\bin\..
Java version: 1.6.0_45, vendor: Sun Microsystems Inc.
Java home: C:\Program Files\Java\jdk1.6.0_45\jre
Default locale: nl_NL, platform encoding: Cp1252
OS name: "windows 7", version: "6.1", arch: "amd64", family: "windows"

If you don’t see the above kind of response in the command prompt, then i advise you to follow the steps properly in the download link provided.

Step 4 : Setting up Apache Tomcat

Very important that you follow this step, even if you think you have Apache Tomcat installed in your System.

Apache Tomcat is an open source web server and servlet container developed by the Apache Software Foundation. This is where your OpenMRS code will be deployed. The deployment process will be explained later.

Download the Zip/ Archive file for your OS  under the Binary distributions > Core from this link. You can even download the tomcat 7 version.  Extract the zip and you will have installed Apache Tomcat server in your system. You don’t need some executable kind of Apache Tomcat version in your system.

Just double-click on startup.bat file in your extracted apache tomcat folder > bin  folder and your own server starts up. Now open your browser and type in localhost:8080 in your url bar(and press enter) and this will show a tomcat welcome page.

For Tomcat version 6 , you will have a link Tomcat Manager to the left side in the page and for Tomcat version 7 , you will have a Manager App button to the right. Clicking on them will result in a popup asking for username and password. You must setup a username and password to use this Tomcat Manager/Manager app. This can be done in extracted apache tomcat folder > conf> tomcat-users.xml file. Open the file and replace the contents with the lines below.

<?xml version=”1.0″ encoding=”UTF-8″?>
<role rolename=”manager”/>
<role rolename=”manager-gui”/>
<user password=”tomcat” roles=”manager,manager-gui” username=”tomcat”/>

This will create a user with username=tomcat and password=tomcat and you can log into the Tomcat Manager/Manager app with these credentials. You can have any username and password of you choice.

This completes the process to setup tomcat.

Step 5 : Setting up Eclipse

This is the biggest part of environment setup.  Eclipse is an open source integrated development environment(IDE). It contains a base workspace and  an extensible plugin system for customizing the environment.

Eclipse 4.2.x(Juno) is the recommended Java development environment .You can download the appropriate version of Eclipse 4.2.x(Juno) for your OS from this link. Extracting the archive file is installing eclipse in your system.

After you’ve installed eclipse, you need to install the maven plugin

  • 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

You also need to Install git plugin

  • 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

Restart Eclipse after this install.

Step 6 : Setting up Eclipse for Debugging

Almost all Java projects need you to know debugging to understand their code. To debug a project of eclipse you need the tomcat server to be started in eclipse in debug mode.

  • Select the servers tab.
  • Click add new server in it.
  • In the Apache folder, select the version of tomcat you have installed(6 or 7) .
  • Select the tomcat installation directory as the extracted apache tomcat folder which you’ve installed earlier and let the Installed JRE be workbench default JRE.

Now you will have the tomcat server shown in the servers tab.

  • Right-Click on the tomcat server and click on properties. Make sure that the Location is set to /Servers/Tomcat v (6.0 or 7.0) server at localhost.server.If the location is shown as [workspace metadata] click on switch location and your location will be changed to /Servers/Tomcat v (6.0 or 7.0) server at localhost.server.
  • Right-Click on your server and click on open. Under the Server Location tab make sure that the “Use tomcat Installation”  radio button is selected.

Done! Your Eclipse is set for debugging.

Next: Learn more about OpenMRS Jargon


8 responses

  1. Where is the servers tab in Eclipse?? I can not find this. 😦
    Thanks for help.

    1. Wojtek, It is usually marked with three colored lines with lever kind of buttons on those lines, if you are unable to find it, then follow this
      Window> Show View> Other> Servers-Server

      and this will open your servers perspective in eclipse.

  2. hey, could help those who are nto using the window os like the linux users also. just help them with some guide to setup their development environment.

    1. @anyprograms, Thank you for the suggestion, I’ve worked almost always on windows so ,I have been able to identify what kind of problems might arise for them. But, as you say there are many who use other OS such as linux and Mac.

      I will start collaborating with someone and create the required content as soon as possible.

  3. For MacOSX I used Macports and it worked fine. “sudo port install maven3” and “port select –set maven maven3”

  4. milankarunarathne | Reply

    Great Post!. Help me a lot. Thank you!.

    Then how to run on debug mode ?
    Right click on webapp -> Debug As -> Debug on Server (Is this the procedure ?)

    I suggest you to write a Post about how to debug using Eclipse and Tomcat (If there is method like variable inspection etc Ex: http://goo.gl/H4qpkK, http://goo.gl/hDQ1Z1 ).

  5. […] dependencies that I needed to run this software. Following directions from the OpenMRS wiki and a separate blog about OpenMRS development, I first installed and configured a local instance of a MySQL sever, in […]

  6. Your post is great! Thank you so much it is of much help to me.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: