/
Set Up OpenMRS Server with OpenMRS SDK

Set Up OpenMRS Server with OpenMRS SDK

The OpenMRS SDK (Software Development Kit) is a developer tool built on top of Apache Maven, designed to streamline the development of OpenMRS modules and the OpenMRS Platform itself. It enables rapid setup, configuration, and deployment, allowing developers to run OpenMRS instances quickly without manually managing Tomcat servers or database configurations.

This instruction below applies to linux and with minor adjustments for windows as well.

Prerequisites :

Before setting up OpenMRS , ensure you have the following installed :

  1. Java SE : download

    1. OpenMRS currently supports Java 8 and Java 11 (Java 21 required for main branch)

    2. Verify the installation with: java -version

    3. If multiple versions are installed on Linux, select the default one using: sudo alternatives --config java and select the version

    4. If Java SE is not recognized, add below lines in your shell configuration files (eg : .bashrc,.zshrc ) based on the version (here jdk-11 is taken as ref.)

    5. export JAVA_HOME=/usr/lib/jvm/jdk-11.0.29-oracle-x64 export PATH=$JAVA_HOME/bin:$PATH

  2. Apache Maven :

    1. fedora : sudo dnf install maven -y

    2. ubuntu : sudo apt install maven -y

    3. verify the installation : mvn -v

  3. Database :

    1. openmrs supports mysql and postgress (mysql – recommended)

    2. You can either install MySQL directly or run it via Docker (recommended for isolation and easy cleanup).

      1. Docker : download docker desktop

        1. start docker

        2. pull MySQL image

        3. run a MySQL container :

        4. docker run -d --name mysql-container -e MYSQL_ROOT_PASSWORD=pass -p 3306:3306 mysql:latest

        5. verify its running : docker ps

        6. If you get errors during this process, try an older version of Docker as described here.

      2. To install Directly:

        1. sudo dnf install mysql-server -y

        2. systemctl start mysqld

        3. check status : systemctl status mysqld

Guide for Windows:

  1. If JDK is not recognized, set JAVA_HOME environment variable. Guide

  2. After downloading maven add Maven to the Windows PATH. Guide

Installing OpenMRS SDK

  1. Run the following command to install OpenMRS SDK :

    mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:setup-sdk

  2. Verify the installation: mvn openmrs-sdk:help

on successfull , you will get “build success” as ouput

For windows user:

  1. Windows users may also need to swap the SDK over to using TCP instead of HTTP connections. You can expose Docker via TCP (instead of just via HTTP) via Docker Desktop through the following setting:

  2. You'll also need to modify the dockerHost in the SDK properties file (found in C:\Users\“youruser”\openmrs\sdk.properties). Change the "dockerHost=http://127.0.0.1:2375/" line to "dockerHost=tcp://127.0.0.1:2375".

    Without this you may encounter the following error: "Unsupported protocol scheme found: 'http://127.0.0.1:2375/". More info here.

Setting Up an OpenMRS Server

  1. run the setup cmd : mvn openmrs-sdk:setup

  2. When prompted, enter a server ID (any unique name for your server or press ENTER for default –

    remember the name)

  3. Choose 2 for latest O3

  4. select the required version of O3 (select 1 – latest version recommended )

Screenshot From 2025-11-04 19-35-54.png

  1. Set up ports:

    1. Default web app port: 8080

    2. Remote debug port: 1044

Screenshot From 2025-11-04 19-42-46.png

  1. Choose MySQL installation method

    1. Enter 2 if you are using Docker. (recommended)

Note: Make sure you have installed Docker and it is running. 

b. Enter 1 if you have installed MySQL directly.

  1. If you choose option 1, you will be prompted to enter the database name and database password .

  1. Select the java version

Screenshot From 2025-11-04 19-44-06.png

When the process is complete, the screen displays a “build success” message.

Possible Issues & Fixes:

  • Port 8080 is already in use

    • Use a different port when prompted during setup or stop the process in that port

Run OpenMRS Server

  1. (Replace server1 with the server ID you chose.)

    mvn openmrs-sdk:run -DserverId=server1

  2. After sometime you will recieve the following msg :

Screenshot From 2025-11-04 11-53-19.png

  1. Open a web browser and navigate to the page and wait patiently it will take some time

Screenshot From 2025-11-04 13-35-47.png

  1. After everything is created and updated successfully, the login page will appear

  2. Use the default credentials to log in:

    • Username: admin

    • Password: Admin123

Screenshot From 2025-11-04 13-59-48.png

  1. If you get a CSRF error, edit ~/openmrs/server1/tmp/openmrs/WEB-INF/csrfguard.properties as described here.

Success you have your OpenMRS instance up and running!

Note :
Follow the below steps if you want to run your modified version of any module eg : https://github.com/openmrs/openmrs-module-billing

  1. Fork and clone it the module

  2. mvn clean install for compiling the billing module

  3. copy the .omod file from ../omod/target and paste in /openmrs/{server_name}/modules

  4. start the openmrs instance again

Final thoughts:
Setting up the OpenMRS SDK correctly is the first real step toward contributing effectively to the community.

Once your local environment is up and running, explore the codebase, review open issues, and start with beginner-friendly tickets to build familiarity with the platform’s structure.

You have completed setting up OpenMRS SDK and server. To learn more about OpenMRS SDK go to: OpenMRS SDK, or OpenMRS SDK Step by Step Tutorials.