Getting Started

Getting Started with OpenMRS on AWS

2026-07-30 · openmrs docs · aws

The CloudSOE OpenMRS image runs the OpenMRS 3 reference application — gateway, frontend, backend and MySQL — as a Docker Compose stack on a hardened Ubuntu base. The database is fully initialized at build time (normally a 30–60 minute import), so your first boot only rotates every baked credential to per-instance values and starts the containers: about five minutes, with a live progress meter when you SSH in.

What you’ll need

  • An AWS account subscribed to the CloudSOE OpenMRS listing on AWS Marketplace
  • An EC2 key pair in your target region (SSH is key-based only; password login is disabled)
  • About fifteen minutes

Step 1 — Launch the instance

  1. Open the OpenMRS listing on AWS Marketplace and click Continue to Subscribe, then Continue to Configuration.
  2. Pick your region and click Continue to Launch → Launch through EC2.
  3. Choose an instance type. t3.large (2 vCPU, 8 GB RAM) is the recommended starting point — the four-container stack needs more memory than a typical web app.
  4. Select your key pair, and keep the root volume at 100 GB — the image ships with multi-gigabyte container images and a pre-initialized database.

Prefer the CLI? Once subscribed:

aws ec2 run-instances \
  --image-id <ami-id-from-the-listing> \
  --instance-type t3.large \
  --key-name my-key \
  --security-group-ids sg-xxxxxxxx \
  --subnet-id subnet-xxxxxxxx \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=openmrs-01}]'

Step 2 — Open the firewall ports

The stack serves plain HTTP on port 80 (see the note on TLS below). Your security group needs two inbound rules:

PortProtocolPurpose
22TCPSSH administration
80TCPHTTP (OpenMRS gateway)

Restrict port 22 to your own IP range where possible — and for a medical records system, consider restricting port 80 to your clinic’s network or VPN until you’ve put TLS in front.

Step 3 — Watch first boot (about 5 minutes)

On the very first boot the openmrs-firstboot service rotates the MySQL passwords and the OpenMRS admin password to per-instance values, starts the container stack and writes your credentials file. SSH in while it’s working and a live progress meter appears automatically:

ssh ubuntu@<public-ip>
# OpenMRS is initializing on this instance (takes ~5 minutes on first boot).
#  / [########################                ]  61%  Starting OpenMRS services

Press Ctrl+C to drop to your shell at any time; run openmrs-bootstrap-status to bring the meter back.

Step 4 — Retrieve your credentials

Once the meter reaches 100%, read the credentials file:

sudo cat /opt/openmrs/default-openmrs-credentials.txt

This file (mode 600) holds the rotated admin password. The MySQL passwords (also rotated) are in /opt/openmrs/.env, root-only.

Step 5 — Log in to OpenMRS

Browse to:

  • Clinical app (O3): http://<public-ip>/ — patients, visits, charts
  • Admin / legacy UI: http://<public-ip>/openmrs — modules, global properties, users, REST/FHIR APIs

The same login works for both: user admin with the password from the credentials file. Change it after first login. The stack has no built-in TLS — see the configuration guide for putting HTTPS in front before real use.

Next steps