Technical Overview

The Build

A self-hosted, offline-first EMR for a volunteer medical mission. This page covers the stack, architecture posture, security model, and the engineering decisions that shaped the system — including the ones that were wrong and got corrected.

Stack

Layer	Technology	Note
OS	Ubuntu 22.04 LTS	Chosen over newer releases for proven OpenEMR package compatibility
Web server	Apache 2.4	mod_php; HTTP redirects to HTTPS at server level
Database	MariaDB 10.6	Migrated from corrupted Windows/XAMPP host via SQL dump
PHP	8.1	EOL — upgrade is a known open item, deferred pre-Laredo
Application	OpenEMR 7.0	Installed from official packages; custom LBFs added on top
VM host	Oracle VirtualBox	Dynamically allocated disk; snapshot-backed baseline for rollback
Remote access	SSH via ed25519 keys	Accessible remotely via SSH config alias

Offline-firstNo cloudStatic IPSnapshot-backedSSH accessLAN-only

Architecture and Security

Network posture

LAN-only. No public IP, no public DNS, no internet dependency during clinic operations. The server is reachable only from devices on the clinic network. Designed for remote sites with intermittent or no connectivity.

Encrypted transport

HTTPS throughout — no unencrypted path to the application. A private certificate authority issues LAN-scoped certificates. Client devices install the CA root once before the mission; all subsequent connections are trusted automatically.

Firewall posture

Default-deny inbound. Web traffic and remote management access are explicitly allowed; everything else is blocked. Verified after configuration and before each deployment.

Access control

Eight station accounts, one per clinical function. Permissions set wide for the trial to minimize training friction; tightening to role-appropriate access is a post-trial milestone.

Backup and recovery

Automated daily backups with rotation. VirtualBox snapshot at a known-good baseline allows full rollback without reconfiguration. The on-mission rebuild demonstrated that the configuration procedure is documented well enough to repeat under pressure.

HIPAA-aligned hybrid model

For Laredo (US jurisdiction): paper-primary during the mission, post-mission EMR entry. Patient records are not held in the live system during clinic hours. This limits real-time data exposure and aligns with HIPAA principles without requiring a formal compliance posture.

Clinical Forms

Six custom Layout-Based Forms (LBFs) — OpenEMR's native form-builder — each built from its paper original with station-lead input. Paper forms are the specification; deviations require clinical justification.

Registration

Intake

Spanish-facing. Two surname fields (paternal/maternal), Cedula tracking for Costa Rica, mission-mode toggle for Laredo.

Triage

Vitals entered once, auto-propagated to all downstream forms. Allergies highlighted in red everywhere. Chief complaint as direct patient quote, read-only downstream.

Medical

SOAP-based. Structured 6-field prescription block. Dedicated diagnosis prompt. Non-sequential entry model to match provider workflow.

Pediatrics

Weight prominently displayed for weight-based dosing. Top-16 recurring-diagnosis checklist. Sample-dispensing tracker. Interpreter flag distinguishes Cabecar from Spanish.

Vision

Full custom form. Autorefractor output captured as photo attachment with optional structured fields. Visual acuity with and without correction. Service tracker with per-row completion and initials.

Dental

Mirrors paper original. Pre-med and medication history sections optional (never filled in practice). Tooth chart visual UI deferred — current form captures structured data.

Key Decisions

Build in-house over contracted setup

Shipped

Chosen

Configure cloud and network infrastructure in-house with the MMDM president

Rejected

$6,000 contracted setup through a Microsoft networking subsidiary

The MMDM president is a former Microsoft employee with hands-on infrastructure experience. Paying $6,000 for a setup we could do ourselves — with someone more familiar with the org's specific needs — was not justified. The in-house build also gave full ownership of the configuration going forward, with no vendor dependency.

Ubuntu over Windows

Shipped

Chosen

Migrate to Ubuntu 22.04 LTS on a fresh VM

Rejected

Continue repairing the corrupted Windows/XAMPP installation

The MariaDB system database was untrustworthy after corruption. Repair would have left questions about silent data damage. Ubuntu gives a known-clean baseline, a real package manager, and SSH access without additional tooling.

Private CA over self-signed certs

Shipped

Chosen

Build a private certificate authority; install root cert once per device

Rejected

Per-endpoint self-signed certs (or no TLS at all)

Self-signed certs require an exception per device per endpoint. A private CA requires one trust install per device, after which all signed certs are trusted automatically. For a multi-station clinic that re-provisions tablets regularly, the operational difference is significant.

Rebuild over patch

Shipped

Chosen

Full OpenEMR reset in place during the Costa Rica mission

Rejected

Continue on the corrupted build, or fall back to an older insecure version

The running version was corrupted. The previous build lacking required security updates was not an acceptable alternative for a system holding patient data. A rebuild from a clean configuration, documented well enough to execute under pressure, was the correct call. The rebuild completed and the system returned to service within the hour.

Paper-primary field protocol

Shipped

Chosen

Paper is the primary workflow during missions; EMR entry happens post-session

Rejected

EMR-primary for the first deployment

Going EMR-primary on a first field deployment introduces data integrity and clinical workflow risks simultaneously. A shadow deployment catches problems at lower stakes. For Laredo, the paper-primary model also serves as the HIPAA-aligned privacy posture: patient data is not held in the live system during clinic hours.

Paper forms as the specification

Shipped

Chosen

Treat each paper form as the canonical spec; deviations require station-lead sign-off

Rejected

Design forms from scratch based on EMR best practices

Station leads have conducted 26 and 32 missions on paper. They know which fields get filled and which get skipped. Forms designed without that input would have required rework. The paper-as-spec rule produced forms the leads recognized as theirs.

Configurable routing thresholds

Shipped

Chosen

Routing thresholds (e.g., vision age cutoff) editable mid-mission without code changes

Rejected

Hardcoded thresholds in form logic

The vision lead changed the age cutoff for routing patients to the eye doctor midway through the Costa Rica deployment. A hardcoded value would have required a code change, a rebuild, and redeployment mid-clinic. The configurable model cost nothing to build and prevented a real operational blocker.

Open Items

highDental tooth chart visual UI (canvas/SVG)
highLaredo-specific form configuration (Medicaid Y/N, mailing address, Prevent Blindness referral) — target: pre-Nov 4, 2026
highPhilippines deployment configuration (Batangas, Feb 2027) — new international scope, form and network requirements TBD
mediumPHP 8.1 end-of-life upgrade — target: pre-Laredo
mediumClient-device CA cert installation testing across all station tablets
mediumPharmacy station account for Laredo (dispensing + e-prescribing workflow) — target: pre-Nov 4, 2026
lowAutorefractor USB/CSV integration (currently photo + manual transcription)
lowlocalhost included in certificate SAN