Setting up an instance of O3

This guide is intended for developers who want to set up an instance of O3. Broadly speaking, there are two approaches for setting up an instance of O3:

• Using the OpenMRS SDK
• Using Docker

Using the OpenMRS SDK

Prerequisites

These prerequisites are explained in detail in the SDK wiki .

• Ensure you have Apache Maven  installed.

• Ensure you have a MySQL or MariaDB instance supported by the O3 distribution you choose.

• Use a current LTS JDK supported by that distribution. The current Reference Application Dockerfile builds and runs on Amazon Corretto 21, so Java 21 is the safest starting point for current O3 work.

• Ensure that your $JAVA_HOME environment variable is set and that it points to the JDK you want the SDK to use. If you have the correct version of Java installed but $JAVA_HOME doesn’t point to it, you could try adding the following alias to your .zshrc file (or .bashrc file if you’re using Bash):

    alias mvn='JAVA_HOME="$(/usr/libexec/java_home -v 21)" mvn'

mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:setup-sdk

mvn openmrs-sdk:setup

mvn openmrs-sdk:run

Troubleshooting the SDK approach

• If you’re running into issues, first ensure that Maven, the OpenMRS SDK, Java, and your database version match the O3 distribution you selected.

Using Docker

Prerequisites

• Ensure you have Docker Desktop  or Docker Compose (v2)  installed on your machine.

Use the following steps to set up a fresh instance of O3 on your machine using Docker:

docker compose -f docker-compose.yml up -d

git fetch --tags
git tag --sort=-v:refname | head
TAG=<release-tag> docker compose -f docker-compose.yml up -d

curl -f http://localhost/openmrs/health/started

while [[ "$(curl -s -o /dev/null -w '%{http_code}' http://localhost/openmrs/health/started)" != "200" ]]; do sleep 10; done

Running an O3 Docker image on top of an existing database

To run the O3 Docker image on top of an existing database, do the following:

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"
    environment:
      OMRS_CONFIG_MODULE_WEB_ADMIN: "true"
      OMRS_CONFIG_AUTO_UPDATE_DATABASE: "true"
      OMRS_CONFIG_CREATE_TABLES: "true"
      OMRS_CONFIG_CONNECTION_SERVER: host.docker.internal
      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
 
volumes:
  openmrs-data: ~

Troubleshooting the Docker approach

• If you’re running into issues related to the Docker daemon, make sure that the daemon is running correctly.

• If you’re running into an issue on Windows about your WSL version being too low to support running the dockerized build, follow the directions in the error message to update your WSL version. Once done, make sure to restart Docker Desktop or the Docker daemon.

• If you’re encountering permission errors after running docker compose up, you might be dealing with orphaned volumes left by a previous Docker Compose run. This is a known issue with Docker volumes. Run the following command to delete all orphaned volumes:

  docker compose down -v --remove-orphans

  This command:

  • Stops the running containers defined in the Docker compose file.
  • Removes the containers.
  • Deletes the networks created by the Docker compose.
  • Deletes the volumes associated with the containers.
  • Removes any orphaned containers (containers that were not defined in the docker-compose.yml but are part of the Docker Compose project).

Updating metadata

Based on your requirements, you might want to customize configurations and metadata like concepts, visit types, encounter types, locations, etc. that gets loaded by the initializer module. When customizing such metadata, build the Docker image locally and use that local image for the changes to be shown in the instance. The reference application repository includes docker-compose.override.yml, which adds local build contexts for the gateway, frontend, and backend services when you run Compose from the cloned source tree.

Step 1: Stop your instance

If your O3 instance is actively running, bring it down by running:

docker compose down

This command stops the current containers without the deletion of your volumes, ensuring the retention of your data.

Step 2: Build the local Docker image

To reflect the updated metadata in your instance, you’ll need to build a local Docker image. Ensure your configuration files follow the accepted conventions for each configuration , as incorrect formats might prevent the metadata from appearing in the instance as expected.

TAG=your-custom-tag docker compose build

Replace your-custom-tag with any unique tag of your choice.

Step 3: Run the instance with the updated image

Next, start your instance using the locally built image by running:

TAG=your-custom-tag docker compose -f docker-compose.yml up -d

Ensure that the argument passed to TAG variable matches the tag you used in the previous step. This command launches the instance using your locally built image instead of pulling one from Docker Hub.

Step 4: Wait for the instance to spin up

Finally, follow Step 4 of the setup guide and wait for your instance to fully spin up with the updated metadata.

Preparing for production

By default, the RefApp source tree is configured to build the frontend with next tagged versions of frontend modules  and the app shell . This means a local image build uses the latest pre-release packages available. Pre-release versions get published to NPM each time a commit is merged into the main branch, so they are not recommended for production use.

{
  "frontendModules": {
    "@openmrs/esm-active-visits-app": "x.y.z",
    "@openmrs/esm-appointments-app": "x.y.z"
    // ... other frontend modules
  }
}

  ...
  ARG APP_SHELL_VERSION=x.y.z
  ...

Next steps

Once you’ve set up your O3 instance, there are various things you might want to do, including:

• Setting up a TLS certificate for your instance. This is important if you’re planning to run your instance in production. You can use a service like Let’s Encrypt  to get a free TLS certificate.

• Changing the default language of your instance. You can do this by navigating to the Administration section of the legacy OpenMRS UI and changing the default locale.

• Customizing O3. You can tweak your branding, configure modules, and more. See the Configuration overview guide for details.

• Ensuring that your modules are working correctly (this is relevant only if you’re setting up O3 on top of an existing database). You can use the Manage modules page in the legacy admin interface to see whether modules are running correctly.

• Testing various features - try registering a patient and launching their chart. Look out for any console errors or any errors in the UI, You might also want to look out for errors in the browser’s devtools network tab. If you don’t have the fhir module running, you should expect to see problems with rendering the patient banner and most other widgets in the chart because things in the chart depend on a valid patient UUID being available, and the patient object gets fetched via a FHIR endpoint,

• Thinking about how to set up your forms in O3. New O3 forms are usually JSON form schemas that conform to this standard schema  and are rendered by the O3 React Form Engine. O3 can also render configured HTML Form Entry forms through the Patient Forms app, so conversion is only required when you want to move those forms to the JSON schema and Form Engine workflow. Check out the embedded form builder in O3 for an idea of what this format looks like. The schema editor can allow you to build a new form using a dummy schema scaffold. To learn more about forms in O3, read the Building forms using the O3 form builder recipe.

  ℹ️

  An OpenMRS module exists for converting HTML Form Entry schemas into JSON schemas compatible with the O3 standard schema at https://github.com/openmrs/hfe-o3-form-schema-converter . Currently, work is ongoing to improve the tool. Go through the repo’s README to learn what’s possible. See also the Convert HTML form entry forms to O3 guide.

Useful links

• OpenMRS SDK documentation 
• OpenMRS Docker documentation 
• O3 implementer documentation  (most of the content from this has been included in this guide)