Backend Module Development Using Docker (No SDK)

This guide explains how to run an OpenMRS Reference Application locally using Docker Compose and how to load and test custom OpenMRS modules (.omod files) without using the OpenMRS SDK.

Instead of relying on the SDK (which automates setup), this approach gives you:

Full control over Docker-based OpenMRS setup
Easy debugging of backend modules
Direct integration of custom module builds
A production-like environment locally

Prerequisites

Before starting, make sure you have:

Java (8 / 21 depending on project branch)
Apache Maven (3.8+ recommended)
Docker Desktop (running)
Git

In this guide, we are using the Authentication module as a demo example to show how module injection works.

You can follow the same steps for any OpenMRS module you are developing or testing.

Step 1: Clone OpenMRS Reference Application

git clone https://github.com/openmrs/openmrs-distro-referenceapplication
cd openmrs-distro-referenceapplication

This repository contains the Docker setup for running OpenMRS 3.x.

Step 2: Create a Temporary Docker Compose Override File

Before starting the system, create a temporary override file to customize the backend configuration for module injection.

Create a file named:

<anyname>.yml

Add the following content:

You have to change these according to your needs.

services:
  backend:
    environment:
      OMRS_DEV_DEBUG_PORT: 1044
    ports:
      - "1044:1044"
    volumes:
      - openmrs-data:/openmrs/data
      - ./authentication-2.4.0-SNAPSHOT.omod:/openmrs/data/modules/authentication-2.4.0-SNAPSHOT.omod

What this does:

Enables remote debugging on port 1044
Keeps OpenMRS data persistent
Mounts your custom .omod file into the backend container

Important: This file is temporary and used only for local development.

Here is an example of how I did

🐳 Step 3: Start OpenMRS using Docker Compose

Run the system with both default and override configurations:

docker compose -f docker-compose.yml -f dilanomrs.yml up -d

Change the .yml file name according to yours.

This starts:

OpenMRS backend
Frontend
Gateway
Database

Open in browser:

http://localhost/openmrs/

Default login:

Username: admin
Password: Admin123

Step 4: Build Your Custom OpenMRS Module

Go to your module project (example: authentication module):

cd openmrs-module-authentication
mvn clean install

After build completes, your .omod file will be generated at:

omod/target/authentication-2.4.0-SNAPSHOT.omod

Example:

Step 5: Inject Module into OpenMRS Docker Setup

Copy the generated module into the distro project:

cp omod/target/authentication-2.4.0-SNAPSHOT.omod \
../openmrs-distro-referenceapplication/

This file is mounted into the backend container via dilanomrs.yml (your yml file).

Step 6: Restart Backend

After adding or updating a module:

docker compose restart backend

If changes are not reflected:

docker compose down
docker compose up -d

Step 7: Verify Module Installation

Option 1: UI

http://localhost/openmrs/admin/modules/module.list

Option 2: Logs

Common Issues & Fixes

1. Module not appearing

Ensure .omod file exists in distro folder
Ensure Docker volume path is correct
Restart backend container

“Is a directory” error

This happens when Docker creates a folder instead of a file.

Happy Coding!