GSOC 2025: Replacing OpenMRS Standalone with a Modern, User-Friendly Alternative - Updates and Discussion

jonathan · August 13, 2025, 5:09pm

So basically, when we use:

-Drefapp.version=3.4.0

It locates distro-emr-configuration-3.4.0.zip from: JFrog

Downloading from openmrs-repo: https://mavenrepo.openmrs.org/public/org/openmrs/distro-emr-configuration/3.4.0/

However, when we specify:

-Drefapp.version=3.6.0-SNAPSHOT

It is unable to locate distro-emr-configuration-3.6.0-SNAPSHOT.zip because in the location: 3.6.0-SNAPSHOT Location

I see we have:

distro-emr-configuration-3.6.0-20250807.131409-1.zip

with release timestamps included, which makes distro-emr-configuration-3.6.0-SNAPSHOT.zip unavailable. This also happens for other versions that follow similar timestamped SNAPSHOT versioning in their repository folders.

jonathan · August 14, 2025, 11:48am

@dkayiwa Just made a deep dive and During the build process, I observed that specifying a SNAPSHOT version like:

-Drefapp.version=3.6.0-SNAPSHOT

causes the build to look in: https://openmrs.jfrog.io/ui/native/public/org/openmrs/distro/referenceapplication-distro/.

In contrast, if we use a release version, for example:

-Drefapp.version=3.4.0

it fetches the distribution from: https://openmrs.jfrog.io/ui/native/public/org/openmrs/distro-emr-configuration/.

This behavior is managed internally by the OpenMRS SDK Maven Plugin (org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:6.4.0) with the configuration:

<plugin>
    <groupId>org.openmrs.maven.plugins</groupId>
    <artifactId>openmrs-sdk-maven-plugin</artifactId>
    <version>6.4.0</version>
    <executions>
        <execution>
            <id>build-distro</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>build-distro</goal>
            </goals>
            <configuration>
                <distro>referenceapplication:${refapp.version}</distro>
                <dir>${project.build.directory}/distro</dir>
            </configuration>
        </execution>
    </executions>
</plugin>

For versions like 3.0.0-SNAPSHOT, the build succeeds because the required distro artifact is available in the referenceapplication-distro repository → https://openmrs.jfrog.io/ui/native/public/org/openmrs/distro/referenceapplication-distro/.

I’ve realized that the issue isn’t the timestamped SNAPSHOTs, as I initially thought, but rather that build-distro sometimes fails to locate the artifact, even though mvn openmrs-sdk:setup can resolve it internally.

mherman22 · August 14, 2025, 1:42pm

We usually have to run mvn openmrs-sdk:setup-sdk to update the settings.xml file .m2 folder. Did you?

jonathan · August 14, 2025, 1:46pm

Oh yes I specified mine here

github.com/openmrs/openmrs-standalone

.github/maven-settings.xml

19c474e97


      
          <?xml version="1.0" encoding="UTF-8"?>
          <settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 http://maven.apache.org/xsd/settings-1.2.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.2.0"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
              <profiles>
                  <profile>
                      <repositories>
                          <repository>
                              <id>openmrs-repo</id>
                              <name>OpenMRS Repository</name>
                              <url>https://mavenrepo.openmrs.org/public</url>
                          </repository>

And i use mvn install --settings .github/maven-settings.xml

mherman22 · August 14, 2025, 6:52pm

So i have looked through your draft pull request and i see the limitation with build-distro, perhaps something we can think about fixing but the workaround i found was to do a two-step execution i.e (generate-distro, then build-distro) where generate-distro creates the openmrs-distro.properties file based off the provided answers using the batchAnswers parameter, then build-distro uses that file to generate the required docker configuration files.

See build when i do that Ubuntu Pastebin

jonathan · August 14, 2025, 7:37pm

great great work @mherman22 thanks for the look up let me test it out

jonathan · August 15, 2025, 5:00am

Really excited about this solution! The working PR is here:

github.com/openmrs/openmrs-standalone

STAND-129: Fix build-distro SNAPSHOT resolution in 3.x Standalone

openmrs-emr3 ← Muta-Jonathan:STAND-129

opened 02:12PM - 14 Aug 25 UTC

Muta-Jonathan

+57 -4

See https://openmrs.atlassian.net/browse/STAND-129 ## Description ### Proble…m: The OpenMRS SDK Maven Plugin build-distro fails for SNAPSHOT versions (e.g., 3.6.0-SNAPSHOT) in CI due to missing directories or unresolved SNAPSHOT artifacts. Locally, builds may succeed because Maven caches artifacts, but CI consistently fails with artifact null errors. ### Solution: This PR implements a robust approach that works for both local and CI builds: Pre-create directories for distro artifacts using maven-antrun-plugin: ``` <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-antrun-plugin</artifactId> <version>3.1.0</version> <executions> <execution> <id>create-directories</id> <phase>generate-resources</phase> <goals> <goal>run</goal> </goals> <configuration> <target> <mkdir dir="${project.build.directory}/openmrs3x"/> </target> </configuration> </execution> </executions> </plugin> ``` Configure openmrs-sdk-maven-plugin for generate-distro and build-distro: ``` <plugin> <groupId>org.openmrs.maven.plugins</groupId> <artifactId>openmrs-sdk-maven-plugin</artifactId> <version>6.5.0</version> <executions> <execution> <id>generate-distro</id> <phase>generate-resources</phase> <goals> <goal>generate-distro</goal> </goals> <configuration> <outputLocation>${project.build.directory}/openmrs3x</outputLocation> <batchAnswers> <batchAnswer>Reference Application 3.x</batchAnswer> <batchAnswer>${refapp.version}</batchAnswer> </batchAnswers> <testMode>true</testMode> </configuration> </execution> <execution> <id>openmrs-sdk:build-distro</id> <goals> <goal>build-distro</goal> </goals> <phase>generate-resources</phase> <configuration> <distro>${project.build.directory}/openmrs3x/openmrs-distro.properties</distro> <dir>${project.build.directory}/distro</dir> </configuration> </execution> </executions> </plugin> ``` ### CI pre-run step: Before running Maven goals in CI, ensure the SDK is set up non-interactively with proper settings: ``` - name: Pre-run OpenMRS SDK Plugin run: mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:6.5.0:setup-sdk -B --settings .github/maven-settings.xml -DinteractiveMode=false -DstatsEnabled=false ``` ### Benefits: * Works consistently for SNAPSHOT and release versions locally and in CI. * Eliminates artifact null errors. * Does not change the developer workflow for local builds. ### Testing: * ✅ Local build: `mvn clean package -Drefapp.version=3.6.0-SNAPSHOT` succeeds. * ✅ Local build: `mvn clean package -Drefapp.version=3.6.0-SNAPSHOT` succeeds. * ✅ CI build passes after pre-running setup-sdk.

and the associated ticket is STAND-129: Build-distro fails to resolve SNAPSHOT artifacts while sdk:setup succeeds in 3.x Standalone.

A big thanks to @mherman22 for the quick guidance—it’s much appreciated!

With this fix, I believe the 3.x Standalone is now ready for testing and can be considered for the final 3.5.0 release once we get the green light.

cc: @wikumc @dkayiwa @ruhanga @jayasanka @jwnasambu @dkigen

jonathan · August 20, 2025, 6:05pm

Hi all,

I’m running into an issue when trying to run OpenMRS 3.x Standalone with MariaDB.

When I set my connection URL like this:

connection.url=jdbc:mariadb://127.0.0.1:3316/openmrs?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8&zeroDateTimeBehavior=convertToNull

I get the following exception on startup:

java.lang.IllegalStateException: No WebApplicationContext found: no ContextLoaderListener registered?
	at org.springframework.web.context.support.WebApplicationContextUtils.getRequiredWebApplicationContext(WebApplicationContextUtils.java:85)
	at org.springframework.orm.hibernate5.support.OpenSessionInViewFilter.lookupSessionFactory(OpenSessionInViewFilter.java:194)
	at org.springframework.orm.hibernate5.support.OpenSessionInViewFilter.lookupSessionFactory(OpenSessionInViewFilter.java:180)
	at org.springframework.orm.hibernate5.support.OpenSessionInViewFilter.doFilterInternal(OpenSessionInViewFilter.java:131)
	at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
	at org.springframework.web.multipart.support.MultipartFilter.doFilterInternal(MultipartFilter.java:125)
	at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:117)
	at org.openmrs.web.filter.StartupFilter.doFilter(StartupFilter.java:120)
	at org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:201)

Full error trace here: Pastebin link

Observations:

This does not happen when I switch to MySQL instead of MariaDB.
I’m using OpenMRS 2.8.0 libraries inside 3.x standalone.
On server restart, OpenMRS cannot connect to the database and redirects to the installer, trying to create a new instance.
I also tried specifying:

hibernate.dialect=org.hibernate.dialect.MariaDBDialect

in openmrs-runtime.properties, but the same result occurs.

This setup was intended to solve:

java.sql.SQLSyntaxErrorException: Unknown column 'RESERVED' in 'WHERE'

The commit by @raff adding MariaDB support for replication/failover might be related: Commit link

Questions:

Has anyone else seen this No WebApplicationContext found error when using MariaDB in 3.x standalone?
Is this an incompatibility with the 2.8.x OpenMRS core libraries and MariaDB?
Could there be a missing configuration step for the MariaDB driver to work correctly with OpenMRS 3.x?

cc @dkayiwa, @wikumc @ian, @raff

Any guidance would be appreciated!

For a checkout Kindly take a look by changing the connection.url in openmrs-runtime.properties here openmrs-standalone/src/main/config/openmrs-runtime.properties at e4c0929f8e14fc9b9bb850b31b4486aa9a88e703 · openmrs/openmrs-standalone · GitHub to connection.url=jdbc:mariadb://127.0.0.1:3316/openmrs?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8&zeroDateTimeBehavior=convertToNull

dkayiwa · August 20, 2025, 8:17pm

Did you change the driver from mysql-connector-java to mariadb-java-client in the standalone?

jonathan · August 20, 2025, 10:29pm

Yes, I did. I switched from mysql-connector-java to mariadb-java-client in the standalone by adding the following dependency:

<dependency>
    <groupId>org.mariadb.jdbc</groupId>
    <artifactId>mariadb-java-client</artifactId>
    <version>3.5.4</version>
    <scope>compile</scope>
</dependency>

I also updated openmrs-runtime.properties to explicitly use the MariaDB driver:

hibernate.connection.driver_class=org.mariadb.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MariaDBDialect

And in code, I replaced:

Class.forName("com.mysql.cj.jdbc.Driver").newInstance();

with:

Class.forName("org.mariadb.jdbc.Driver").newInstance();

However, even after making these changes, I was still getting the same error.

dkayiwa · August 21, 2025, 11:02am

Can you just raise a pull request with your changes?

jonathan · August 21, 2025, 1:00pm

Sure here is the PR

dkayiwa · August 21, 2025, 11:24pm

I have just made a commit to openmrs-core. To take advantage of these changes, you will need to compile the standalone with something like mvn package -Dopenmrs.version=2.8.1-SNAPSHOT

jonathan · August 22, 2025, 9:36am

Wonderful @dkayiwa thanks for the fix … Just tested and works as expected …

I will go ahead and switch version also on the PR to use 2.8.1-SNAPSHOT OpenMRS core version

jonathan · December 3, 2025, 3:24pm

Hi all,

I’m putting out a heads-up about the OpenMRS Standalone revamp aimed at pushing it towards production. I’ll be creating an epic for this work soon, and would appreciate it if you could keep an eye on it, provide feedback, or pick up items once they’re created this will also include some intro tickets.

I’ll be communicating updates here, so everyone can stay aligned. The plan is to bring Standalone back to life, and your input will be key to making this transition to production a success.

Let’s make it happen!
cc @dkayiwa

dkayiwa · December 3, 2025, 5:08pm

Thank you so much @jonathan

jonathan · January 12, 2026, 1:57pm

Hi all,

Happy New Year!

Just putting this out there — a new epic has been created to track the OpenMRS Standalone revamp: STAND-137.

This epic will cover all the work to get Standalone production-ready, including intro tickets and updates along the way. Everyone’s feedback and contributions will be super valuable, so feel free to follow, comment, or pick up items as they appear.

Looking forward to bringing Standalone back to life with the community in 2026!

cc @dkayiwa