Adopting OpenMRS HIS: what if you already have a `distro.properties` file?

Software Ozone HIS
1

With any Ozone-based distribution, such as OpenMRS HIS, you can –and often should– create your own customized distribution. The most common approach is to start by creating a new Maven project (using the available helper tools), then configuring it, packaging it, and distributing it.

A key component of every Ozone distribution is the OpenMRS distribution itself. To define it, you have two options:

  • Follow the established Ozone patterns, which combine Maven dependencies with backend and frontend configuration folders.

  • Or create a distro.properties file or reuse an existing one.

The second option, however, does not support multi-level Ozone distributions. You can work around this limitation by using Content Packages.

The article below specifically explains how to reuse a distro.properties-based distribution within OpenMRS HIS or any Ozone distribution in general.

:backhand_index_pointing_right: To better understand Ozone distributions, checkout Ozone Docs - Implementers Docs - Introduction

To help groups that may already have a standard distro.properties-based OpenMRS instance, we have put together some instructions to migrate from such distribution to an OpenMRS HIS distribution.

What is a “standard EMR distribution”?

What we call a standard OpenMRS distribution is a distribution defined by a distro.properties file.

This file specifies:

  • the version of OpenMRS Core

  • the modules that make up the distribution

  • any additional content packages

With this single file, the OpenMRS SDK can build a consistent, reproducible EMR distribution.

Fork the OpenMRS HIS repository. (:warning: Forking is generally not advised, however, in this case, OpenMRS HIS can be used as a template for your new Ozone distribution –most of the features are defined in Ozone and are not specific to OpenMRS HIS– thus, forking is does not put you at risk).

Then move your distribution resources as described below:

  • distro.properties

Drop your existing distro.properties file into configs/openmrs/distro_assembly/. This becomes the entry point for building your distribution package.

  • Configuration folders

If your EMR has custom configurations (frontend or backend), copy them into the appropriate configuration directories:

  • configs/openmrs/frontend_config/ → for frontend configuration files

  • configs/openmrs/initializer_config/ → for Initializer-based system configuration

:warning: Within Ozone, the list of orderables must match between apps so the integrations can work effectively. This means you might also need to configure Odoo to load your products.

Note that with the recent addition of the Product Catalog, drugs need to be loaded in Odoo only and will be created in OpenMRS by the integration. You can then remove drugs from the OpenMRS configs.

:backhand_index_pointing_right: See Ozone documentation for configuring Odoo: https://docs.ozone-his.com/implementers/configure-apps/#overriding-the-odoo-config

  • Pre-compiled OpenMRS Modules

If you’re using pre-built OMODs (compiled modules), you can place them under binaries/openmrs/modules/. (That is only for pre-built OMODs, which is rare. In fact you probably should always declare your omods into your distro.properties)

  • Database scripts

If your current EMR distribution relies on SQL scripts for database initialization (which is discouraged in favor of Liquibase or Initializer) you have two paths:

  • Copy plain SQL scripts to data/mysql/openmrs/ → these will be executed during initial MySQL setup

  • (Preferred) Convert your SQL into Liquibase changesets and place them inside configs/openmrs/initializer/liquibase/

Build the project

Once the above is organized:

  • Comment or remove the Exclude unneeded Ozone files build step.

  • Run the build: mvn clean package

  • The Reference Application will not be used. Instead, your own distribution, built from your distro.properties and configurations, will serve as the runtime base.

Enabling Single Sign-On:

If you want to enable Single Sign-On, there a few manual steps to apply:

  • Make sure the Oauth2Login module is part of your distro.properties file. Additionally, note that the Authentication module may need to be removed from your distro.properties if present.

  • Copy this oauth2.properties file into configs/openmrs/properties

  • Add this config to your frontend configuration file:

     "@openmrs/esm-login-app": {
    "provider": {
      "type": "oauth2",
      "loginUrl": "/openmrs/oauth2login",
      "logoutUrl": "/openmrs/oauth2logout"
    }
  }

  • Rebuild: mvn clean package

Run your OpenMRS HIS distro

Follow the standard Ozone instructions to run your project:

source target/go-to-scripts-dir.sh


./start.sh

If SSO is enabled and configured during build, run Ozone with:

./start-with-sso.sh

Attention: Once all services are up, you may run into a 502 error with accessing OpenMRS. If so, run docker restart openmrs-his-openmrs-1

Browse

Once started, the script will output the URLs to access the HIS apps and services as well as the access credentials:

For example:

Screenshot 2025-09-15 at 2.12.15 PM
Screenshot 2025-09-15 at 2.12.15 PM586×207 19.3 KB

Important notes & limitations

  • At the moment, there isn’t a mechanism to override a distro.properties provided by a parent project (e.g. the one from the Reference Application).

  • The OpenMRS SDK will only use one distro.properties file during build. Support for merging multiple distro.properties files would be needed for finer-grained overrides, but this is not available yet.

  • Keeping configurations in Initializer (rather than plain SQL) is strongly recommended, as it provides better reproducibility, version control integration, and long-term maintainability.

  • OpenMRS HIS is just a distribution of Ozone HIS. You can also directly create an Ozone distribution of your own by following the Ozone HIS documentation: Create Your Own Distribution - Docs

  • cc @ibacher @grace @michaelbontyes @Mekom @mseaton @raff @burke

7 Likes