# Enhance OpenMRS SDK to support Dockerized Module-Based Distribution Builds **URL:** \ **Category:** Quality Assurance\ **Tags:** module, openmrs-sdk, core\ **Created:** [May 21, 2025, 12:19pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082 "2025-05-21T12:19:48Z")\ **Posts on this page:** 13\ **Page:** 1
**Author:** ![ruhanga](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ruhanga/32/8318_2.png) [@ruhanga](https://talk.openmrs.org/u/ruhanga)\ **Post date:** [May 21, 2025, 12:19pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/1 "2025-05-21T12:19:48Z")
Hi all, Following the great conversations in the threads below — which represent a significant step forward in achieving more consistent and modern software development and deployment practices — I’d like to propose an additional improvement to help fully realize the underlying goals: - [Dockerizing Development and Deployment of OpenMRS](https://talk.openmrs.org/t/dockerizing-development-and-deployment-of-openmrs/36410) - [My Fellowship Journey – Bett Kipchumba](https://talk.openmrs.org/t/my-fellowship-journey-bett-kipchumba/36880/7) ### 🔍 Why The above Efforts Matter Both development and deployment workflows fundamentally require a correctly provisioned environment — typically involving compatible versions of Java, Maven, and system-level dependencies. Docker allows this environment to be defined and shared consistently, avoiding “it works on my machine” problems and making CI/CD pipelines more predictable at the same time improving developer experience. The benefits can be summarised as, being able to: - Provide a **standardized, reproducible runtime** across teams and platforms. - Eliminate local/host system dependency issues. - Improve developer onboarding by reducing setup complexity. - Make it easier to test against OpenMRS distributions or module versions. It is from the last point above that I’d like to discuss an area to improve on the **OpenMRS SDK**. The **OpenMRS SDK** already provides powerful features for managing development servers, creating distributions, and scaffolding modules. During module development, being able to also build deployable module based distributions can be great addition to the above efforts. Here is where this would lead to — being able to generate a run-able distribution based on a module’s `config.xml` file which consequently involves resolving the transitively required modules. With this, we would eliminate the need to have extra `distro-properties.xml` or `docker-compopse.yml` files residing within modules. * * * ### ⚙ Proposed Enhancements to the **OpenMRS SDK** 1. Introduce a lightweight function to build a distribution based on a module’s `config.xml` file, into the **OpenMRS SDK**. 2. Extend existing **OpenMRS SDK** commands to Support 1 above, such as: ```auto mvn openmrs-sdk:build-distro -Dmodule-based # Build module based Dockerized distribution ``` The command can be run locally or executed within a mounted Docker container. This improvement is optional and opt-in for devs and, as usual, allows for execution in CI environments Devs are allowed to define or override Docker Compose instance files as part of their project deployment setups, enabling custom local dev stacks. Looking forward to your thoughts and feedback @ibacher, @dkayiwa, @wikumc, @raff, @mseaton, [@dev5](https://talk.openmrs.org/groups/dev5), [@dev4](https://talk.openmrs.org/groups/dev4), [@dev3](https://talk.openmrs.org/groups/dev3), and anyone else interested in improving our tooling ---
**Author:** ![kazlaw](https://talk.openmrs.org/user_avatar/talk.openmrs.org/kazlaw/32/15943_2.png) [@kazlaw](https://talk.openmrs.org/u/kazlaw)\ **Post date:** [May 21, 2025, 12:39pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/2 "2025-05-21T12:39:00Z")
Sounds exciting. Cant wait to hear feedback. ---
**Author:** ![mozzy](https://talk.openmrs.org/user_avatar/talk.openmrs.org/mozzy/32/11815_2.png) [@mozzy](https://talk.openmrs.org/u/mozzy)\ **Post date:** [May 22, 2025, 4:45pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/3 "2025-05-22T16:45:29Z")
> [@ruhanga](#): > > During module development, being able to also build deployable module based distributions can be great addition to the above efforts. Here is where this would lead to — being able to generate a run-able distribution based on a module’s `config.xml` file which consequently involves resolving the transitively required modules Great Idea — resolving a deeply nested transitive dependency tree for the required modules is definitely one of the more complex pieces of this proposal. That said, it’s also a necessary step if we want to support truly self-contained module-based distributions. Perhaps , we could leaverage the existing fucntionality where the SDK will generate either a Platform-based distribution or Reference-App based distribution depending on the module’s `config.xml` file and just plugin a few extra required modules not part of the distribuiton. Definitely this is an area where thoughtful design and contributions would make a big impact. ---
**Author:** ![ruhanga](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ruhanga/32/8318_2.png) [@ruhanga](https://talk.openmrs.org/u/ruhanga)\ **Post date:** [May 23, 2025, 11:55am UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/4 "2025-05-23T11:55:50Z")
> [@mozzy](#): > > Great Idea — resolving a deeply nested transitive dependency tree for the required modules is definitely one of the more complex pieces of this proposal. That said, it’s also a necessary step if we want to support truly self-contained module-based distributions. Correct, @mozzy. You can think of this as enabling the dynamic generation of a distribution where the developer only needs to specify the module they’re working on. One challenge, though, is ensuring the availability of necessary initialization metadata to successfully run the modules. I guess this shouldn’t pose a major hurdle in most cases, since many modules already include their default metadata via Liquibase migrations and/or `config.xml` definitions. ---
**Author:** ![dkayiwa](https://talk.openmrs.org/user_avatar/talk.openmrs.org/dkayiwa/32/179_2.png) [@dkayiwa](https://talk.openmrs.org/u/dkayiwa)\ **Post date:** [May 23, 2025, 12:11pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/5 "2025-05-23T12:11:02Z")
> [@ruhanga](#): > > since many modules already include their default metadata via Liquibase migrations and/or `config.xml` definitions. We generally discourage distributing module metadata via liquibase. ---
**Author:** ![ruhanga](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ruhanga/32/8318_2.png) [@ruhanga](https://talk.openmrs.org/u/ruhanga)\ **Post date:** [May 23, 2025, 12:22pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/6 "2025-05-23T12:22:41Z")
> [@dkayiwa](#): > > We generally discourage distributing module metadata via liquibase. Ahh, right. Thanks for the clarification @dkayiwa… 🙂 ---
**Author:** ![mseaton](https://talk.openmrs.org/user_avatar/talk.openmrs.org/mseaton/32/8088_2.png) [@mseaton](https://talk.openmrs.org/u/mseaton)\ **Post date:** [May 23, 2025, 12:46pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/7 "2025-05-23T12:46:20Z")
It is a good idea and opens up a lot of possibilities for us to add features to the SDK based on specifications in a module’s config.xml file. I definitely see value in parsing out a list of module and core requirements for a given module, by walking the config.xml dependency tree recursively. It’s actually quite surprising that this has never been part of the SDK. Before we dive it though, it would be good to clearly lay out what problem we are trying to solve so that we can best identify the specific features that we should add to the SDK. It might be that it is best to develop a few small, independent features that can be composed together, each of which is independently useful. For example, outside of the CI goals listed here, another obvious use case would be If one deploys a module or a distribution into an existing SDK instance, the SDK should be able to check whether all of that module’s / distribution’s dependencies are present, and if they are not, should prompt the user to add what is needed, iterating over each missing dependency and presenting the user with a list of compatible versions of each that they could install. ---
**Author:** ![ruhanga](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ruhanga/32/8318_2.png) [@ruhanga](https://talk.openmrs.org/u/ruhanga)\ **Post date:** [May 26, 2025, 7:07am UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/8 "2025-05-26T07:07:54Z")
> [@mseaton](#): > > Before we dive it though, it would be good to clearly lay out what problem we are trying to solve so that we can best identify the specific features that we should add to the SDK. It might be that it is best to develop a few small, independent features that can be composed together, each of which is independently useful. Indeed, @mseaton — the intention behind this feature is to complement and carry forward the efforts initiated by @corneliouzbett, specifically: > [@My Fellowship Journey: Bett Kipchumba](https://talk.openmrs.org/t/my-fellowship-journey-bett-kipchumba/36880/1): > > - Utilizing docker to build and develop openmrs modules. > [@mseaton](#): > > … another obvious use case would be If one deploys a module or a distribution into an existing SDK instance, the SDK should be able to check whether all of that module’s / distribution’s dependencies are present, and if they are not, should prompt the user to add what is needed, iterating over each missing dependency and presenting the user with a list of compatible versions of each that they could install. Absolutely — your suggestion to have the SDK automatically detect and resolve missing dependencies when deploying a module or distribution is spot-on. From the perspective of implementers and testers, this would be really valuable. It would help assess the **dependency safety** of a module or distribution before runtime issues arise. While this extends beyond the original motivation, it’s a highly complementary enhancement. It can easily be scoped as part of the broader effort to improve the SDK’s module/dependency handling — involving interactive prompts or automated resolution where feasible. ---
**Author:** ![dkayiwa](https://talk.openmrs.org/user_avatar/talk.openmrs.org/dkayiwa/32/179_2.png) [@dkayiwa](https://talk.openmrs.org/u/dkayiwa)\ **Post date:** [June 4, 2025, 11:13am UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/9 "2025-06-04T11:13:55Z")
@ruhanga i see that you have started working on migrating from XStream to Jackson. Does that mean that this work, of being able to compile modules within docker, is complete? ---
**Author:** ![ruhanga](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ruhanga/32/8318_2.png) [@ruhanga](https://talk.openmrs.org/u/ruhanga)\ **Post date:** [June 4, 2025, 11:37am UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/10 "2025-06-04T11:37:27Z")
> [@dkayiwa](#): > > being able to compile modules within docker This has already been achieved on our Bamboo CI, @dkayiwa. However I’m still working on the module-based Docker distribution with the SDK, albeit with a lower priority at the moment. That said, two things: 1. The Jackson migration has taken precedence since it seems to be blocking some other upgrades. 2. I’d also like to keep the discussions around the shift to Jackson moving forward. With this in mind, I’ll make sure to get the module based distribution-deployment work completed as soon as possible as well. ---
**Author:** ![dkayiwa](https://talk.openmrs.org/user_avatar/talk.openmrs.org/dkayiwa/32/179_2.png) [@dkayiwa](https://talk.openmrs.org/u/dkayiwa)\ **Post date:** [June 4, 2025, 11:47am UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/11 "2025-06-04T11:47:09Z")
@wikumc has finished Java upgrades for a number of modules but cannot have their snapshot versions run on Bamboo CI. May be you did that already and i am just not aware. If you already did so, can you share the instructions on what he should do with the rest of the modules that he is working on? This is of a higher priority than the XStream to Jackson upgrade work. ---
**Author:** ![ruhanga](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ruhanga/32/8318_2.png) [@ruhanga](https://talk.openmrs.org/u/ruhanga)\ **Post date:** [June 4, 2025, 12:33pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/12 "2025-06-04T12:33:34Z")
Correct @dkayiwa. I should have posted an updated list of those modules already configured in Bamboo to run with Java 21. This I have done on the [migration thread](https://talk.openmrs.org/t/planning-java-21-migration-for-openmrs-modules/45713/31). ---
**Author:** ![ruhanga](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ruhanga/32/8318_2.png) [@ruhanga](https://talk.openmrs.org/u/ruhanga)\ **Post date:** [July 30, 2025, 5:12pm UTC](https://talk.openmrs.org/t/enhance-openmrs-sdk-to-support-dockerized-module-based-distribution-builds/46082/13 "2025-07-30T17:12:04Z")
Happy to announce that the feature discussed above has come to life. For those interested, please take a moment to review and test the PR below when you get a chance: > > > \## Description of what I changed > > > > This PR introduces a feature which will …allow generating a runnable distribution based on a module’s \`config.xml\`, including the resolution of all its transitive module dependencies. > > The following has been done: > > Introduced a lightweight utility class that helps in building a distribution by reading a module’s \`config.xml\` file. > > Extended existing \`build-distro\` command to support this functionality, allowing the specification or override of module artifacts using an \`includeModules\` parameter. This parameter accepts a comma-separated list of artifacts in the format groupId:artifactId:version. If the groupId is omitted, a default (e.g., \`org.openmrs.module\`) can be assumed. > > The way to test this out: > > \* Build the changes on this PR locally > > \`\`\` > mvn clean install > \`\`\` > > \* With a module(s) of your choice, build a module based distro (this can also be done by first checking out a module project and the following command run from the root project directory) > > \`\`\` > mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:6.5.0-SNAPSHOT:build-distro -DincludeModules="groupId1:artifactId1:version1, artifactId2:version2" -e > \`\`\` > > \* Take note of the logs and adjust/override where necessary the selection of the module artifacts used > \* Run the provided docker compose setup generated at the specified target folder. Note that you may need to override the \`Dockerfile\` definition located in the \`web\` folder, by commenting out or deleting the following lines since they break the build and not necessary in the end. > > \`\`\` > COPY openmrs\_config /openmrs/distribution/openmrs\_config > COPY openmrs\_spa /openmrs/distribution/openmrs\_spa > \`\`\` > \## Issue I worked on > > > > > see https://openmrs.atlassian.net/browse/SDK-386 > > \## Checklist: I completed these to help reviewers :) > > > \- \[x\] My IDE is configured to follow the \[\*\*code style\*\*\](https://wiki.openmrs.org/display/docs/Java+Conventions) of this project. > > \- \[x\] I have \*\*added tests\*\* to cover my changes. (If you refactored > existing code that was well tested you do not have to add tests) > > \- \[x\] I ran \`mvn clean install\` right before creating this pull request and > added all formatting changes to my commit. > > \- \[x\] All new and existing \*\*tests passed\*\*. > > \- \[x\] My pull request is \*\*based on the latest changes\*\* of the master branch. cc [@dev5](https://talk.openmrs.org/groups/dev5), [@dev4](https://talk.openmrs.org/groups/dev4), [@dev3](https://talk.openmrs.org/groups/dev3), @all