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

You might want to use the SDK if:

• You already have the SDK, Maven and a Java environment set up on your machine and are very familiar with these tools.
• You're not familiar with Docker or don't want to use Docker.

Prerequisites

These prerequisites are explained in detail in the SDK wiki (opens in a new tab).

• Ensure you have Apache Maven (opens in a new tab) installed.

• Ensure you have MySQL v5.6 and above installed and set up correctly.

• Ensure you have Java 8 installed with JDK 1.8 and JRE 1.8.

• Ensure that your $JAVA_HOME environment variable is set and that it points to v1.8 of Java. 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 1.8)" 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 you're running the prescribed dependency versions i.e. Java 8, MySQL 5.6 or greater, Maven 3, and the latest SDK version.

Using Docker

You might want to use Docker if:

• You are already familiar with Docker and OpenMRS Docker images.
• You don't want to use the SPA module.
• You're working on a deployment that will run Docker containers in production (generally cloud-based or SaaS offerings).
• You want to set up a fresh instance of O3 (i.e. an instance with a brand new database and not one set up on top of your existing database).
• You don't want to go through the hassle of setting up a Java environment and managing multiple dependencies.

Prerequisites

• Ensure you have Docker Desktop (opens in a new tab) installed on your machine.

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

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:

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:
      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: ${OPENMRS_DB_USER:-openmrs}
      OMRS_CONFIG_CONNECTION_PASSWORD: ${OPENMRS_DB_PASSWORD:-openmrs}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/openmrs"]
      timeout: 5s
    volumes:
      - openmrs-data:/openmrs/data
 
  # MariaDB
  db:
    image: mariadb:10.8.2
    restart: "unless-stopped"
    command: "mysqld --character-set-server=utf8 --collation-server=utf8_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: ~

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.

Next steps

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

• Customizing O3. You can tweak your branding, tweak your import map to add or remove widgets from your distribution, and more.

• 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. Forms in O3 are built using JSON and conform to this standard schema, If your existing forms were built using HTML Form Entry, you'll need to convert them into JSON schemas. 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 in O3 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 (opens in a new tab). Currently, work is ongoing to improve the tool. Go through the repo's README to learn what's possible.

Useful links

• OpenMRS SDK documentation (opens in a new tab)
• O3 implementator documentation (opens in a new tab) (most of the content from this has been included in this guide)