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

[jonathan (Mutagubya Jonathan)]

Hi everyone

I’ll be working on the project Replacing OpenMRS Standalone with a Modern, User-Friendly Alternative.

This project aims at replacing OpenMRS Standalone version due to outdated technology and lack of support. A new version, compatible with Java 17 and supporting OpenMRS 2.x, 3.x, and Core Platform 2.7.x/2.8.x, will be built on M1/M2 MacBooks.

I’ll use this thread to give updates and discuss the project.

Mentors

Primary mentor: @dkayiwa

Backup mentor: @wikumc

[jonathan (Mutagubya Jonathan)]

With my contribution to the new version GitHub - MariaDB4j/MariaDB4j: MariaDB Embedded in Java JAR We have been able to support Embedded DBs on M1/M2+ silicon chips to note we used Mariadb binaries of version 11.4.5

Release am using here: Release 3.2.0 · MariaDB4j/MariaDB4j · GitHub

---

However testing this Mariadb4j on 11.4.5 mariadb version with Openmrs Standalone have run into liquidbase changesets errors

---

After a talk with my mentors, I tried to see if this mariadb version (11.4.5) is compatible with openmrs by updating openmrs-distro-referenceapplication locally here openmrs-distro-referenceapplication/docker-compose.yml at 500889e551fc4b7b124c704471059580a1a4d9d1 · openmrs/openmrs-distro-referenceapplication · GitHub since openmrs supports mariadb

from image: mariadb:10.11.7 to image: mariadb:11.4.5 however am running into these errors on the docker logs … 2025-05-20 09:31:55.918 | 2025-05-20 06:31:55+00:00 [Note] [Entrypoint]: Entrypo - Pastebin.com

---

Here is my docker-compose.yml

version: "3.7"

services:
  gateway:
    image: openmrs/openmrs-reference-application-3-gateway:${TAG:-qa}
    restart: "unless-stopped"
    depends_on:
      - frontend
      - backend
    ports:
      - "80:80"

  frontend:
    image: openmrs/openmrs-reference-application-3-frontend:${TAG:-qa}
    restart: "unless-stopped"
    environment:
      SPA_PATH: /openmrs/spa
      API_URL: /openmrs
      SPA_CONFIG_URLS: /openmrs/spa/config-core_demo.json
      SPA_DEFAULT_LOCALE:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      timeout: 5s
    depends_on:
      - backend

  backend:
    image: openmrs/openmrs-reference-application-3-backend:${TAG:-qa}
    restart: "unless-stopped"
    depends_on:
      - db
    environment:
      OMRS_CONFIG_MODULE_WEB_ADMIN: "true"
      OMRS_CONFIG_AUTO_UPDATE_DATABASE: "true"
      OMRS_CONFIG_CREATE_TABLES: "true"
      OMRS_CONFIG_CONNECTION_SERVER: db
      OMRS_CONFIG_CONNECTION_DATABASE: openmrs
      OMRS_CONFIG_CONNECTION_USERNAME: ${OMRS_DB_USER:-openmrs}
      OMRS_CONFIG_CONNECTION_PASSWORD: ${OMRS_DB_PASSWORD:-openmrs}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/openmrs"]
      timeout: 5s
    volumes:
      - openmrs-data:/openmrs/data

  # MariaDB
  db:
    image: mariadb:11.4.5
    restart: "unless-stopped"
    command: "mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_general_ci"
    healthcheck:
      test: "mysql --user=${OMRS_DB_USER:-openmrs} --password=${OMRS_DB_PASSWORD:-openmrs} --execute \"SHOW DATABASES;\""
      interval: 3s
      timeout: 1s
      retries: 5
    environment:
      MYSQL_DATABASE: openmrs
      MYSQL_USER: ${OMRS_DB_USER:-openmrs}
      MYSQL_PASSWORD: ${OMRS_DB_PASSWORD:-openmrs}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-openmrs}
    volumes:
      - db-data:/var/lib/mysql

volumes:
  openmrs-data: ~
  db-data: ~

cc @dkayiwa @wikumc

[wikumc (Wikum Weerakutti)]

For now, remove the command from docker-compose.yml. In newer versions of MariaDB, you may need to add the following to the my.cnf file:

[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci

You can try this by accessing the db container and modifying the configuration file directly.

[jonathan (Mutagubya Jonathan)]

@wikumc

[mysqld] character-set-server=utf8mb4 collation-server=utf8mb4_general_ci

thanks @wikumc removing the command worked out let me try to reproduce the issue

[jonathan (Mutagubya Jonathan)]

Am facing the issue of the platform versions 2.4+ war file with also mariadb 11.4.5 running into maintainance mode when configured with Tomcat version 7.0.109 which i believe this misbehaving issue is due to the mention here by @ibacher from Platform 2.4+ and Tomcat

@ibacher

Apologies for adding a sort of retro-active release note, but this is an important reminder that for platform versions 2.4 and higher, we no longer support Tomcat 7. This is because in 2.4, we upgrade to Spring 5, which dropped support for Tomcat 7 and began requiring Servlet Spec 3.1 or higher. Running on Tomcat 7 appears to mostly work, but you will likely run into issues, and as Tomcat 7 reached its EOL on 31 March 2021, we would strongly advise not running it production, if that’s at all possible.

cc @ibacher @wikumc @dkayiwa what could be your suggestions should i go ahead with the newer tomcat versions and what could be the right version? Also to NOTE: no error logs are showed if i go with the demo Standalone data however Ui turns to the maintanance mode page

for the logs Initial configuration neededDeleting active databaseUnzipping database from - Pastebin.com and left logs here INFO - Slf4JLogger.log(43) |2025-05-21T14:46:01,621| Reading from openmrs.liquib - Pastebin.com

[dkayiwa (Daniel Kayiwa)]

Feel free to upgrade the standalone’s embedded version of tomcat to either 8.x or 9.x.

[ibacher (Ian Bacher)]

Ideally, the standalone should use the latest version of 9.x, I think.

[jonathan (Mutagubya Jonathan)]

trying again distro with maria db 11.4.5 am getting this error INFO - Slf4JLogger.log(43) |2025-05-22T12:40:21,178| Foreign key constraint adde - Pastebin.com using this as my docker-compose.yml and the goal is to see if openmrs is compatible with mariadb 11.4.5 because its what mariadbj4 uses to note this after some minutes about 10 its able to load the ui login page for 03

version: "3.7"

services:
  gateway:
    image: openmrs/openmrs-reference-application-3-gateway:${TAG:-qa}
    restart: "unless-stopped"
    depends_on:
      - frontend
      - backend
    ports:
      - "80:80"

  frontend:
    image: openmrs/openmrs-reference-application-3-frontend:${TAG:-qa}
    restart: "unless-stopped"
    environment:
      SPA_PATH: /openmrs/spa
      API_URL: /openmrs
      SPA_CONFIG_URLS: /openmrs/spa/config-core_demo.json
      SPA_DEFAULT_LOCALE:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      timeout: 5s
    depends_on:
      - backend

  backend:
    image: openmrs/openmrs-reference-application-3-backend:${TAG:-qa}
    restart: "unless-stopped"
    depends_on:
      - db
    environment:
      OMRS_CONFIG_MODULE_WEB_ADMIN: "true"
      OMRS_CONFIG_AUTO_UPDATE_DATABASE: "true"
      OMRS_CONFIG_CREATE_TABLES: "true"
      OMRS_CONFIG_CONNECTION_SERVER: db
      OMRS_CONFIG_CONNECTION_DATABASE: openmrs
      OMRS_CONFIG_CONNECTION_USERNAME: ${OMRS_DB_USER:-openmrs}
      OMRS_CONFIG_CONNECTION_PASSWORD: ${OMRS_DB_PASSWORD:-openmrs}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/openmrs"]
      timeout: 5s
    volumes:
      - openmrs-data:/openmrs/data

  # MariaDB
  db:
    image: mariadb:11.4.5
    restart: "unless-stopped"
    healthcheck:
      test: "mysql --user=${OMRS_DB_USER:-openmrs} --password=${OMRS_DB_PASSWORD:-openmrs} --execute \"SHOW DATABASES;\""
      interval: 3s
      timeout: 1s
      retries: 5
    environment:
      MYSQL_DATABASE: openmrs
      MYSQL_USER: ${OMRS_DB_USER:-openmrs}
      MYSQL_PASSWORD: ${OMRS_DB_PASSWORD:-openmrs}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-openmrs}
    volumes:
      - db-data:/var/lib/mysql

volumes:
  openmrs-data: ~
  db-data: ~

on the standalone am getting Using runtime properties file: openmrs-runtime.properties✅ tomcat set.✅ Reac - Pastebin.com however to note here am using mariadb driver org.mariadb.jdbc.Driver Is it the problem with the mariadb driver connecting with openmrs?

---

here is my openmrs-runtime.properties

connection.password=test

vm_arguments=-Xmx512m -Xms512m -XX:NewSize=128m --add-exports=java.desktop/com.apple.eawt=ALL-UNNAMED

application_data_directory=appdata

connection.username=openmrs

auto_update_database=true

module.allow_web_admin=true

connection.database.data_dir=./database/data

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

tomcatport=8081

cc @wikumc @dkayiwa

[jonathan (Mutagubya Jonathan)]

also tried using Mysql driver com.mysql.cj.jdbc.Driver with auto_update_database=false with the option of demo data running still on mariadb 11.4.5

https://pastebin.com/ad0STjiR

cc @dkayiwa @wikumc

[dkayiwa (Daniel Kayiwa)]

Is this of any help? https://stackoverflow.com/questions/78199720/encountering-java-sql-sqlsyntaxerrorexception-unknown-column-reserved-in-whe

[jonathan (Mutagubya Jonathan)]

yes @dkayiwa used this however this caused me to have to change the connection jdbc url to

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

which was successfully running without without the logs however seemed not supported by openmrs core since there was no connection to the database … on my small investigation saw that openmrs core expects jdbc connections with MySQL and H2 databases

[jonathan (Mutagubya Jonathan)]

for references looked in here

api/src/test/java/org/openmrs/test/DbUtil.java

[jonathan (Mutagubya Jonathan)]

For references after discussions here Support MariaDB JDBC url and MariaDB driver and more from the Platform calls Have managed to make the demonstration to work…(this mode comes with pre-installed Demo Database)

All along Was thinking it was core issue yet it just needed a keen follow-up in the flow of pom steps (modules) here are the screenshots of the working demonstration tested on linux and mac

Screenshots from Linux Ubuntu 20.4.6

---

Screenshots from Mac OS m2 silicon

---

For the next steps Am working on → Making The ciel and expert modes to work as also expected

cc @dkayiwa @wikumc

[mherman22 (herman muhereza)]

@jonathan

All along Was thinking it was core issue

Great work @jonathan, some context on what the fix to that issue is/was? I am just curious to know

[jonathan (Mutagubya Jonathan)]

Indeed @mherman22, initially I encountered the following error:

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

This was due to using a newer version of MariaDB, where some reserved keywords or schema differences can cause SQL syntax issues—particularly with older queries or Liquibase changesets that haven’t accounted for MariaDB-specific behaviors. While this error also appears in the OpenMRS distro 3.x builds (even with MariaDB 11.4.5), it shows up as a warning there and doesn’t block the application from starting. The home page still loads correctly in that case.

However, when working with the OpenMRS Standalone project—especially in demonstration mode, which includes a pre-loaded demo database—I ran into deeper issues. Specifically, I saw errors like:

There was an error while updating the database to the latest. 
file: org/openmrs/liquibase/updates/liquibase-update-to-latest-2.0.x.xml. 
Error: liquibase.exception.LiquibaseException: Unable to execute change set: liquibase-update-to-latest.xml::20090402-1519-concept_map::bwolfe

These errors were due to missing tables and Liquibase changesets failing to apply. The root cause was that I was pre-loading the database manually, without using the Maven plugins to trigger the appropriate Liquibase updates during build or runtime which i thought were core related.

Solution

To resolve this:

1. I switched to using the Liquibase Maven plugin to ensure all database changesets were applied correctly during the build process.
2. Some of the changesets in the standalone project were only tagged with dbms="mysql", which excludes MariaDB by default. I modified these to include dbms="mysql,mariadb" so that they apply cleanly regardless of whether MySQL or MariaDB is used.
3. The warning Unknown column 'RESERVED' in 'WHERE' is still present and is related to reserved keywords that don’t align with newer MariaDB versions. For references @dkayiwa shared a solution here GSOC 2025: Replacing OpenMRS Standalone with a Modern, User-Friendly Alternative - Updates and Discussion - #10 by dkayiwa. From which later I recommended the approach to ensure proper JDBC configuration, as described in this discussion: Support MariaDB JDBC URL and MariaDB driver

I hope this sheds light on the root cause and the fix!

[dkayiwa (Daniel Kayiwa)]

@jonathan

I modified these to include dbms="mysql,mariadb" so that they apply cleanly regardless of whether MySQL or MariaDB is used.

Did you investigate why the changesets in openmrs-core run fine on mariadb even when they have dbms=“mysql” instead of dbms=“mariadb”?

[jonathan (Mutagubya Jonathan)]

@dkayiwa

Did you investigate why the changesets in openmrs-core run fine on mariadb even when they have dbms=“mysql” instead of dbms=“mariadb”?

Oh yes, I did investigate that.

One important thing to note is that changesets with dbms="mysql" (or other specific dbms attributes such as oracle) are actually skipped when Liquibase detects that the current dbms is MariaDB. This behavior shows up in the logs, for example:

[INFO] Marking ChangeSet: liquibase-update-to-latest.xml::201610042145-2.1::vshankar ran despite precondition failure due to onFail='MARK_RAN': 
          liquibase-update-to-latest-from-1.9.x.xml : DBMS Precondition failed: expected mysql, got mariadb
          liquibase-update-to-latest-from-1.9.x.xml : DBMS Precondition failed: expected oracle, got mariadb

This means that Liquibase recognizes that the dbms attribute is set to mysql, but since the runtime DBMS is MariaDB, the precondition fails and—depending on the onFail behavior (like MARK_RAN)—the changeset is skipped or marked as executed without being run. as can be seen here Quote from “Preconditions”