Run Medplum Locally

Medplum is an open-source set of tools designed to provide FHIR Storage, REST APIs and GraphQL

Running Medplum locally is a great way to debug and test your applications offline

Prerequisites

• Node.js 21.7.3
• Docker Desktop
• Git
• WSL2 (if using Windows)
• NVM (recommended)

Quick Setup

1. Clone Repository

git clone https://github.com/claimpowerehr/medplum.git
cd medplum

2. Start Required Services

docker-compose up -d

This starts:

PostgreSQL database (port 5432) Redis cache (port 6379)

3. Install Dependencies

npm install
npm install -g @microsoft/api-extractor @microsoft/api-documenter @testing-library/jest-dom rimraf turbo

4. Build packages

There are two important packages in the monorepo

Located in the /packages directory

npm run build -- --filter=@medplum/server
npm run build -- --filter=@medplum/app

Both commands need to succed in order to continue, with an output similar to

 Tasks:    8 successful, 8 total
Cached:    4 cached, 8 total
  Time:    26.378s

5. Start the server

cd packages/server
npm run dev

Server runs at: http://localhost:8103

5.a Start the app

The dashboard is located in /packages/app

cd packages/app
npm run dev -- --port=4000

Dashboard runs at: http://localhost:4000

6. Point your app & lotus to the local server

NODE_ENV=development
MEDPLUM_BASE_URL=http://localhost:8103

7. Using NVM

Use node version manager to use a specific version of node

nvm install 21.7.3
nvm use 21.7.3

Windows Users

If you're using Windows, we strongly recommend using WSL2:

• Install WSL2 and Ubuntu
• Install Docker Desktop with WSL2 backend
• Run all commands in WSL terminal

Troubleshooting

Database Connection

Verify PostgreSQL is running:

docker ps | grep postgres

Logs & Redis Connection

Verify Redis is running:

docker-compose logs

Reference

• See Dockerfile-medplum-dev for build steps
• Check docker-compose.yml for service configurations
• Visit Medplum Docs for detailed setup