Locally running OpenMRS ESM Template App and backend

Software O3
,
1

Dear Team, I am new to OpenMRS 3 and trying to learn by following Intro to OpenMRS 3: For Developers and Technical Teams In below video , https://openmrs.org/academy/intro-to-openmrs-3/lesson/o3-frontend-development-live-coding-session-hello-world-in-10-mins/ I ran OpenMRS ESM Template App locally (not used gitpod) cloned the repository and cd to it then yarn and yarn start and i can open the app in browser http://localhost:8080/openmrs/spa/home# Now question is where and by which command the openmrs back-end is running ? little bit confused as i also watched other videos like setting up O3 with Docker and SDK and here i see that no need for setup. I am sure that i am missing some basic fundamental here, any hint reference to understand same? I also see in some videos , regarding Implementer tool by which we can do changes using same and could load the config to apply it to persist. What are the use-case of these two scenarios Implementer Tools and through “OpenMRS ESM Template App” way? One last question, when we run O3 by using GitHub - openmrs/openmrs-distro-referenceapplication: The reference distribution of the OpenMRS EMR application (v3) , which repository it uses to build frontend ? is OpenMRS ESM Template ?

Thanks in advance

2

Hey @horaira, sorry for the very late reply. For posterity, here’s a quick explainer on what those things are:

Understanding OpenMRS 3 Development: Backend vs Frontend

When you run yarn start in the Template app, you’re only running the frontend - but it works because the OpenMRS CLI automatically configures your development server to proxy API requests to OpenMRS - Home .

What is the Template App?

The Template app is a starter template for creating new OpenMRS frontend modules (or “apps”). Think of it like a “Hello World” project template.

What it provides:

  • Pre-configured build tools and dependencies
  • Basic React component structure
  • OpenMRS integration patterns and examples
  • Development server setup with API proxy configuration

Use it for:

  • Learning OpenMRS 3 frontend development
  • Building new features (patient widgets, forms, reports, etc.)
  • Creating custom modules for specific implementation needs
  • Prototyping before contributing to existing apps

Real-world examples: If you need a custom lab results widget or a specific patient registration form, you’d start with the Template app.

Scenario 1: Developing Individual Modules (Template app)

What happens when you run yarn start:

  • Starts a local frontend development server (port 8080)
  • Proxies all /openmrs/ws/rest/* API calls to OpenMRS - Home
  • Your browser loads the frontend locally but data comes from the remote server

To connect to different backends:

# Proxy API calls to your local Docker backend
yarn start --backend=http://localhost:8080/openmrs

# Proxy API calls to QA environment
yarn start --backend=https://test3.openmrs.org/openmrs

Use this for: Building new features, learning, testing individual modules

Scenario 2: Running Complete OpenMRS (Reference Distribution)

What happens when you run docker compose up or mvn openmrs-sdk:run:

  • Starts local backend server (OpenMRS Core)
  • Starts local database (MariaDB)
  • Builds complete frontend from 40+ modules
  • Everything runs on your machine at http://localhost

Use this for: Production-like testing, implementing for real clinics

Key Difference: Individual vs Complete

ESM Template (yarn start) Reference Distro (docker compose or OpenMRS SDK)
Develop one module at a time Run complete OpenMRS system
Proxies API calls to remote backend Uses local backend + database
Fast development cycle Slower, production-like
Good for learning & building Good for implementation & testing

Implementer Tools: Tweak configuration properties on the fly

What it does: Lets you customize OpenMRS through a web interface or the embedded JSON editor

Two ways to make changes:

  1. Temporary changes (lost when browser clears):

    • Use Implementer Tools UI in your browser
    • Changes saved to browser storage only

  2. Permanent changes (survive restarts):

    • Edit config-core_demo.json file in your distro
    • Or submit code changes to individual modules

Use this for: Customizing layouts, hiding features, changing workflows.

Read more about the Implementer tools and configuring O3 here.

Quick Start Recommendations

  • If you’re learning or building custom features: Start with the Template app + yarn start
  • If you’re implementing or testing complete system: Use the Reference Distribution + docker compose up or openmrs-sdk:run

Read more about this here.

3 Likes