Getting started

MDMbox is distributed as versioned Docker images under healthsamurai/mdmbox. Select a published release tag and set MDMBOX_VERSION before using the Compose examples. Release tags include the compatible Aidbox version, for example 2604.2-aidbox2603.0.

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).

export MDMBOX_VERSION=2604.2-aidbox2603.0

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.

Pin the same release tag in values.yaml:

image:
  tag: 2604.2-aidbox2603.0

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