Quickstart Guide

This guide will help you set up OmniEHR on your local machine. You’ll have a fully functional FHIR-compatible EHR system running in minutes.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ and npm
Docker and Docker Compose (for MongoDB)
Git for cloning the repository
OpenSSL for generating encryption keys

If you already have MongoDB running, you can skip Docker and point to your existing instance using the MONGODB_URI environment variable.

Installation Steps

Clone the Repository

Clone the OmniEHR repository to your local machine:

git clone https://github.com/amankiit/OmniEHR.git
cd OmniEHR

Start MongoDB

Use Docker Compose to start a local MongoDB instance:

docker compose up -d

This starts MongoDB 7 on localhost:27017 with a database named ehr.

Docker Compose Configuration

The docker-compose.yml file includes:

services:
  mongo:
    image: mongo:7
    restart: unless-stopped
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_DATABASE: ehr
    volumes:
      - mongo_data:/data/db

Data persists in the mongo_data Docker volume.

Verify MongoDB is running:

docker ps

You should see the mongo:7 container.

Install Dependencies

Install all dependencies for both server and client:

npm install

This installs dependencies for the monorepo workspace, including:Server dependencies:

express - REST API framework
mongoose - MongoDB ODM
jsonwebtoken - JWT authentication
bcryptjs - Password hashing
helmet - Security headers
zod - Input validation

Client dependencies:

react & react-dom - UI framework
react-router-dom - Client routing
vite - Build tool

Configure Environment Variables

Copy the example environment files:

cp server/.env.example server/.env
cp client/.env.example client/.env

Server Configuration

Edit server/.env with the following values:

NODE_ENV=development
PORT=4000

# Database connection
MONGODB_URI=mongodb://127.0.0.1:27017/ehr

# JWT authentication (generate a secure random string)
JWT_SECRET=your-secure-jwt-secret-here-make-it-long-and-random
JWT_EXPIRES_IN=8h

# PHI encryption key (MUST be 64 hex characters - see below)
PHI_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

# CORS origin for frontend
CORS_ORIGIN=http://localhost:5173

Security Critical: Generate a new PHI_ENCRYPTION_KEY before storing any real data!

Generate a secure 256-bit (32-byte) encryption key:

openssl rand -hex 32

This outputs a 64-character hex string. Copy it to PHI_ENCRYPTION_KEY in server/.env.Example output:

a7f8e9d0c1b2a3f4e5d6c7b8a9f0e1d2c3b4a5f6e7d8c9b0a1f2e3d4c5b6a7f8

Client Configuration

Edit client/.env:

# API endpoint for local development
VITE_API_BASE_URL=http://localhost:4000/api

Environment Variable Reference

Variable	Description	Required	Default
`NODE_ENV`	Environment mode	Yes	`development`
`PORT`	Server port	Yes	`4000`
`MONGODB_URI`	MongoDB connection string	Yes	-
`JWT_SECRET`	Secret for signing JWTs	Yes	-
`JWT_EXPIRES_IN`	Token expiration time	Yes	`8h`
`PHI_ENCRYPTION_KEY`	64-char hex key for AES-256-GCM	Yes	-
`CORS_ORIGIN`	Allowed frontend origin	No	-
`VITE_API_BASE_URL`	Backend API URL	Yes	-

Start the Application

Run both server and client in development mode:

npm run dev

This starts:

API Server at http://localhost:4000
Frontend UI at http://localhost:5173

You can also run them separately:

npm run dev:server

The server uses nodemon for hot-reloading. The client uses Vite’s HMR for instant updates.

Access the Application

Open your browser and navigate to:

http://localhost:5173

You’ll see the OmniEHR login page.

Demo Credentials

OmniEHR includes demo accounts for testing different roles:

Admin Account

Email: [email protected]Password: Abcdefgh@998761Full system access including user provisioning and patient management.

Practitioner Account

Email: [email protected]Password: Abcdefgh@998761Clinical access with restrictions to own schedule and tasks.

These demo credentials are for development only. Change or remove them before deploying to production.

Verify Installation

Test that everything is working correctly:

1. Check API Health

curl http://localhost:4000/api/health

Expected response:

{
  "status": "ok",
  "timestamp": "2026-03-04T..."
}

2. Test Authentication

curl -X POST http://localhost:4000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Abcdefgh@998761"
  }'

You should receive a JWT token and user object.

3. Check FHIR Metadata

curl http://localhost:4000/api/fhir/metadata \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

This returns the FHIR CapabilityStatement showing supported resources:

Patient
Observation
Condition
AllergyIntolerance
MedicationRequest
Encounter
Appointment
Task

Next Steps

Now that OmniEHR is running, explore these features:

Create a Patient

Schedule Appointments

Book appointments with conflict detection

Use FHIR APIs

Interact with RESTful FHIR endpoints

Review Audit Logs

Monitor system access and changes

Common Issues

MongoDB Connection Failed

Error: MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017Solution:

Verify MongoDB is running: docker ps
Check MongoDB logs: docker logs [container_id]
Ensure MONGODB_URI in server/.env matches your setup

Invalid PHI_ENCRYPTION_KEY

Error: PHI_ENCRYPTION_KEY must be a 64-char hex string (32 bytes)Solution: Generate a new key with exactly 64 hex characters:

openssl rand -hex 32

Update PHI_ENCRYPTION_KEY in server/.env

CORS Errors in Browser

Error: Access to fetch at 'http://localhost:4000/api/...' has been blocked by CORS policySolution:

Ensure CORS_ORIGIN=http://localhost:5173 in server/.env
Restart the server: npm run dev:server
Verify client is running on port 5173

Port Already in Use

Error: Error: listen EADDRINUSE: address already in use :::4000Solution:

Find process using port: lsof -i :4000 (macOS/Linux) or netstat -ano | findstr :4000 (Windows)
Kill the process or change PORT in server/.env

Development Workflow

Running Tests

# Lint code
npm run lint

# Build client for production
npm run build --workspace client

Project Structure

omniehr/
├── server/              # Backend API
│   ├── src/
│   │   ├── models/      # Mongoose schemas (Patient, User, etc.)
│   │   ├── routes/      # Express routes (FHIR, auth, admin)
│   │   ├── services/    # Business logic (encryption, validation)
│   │   ├── middleware/  # Auth, audit, error handling
│   │   └── config/      # Environment and database config
│   └── package.json
├── client/              # React frontend
│   ├── src/
│   │   ├── pages/       # Page components
│   │   ├── components/  # Reusable UI components
│   │   ├── context/     # React context (AuthContext)
│   │   └── api.js       # API client
│   └── package.json
├── docker-compose.yml   # MongoDB container
└── package.json         # Workspace root

Production Deployment

Before deploying to production:

Generate new JWT_SECRET and PHI_ENCRYPTION_KEY
Use managed MongoDB with backups (MongoDB Atlas, etc.)
Enable TLS/HTTPS for all connections
Remove or change demo credentials
Set NODE_ENV=production
Configure rate limiting and monitoring
Review security hardening recommendations

Recommended production enhancements:

Multi-factor authentication (MFA)
Token refresh and revocation
Immutable audit log storage (WORM)
SIEM integration for monitoring
Automated security scanning
Penetration testing
Business Associate Agreements (BAAs)

Getting Help

Need assistance?

Check the API Reference for endpoint documentation
Review Security Best Practices
Open an issue on GitHub
Join our community discussions

Remember: HIPAA compliance requires organizational policies, procedures, training, and risk management beyond these technical controls.

Get Started

Core Features

Security & Compliance

Deployment

Quickstart Guide

Quickstart Guide

Prerequisites

Installation Steps

Server Configuration

Client Configuration

Demo Credentials

Admin Account

Practitioner Account

Verify Installation

1. Check API Health

2. Test Authentication

3. Check FHIR Metadata

Next Steps

Create a Patient

Schedule Appointments

Use FHIR APIs

Review Audit Logs

Common Issues

Development Workflow

Running Tests

Project Structure

Production Deployment

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

Security & Compliance

Deployment

​Quickstart Guide

​Prerequisites

​Installation Steps

​Server Configuration

​Client Configuration

​Demo Credentials

Admin Account

Practitioner Account

​Verify Installation

​1. Check API Health

​2. Test Authentication

​3. Check FHIR Metadata

​Next Steps

Create a Patient

Schedule Appointments

Use FHIR APIs

Review Audit Logs

​Common Issues

​Development Workflow

​Running Tests

​Project Structure

​Production Deployment

​Getting Help

Build docs developers (and LLMs) love

Quickstart Guide

Prerequisites

Installation Steps

Server Configuration

Client Configuration

Demo Credentials

Verify Installation

1. Check API Health

2. Test Authentication

3. Check FHIR Metadata

Next Steps

Common Issues

Development Workflow

Running Tests

Project Structure

Production Deployment

Getting Help