Getting started

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

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

Image versions

Each MDMbox release is built for a specific Aidbox version. Image tags follow the pattern {mdmbox-version}-aidbox-{aidbox-version}:

In shared mode, use the tag that matches your Aidbox version.

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.

Shared deployment with Aidbox

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

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

Configuration reference

Database

MDMbox uses the standard Aidbox database environment variables:

FHIR engine

MDMbox includes an embedded FHIR engine that uses the standard Aidbox BOX_* environment variables. In shared mode, these must match your Aidbox configuration. See the docker-compose examples above for the full list.

Key settings: BOX_BOOTSTRAP_FHIR_PACKAGES, BOX_FHIR_SEARCH_ENGINE, BOX_FHIR_COMPLIANT_MODE, BOX_SECURITY_DEV_MODE, BOX_ROOT_CLIENT_ID, BOX_ROOT_CLIENT_SECRET.

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