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 openmrs-runtime.properties 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 “openmrs-runtime.properties” 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

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 openmrs-runtime.properties/ 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