Building OpenMRS

For this process you need to have the environment setup and the local copy of OpenMRS source code in your system. If you are not sure what they mean please follow the previous pages and return to this page.

There are a few steps you need to follow to build the openmrs.war file.

Step-1: Importing Code into Eclipse:

  • Open your Eclipse in which you have imported and configured all the plugins.
  •  Open File>Import and under maven folder select Existing Maven Projects and click on Next.
  • For the root directory browse to the folder created while cloning the code from github , click on Next until you can finish the process.This will import all the code files into your eclipse project explorer.
  • For openmrs-core they would be openmrs-api, openmrs-web, openmrs-webapp, openmrs-test, openmrs-tools,, openmrs-release-test.

Step-2: Sharing your Local Git Repository with Eclipse:

This step is useful when you switch your branch in git bash, the branch switch will automatically be reflected in Eclipse

  • Right click on the one of the project folder like openmrs-api and in the Team option select share project.
  • And select Git under the repository type and click next, your github clone folder will be shown automatically and click on finish. (If you can’t find Git in the repository type then you need to install the egit plugin into your eclipse).
  • In your project explorer you can now see the repository name and it’s current branch separated by a space beside the folder.
  • Similarly follow this process for each folder.

Step-3: Building openmrs.war:

Now, you are ready to build openmrs.war file

  • Right-Click on the openmrs folder and select Run as and select Maven Build. A window will open where in the space for “Goal” enter “clean install”. This step will do a maven clean and a maven install.
  • You will frequently experience a MOJO Failure redirecting you to some link. This can be caused by many reasons that include corrupt dependencies , not having permission to clean and even having dependencies that don’t exist anymore to download.  Solution: Most of the times it is due to permission issues/corrupt dependencies so in your “Goal” use this message “-U clean install”. Some times even this wont work, then just restart eclipse as it sometimes runs a process that wont allow cleaning of dependencies.For problems regarding non-existent dependency in the repository, you can go to the path mentioned in the console and see which version is existing online and just change the version used in pom.xml.
  • If you would like to skip the tests because you are in a hurry you can keep the option checked in the window. But remember when you are trying to contribute your code then you must make sure that no tests are failing because of your changes. So, while contributing do run the tests.
  • The openmrs.war file is generated in the “openmrs>webapp>target” folder.

As a developer you need to know where the dependencies are stored in your system. In windows, in your “username” folder a “.m2” folder will be there and when you navigate into “.m2>org>openmrs” you will find the dependencies that are downloaded while building openmrs. You can confirm this by deleting this folder and building the war again.

Step-4: Deploying war in Tomcat:

You have generated the war file, now you need to deploy it.

  • Copy the war file in “openmrs>webapp>target” path and paste it in you “apache tomcat (version) > webapps” folder .
  • Now start the server by double clicking startup.bat file in “apache tomcat (version) > bin” folder or by starting the server directly from eclipse.
  • Now go to your browser and type in the url “localhost:8080/openmrs” and as this is your first time, this will open up the initial installation of OpenMRS.

This will extract the openmrs.war into openmrs folder in “apache tomcat (version) > webapps” folder.

Step-5: Initial Installation of OpenMRS:

  • In the initial setup as you are a first time user, it is better you select the simple version of the installation where your inputs are minimal.
  • Provide your details such as the root password and let it create the demo data. you don’t need to change much here as the options are very clear.
  • You might see some warning such as “Unable to find file” this is because you don’t have one and this will be created after your installation process is complete.

So again as a developer you need to understand what all changes are happening in your file system.

  1. In “Appdata>roaming>OpenMRS” your settings and the “” will be generated.
  2. A database schema “openmrs” will be created with minimal data. And there will be a super user created with usernam/password as “admin/Admin123” by default.

If you see this screen after the process then the deployment has been successful and you can start exploring OpenMRS by entering the username/password details.

OpenMRS Start Screen

OpenMRS Start Screen

If you are unable to see this screen and some kind of exception is being shown, then there must be something that went wrong. So , what are the possibilities?

  1. There is some problem with building openmrs.war?Solution: Delete the “.m2>org>openmrs” folder and try building the war again.
  2. There is some problem with deploying openmrs.war in tomcat?Solution: Delete the “apache tomcat (version) > webapps>openmrs” folder.
  3. There is some problem while generating AppData?Solution: Delete “Appdata>roaming>OpenMRS” folder.
  4. There is some problem while creating the database and updating it? Drop openmrs schema in mysql and start openmrs initial setup again.

Try cleaning everything of openmrs and doing it from the start. If it still doesn’t work , then you should be posting the problem in developers list or in the irc channel and wait. Till then you can switch to some other version such as 1.9 and try working.

Step-6: Adding Demo Data:

  • Drop the schema openmrs from mysql.
  • Download your openmrs version’s demo data from this link.
  • Create a new schema openmrs.
  • Open the script you downloaded in mysql and enter “use openmrs;” line above the script and execute the whole script.
  • OpenMRS will start in a maintenance mode so that it can synchronize the data tables with the version you are running.

Previous: Learning Git

Next: Things to Learn


29 responses

  1. This is helpful. Is there a more detailed tutorial on how to debug openmrs on eclipse, keeps getting error ”cannot create or copy to wtpapps”.

    1. I have given a reply to your previous comment and I think it should do the trick, If you are still having a problem with it. Then just ping me in the openmrs irc or email me, maybe you can send me the the screenshots so that i can get a better idea.

  2. I was able to get pass setting up the environment, downloading and creating the war file but I got stuck on starting the server from eclipse after deploying the war file on tomcat.

    1. @splucena, can you tell me while ding what exactly are you stuck.
      As far as I know, there are 3 places where you can check if you have the right properties set. It might be cleaner if you delete the server in your eclipse and follow the process making sure of the following points.
      1. While adding the server,in the add and remove step, make sure you don’t anything, even openmrs webapp into it and complete the process.
      2. Right-Click on your server and select the properties option and check that in the general tab you have the location as /Servers/Tomcat v7.0 server at localhost.server.
      3. Right-Click on the server and click on open and under the server location tab, select the second option mentioned as “use tomcat installation(takes control of the tomcat installation)”.

      And “wtpwebapps” is the deploy path under server locations which is never used, because when you start the server in debug or normal mode , the normal webapps of the server will get deployed, where you have copied the openmrs.war file.

  3. Thanks for the guide so far. Just letting you know that demo-1.9.0 was updated so the password is Admin123 now.

    1. @Marvin, Thank you for the information, I’ve updated the page.

  4. A small doubt in here buddy….. which file does this page refer to…. I didn’t get any file with name obs…. searched by using this command “find . -iname “*obs*” “

    1. Akash,

      in this file as I mentioned in the guide,for


      after trimming out the common parts( and parameters(?obsId=421701) ,

      you would be left with “obs.form”

      so in your eclipse search for obsform.jsp with ctrl+shift+r and you will find obsform.jsp, that would help you with your ticket.

      1. okay … got you… thanx… 🙂

  5. @srimaurya what is your nick in irc … I don’t seem to find you…. 😦

    1. my nick in irc is “maurya”

  6. can you please specify your slot if any for irc availability…. ?

    1. Hi Akash, I am actually not that active on IRC so, I would be more reachable on Email or on Skype, just mail me if you would like to talk about something. I am presently working on my previous DHIS integration module so, unable to be active in IRC.

      1. okay … yaa sure…

  7. After importing the source code in eclipse, it shows many errors just in openmrs-webapp like:

    openmrs-webapp/src/main/webapp/test/velocity_test.jsp : line 20 —
    “The method setFirstName(String) is undefined for the type Patient”

    openmrs-webapp/src/main/webapp/WEB-INF/tags/concept.tag : line 4 —
    “The method getJspContext() is undefined for the type

    and many more

    What’s the solution for this ?

    I would like to send the screenshot.

      1. I replied to your earlier comment, hope it clarifies it.

    1. Sorry for the delay in response, There will be some files that eclipse cannot understand the references of. Don’t worry about them until they break your build 🙂

  8. Thanks for your guide.
    But I’ve encountered a problem while building OpenMRS in step 3.
    Maven logged something like this:
    [ERROR] openmrs-core\api\src\main\java\org\openmrs\util\[77,32] is Sun proprietary API and may be removed in a future release

    Please help me.

  9. when I try to run the mvn -U clean install ,there is an error in the openmrs-api

    Running org.openmrs.OpenmrsTestsTest
    Tests run: 4, Failures: 4, Errors: 0, Skipped: 0, Time elapsed: 0.013 sec <<< FAILURE!
    Results :

    Failed tests:

    Tests run: 2849, Failures: 4, Errors: 0, Skipped: 24

    1. As the code is constantly changing there might be tests that fail, if you have the latest code from github try building it with skipping the tests.

  10. Can you more elaborate the step 6 ? (Are you using MySQL-Workbench or MySQL console) Detailed steps would be more helpful.

    1. I looked at into the “Demo-1.9.0.sql” mysql script. It is checking for DATABASE exists and using “USE `openmrs`;” command as well.
      Then following steps works for me.
      *. Install OpenMRS with demo data first (it contains small set of sample data)
      *. Download demo data and unzip it (e.g. -> Demo-1.9.0.sql)
      *. Go to directory where Demo-1.9.0.sql file exists using a terminal (in Linux)
      *. Run command “mysql -u openmrs_user -p < Demo-1.9.0.sql"
      *. Insert password which can obtain from "~/.OpenMRS/" file (connection.password=xxxxxxxxxx)

      Hope this would be help you!

      1. Thanks for the information, I believe it will help someone.

  11. Thank you for this detailed tutorial, everything worked fine for me.
    However, am wondering why the GUI looks like the old openMRS??
    How do I get the same set up but with the new WEb UI?


    1. The new UI is nothing but a set of modules that you need to install the modules can be downloaded from here

  12. When building openmrs on Netbeans, I encountered this problem. Build succeed, but Netbeans can’t deploy openmrs on tomcat. Below is the output of Netbeans. Any help is highly appreciated.

    NetBeans: Deploying on Apache Tomcat
    profile mode: false
    debug mode: false
    force redeploy: true
    In-place deployment at /home/***/openmrs-core/webapp/target/openmrs
    Cannot deploy the module. The context.xml file seems to be broken. Check whether it is well-formed and valid.

  13. Why there is need to copy war file? Isn’t there a way we can deploy war file on tomcat server? In addition, I want to debug the code, How can I debug the code. I tried to setup debug as -> Debug configuration. I checked from the terminal localhost port 8000 is listening. When I debug by specifying connect settings
    I get the error unable to connect to host port closed in eclipse. I google the error and still i am unable to fix it.
    your thoughts would be appreciated.

Leave a Reply

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

You are commenting using your 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: