Hospital Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Hospital Deployment Guide provides instructions and architectural details for deploying the AI-powered OpenMRS EHR system in a clinical environment. The system integrates a standard OpenMRS core with advanced AI services for voice transcription, OCR, and automated vitals extraction, tailored specifically for workflows in Indian public hospitals.
The scope of this guide covers hardware requirements, software prerequisites, environment configuration, and the automated metadata initialization process necessary to support specialized clinical documentation.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:1-40, README.md:1-15
System Architecture
The deployment is based on a containerized microservices architecture using Docker. It consists of the core OpenMRS stack (Backend, Frontend, and MariaDB) complemented by an AI Backend, a Gemini Proxy for LLM tasks, and a specialized EHR Dashboard.
Component Overview
| Service | Technology | Role | Port |
|---|---|---|---|
| MariaDB | MariaDB 10.11 | Patient database (internal clinical data) | 3306 |
| OpenMRS Backend | Java/Spring | REST API and core clinical logic | 8080 |
| OpenMRS Frontend | React/TypeScript | O3 Patient Chart SPA | N/A (via Gateway) |
| Gateway | Nginx | Reverse proxy for OpenMRS Frontend/Backend | 80 |
| AI Backend | Python/FastAPI | Voice transcription, OCR, and vitals extraction | 3001 |
| Gemini Proxy | Python/FastAPI | LLM summarization via Google Gemini | 8001 |
| EHR Dashboard | React/Vite | Physician overview and section editing | 5175 |
| Metadata Init | Python | One-shot job to create custom concepts and types | N/A |
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:42-63, README.md:17-30
Network and Data Flow
The system distinguishes between local hospital LAN traffic and external cloud API requests for AI features. The Gateway manages clinical chart access, while the EHR Dashboard interacts with AI services to provide summaries.
The diagram shows how internal clinical data flows between the OpenMRS components while AI requests are routed through the AI Backend to external providers.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:66-78, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:395-425
Deployment Requirements
Hardware Specifications
The production setup does not require a GPU as AI tasks (transcription and LLM) are offloaded to cloud APIs.
| Resource | Minimum (50 users) | Recommended (50-200 users) |
|---|---|---|
| CPU | 4 cores (x86_64) | 8 cores |
| RAM | 8 GB | 16 GB |
| Storage | 100 GB SSD | 500 GB SSD |
| OS | Ubuntu 22.04 / Debian 12 | Ubuntu 22.04 LTS |
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:81-110
Environment Configuration
Sensitive credentials must be configured in a .env file within the deployment/ directory.
# Critical Security Variables
MYSQL_ROOT_PASSWORD=32_char_random_password
OMRS_DB_PASSWORD=32_char_random_password
OPENMRS_PASSWORD=admin_password
# AI Service Keys
SARVAM_API_KEY=your_sarvam_key
GEMINI_API_KEY=your_google_ai_key
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:157-178, README.md:71-85
Metadata Initialization
A critical phase of deployment is the automated creation of medical documentation metadata. This system utilizes 326 custom concepts, 27 encounter types, and various person attributes.
Initialization Process
The metadata-init service runs as a "one-shot" container. It performs the following sequence:
- Waits for the OpenMRS Backend health check to pass.
- Executes
setup_medical_documentation_concepts.pyto create clinical structures. - Executes
setup_openmrs_concepts.pyfor voice recording metadata. - Verifies the existence of critical concepts (e.g., "Background History").
UUID Stability
All metadata is created using deterministic UUIDs defined in medical_documentation_config.json. This ensures that the frontend and AI backend, which rely on hardcoded UUIDs for form mapping and data extraction, remain consistent across different hospital installations.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:232-245, openMRS-main/setup_medical_documentation_concepts.py:53-65
Operational Procedures
Deployment Execution
The full stack is launched using a single Docker Compose command from the deployment directory.
docker compose -f docker-compose.production.yml up -d --build
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:180-190
Update Workflow
Updating specific parts of the system does not require a full stack restart.
| Component Changed | Command to Update |
|---|---|
| Dashboard UI | docker compose ... up -d --build ehr-dashboard |
| AI Backend Code | docker compose ... up -d --build ai-backend gemini-proxy |
| New Metadata | docker compose ... build metadata-init && docker compose ... run --rm metadata-init |
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:295-315
Backup and Recovery
Automated daily backups are recommended, targeting the MariaDB dump, OpenMRS application data, and AI recordings.
# Database Dump Example
docker compose -f docker-compose.production.yml exec -T db \
mysqldump -u root -p"$MYSQL_ROOT_PASSWORD" --all-databases > openmrs-db.sql
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:345-365
Voice Vitals Integration
The deployment includes a specialized feature for voice-to-vitals recording. This module uses the AI Backend to process audio recordings and auto-populate EHR forms.
Conclusion
The OpenMRS Hospital Deployment is a multi-layered system that balances local clinical data management with cloud-based AI enhancements. Successful deployment relies on the stability of metadata UUIDs and the correct configuration of AI service keys. By following the containerized deployment model and the automated metadata initialization process, hospital IT staff can ensure a consistent and reliable EHR environment.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:435-440, README.md:150-160