Getting started

MDMbox is distributed as a Docker image: healthsamurai/mdmbox.

It requires a PostgreSQL 14+ database. All configuration is done through environment variables.

The docker-compose.yml snippets below are minimal examples for local trial runs — clone, tweak, docker compose up. For Kubernetes, see Kubernetes (Helm).

Standalone deployment

In standalone mode, MDMbox manages its own database. You need two containers: PostgreSQL and MDMbox.

Start the services:

docker compose up

MDMbox is available at http://localhost:3000. Open http://localhost:3000/api/docs for the Swagger UI.

As Aidbox plugin

When you already have an Aidbox instance, MDMbox can connect to the same PostgreSQL database. Both services share FHIR data.

Each MDMbox release is built for a specific Aidbox version. Contact us to get a build compatible with your Aidbox version.

Pass the same BOX_* environment variables to MDMbox that your Aidbox uses:

Kubernetes (Helm)

For Kubernetes, MDMbox is published as a Helm chart: HealthSamurai/helm-charts/mdmbox. The chart does not provision PostgreSQL — bring your own (managed service, in-cluster operator, or bitnami/postgresql) — and supports the same two modes as the Compose examples above.

helm repo add healthsamurai https://healthsamurai.github.io/helm-charts

helm upgrade --install mdmbox healthsamurai/mdmbox \
  --namespace mdmbox --create-namespace \
  --values values.yaml

config:
  MDMBOX_LICENSE: <license JWT>
  BOX_DB_HOST: postgres
  BOX_DB_PORT: "5432"
  BOX_DB_DATABASE: mdmbox

extraEnvFromSecrets:
  - mdmbox-db   # contains BOX_DB_USER, BOX_DB_PASSWORD

aidboxConfigMap: aidbox-config   # BOX_DB_HOST, BOX_DB_PORT, BOX_DB_DATABASE...
aidboxSecret: aidbox-secret      # BOX_DB_USER, BOX_DB_PASSWORD...

config:
  MDMBOX_LICENSE: <license JWT>

The full list of values is in the chart README.

Configuration

For production, pass MDMBOX_LICENSE as an environment variable. For local trial runs, you can leave it unset and activate MDMbox in the browser after startup.

See Configuration reference for all environment variables, authentication settings, and runtime defaults.

Endpoints

Once running, the following endpoints are available:

Next steps