From recent setup and upgrade experiences, one recurring challenge is that new implementers can easily feel pushed toward developer tooling such as the OpenMRS SDK, Maven, building backend modules, or building frontend ESMs locally (Here is an example from talk: My Experience and Beginner’s Guide: Setting Up OpenMRS Core and O3 Frontend from Scratch - Community - OpenMRS Talk). While these tools are very useful for developers, they can be a barrier for implementers whose goal is simply to install, configure, upgrade, and run a working O3 instance. The current developer-oriented documentation is valuable, but a simpler implementer-first path would make OpenMRS 3 easier to adopt for new teams, especially those coming from OpenMRS 2 or those evaluating O3 for the first time.
We would like to suggest improvements to the OpenMRS 3 documentation, that differentiates OpenMRS 3 set up from scratch or upgrade from an existing version, without needing to do active development. It will be helpful to have clearly separated documentation paths for implementers such as:
- Set up OpenMRS 3 from scratch as an implementer, without the need to write code
- Upgrade your instance to OpenMRS 3 as an implementer, without the need to write code
These guides could focus on using released artifacts and configuration that are versioned and tested for compatibility rather than local builds. For example, they could explain:
- How to deploy an instance from a released O3 distribution or Docker-based setup
- How to install OpenMRS 3 from scratch using released backend and frontend components
- How to upgrade from OpenMRS 2.x or earlier O3 versions to the latest O3 release
- Which backend modules are required, and where to get their released .omod files
- Which frontend modules / ESMs are required and compatible with the target platform version, and how they are loaded without building them locally
- How to configure the frontend using configuration files, import maps, environment variables, or distribution configuration
- How to add or remove released apps/features without cloning repositories
- How to verify that the backend, frontend, modules, and ESMs are compatible and correctly connected
- Which metadata is critical to ensure the instance load and function as expected/without errors.
- A troubleshooting section for common setup and upgrade errors faced by implementers
- A clear point at which the implementer should switch to developer documentation if they want to customize code
Making a distinction in the documentation between the following audiences could help improve the installation and upgrade processes:
- Implementers, who want to install, configure, and upgrade OpenMRS 3
- System administrators / DevOps teams, who want to deploy and maintain it
- Developers, who want to build modules, ESMs, or contribute code