Creating a build pipeline for OpenMRS 3.0

As the OpenMRS 3.0 Framework is beginning to get piloted and we expect adoption only to grow, we need to migrate from an ad hoc deployment at to a more automated CI-based process that can be hosted within the OpenMRS infrastructure (e.g., something like,,

Adapting the proposed RefApp 3.x folder layout to define everything needed to deploy an instance of the current version of OpenMRS 3 (running at would be a great start and would have some immediate benefits:

  • Provide the recipe for automated CI builds so we can have qa, staging, and demo environments for OpenMRS 3.0 work
  • Harden our convention for defining deployments (both for OpenMRS 2.x & 3.x)
  • Make it easier for people to try out OpenMRS 3.0 for themselves (either through a hosted environment or by deploying locally)

Some of the pieces I think we need are:

  • Pulling settings (host location, port, etc.) into environment variables
  • A repo for OpenMRS 3.0 Framework with GitHub action(s) to build docker containers and deploy them to OpenMRS on Docker Hub
  • ansible-docker-compose file(s) that define the hosted environments for our infrastructure
  • CI plans to deploy those environments

I assume micro frontends (with its myriad of esm modules) would be similar to the RefApp (with its myriad of OpenMRS modules) – i.e., changes to individual esm repos wouldn’t trigger a new deployment to qa; rather, a commit to the OpenMRS 3.x repository (like a change to its import map configuration) would trigger a new build & deployment. Then CI could be used to manually promote any one of those builds to staging/demo sites.

I know there are more pieces, but I wanted to get the conversation started here. Thoughts about other steps/pieces we’ll need?

/cc @mksrom @jdick @grace @mksd @bistenes @dkayiwa @ibacher @cintiadr

1 Like

Thanks for kicking this off Burke!

A few immediate thoughts:

  1. Separating App releases from Production environment releases: I think we need to think of these as two different though related release pipelines, similar to how we think of Modules vs RefApp release right now. We kind of have this already: in npm, MF apps/widgets get labelled with “next” or “latest” depending on whether they’re production ready or in draft.

I want to see us focus, for the next few weeks, on the other release process: releasing regular improvements to our production/demo site.

I.e. every 1-2 weeks we should update the Demo/production site with the most recent published version of widgets. This frequent cadence culture will help us get used to getting value out the door, promptly, together.

  1. Demo Site: Let’s keep it simple to start with and just have 2 environments: our dev/QA environment, and our demo/production environment. I know big big teams often have a staging environment in between but at our current size and scope it adds unnecessary complexity (esp. since our production product is a demo site, not a patient or physician facing product). We have a staging environment in the OCLOMRS project and honestly it’s rarely used, and adds an additional layer that our PMs have to QA which is rather irritating at this stage.

If we find there’s lots of issues like merge conflicts between these two, then we can consider adding a staging environment. But let’s reduce complexity ad much as we can for now.

Thanks @burke, definitely needing to loop in @achachiez.

Agreed. As I was writing the post, I was already thinking there’s little need for a staging environment at this point. Starting with a qa & demo makes sense. Actually, if we follow the path of RefApp CI, the next next environment we’ll likely want would be uat (i.e., user acceptance testing = an environment for testing of features/changes that is safe from automated/unexpected changes but not yet ready for the demo site). But let’s start by focusing on an automated qa first (an automated version of what openmrs-spa is doing now).

@mksrom / @dkayiwa / @ibacher,

When I checkout the 3.x branch of openmrs-distro-referenceapplication and run mvn clean package, it fails with this error:

[ERROR] Failed to execute goal on project openmrs-distro-package: Could
not resolve dependencies for project
org.openmrs:openmrs-distro-package:pom:1.0.0-SNAPSHOT: Failed to
collect dependencies at org.openmrs.web:openmrs-webapp:war:2.3.3:
Failed to read artifact descriptor for
org.openmrs.web:openmrs-webapp:war:2.3.3: Could not transfer artifact
org.openmrs.web:openmrs-webapp:pom:2.3.3 from/to
maven-default-http-blocker ( Blocked mirror for
repositories: [openmrs-repo
default, releases+snapshots), archetype
default, releases+snapshots), openmrs-repo-thirdparty
default, releases+snapshots)]
1 Like

You’ve got the latest Maven apparently. The URLs on that repo will need to be changed to https instead of http or you can downgrade to Maven 3.6.3 (this is a breaking, security-related change in Maven 3.8.1).

Yeah, it seems like we might want an environment that we can run some automated and manual tests against that isn’t the development environment, for much the same reasons it makes sense to have a demo environment.

Is there any preference as to which servers these will be deployed on? Currently both demo and qa-refapp run on balaka.

Ahh great point.

One caveat: @ibacher in the case of 3.0, the Demo is equivalent to our Production application :stuck_out_tongue: So we’ll have to be kinda careful how we use that word in the 3.0 context.

Thanks @ibacher. I replaced a couple “http:” with “https:” in package/pom.xml and in my ~/.m2/settings.xml and mvn clean package succeeded. :slight_smile:

Is it safe (backwards-compatible) to update the package/pom.xml to use https (if I update the pom.xml to use https, will it still work for people using older versions of mvn)?

Yeah, it’s totally safe, as long as it isn’t pointing to the repo (we use that for SASS in some of the UI modules; see here).

@burke any updates? Are we any closer to having two environments, dev vs production/demo, for 3.0?