OpenMRS Core: Java EMR platform build and deployment

OpenMRS Core's role in healthcare record management

OpenMRS Core addresses a specific problem in clinical software: healthcare providers need an electronic medical record system that can be adapted to different workflows, data models, and deployment environments. The README describes OpenMRS as patient-based and customizable, with an emphasis on health care delivery in resource-constrained environments. The intended users are therefore not only Java developers. Hospitals, clinics, implementers, and technical teams working with clinical systems also need a platform that can be extended rather than treated as a closed application.

The repository is the core of that platform, not a standalone package intended for installation through a conventional package manager. Its top-level structure separates concerns such as `api/`, `web/`, `webapp/`, `liquibase/`, `tools/`, and test-related modules. The Maven build assembles these parts into an OpenMRS application packaged as a WAR. That packaging choice is important for adopters. It indicates a web application intended to run inside an application server rather than a command-line program or a narrowly scoped library.

The platform also supports extension through modules, which the README presents as the way to add functionality to OpenMRS. That makes the core repository a foundation for implementation work, not necessarily the whole clinical product. The documentation does not claim that every clinical workflow is included by default, and it does not provide a list of ready-made clinical modules. Teams evaluating it must account for configuration, extension, and integration work rather than assuming that the core repository is a complete hospital information system.

The OpenMRS Core module and deployment architecture

The repository layout provides the clearest view of the architecture. `api/` contains the API module, `web/` is the web layer, and `webapp/` produces the deployable application. The root `pom.xml` coordinates these modules, while `bom/` provides build dependency management and `liquibase/` sits alongside the application modules. The build output is documented as `webapp/target/openmrs.war`, which is the direct deployment artifact for Tomcat, Jetty, or another compatible application-server environment.

The documented development flow separates compilation from local serving. Maven packages the application, then a developer can launch Jetty from the `webapp` directory. The Compose configuration adds a database service using `mariadb:10.11.7`. It passes database-related environment variables to the OpenMRS service, including `OMRS_DB`, `OMRS_DB_HOSTNAME`, `OMRS_DB_NAME`, `OMRS_DB_USERNAME`, and `OMRS_DB_PASSWORD`. The service definition maps port `8080` on the container to port `8080` on the host and uses a persistent `db-data` volume for the MariaDB data directory.

That structure is more than a single-process Java application. A local Jetty command uses an embedded development server, while the production Compose file is described as first building a development image and then an image containing Tomcat and `openmrs.war`. This separation suggests that development convenience and production packaging are different concerns. It also means database availability, environment configuration, and the selected runtime must be considered together before installation.

Building OpenMRS Core from the master branch

The README says that building the `master` branch requires a Java JDK with a minimum version of 8. It also requires Maven and Git. The repository includes an `mvnw` wrapper, so the documented build does not require selecting a system Maven executable for the build command itself. First confirm that Maven is using the JDK required by the branch. The documentation specifically gives this check:

mvn -version

The output should identify the Maven version and the Java runtime Maven is configured to use. Clone the repository, then build it from the project directory:

git clone https://github.com/openmrs/openmrs-core.git
cd openmrs-core
./mvnw clean package

The build should generate `webapp/target/openmrs.war`. The README does not specify a complete first-login procedure, database initialization command, or application configuration sequence for that WAR, so those steps must be taken from the linked developer documentation rather than inferred. The repository includes files related to startup and database initialization, but the excerpt does not establish a complete operational sequence for them.

This build command is a real first use in a development sense because it produces the deployable application, but it is not the same as installing a finished production system. The expected result is a Maven package output, not a hosted URL. A user who needs a hosted OpenMRS service would need a deployment target and configuration beyond the README's basic build instructions.

Jetty and Cargo development startup

For development purposes, the README says to run the application from the `webapp` directory with Jetty. The default command is:

cd openmrs-core/webapp
../mvnw jetty:run

If Jetty starts correctly, the README says to check the console output and then access `localhost:8080/openmrs`. That address is the documented development endpoint, not a claim that every configuration will be ready without database setup.

A custom port is supported through the `jetty.http.port` property. The exact documented command is:

../mvnw -Djetty.http.port=8081 jetty:run

The README also documents Cargo as an alternative runtime. Its command is:

../mvnw cargo:run

Cargo can also use a custom `cargo.servlet.port` property:

../mvnw -Dcargo.servlet.port=8081 cargo:run

Jetty and Cargo are development options, not evidence that OpenMRS Core is a lightweight standalone binary. The database layer still exists in the broader deployment setup. The README's own Docker instructions also warn that code changes currently require a full container restart and rebuild, and that Spring Boot auto-reload support is not yet documented. That limitation can slow an edit-and-preview loop even when the application itself is otherwise conventional.

Docker Compose configuration for OpenMRS Core

Docker support is described as a work in progress, so it should be treated as a documented development and packaging path rather than a fully settled installation system. The README identifies Docker as the only prerequisite for the Compose build. The basic development image command is:

docker compose build

By default, the Compose build calls `mvn install`. The documentation allows Maven build arguments to be changed through `MVN_ARGS`. For example:

docker compose build --build-arg MVN_ARGS='install -DskipTests'

Skipping tests changes the build process, so it should be an explicit choice rather than a default assumption for release validation. The development Compose service is then started with:

docker compose up

For the production-oriented Compose file, the documented commands are:

docker compose -f docker-compose.yml build
docker compose -f docker-compose.yml up

The README describes this path as building a development image first and then an image with Tomcat and `openmrs.war`, without development dependencies. It also documents running an available published tag:

TAG=nightly docker compose -f docker-compose.yml up

The Compose file shows a MariaDB service with a persistent volume and explicit OpenMRS database environment variables. It also exposes port `8080`. For debugging, the README says to connect a debugger to port `8000`, which is exposed by default in the development setup. Since the README says code changes require a full restart and rebuild, Compose is more suitable for repeatable builds and environment reproduction than for fast hot reload.

Extension boundaries and deployment trade-offs

OpenMRS Core's module system is a central adoption feature because the README explicitly presents extension as the intended way to add functionality. For teams with domain-specific workflows, that can be more useful than a closed EMR interface. The repository includes `api/`, `web/`, and `webapp/` as distinct modules, which also gives implementers places to work when adding an API, web behavior, or deployment integration.

The trade-off is that customization carries responsibility. The README does not provide a list of supported clinical workflows, a compatibility matrix for every module, or a simple upgrade procedure. It does not document rollback behavior. The repository contains a `liquibase/` directory and startup-related files, but the excerpt does not explain how database migrations should be reviewed, reversed, or coordinated with a custom implementation. That omission matters because an EMR deployment involves persistent clinical data as well as application code.

The Docker documentation also exposes a practical limitation: changes require a full restart and rebuild, and Spring Boot auto-reload is not yet available as a documented feature. A team that expects a conventional hot-reload development loop may find the documented workflow slower than expected. A team that expects to deploy only a single JAR without thinking about a database and application server is also looking at the wrong shape of tool.

Compared with a hosted clinical platform or a small standalone service, OpenMRS Core offers more control over the application and its extensions. In return, it requires Java and Maven expertise, a deployment runtime, database configuration, and decisions about data migration. That is a different approach from accepting a managed clinical environment whose infrastructure responsibilities sit outside the application repository.

Maintenance, releases, and licensing boundaries

The repository is not archived, and the last push was on 2026-10-14. Recent releases include `2.8.10` on 2026-10-06, `2.7.6` on 2025-09-12, and `2.8.0` on 2025-08-15. These facts show recent repository activity and published releases, but they do not by themselves establish compatibility, upgrade safety, or the cost of adapting a custom installation.

The repository identifies its license as a custom GitHub classification and points to the `LICENSE` file. Source headers visible in `docker-compose.yml` and the `Dockerfile` state that the code is subject to the Mozilla Public License, version 2.0, and also refer to the Healthcare Disclaimer at the OpenMRS license URL. The repository therefore has licensing information in multiple places, and adopters should read the actual `LICENSE` and `NOTICE.md` files for the scope of use, redistribution, attribution, and disclaimer terms. This review does not provide legal advice or infer a complete set of obligations from the short classification.

Upgrade planning is particularly project-specific because the application is packaged as a WAR and includes database-related modules. The README documents building and deployment commands, but it does not document a rollback procedure or a complete upgrade checklist. Before adopting a release, an implementation team should compare its modules and database migrations against the target release rather than treating the release number alone as an upgrade plan.

Editorial conclusion

Healthcare organizations and implementation teams should adopt OpenMRS Core when they need a patient-based EMR foundation and have Java, Maven, database, and application-server capacity available. Organizations seeking a small standalone service with little infrastructure should not choose this multi-module platform without first validating its deployment requirements. The first project-specific check is whether `./mvnw clean package` produces `webapp/target/openmrs.war` in the intended build environment.

Frequently asked questions

Official sources

1. Issues
2. openmrs/openmrs-core on GitHub
3. Project website
4. README
5. Releases