Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents

Table of Contents


YouTube Video Setup Demonstration


The basic commands that we will use are listed below. It is important to note, that in order to run Maven, you MUST be in the directory that the “pom.xml” file whose command you want to run is in.



mvn clean

This command attempts to clean and remove the directories that are used during the Maven build.

mvn install

This command builds the Java Application. This creates the directory, creates all necessary files, and downloads/installs all dependencies that are needed by the build. This command also runs all unit tests that are implemented in the project.

mvn jetty:run

This command runs your Java Application. Once this command executes, it will constantly listen for program execution, and will allow the program to run.

It is also important to note that Maven commands can be strung together in one. For example, a developer can use the command “mvn clean install” to both clean the Maven build, as well as install the build again.


In order to look at the databases, once OpenMRS is built and installed, you can use the following commands.


First, you will need to log in to MySQL. This can be done using the following command from the terminal application:

            mysql –u root –p –h localhost 

This will launch the MySQL command line tool. Once in this tool, there are a variety of commands that can be used. These can be found below:



show databases;

This will show a list of all of the databases that are stored in MySQL. All of the databases for OpenMRS are stored in a database called “openmrs”.

use openmrs;

This command will put MySQL in the perspective of the openmrs database. All commands from here will now be limited to this database.

show tables;

This command will provide a list of all tables that are in the specified database.

4. Git

Git is the source code management tool that OpenMRS uses for the development of the software. Git allows for many developers to work on the application at the same time, without having major conflicts. Git manages the changes to software over both short and long periods of time so developers can keep track of specific versions later. In order for a user to use git on their own machines, they must install it. The download link can be found at Users should just download and install it for the machine that they are working on.


Below is an overview of the various commands that can be performed with git. It is important to note that in order to use most of the commands, you MUST be in the root directory that contains the clone of the git repository. This directory will contain a .git folder.



git clone gitUrl [folderUrl]

This command clones a specific repository to the user’s machine. The gitUrl is the URL to which the repository is stored on a server. This could be on GitHub or some other hosted site. The folderUrl is an optional parameter that allows the user to specify the folder to copy the repository to. By default, if the parameter is not given, the repository is cloned to the current directory.

git status

This command allows the user to view changes to files in the current directory. If you make a change to a file, it will be displayed in a list here. Otherwise, this will return that there are no uncommitted changes.

git add fileName

This command adds a previously unknown file to git. You need to use this if you create a new file in the solution.

git commit [-m “Message”]

This command adds all current repository changes to the LOCAL repository. This allows for code to be retrieve from the LOCAL machine later, though it does not send the changes to the repository on the server. Optionally, a user can submit a message detailing any changes that were made.

git push

This command pushes committed changes to the server. In order for this command to work, the changes in the repository must have been committed using the above command.


The code for OpenMRS’ modules can be found at  GitHub is a git-based website that allows you to view the code of various applications, download that code to your machine, and store your own code on the cloud.


Eclipse is one environment that you can use to develop using OpenMRS. Eclipse is an IDE for building Java applications. The download for Eclipse can be found here: 

Follow the Steps below to get your code built into Eclipse:

1.First thing you want to do is go to File->Import


2. Next, you are going to want to go to git -> projects from git


3.  Next, you are going to want to clone a uri (since the code is hosted on Github).


4. Fill in the URI field with the URL:


5. Make sure all branches are checked.


6.  Choose a location to store the code. The default is a “User/git/openmrs-core”


7. Wait for all of the code to be downloaded. Then, you should see a screen prompting you to import using a project wizard. Hit “Cancel”. Your code has been pulled to your machine.


11. Once you navigate to the directory, you should then see a list of projects in the projects box. Your screen should look like the one below. Once you have this, hit “Finish”. Your openmrs project should then appear in the project explorer.


Cloning Using Command Line


Code Block
~/Projects/OpenMRS/code $ cd ./openmrs-core 
~/Projects/OpenMRS/code/openmrs-core $ mvn clean install


The build may take a few minutes, especially on the first run. Maven needs to download and install all of the dependencies needed by the project. If the build is successful, you should see a screen like below. Make sure that all components of the project have the message SUCCESS.


After the build has successfully finished, start the MySQL server (unless it is already up and running). You need to know the password for the MySQL root user as it is requested for the initialization of the OpenMRS application.

Code Block
~/Projects/OpenMRS/code/openmrs-core(master) $ sudo /usr/local/mysql/support-files/mysql.server start


Next, cd into the webapp subfolder and start the OpenMRS web application. This can be done using the command mvn jetty:run. With Maven's default settings, the web server ran out of memory so I have increased the memory settings. Make sure there are no errors when running this command.

Code Block
export MAVEN_OPTS="$MAVEN_OPTS -Xms1024m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=1024m"
~/Projects/OpenMRS/code/openmrs-core(master) $ cd ./webapp/
~/Projects/OpenMRS/code/openmrs-core/webapp(master) $ mvn jetty:run


When being started for the first time, OpenMRS needs to be initialised. The application figures out whether it has been initialised or not, so when you open a browser and access http://localhost:8080/openmrs/index.htm, you are redirected to http://localhost:8080/openmrs/initialsetup.

You should see a screen like the one below:


Select the language you wish to use and hit the green arrow. For now, just select the “Simple” installation and hit the green right arrow. Here, you should see a box asking for a password. This is the password for your mySQL. This is the same password that you used to start the SQL server earlier. The last question asks whether you want demo data in your database. You can either choose yes or no here. Once you are finished, hit the green right arrow. The next screen asks you to verify the settings for the installation of OpenMRS. Hit the green right arrow when you are finished.

It may take a few minutes to set up the databases. Once it is finished your screen should look like the one below:


Once you see this screen, once again visit the URL http://localhost:8080/openmrs/index.htm. You should see a message explaining that you do not have a UI framework installed. This is due to the fact that the API (which you just installed) has been separated from the UI, and you do not yet have a UI framework installed. Your screen should look similar to the one below.


Once again, you can either use the Eclipse way of cloning the repository, or using the command line. Follow the same steps that were used above. There are a variety of different UI frameworks that can be used, but for this tutorial, we will just be using the legacy UI, which can be found at


First, we want to make sure that the previous maven command that we ran has been stopped. We need to cancel the “mvn jetty:run” command that was executed earlier. You can either use ctrl-c to cancel the execution or close the terminal window.

First, cd into the new folder that was created openmrs-module-legacyui.


Once in this folder, we want to build the UI framework. This can be done the same way that we did for the core code. Use the command mvn clean install while inside the UI folder. Once again, this may take a few minutes to install dependencies and run the tests. This should be quicker than the API, however, since these modules are much smaller than the API. Make sure that all of the projects have the status SUCCESS.


Next, we need to fetch the UI Framework file that was generated by maven, and place it in our OpenMRS directory. 

We want to cd into the folder omod then cd into the folder target.


Once here, you should see a file called legacyui-{version}-SNAPSHOT.omod. You need to copy this to your OpenMRS folder in your user folder. You can do this using the command cp legacyui-{version}-SNAPSHOT.omod ~/.OpenMRS/modules/