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.

License

MDMbox requires a license to start. There are two ways to activate it:

1. Environment variable. Sign in to the Aidbox portal, open the MDMbox project, copy the license JWT, and pass it to the MDMbox container as MDMBOX_LICENSE. Recommended for production and CI.
2. Browser activation. Leave MDMBOX_LICENSE unset and start MDMbox. Open http://localhost:3000, click Continue with Aidbox account, sign in to the portal — a development MDMbox license is generated and stored in the database automatically. Useful for local development.

Configuration reference

Database

MDMbox uses the standard Aidbox database environment variables:

MDMbox connection pool

MDMbox maintains its own connection pool separate from the embedded FHIR engine. Both pools connect to the same database but are sized independently.

HTTP server

Endpoints

Once running, the following endpoints are available:

Next steps