Running the containers

Mercury ships as a single binary and a Docker image. The quickest way to try it against a realistic pipeline is the drop-in Measure Calculator stack; for development you can also run the server on its own.

Pull the image you were given access to:

docker login <registry-host>
docker pull IMAGE_URI
export MERCURY_IMAGE=IMAGE_URI

Examples below use $MERCURY_IMAGE. Paid AWS Marketplace subscribers use the Marketplace image URI from their subscription instead — see AWS Marketplace.

The drop-in Measure Calculator stack

Mercury slots in as the evaluator inside a Measure Calculator environment, alongside the MCT frontend/backend and facility FHIR servers — matching the layout an existing CQF pipeline already uses. A compose file for that layout looks like this:

docker-compose.yml

services:
  mercury:
    image: ${MERCURY_IMAGE:?set MERCURY_IMAGE}
    ports:
      - "8090:8080"
    volumes:
      - mercury-data:/var/lib/mercury

  mct-ui:
    image: <your-mct-frontend-image>
    ports:
      - "3000:3000"

  mct-backend:
    image: <your-mct-backend-image>
    ports:
      - "8088:8088"

  facility-a-fhir:
    image: <your-fhir-server-image>
    ports:
      - "8080:8080"

  facility-b-fhir:
    image: <your-fhir-server-image>
    ports:
      - "8082:8080"

volumes:
  mercury-data:

docker compose up

Docker Compose reads MERCURY_IMAGE from your shell environment.

Ports it brings up:

Service	URL
MCT UI	http://localhost:3000
MCT backend	http://localhost:8088
Facility A FHIR	http://localhost:8080/fhir
Facility B FHIR	http://localhost:8082/fhir
Mercury (CQF / API / FHIR)	http://localhost:8090 — base paths /cqf, /api, /fhir

Note

Because Mercury speaks the same FHIR CQF API as the reference evaluator, MCT and your harness point at Mercury’s base URL unchanged. That’s the whole idea of “drop-in”.

Comparing against the reference engine

To check output parity, run your existing reference stack (the CQL translation service and CQF Ruler, or whatever you use today) side by side with Mercury, and compare results for the same libraries and patients against both base URLs. The reference stack exists only to check outputs and behavior — Mercury is the evaluator in the main pipeline.

Running the server on its own

Binary

mercury serve --host 127.0.0.1 --port 8080

Docker (image only)

# Map the port and a data volume (see "Mounting your data drive")
docker run --rm \
  -p 8080:8080 \
  -v mercury-data:/var/lib/mercury \
  "$MERCURY_IMAGE"

Health checks

Every deployment exposes readiness and liveness endpoints — use them in compose healthchecks, Kubernetes probes, or a load balancer.

curl -fsS http://localhost:8080/api/health
curl -fsS http://localhost:8080/api/ready

/api/health includes the build version, edition, and enabled packs:

{
  "status": "UP",
  "version": "<your version>",
  "edition": "community",
  "packs": ["core"]
}

The exact version value reflects the build you pulled.

The image entrypoint already starts mercury serve with HOST=0.0.0.0 and PORT=8080. Override HOST, PORT, CQF_BASE_PATH, API_BASE_PATH, or FHIR_BASE_PATH as environment variables only when you need non-default routing.

Contributors / Source Repo

If you have the source repository, you can build a local contributor image:

docker build -t mercury:community .
export MERCURY_IMAGE=mercury:community

Next steps

• Mounting your data drive — so libraries, measures, and data survive docker compose down.
• Loading data: preload vs inline — get patient data into an evaluation.
• CLI reference — flags for serve, run, and lang-tests.