How to Build Your Own Medical Records System on Your Computer: A Super Simple Guide for Doctors (No Tech Skills Needed!)

mark_fernando · October 23, 2025, 10:15am

How to Build Your Own Medical Records System on Your Computer

A Super Simple Guide for Doctors (No Tech Skills Needed!)

By Dr Mark Fernando, Dr. Bernard Fernando, Dr. Dilushi Wijayaratne

October 23, 2025

Introduction

By the end of this guide, you will have:

Your own medical records system running on your laptop.
A system for tracking dialysis patients (or any patients!)
Something you can customize for YOUR clinic.
A FREE system and yours forever.

Why I Made This Guide

I am a medical doctor and a member of a research team working on the management of Chronic Kidney Disease (CKD) in Sri Lanka. I needed an inexpensive way to monitor and follow up renal patients who come to our institution. While looking for such solutions, I got to know openMRS and openEHR. I selected openMRS over openEHR because openMRS is currently used in Sri Lanka in healthcare. Even though there are so many documents about openMRS and working examples of open MRS systems, it is not possible to understand the openMRS system in a useful way unless you try it for yourself. So, my initial goal was to build a minimal system on my laptop to explore this system.

I have managed to install openMRS reference application on my laptop. The goal of this article is to write a stepwise guide for clinicians with little to no computer knowledge on how to create an open MRS Based system on your PC. My secret weapon was…No surprise.. AI Agents. This article concludes with insights from Health Informatics expert Dr. Bernard Fernando and Consultant Nephrologist Dr. Dilushi Wijayaratne on Health Informatics, AI, and the need for EMR in public healthcare, especially in Low- and Middle-Income Countries (LMIC).

While AI has simplified the learning curve, it has not achieved true autonomy—it is a powerful assistant, not a replacement for human judgment. Use it to build smarter systems but always validate and test thoroughly before deployment.

For vibe coders: this file serves as your system prompt—simply upload it to your AI agent and let it guide your build.

Basics

OpenMRS- You have a huge collection of medical forms, patient files, and data sheets. OpenMRS is like a magic filing cabinet that: Organizes all your patient information, lets you search instantly (“Show me all patients with diabetes”), Creates custom forms for YOUR specialty, Best part? It is used in 60+ countries, so it is proven and reliable.
What is Docker? A self-contained ‘lunch box’ without which installing software is like trying to assemble a complex toy that needs: Specific batteries (database), Special tools (Java, Tomcat), and Exact instructions (configuration files). If ONE thing is wrong, nothing works.
What is PowerShell? Way of talking to your computer instead of pointing. You type what you want, and the computer does it.

What You Need (Shopping List)

A Computer
- Minimum: 8GB RAM (check: Right-click “This PC” → Properties)
- Better: 16GB RAM
- Operating System: Windows 10 or 11
Internet Connection- You’ll download about 1GB of files (one-time)
Time- First time: 2-3 hours (mostly waiting for downloads), After that: 5 minutes to start the system.
Patience- Things might not work on first try, That’s NORMAL - even for programmers! This guide has solutions for every problem I hit

Step 1: Install Docker (The Lunchbox System)

Download Docker Desktop

Do this:

Open your web browser
Go to: Docker Desktop: The #1 Containerization Tool for Developers | Docker
Click the big blue button: “Download for Windows.”
Wait (it is about 500MB - like one short movie).

Install Docker

Find the downloaded file (probably in the “Downloads” folder)
Double-click it (like installing any program)
Click “OK” to everything (accept all defaults)
Important: When it asks about “WSL 2” → Click YES

What’s WSL 2? Do not worry about it - just say yes! – WSL is Windows Subsystem for Linux. It is a component in Microsoft Windows that allows the use of a Linux environment in Windows.

When done, click “Restart Computer”

Open Docker Desktop

After restart:

Press the Windows key
Type “Docker”
Click “Docker Desktop”
Wait for a green message: “Docker Desktop is running.”

Step 2: Check If Docker Works - We need to make sure Docker is working before we continue.

Open PowerShell
Press Windows key
Type “PowerShell”
Click “Windows PowerShell”
A blue window with text appears - this is PowerShell!
Test Docker
- Copy this text EXACTLY (including spacing): docker --version
- Then press Enter
- What you should see: Docker version 28.5.1, build e180ab8
- The number might be different - that is okay!
- If you see this → Docker is working!
- If you see an error → Docker did not install correctly. Try:
Restart computer again
Open Docker Desktop first
Wait for green “running” message
Try the test again

Step 3: Create Your Project Folder

Choose Your Location I recommend: G:\Your Research Folder\OpenMRS-Dialysis-Registry
Change this to YOUR preferred location! For example:
- C:\Medical Research\OpenMRS
- D:\My Projects\Dialysis Registry
- G:\Research\Patient System
Create the Folders- In PowerShell, copy ALL of this (change the path to yours):

# Set your project path
$ProjectPath = "G:\Your Research Folder\OpenMRS-Dialysis-Registry"

# Create main folder
New-Item -Path $ProjectPath -ItemType Directory -Force

# Go to that folder
cd $ProjectPath

# Create subfolders
New-Item -Path "openmrs\modules" -ItemType Directory -Force
New-Item -Path "mysql-init" -ItemType Directory -Force
New-Item -Path "backups" -ItemType Directory -Force

Press Enter
What is happening?

Line 1: “Hey computer, remember this folder path” Line 2: “Make that folder” Line 3: “Go inside that folder” Lines 4-6: “Make some organizing folders inside”

Like this:

OpenMRS-Dialysis-Registry (main folder)
  openmrs
    modules (will hold add-ons)
  mysql-init (database stuff)
  backups (safety copies)

Step 4: Create Password File - Your system needs passwords to keep patient data safe.

Create .env File Copy this into PowerShell:

@"
# Database Configuration
MYSQL_ROOT_PASSWORD=MySecretPassword2024!
MYSQL_DATABASE=openmrs
MYSQL_USER=openmrs_user
MYSQL_PASSWORD=OpenMRS2024!
"@ | Out-File -FilePath .env -Encoding utf8

Press Enter
IMPORTANT: Change the passwords!

Change MySecretPassword2024! to YOUR password Change OpenMRS2024! to ANOTHER password Make them strong (numbers, letters, symbols)

What is this file? Think of it like a locked safe. The passwords you create here will be used to protect your patient database. Only you will know these passwords! Security tip: Write these passwords in a safe place - you will need them if something goes awry

Step 5: Create Configuration File

Create docker-compose.yml- Copy ALL of this into PowerShell (scroll down - it is long!):

version: '3.8'

services:
  mysql:
    image: mysql:5.7
    container_name: renal-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --max_allowed_packet=256M
      - --innodb_buffer_pool_size=1G
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  openmrs:
    image: openmrs/openmrs-reference-application-distro:2.12.0
    container_name: renal-openmrs
    restart: unless-stopped
    environment:
      DB_HOST: mysql
      DB_PORT: 3306
      DB_DATABASE: ${MYSQL_DATABASE}
      DB_USERNAME: ${MYSQL_USER}
      DB_PASSWORD: ${MYSQL_PASSWORD}
      DB_AUTO_UPDATE: "true"
      DB_CREATE_TABLES: "true"
    ports:
      - "8080:8080"
    depends_on:
      mysql:
        condition: service_healthy
    volumes:
      - openmrs_data:/openmrs/data

  adminer:
    image: adminer:latest
    container_name: renal-adminer
    restart: unless-stopped
    ports:
      - "8081:8080"
    environment:
      ADMINER_DEFAULT_SERVER: mysql

volumes:
  mysql_data:
  openmrs_data:

Press Enter
Good news! Notice we are using ${MYSQL_ROOT_PASSWORD} instead of typing passwords here. Docker Compose automatically reads these from the .env file you created in Step 4. You only need to set passwords ONCE (in Step 4)!
What did this do? You just created a recipe card that tells Docker:
1. Download MySQL (the filing cabinet for patient data)
2. Download OpenMRS (the medical records system)
3. Download Adminer (a tool to peek inside the database)
4. Connect them all together
5. Start them automatically

Step 6: Download the User Interface

Download Legacy UI Module

Write-Host "Downloading the user interface..." -ForegroundColor Yellow

Invoke-WebRequest -Uri "https://addons.openmrs.org/api/v1/addon/org.openmrs.module.legacyui/1.13.0/download" -OutFile "openmrs\modules\legacyui-1.13.0.omod" -UserAgent "Mozilla/5.0"

Write-Host "Done! Checking file size..." -ForegroundColor Green

Get-ChildItem "openmrs\modules\legacyui-1.13.0.omod" | Select-Object Name, @{Name="Size(MB)";Expression={[math]::Round($_.Length/1MB, 2)}}

Press Enter and wait (takes 30 seconds). What you should see:

Name                     Size(MB)
----                     --------
legacyui-1.13.0.omod     3.78

If you see 3.78 MB → Perfect!

If you see 0.37 MB or less → Download failed. Try again with better internet.

What is this file? This is the “user interface” - the screens, buttons, and forms you will click on to use OpenMRS. Without this file, you would only see a blank page!

Step 7: Start OpenMRS!

Copy this into PowerShell: docker compose up -d
Press Enter
What Happens Now (Be Patient!). First time ONLY: Docker downloads everything needed (~1GB) You’ll see messages like:

[+] Pulling mysql (mysql:5.7)
[+] Pulling openmrs (openmrs/...)
[+] Pulling adminer (adminer:latest)

This is like: Going to the store to buy all ingredients before cooking. First time takes long, but you only do it once!

Time: 5-10 minutes (depends on internet speed)

When it is done, you will see:

[+] Running 3/3
Container renal-mysql     Healthy
Container renal-adminer   Started
Container renal-openmrs   Started

All three say “Started” or “Healthy”? → Perfect!

Step 8: Watch OpenMRS Wake Up

Check the Startup Copy this: docker compose logs -f openmrs
Press Enter
What you will see: Lots of scrolling text

Do not panic - this is normal! OpenMRS is:

Checking the database
Loading medical dictionaries
Setting up forms
Starting the web server

Wait for THIS message: INFO: Server startup in 79501 ms

The number will be different - that is fine!

When you see “Server startup” → OpenMRS is ready!
Press Ctrl+C to stop watching logs (OpenMRS keeps running!)

Step 9: Install the User Interface (Critical!) - Copy UI Into OpenMRS

Copy each line, press Enter, wait for it to finish:

# Remove any old files
docker exec renal-openmrs rm -rf /usr/local/tomcat/.OpenMRS/modules/*

# Copy the UI file we downloaded
docker cp "openmrs\modules\legacyui-1.13.0.omod" renal-openmrs:/usr/local/tomcat/.OpenMRS/modules/

You should see: Successfully copied 3.96MB to renal-openmrs:/usr/local/tomcat/.OpenMRS/modules/
Verify It is There

docker exec renal-openmrs ls -lh /usr/local/tomcat/.OpenMRS/modules/

You should see: A file called legacyui-1.13.0.omod with size 3.8M

Step 10: Restart OpenMRS

Restart Copy this:

docker compose restart openmrs

Press Enter and wait (30 seconds)

Watch It Start Again

docker compose logs -f openmrs

Wait for: INFO: Server startup in XXXX ms
Press Ctrl+C when you see it

Step 11: Open OpenMRS in Your Browser!

Open Your Web Browser Type this EXACT address: http://localhost:8080/openmrs/login.htm
What You Should See A page with:

Login at the top Username: box Password: box Location for this session: dropdown menu

Step 12: Login for the First Time

Enter Your Credentials

Username: admin
Password: Admin123
Location: Click dropdown, select “Registration Desk”

Click “Login”
What You’ll See After Login

The OpenMRS home page! You will see:

Your name (admin) at the top

Menus like “Administration”, “Find Patient”, etc. A clean, simple interface

Congratulations! You now have a working medical records system on your computer!

What Can You Do Now?

Immediate Next Steps
1. Click around and explore - you cannot break anything!
2. Try creating a test patient
  - Click “Register a Patient”
  - Fill in fake information See how the system works
3. Look at the menus:
4. Administration → System settings
5. Concept Dictionary → Medical terms (we will add dialysis terms here!)
6. Forms → Create custom patient forms
7. Building Your Dialysis Registry (Next Article!)

Step 13: Troubleshooting (Problems I Hit)

Problem 1: “Docker is not running”

You will see: Error messages mentioning “daemon” or “Docker Desktop”

Solution:

Open Docker Desktop (from Start menu)
Wait for green “Docker Desktop is running”
Try your command again

Why? Docker Desktop must be open before running commands - like how you must turn on your TV before changing channels!

Problem 2: “Port 8080 is already in use”

You will see: Error saying “address already in use”

What this means: Something else on your computer is using the same “door” (port) that OpenMRS wants to use.

Solution:

# See what is using port 8080
netstat -ano | findstr :8080

# Stop it
docker compose down

# Start again
docker compose up -d

Why? Only ONE program can use a port at a time. It is like a phone line - only one call at a time!

Problem 3: “Username or password is incorrect”

Default credentials:

Username: admin Password: Admin123

Case sensitive! Must be exactly: Admin123 (capital A, capital M, lower 123)

Problem 4: Downloaded file is too small (0.37 MB)

This happened to me! The download did not work properly.

Solution:

# Delete bad file
Remove-Item "openmrs\modules\legacyui-1.13.0.omod" -Force

# Download again (sometimes internet hiccups happen!)
Invoke-WebRequest -Uri "https://addons.openmrs.org/api/v1/addon/org.openmrs.module.legacyui/1.13.0/download" -OutFile "openmrs\modules\legacyui-1.13.0.omod" -UserAgent "Mozilla/5.0"

The file MUST be 3.78 MB! If it is smaller, download failed.

Step 14: Daily Use (Starting and Stopping)

How to Start OpenMRS (Every Day)

Simple version:

Open Docker Desktop (wait for green “running”)
Open PowerShell
Navigate to your project: cd "G:\Your Research Folder\OpenMRS-Dialysis-Registry"
Start OpenMRS: docker compose up -d
Wait 2-3 minutes
Open browser: http://localhost:8080/openmrs/login.htm
How to Stop OpenMRS (End of Day):

cd "G:\Your Research Folder\OpenMRS-Dialysis-Registry"
docker compose down

Why stop it? Saves computer resources (RAM, battery). Your data is saved - do not worry!

Step 15: Backing Up Your Data (IMPORTANT!)

Imagine: You spent weeks entering patient data. Your computer crashes. Without backups, it is ALL GONE! Solution: Regular backups! (Like saving your Word documents)
How to Back Up

cd "G:\Your Research Folder\OpenMRS-Dialysis-Registry"
docker compose exec mysql mysqldump -u root -p'MySecretPassword2024!' openmrs > backups/backup-$(Get-Date -Format "yyyyMMdd").sql

Replace MySecretPassword2024! with YOUR password from Step 4!

What this does: Creates a copy of your entire database in the backups folder. Each backup is dated (like backup20251019.sql).

Step 16: Help from the Community

The community is friendly! They love helping healthcare workers.

What I Wish I Knew Earlier:

Docker makes everything easier - Don’t try to install OpenMRS directly on Windows.
The UI module is separate - Not obvious from documentation!
File paths matter - Module must be in EXACT right location.
The URL must include /login.htm - Not documented anywhere clearly!
Log files have answers - When stuck, check logs first.
Download file sizes matter - Small files (377 bytes) are HTML errors
Community helps - Don’t suffer alone, ask questions!

Checklist:

Before you start:

Computer has 8GB+ RAM.
Windows 10 or 11
Good internet connection
2-3 hours available

Installation:

Docker Desktop installed
Docker Desktop shows “running” (green)
docker --version works in PowerShell.
Project folder created
.env file created (with YOUR passwords!)
docker-compose.yml file created (with matching passwords!)
Legacy UI module downloaded (3.78 MB - check size!)

Launching:

docker compose up -d ran successfully.
Waited for “Server startup” message.
Copied UI module to container.
Restarted OpenMRS
Can access http://localhost:8080/openmrs/login.htm
Can login with admin/Admin123?

System prompt to Vibe code

You are helping a healthcare professional with zero coding experience set up OpenMRS using Docker on Windows.

CONTEXT:

User: Clinician with no IT background
Goal: Create a working OpenMRS-based patient registry
Environment: Windows 10/11, PowerShell, Docker Desktop
Stack: Docker Compose, MySQL 5.7, OpenMRS Reference Application 2.12.0, Adminer

CONSTRAINTS:

Explain technical concepts using simple analogies
Provide complete, copy-paste ready commands
Always specify which tool to use (PowerShell, browser, Docker Desktop)
Include exact file paths and syntax
Verify each step before proceeding
Troubleshoot errors with step-by-step solutions

KEY TECHNOLOGIES:

Docker: Container platform (isolated environments)
PowerShell: Windows command-line interface
docker-compose.yml: Configuration file defining services
.env: Password storage file
MySQL: Database for patient data
OpenMRS: Electronic medical records system
Adminer: Database viewer tool

COMMON ISSUES:

Port conflicts (8080, 3306)
Module download failures (check file size)
Container startup delays (wait for “Server startup” message)
Password mismatches between .env and docker-compose.yml

Always provide exact commands, explain what each step does in plain language, and confirm success before moving forward.

Final Pep Talk

You might feel:

“This is too technical for me.”

“I’ll mess something up.”

“I should just pay someone.”

But here is the truth:

This guide has EVERY step (nothing assumed) You CAN’T break your computer (Docker is isolated) Learning this saves you money and gives you control.

Reflections on Building an Electronic Patient Record in the Age of AI - Dr. Bernard Fernando

The holy grail of health informatics was once the creation of a perfect Electronic Medical Record (EMR). In those days, systems were usually standalone, and interoperability was added later as an afterthought. Building such systems was never easy: it required a sound knowledge of relational databases, operating systems, user interface design, and, of course, the ability to code the operational logic in a suitable programming language.

The situation has changed dramatically in recent years, and the pace of change has been astonishing. Today, one can simply describe what is needed to an AI agent, such as ChatGPT or Claude, and it will provide clear, step-by-step instructions to build a system. Gone are the days when we had to spend countless hours searching the web for code snippets — that was our reality until quite recently.

This shift has lowered the barriers to entry in a remarkable way. The success in setting up OpenMRS using Docker, guided by AI, is an excellent example. Although Dr. Mark has a medical degree rather than formal training in computer science or health informatics, he has achieved something that, in my day, would have required a multidisciplinary team and months of effort. It is a powerful illustration of how accessible these technologies have now become to motivated clinicians.

We are therefore in a far better position to build EMRs quickly, but we must remain cautious. AI agents can generate plausible answers that are not always correct. Errors can creep in silently, so systematic testing, validation, and quality assurance are essential. The new rhythm must be build, build — then evaluate, evaluate.

With the technical barriers reduced, we can now devote more time and energy to what really matters — thoughtful design. The key tasks ahead are to define and model clinical concepts, group them logically to match user interfaces, and design those interfaces to minimise the cognitive load on clinicians while aligning with real clinical workflows. Designing a system that reflects the patient’s journey — their past, present and future — remains a central challenge.

Given the rapidly changing technological landscape, EMRs must also be designed in a future-proof way, able to evolve with new standards, data structures, and technologies. Security, privacy, and ethical governance are equally critical. EMRs contain some of the most sensitive data imaginable, and ensuring their confidentiality, integrity, and compliance with frameworks such as GDPR is a fundamental responsibility.

At the same time, the open-source movement and AI tools now complement one another beautifully. Open-source platforms such as OpenMRS provide a trustworthy, community-tested foundation, while AI accelerates learning, prototyping and configuration. This combination offers immense potential for clinicians who wish to tailor digital systems to the needs of their patients and their local health services.

Yet, I do not believe AI agents can handle all these tasks independently. They can assist and accelerate, but not replace, sound human judgement. Building a safe and useful EMR still requires an understanding of health informatics, systems thinking, and computer science fundamentals. You cannot simply “vibe-code” an EMR!

It is both humbling and inspiring to see a new generation of doctors taking an active role in building the systems they use. If they combine technological curiosity with clinical insight and ethical awareness, the future of digital health will indeed be in good hands.

Electronic medical records: A dire need in renal medicine… and finally accessible to low resource settings? - Dr. Dilushi Wijayaratne

The specialty of nephrology is unique in that it covers patients from a variety of disease perspectives, with patients often shifting between these. The trajectory of a patient with progressive disease may be through early kidney disease, to intermediate disease, to end-stage kidney disease, requiring lifesaving dialysis, and then to kidney transplantation. During each of these stages the needs and risks a patient faces may be unique to that stage. As an example, a patient on dialysis may be at high risk of sudden death due to high serum potassium, or a kidney transplant recipient may be at risk of losing his/her kidney due to rejection if early changes in kidney function are missed. Smooth transitions in care as patients pass through these stages is important to improve outcomes. During each of these stages, patients may also have opportunities to improve outcomes, such as the administration of disease slowing treatments in early-stage disease or the early referral for creation of access for dialysis in patients who are going to progress to end-stage disease.

Apart from the heavy case burden, the ratio of specialists to population in Sri Lanka is low (approx. 1.6 per million population), making it extremely challenging to manage this diverse group of patients systematically and safely. Many patients are managed by junior doctors, under the supervision of consultants. Direct oversight is impossible, and lapses are inevitable.

An ideal renal EMR will incorporate patient clinical data, updatable treatment algorithms and alerts, referral pathways, the generation of individual and overall summary data for day-to-day management, and the generation of statistics for audit and quality control. A user-friendly a system with these capabilities can only be designed with the input of clinicians. In a low-resource setting funding, skills, time, and infrastructure to develop such systems is scarce, and despite a dire need, setting up such a system is extremely challenging.

However, in this new brave world where knowledge can be readily accessed using AI, we are now able to meet some of these challenges with minimal resources (i.e. a computer and an internet connection) and our greatest asset, a seeking mind. Indeed, in fewer than 4 months Dr Mark has gone from collecting data in to google sheets to developing the beginnings of an EMR.

While the input of specialists in Health Informatics remains indispensable, bringing the language of developing these systems into the vocabulary of clinicians, and making the tools of development more accessible, means we are able to create and refine systems that are better suited to our needs, and do this more quickly and efficiently.

Feedback Welcome!

This is my first OpenMRS implementation. I’d love to hear from you:

What worked well?
What challenges did you face?
How can I improve this guide?

Reply in this thread with questions

Or message me via OpenMRS Talk

I’m particularly interested in hearing from:

Other clinicians attempting their first implementation
Implementers in low-resource settings
Anyone adapting this for other specialties (cardiology, pediatrics, etc.)

Looking forward to your feedback and questions!

nethmi · October 24, 2025, 7:28am

Hello Dr. Mark, Dr. Bernard and Dr Dilushi! Very happy to see how you’ve set up OpenMRS, and thank you for sharing this very helpful guide with the community!

Sidenote - I noticed that you are setting up the legacy UI version of OpenMRS. Have you tried out the new version (O3) of OpenMRS? The development environment (contains the latest development changes and updates as soon as new changes are made) is accessible on dev3.openmrs.org and the latest stable environment is accessible on o3.openmrs.org. This is the guide on setting it up locally with Docker - https://openmrs.atlassian.net/wiki/spaces/docs/pages/150930190/Set+Up+an+Instance+of+O3#Using-Docker

mark_fernando · October 24, 2025, 10:22am

Thank you!!! @nethmi for you suggestions. I used the resources you suggested and created a system withing 10-15 mts with the help of AI. I am hoping to upload a simmilar step by step guide of the new O3 system in the near future.

mark_fernando · October 27, 2025, 12:10am

Appendix: Setting Up OpenMRS O3 (Version 3.x)

What is O3?

OpenMRS O3 is the next-generation version of OpenMRS with a modern, mobile-friendly interface. It’s the future of OpenMRS - all new development happens here.

Key Differences:

Modern React-based interface vs traditional menu system
Search-focused navigation vs menu-driven
Mobile-responsive design
JSON schema forms vs HTML forms

Note: O3 runs on a different port (8082) so it won’t conflict with the Legacy UI system you just installed (port 8080). You can run both simultaneously!

Quick Setup Steps

Prerequisites

If you already completed the main guide, you have everything needed:

Docker Desktop installed and running
PowerShell knowledge
Same computer requirements (8GB+ RAM)

Step 1: Create O3 Project Folder

Open PowerShell and run (change path to match yours):

# Navigate to your research folder
cd "G:\Your Research Folder"

# Create O3 folder
New-Item -Path "OpenMRS-O3" -ItemType Directory -Force

# Go into the folder
cd OpenMRS-O3

Step 2: Create Configuration File

Copy this into PowerShell:

@"
version: '3.7'

services:
  gateway:
    image: openmrs/openmrs-reference-application-3-gateway:3.0.0-beta.20
    restart: unless-stopped
    depends_on:
      - frontend
      - backend
    ports:
      - "8082:80"

  frontend:
    image: openmrs/openmrs-reference-application-3-frontend:3.0.0-beta.20
    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:3.0.0-beta.20
    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
      OMRS_CONFIG_CONNECTION_PASSWORD: openmrs
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/openmrs"]
      timeout: 5s
    volumes:
      - o3-openmrs-data:/openmrs/data

  db:
    image: mariadb:10.8.2
    restart: unless-stopped
    command: "mysqld --character-set-server=utf8 --collation-server=utf8_general_ci"
    healthcheck:
      test: 'mysql --user=openmrs --password=openmrs --execute \"SHOW DATABASES;\"'
      interval: 3s
      timeout: 1s
      retries: 5
    environment:
      MYSQL_DATABASE: openmrs
      MYSQL_USER: openmrs
      MYSQL_PASSWORD: openmrs
      MYSQL_ROOT_PASSWORD: openmrs
    volumes:
      - o3-db-data:/var/lib/mysql

volumes:
  o3-openmrs-data:
  o3-db-data:
"@ | Out-File -FilePath docker-compose.yml -Encoding utf8

Press Enter.

Step 3: Start O3

docker compose up -d

First time: Downloads ~1GB (5-10 minutes)

You’ll see: Messages about pulling images and starting containers.

Step 4: Wait for Backend Initialization

CRITICAL: The backend needs 5-10 minutes to initialize.

Watch the logs:

docker compose logs -f backend

Wait for this message:

INFO: Server startup in XXXXX ms

Press Ctrl+C when you see it (backend keeps running).

Don’t skip this step! If you access O3 before initialization completes, you’ll see a broken interface.

Step 5: Access O3 in Browser

Open your browser and go to:

http://localhost:8082/openmrs/spa

You should see: Modern O3 login page with clean design.

Login credentials:

Username: admin
Password: Admin123
Location: Select any from dropdown

Daily Use

Start O3:

cd "G:\Your Research Folder\OpenMRS-O3"
docker compose up -d

Wait 2-3 minutes, then access: http://localhost:8082/openmrs/spa

Stop O3:

cd "G:\Your Research Folder\OpenMRS-O3"
docker compose down

Quick Troubleshooting

Port 8082 already in use?

Change to port 8083:

(Get-Content docker-compose.yml) -replace '8082:80', '8083:80' | Set-Content docker-compose.yml
docker compose down
docker compose up -d

Access at: http://localhost:8083/openmrs/spa

Blank page or missing elements?

Backend not ready. Check for “Server startup”:

docker compose logs backend | Select-String "Server startup"

If not found, wait longer and refresh browser.

Both Systems Running

You now have two OpenMRS systems:

Legacy UI:

Port: 8080
URL: http://localhost:8080/openmrs/login.htm
Your existing work (474 concepts, forms)

O3:

Port: 8082
URL: http://localhost:8082/openmrs/spa
Fresh installation to explore

Both run independently. Data is not shared between them.

O3 vs Legacy: Quick Comparison

Feature	Legacy UI	O3
Interface	Traditional menus	Modern, search-based
Forms	HTML Form Entry	JSON Schema
Mobile	Desktop only	Fully responsive
Learning Curve	Easier	Steeper
Future Support	Being phased out	Active development
Best For	Quick start, simpler forms	Long-term, modern UX

Recommendation: Try both! O3 on port 8082 won’t affect your Legacy UI work. Explore O3’s interface and decide which system fits your workflow better.

Next Steps

Once logged into O3:

Explore the interface - Search bar, modern navigation
Register a test patient - Click search bar → “Add new patient”
Compare with Legacy UI - Open both in different browser tabs
Decide which to use - Both are valid choices!

For building your dialysis registry in O3, we’ll cover concept creation and form building in future guides.

That’s it! You now have OpenMRS O3 running alongside your Legacy UI installation.

How to Build Your Own Medical Records System on Your Computer: A Super Simple Guide for Doctors (No Tech Skills Needed!)

How to Build Your Own Medical Records System on Your Computer

A Super Simple Guide for Doctors (No Tech Skills Needed!)

Table of Contents

Introduction

By the end of this guide, you will have:

Why I Made This Guide

Basics

What You Need (Shopping List)

Step 1: Install Docker (The Lunchbox System)

Download Docker Desktop

Open Docker Desktop

Step 2: Check If Docker Works - We need to make sure Docker is working before we continue.

Step 3: Create Your Project Folder

Step 4: Create Password File - Your system needs passwords to keep patient data safe.

Step 5: Create Configuration File

Step 6: Download the User Interface

Step 7: Start OpenMRS!

Step 8: Watch OpenMRS Wake Up

Step 9: Install the User Interface (Critical!) - Copy UI Into OpenMRS

Step 10: Restart OpenMRS

Step 11: Open OpenMRS in Your Browser!

Step 12: Login for the First Time

Step 13: Troubleshooting (Problems I Hit)

Problem 1: “Docker is not running”

Problem 2: “Port 8080 is already in use”

Problem 3: “Username or password is incorrect”

Problem 4: Downloaded file is too small (0.37 MB)

Step 14: Daily Use (Starting and Stopping)

Step 15: Backing Up Your Data (IMPORTANT!)

Step 16: Help from the Community

What I Wish I Knew Earlier:

Checklist:

System prompt to Vibe code

Final Pep Talk

Reflections on Building an Electronic Patient Record in the Age of AI - Dr. Bernard Fernando

Electronic medical records: A dire need in renal medicine… and finally accessible to low resource settings? - Dr. Dilushi Wijayaratne

Feedback Welcome!

Appendix: Setting Up OpenMRS O3 (Version 3.x)

What is O3?

Quick Setup Steps

Prerequisites

Step 1: Create O3 Project Folder

Step 2: Create Configuration File

Step 3: Start O3

Step 4: Wait for Backend Initialization

Step 5: Access O3 in Browser

Daily Use

Start O3:

Stop O3:

Quick Troubleshooting

Port 8082 already in use?

Blank page or missing elements?

Both Systems Running

O3 vs Legacy: Quick Comparison

Next Steps