/
O3 Setup, Configuration & Deployment

O3 Setup, Configuration & Deployment

Better O3 Documentation is Available

Please Note: Since this page was last created/updated, we have created a much better set of O3 Docs. Please see instead: O3 for Developers



This documentation is intended to enable administrators, implementers, and developers to set up and configure an OpenMRS Frontend 3.0 application (aka 3.x, aka O3). The O3 Project Overview is also helpful.

In This Guide: 

  • Once you've followed the steps in this Implementer Guide, you can also see the Developer Guide for more guidance on building with the 3.x tooling.
  • Github Logo - Free social media icons Looking for a repo? See the Dev Guide's Repositories You Should Know. 
  • Exclamation Question Mark Emoji Still confused? Try using the search bar in the Dev Guide to search for a key term:
  • If you still can't find what you need, please reach out to our 3.x squad on this slack channel: #openmrs-helpme We'd also love to hear from you any suggestions on how to improve this guide!

Orientation

Two Important Qualities of the OpenMRS 3 Frontend

The OpenMRS 3 Frontend has two important qualities:

  • It can be served independently of the OpenMRS server itself. It is just static files, and you can use any web server to serve them. They will communicate with the OpenMRS server via network requests (REST, FHIR, etc).
  • The frontend modules come together to form the application on the client's computer. This means that the modules can be served independently of the base frontend application.

What is a Frontend Module?

OpenMRS Frontend 3.0 uses frontend modules. A frontend module is a self-contained piece of application. It has some UI, and some ideas about where in the application it should be rendered. Each frontend module can be configured and some aspects of how frontend modules interact can be configured, too.

Important Pieces of the O3 frontend modules system 

There are four important pieces of the OpenMRS 3 frontend module system:

  • The app shell, which is the "base" of the application and coordinates everything
  • The framework, which is a shared library that all frontend modules use
  • The import map, which is a file that tells the app shell what frontend modules to use and where they are
  • The frontend modules, from which the interface is composed

Feeling confused about the pieces of 3.x?

A visual map of building a 3.x application is described in more detail in the Dev Guide's Map of the Project.

Each frontend module is an NPM package with a name ending in -app. Examples shown in the examples below: (Click to expand)


Quick Start Guide: Get O3 running on your machine quickly

You will need a good internet connection for these steps. 

1) Install Docker: You will first need to install a program called Docker Desktop on your machine (skip this step if you already have Docker Desktop installed - but double check that you have Docker Compose). Why? Docker will help handle some of the pesky technical tasks for you, like a chef in a kitchen helping you cook! We are trying to make your life easier by using this tool (smile) 

Tip: On Macs: Check that you can manually open the Docker app. You will need to agree to some permissions in order for your machine to finish the installation. 

2) Set up the recipe, the "Docker Compose File": The "docker compose" file is like your recipe for getting OpenMRS 3 onto your machine; and Docker is the chef that will do this for you. OpenMRS 3.x is a WIP, but to get the latest version of 3.x running on your machine, use this Docker Compose file. (This file will also share some documentation about the docker images.) Copy the docker-compose.yml file into a blank directory / empty folder on your own computer - eg put it into a directory/folder named "o3-docker-compose", and be sure to name the docker-compose.yml file as "docker-compose.yml".

Example of the contents of the O3 docker-compose.yml file copied into a user's own file in VS Code:

3) Time to get things running!

1. Go to the directory (folder) you created to hold the .yml file
LINUX:
$ cd /home/YOURUSERNAME/FOLDER/o3-docker-compose
WINDOWS: 
C:\Users\YOURUSERNAME\FOLDER\o3-docker-compose
MACS: 
% cd /Users/YOURUSERNAME/FOLDER/o3-docker-compose
2. Now run your .yml file by entering:
LINUX:
$ docker-compose up
WINDOWS:
> docker-compose up
MACS: 
% docker-compose up

You will start to see lots of lines / activity happening as docker, your chef, uses your docker-compose.yml file as the recipe for all the things it needs to build the EMR on your machine. 

You will know you were successful when you see lines like: frontend_1  | 127.0.0.1 - - [12/Oct/2022:00:51:59 +0000] "GET / HTTP/1.1" 301 169 "-" "curl/7.83.1"

Also check for success by opening your Docker Desktop app - if things have gone successfully, you should see these 4 containers (frontend, backend, gateway, and mariadb):