Skip to content

VIM Team Docs — Medplum AWS Dev Environment

What we are doing

We are setting up a VIM-controlled development environment for the open source Medplum platform on AWS.

This is not production and must not contain PHI or real patient data until security, compliance, and clinical review are complete.

Why Medplum AWS first

Medplum's official self-hosting docs recommend AWS as the most mature deployment option. The AWS path uses CDK/CloudFormation to provision the core infrastructure: networking, app hosting, database, cache, storage, certificates/DNS support, logging, and related security resources.

Current status

Robbie has created the local setup repository and documentation. AWS access and account aliases are configured for VIM Dev, Stage, and Prod. The latest architecture decision is that these accounts are shared VIM environment accounts, not Medplum-only accounts. Medplum is the first workload to launch, followed by Patient app, Doctor UI, and other applications.

Key DNS decisions now documented:

  • dev.vimmedicine.app is delegated to the Dev account.
  • stage.vimmedicine.app is delegated to the Stage account.
  • Internal prod app zones should be delegated to Prod as needed, starting with medplum.vimmedicine.app when Medplum prod is imminent.
  • Existing Medplum dev work under medplum-dev.vimmedicine.app remains documented as the current/legacy dev path.

What VIM needs to decide next

  1. Whether to continue current dev on medplum-dev.vimmedicine.app or migrate future dev naming to medplum.dev.vimmedicine.app for shared-environment consistency.
  2. What SES email identity each Medplum environment should use for invites/password resets.
  3. Who from engineering/security/clinical should review before live or real-data use.
  4. Should each environment be public, VPN-only, or IP-allowlisted/WAF-restricted?
  5. What budget alarm thresholds and owners should be used for Dev, Stage, and Prod.

Documentation map

  • architecture-and-configuration-brief.md — executive architecture/configuration summary and latest account/DNS/deployment decisions.
  • decision-log.md — chronological project/platform decisions and rationale.
  • metriport-record-retrieval-decision.md — decision and rationale for using hosted Metriport as the initial external clinical record retrieval layer feeding Medplum.
  • initial-install-and-iac-plan.md — plan for GitHub-backed IaC, GitHub Actions, and the initial AWS install.
  • project-overview.md — business/technical summary.
  • deployment-guide.md — human-readable deployment process.
  • operating-runbook.md — how to operate after deployment.
  • decision-checklist.md — decisions needed before deployment.
  • security-and-data-boundary.md — dev safety boundary.

Keep these markdown files as the source of truth, then publish a human-friendly copy to the team's normal workspace:

  • Best immediate option: create a dedicated Notion/Google Drive folder named Medplum AWS Dev Environment and paste/sync these docs there.
  • Better engineering option: put the markdown docs in the infra GitHub repo under /docs/vim-team/ so changes are versioned and PR-reviewed.
  • Long-term option: publish from markdown to an internal docs site using Docusaurus or MkDocs, with separate sections for engineering, security, clinical, and product.

My recommendation: start with GitHub markdown as source of truth + Google Drive/Notion index for non-engineers. That gives version control without forcing every stakeholder into GitHub.