SDK-386: Added support for module based docker distribution

[Ruhanga]

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.6.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 :)

• My IDE is configured to follow the code style of this project.

• I have added tests to cover my changes. (If you refactored
  existing code that was well tested you do not have to add tests)

• I ran mvn clean install right before creating this pull request and
  added all formatting changes to my commit.

• All new and existing tests passed.

• My pull request is based on the latest changes of the master branch.

[mherman22]

Hey @Ruhanga, so i attempted to use mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:6.5.0-SNAPSHOT:build-distro -DincludeModules="org.openmrs.module:legacyui-omod:1.23.0, org.openmrs.module:webservices.rest:2.49.0" -e, i get a distribution but the included modules have not changed version, for example the existing legacyui omod version is 1.16.0 but i was trying to override to 1.23.0 it using includeModules but i didn't workout.

And when i try mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:6.5.0-SNAPSHOT:build-distro -DincludeModules="org.openmrs.module:facilityregistry-omod:1.0.0-SNAPSHOT" -e i dont see any logging of what's going on and the module doesnt get added.

Am i missing something?

[mherman22]

Scratch that, i was running the command in a directory that already had openmrs-distro.properties so i guess it was overriding the command. After deleting it worked as expected.

[Ruhanga]

Thanks for checking this out @mherman22. Did you first clean install?

You should have something along the lines:

$ mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:6.5.0-SNAPSHOT:build-distro -DincludeModules="org.openmrs.module:legacyui-omod:1.23.0, org.openmrs.module:webservices.rest:2.49.0" -e
[INFO] Error stacktraces are turned on.
[INFO] Scanning for projects...
[INFO] 
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO] 
[INFO] --- openmrs-sdk-maven-plugin:6.5.0-SNAPSHOT:build-distro (default-cli) @ standalone-pom ---

Specify build directory for generated files (-Ddir, default: 'docker') (default: 'docker'): docker3

The directory at '/Users/user/example/target/docker3' contains docker config. Only modules and openmrs.war will be overriden
[INFO] Resolving: groupId=org.openmrs.module, artifactId=legacyui-omod, version=1.23.0
[INFO] Configured Artifact: org.openmrs.module:legacyui-omod:1.23.0:jar
[INFO] Copying legacyui-omod-1.23.0.jar to /Users/user/example/target/${project.basedir}/target/moduleBasedArtifactsTempDir/legacyui-1.23.0.jar
[INFO] Resolving: groupId=org.openmrs.module, artifactId=webservices.rest-omod, version=2.49.0
[INFO] Configured Artifact: org.openmrs.module:webservices.rest-omod:2.49.0:jar
[INFO] Copying webservices.rest-omod-2.49.0.jar to /Users/user/example/target/${project.basedir}/target/moduleBasedArtifactsTempDir/webservices.rest-2.49.0.jar
[INFO] 
[INFO] =================================== Resolved Modules ===================================
[INFO] Module ID                      | Group ID                  | Version
[INFO] ----------------------------------------------------------------------------------------
[INFO] webservices.rest               | org.openmrs.module        | 2.49.0
[INFO] legacyui                       | org.openmrs.module        | 1.23.0
[INFO] 

Downloading modules...

[INFO] Configured Artifact: org.openmrs.web:openmrs-webapp:2.7.4:war
[INFO] Copying openmrs-webapp-2.7.4.war to /Users/user/example/target/docker3/web/openmrs-2.7.4.war

file:/Users/user/example/target/docker3/web/openmrs-2.7.4.war

target:docker3/web
[INFO] Configured Artifact: org.openmrs.module:webservices.rest-omod:2.49.0:jar
[INFO] Configured Artifact: org.openmrs.module:legacyui-omod:1.23.0:jar
[INFO] Copying webservices.rest-omod-2.49.0.jar to /Users/user/example/target/docker3/web/modules/webservices.rest-2.49.0.omod
[INFO] Copying legacyui-omod-1.23.0.jar to /Users/user/example/target/docker3/web/modules/legacyui-1.23.0.omod
[INFO] Using Node.js version: 20.17.0
[INFO] Using NPM version: 10.8.2
[INFO] Using OpenMRS Core frontend CLI version: next

No spa configuration found in the distro properties

Creating Docker Compose configuration...


The 'modulebaseddistro' distribution created! To start up the server run 'docker-compose up' from /Users/user/example/target/docker3

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  10.186 s
[INFO] Finished at: 2025-07-25T10:42:38+03:00
[INFO] ------------------------------------------------------------------------

And:

mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:6.5.0-SNAPSHOT:build-distro -DincludeModules="org.openmrs.module:facilityregistry-omod:1.0.0-SNAPSHOT" -e
[INFO] Error stacktraces are turned on.
[INFO] Scanning for projects...
[INFO] 
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO] 
[INFO] --- openmrs-sdk-maven-plugin:6.5.0-SNAPSHOT:build-distro (default-cli) @ standalone-pom ---

Specify build directory for generated files (-Ddir, default: 'docker') (default: 'docker'): docker

The directory at '/Users/user/example/target/docker' contains docker config. Only modules and openmrs.war will be overriden
[INFO] Resolving: groupId=org.openmrs.module, artifactId=facilityregistry-omod, version=1.0.0-SNAPSHOT
[INFO] Configured Artifact: org.openmrs.module:facilityregistry-omod:1.0.0-SNAPSHOT:jar
Downloading from mks-nexus-public: https://nexus.mekomsolutions.net/repository/maven-public/org/openmrs/module/facilityregistry-omod/1.0.0-SNAPSHOT/maven-metadata.xml
Downloading from mks-nexus-public: https://nexus.mekomsolutions.net/repository/maven-public/org/openmrs/module/facilityregistry-omod/1.0.0-SNAPSHOT/facilityregistry-omod-1.0.0-SNAPSHOT.pom
Downloading from openmrs-repo-thirdparty: https://mavenrepo.openmrs.org/thirdparty/org/openmrs/module/facilityregistry-omod/1.0.0-SNAPSHOT/facilityregistry-omod-1.0.0-SNAPSHOT.pom
[INFO] Configured Artifact: org.openmrs.module:facilityregistry-omod:1.0.0-SNAPSHOT:omod
[INFO] Configured Artifact: org.openmrs:facilityregistry-omod:1.0.0-SNAPSHOT:jar
Downloading from mks-nexus-public: https://nexus.mekomsolutions.net/repository/maven-public/org/openmrs/facilityregistry-omod/1.0.0-SNAPSHOT/maven-metadata.xml
Downloading from mks-nexus-public: https://nexus.mekomsolutions.net/repository/maven-public/org/openmrs/facilityregistry-omod/1.0.0-SNAPSHOT/facilityregistry-omod-1.0.0-SNAPSHOT.pom
Downloading from openmrs-repo-thirdparty: https://mavenrepo.openmrs.org/thirdparty/org/openmrs/facilityregistry-omod/1.0.0-SNAPSHOT/facilityregistry-omod-1.0.0-SNAPSHOT.pom
[INFO] Configured Artifact: org.openmrs:facilityregistry-omod:1.0.0-SNAPSHOT:omod
[WARNING] Failed to resolve: groupId=org.openmrs.module, artifactId=facilityregistry-omod, version=1.0.0-SNAPSHOT
[WARNING] Reason: class java.lang.RuntimeException: Failed to download artifact: org.openmrs.module:facilityregistry-omod:1.0.0-SNAPSHOT
[INFO] 
[INFO] =================================== Unresolved Modules =================================
[INFO] Module ID                      | Group ID                  | Version
[INFO] ----------------------------------------------------------------------------------------
[INFO] facilityregistry               | org.openmrs.module        | 1.0.0-SNAPSHOT
[INFO] 

Downloading modules...

[INFO] Configured Artifact: org.openmrs.web:openmrs-webapp:2.7.4:war
[INFO] Copying openmrs-webapp-2.7.4.war to /Users/user/example/target/docker/web/openmrs-2.7.4.war

file:/Users/user/example/target/docker/web/openmrs-2.7.4.war

target:docker/web
[INFO] Using Node.js version: 20.17.0
[INFO] Using NPM version: 10.8.2
[INFO] Using OpenMRS Core frontend CLI version: next

No spa configuration found in the distro properties

Creating Docker Compose configuration...


The 'modulebaseddistro' distribution created! To start up the server run 'docker-compose up' from /Users/user/example/target/docker

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  14.736 s
[INFO] Finished at: 2025-07-25T10:41:58+03:00
[INFO] ------------------------------------------------------------------------