Self-hosted Journey deployment¶
deploy/openmed-compose.yaml is the reference single-host Journey profile. It starts the REST API, an operational worker, PostgreSQL, content-addressed artifact storage, and a one-shot migration gate. The optional mcp profile adds the streamable HTTP MCP surface; the optional smoke profile runs one idempotent synthetic golden journey.
The runtime remains local-first. The application containers use an internal Docker network, publish the API to 127.0.0.1:8080 by default, run as 65532:65532, drop Linux capabilities, and keep their root filesystems read-only. Metrics, tracing, remote model access, the privacy gateway, and OpenHIM are disabled unless explicitly enabled in a reviewed override.
Prepare the image and secret¶
Build while the host can reach the required package and image registries:
Create a strong database password in the deployment secret manager and expose it, together with the matching Journey DSN, only to the Compose invocation as OPENMED_POSTGRES_PASSWORD and OPENMED_JOURNEY_POSTGRES_DSN. Do not write them into this YAML, an image, a support bundle, or shell output. A clean development machine can generate ephemeral values for its current shell:
export OPENMED_POSTGRES_PASSWORD="$(openssl rand -hex 32)"
export OPENMED_JOURNEY_POSTGRES_DSN="postgresql://openmed:${OPENMED_POSTGRES_PASSWORD}@postgres:5432/openmed"
Both values are required; Compose fails before startup when either is absent. They are delivered as Compose secrets:, not container environment variables: Compose writes them to /run/secrets/openmed_postgres_password for PostgreSQL (POSTGRES_PASSWORD_FILE) and to /run/secrets/openmed_journey_postgres_dsn for the migration, worker, API health, and golden containers (OPENMED_JOURNEY_POSTGRES_DSN_FILE), owned by 65532:65532 with mode 0400. docker inspect and /proc/<pid>/environ of the OpenMed containers therefore show only the file paths. Some Compose releases print a warning that secret uid, gid, and mode only apply to Swarm; current releases apply them to environment-sourced secrets, and the prod profile refuses a world-readable secret file with secret_file_permissions_too_open if one does not. See mounted secret files for the file rules and error codes.
For a long-lived deployment, inject the values from the host's secret service rather than a checked-in .env file. HF_TOKEN is not configured by this profile.
Prepare PostgreSQL TLS¶
The Journey containers connect with sslmode=verify-full and verify the PostgreSQL server certificate and host name against an operator CA bundle at /run/openmed/postgres-tls/ca.crt (OPENMED_JOURNEY_POSTGRES_SSLROOTCERT). The production profile refuses a plaintext or non-verifying DSN before opening a socket and reports the value-free code postgres_tls_required.
Point OPENMED_POSTGRES_TLS_DIR at a host directory containing:
ca.crt, the CA bundle that issued the server certificate;server.crt, issued for the DNS namepostgres(the Compose service name);server.key, readable only by the PostgreSQL container user (uid70inpostgres:17-alpine, mode0600).
Use the organization's certificate authority for long-lived deployments. A clean development machine can create a short-lived synthetic CA:
export OPENMED_POSTGRES_TLS_DIR="$PWD/postgres-tls"
mkdir -p "$OPENMED_POSTGRES_TLS_DIR" && cd "$OPENMED_POSTGRES_TLS_DIR"
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
-days 30 -subj "/CN=OpenMed Compose Development CA" \
-keyout ca.key -out ca.crt
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
-subj "/CN=postgres" -keyout server.key -out server.csr
printf '%s\n' "subjectAltName=DNS:postgres" \
"basicConstraints=critical,CA:FALSE" \
"keyUsage=critical,digitalSignature" \
"extendedKeyUsage=serverAuth" > server.ext
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-days 30 -extfile server.ext -out server.crt
sudo chown 70:70 server.key && chmod 0600 server.key
Keep ca.key outside the Compose host and never commit any of these files. Only ca.crt is mounted into the OpenMed containers, read-only. Server-side pg_hba.conf enforcement, role management, and database encryption at rest remain operator responsibilities.
Start and run the golden journey¶
Start PostgreSQL, wait for it to become healthy, run the migration job, start the worker, and finally admit the API:
docker compose -f deploy/openmed-compose.yaml up -d --no-build
docker compose -f deploy/openmed-compose.yaml ps
curl --fail http://127.0.0.1:8080/readyz
Run the synthetic deployment proof without an external model service:
Success is a value-free JSON result with state=passed, code=golden_journey_verified, and artifact_count=1. The command writes a fixed synthetic artifact to the content-addressed volume, commits its metadata to PostgreSQL, and verifies both read paths. Repeating it is idempotent. It does not contain clinical input, identifiers, credentials, or an external API call.
Enable MCP only when needed:
The MCP container is reachable only on the internal Docker network. Publish it through a reviewed TLS and authentication boundary if another host needs it.
Startup and health semantics¶
The dependency order is part of the profile contract:
- PostgreSQL passes
pg_isready. journey-migrateobtains the migration lock, applies the append-only schema chain, checks migration checksums, and exits successfully.journey-workerverifies migration and metadata-store schema readiness plus artifact storage with a deterministic synthetic write/read marker, then exposes/livezand/readyzon the internal network.- The API starts after the migration and worker gates. Its container health command combines migration, store, artifact, worker, and local model readiness.
The combined response follows openmed.journey.deployment-health.v1 with compatibility major 1. Every component has one typed state: ready, pending, unavailable, incompatible, or disabled. Reason codes and schema versions are safe for operational logs; exception strings and configured URLs are not returned.
/livez means only that a process can answer. /readyz means its required dependencies are usable. Keep both: restarting a live process because a database is temporarily unavailable creates avoidable failure loops.
Storage and permissions¶
openmed-postgresowns PostgreSQL's durable database files.openmed-cache:/cachecontains the application cache and the content-addressed artifact namespace at/cache/artifacts.openmed-models:/models:rocontains pre-staged model inputs and remains read-only./tmpis a boundedtmpfsfor the non-root application containers.
When replacing a named volume with a host path, use long syntax and create_host_path: false; make the cache writable by 65532:65532 and keep models read-only:
services:
openmed:
volumes:
- type: bind
source: /srv/openmed/models
target: /models
read_only: true
bind:
create_host_path: false
Every OpenMed container has CPU and memory limits and a 512-process cap. The API and MCP containers default to 2 CPUs and 4 GiB, matching the Helm chart; raise them with OPENMED_CPU_LIMIT / OPENMED_MEMORY_LIMIT and OPENMED_MCP_CPU_LIMIT / OPENMED_MCP_MEMORY_LIMIT for larger models. The worker gets 1 CPU and 1 GiB, the migration and smoke jobs 0.5 CPU and 512 MiB.
The local log driver rotates three 10 MiB files. Operational output contains states and counts only. It must never contain source text, artifact bytes, database connection strings, vault values, or request bodies.
Offline boundary¶
The application containers set OPENMED_OFFLINE=1, HF_HUB_OFFLINE=1, TRANSFORMERS_OFFLINE=1, and HF_DATASETS_OFFLINE=1. They also set HF_HUB_DISABLE_TELEMETRY=1, DISABLE_TELEMETRY=1, and DO_NOT_TRACK=1. The openmed-internal network is internal, so containers have no default egress-capable network after images and model artifacts are prepared.
The default port mapping is 127.0.0.1:8080:8080. Changing OPENMED_BIND_ADDRESS requires authentication, TLS, and an explicit trusted host policy. The bundle defaults to OPENMED_PROFILE=prod, whose security profile keeps the API closed until authentication is configured and, because the bundle enables Journey storage, until Journey principal binding and encryption ship; set OPENMED_PROFILE=dev to evaluate it locally. The deployment posture lane checks this file against the production contract offline, including the offline and telemetry flags of every OpenMed service. A remote integration requires a separately declared network and a documented egress allowlist. Telemetry is opt-in and must remain value-free.
Connection and request-body bounds¶
The openmed service sets OPENMED_SERVICE_LIMIT_CONCURRENCY=128, OPENMED_SERVICE_TIMEOUT_KEEP_ALIVE=5, and OPENMED_SERVICE_TIMEOUT_GRACEFUL_SHUTDOWN=30 for the reference launcher, and OPENMED_SERVICE_REQUEST_BODY_TIMEOUT_SECONDS=60, OPENMED_SERVICE_REQUEST_BODY_GRACE_SECONDS=10, and OPENMED_SERVICE_REQUEST_BODY_MIN_BYTES_PER_SECOND=1024 for request bodies. Override any of them in the shell that runs Compose. Keep the graceful-shutdown timeout below the service's 45s stop grace period. A stalled or trickling upload returns 408 request_body_timeout, and connections beyond the limit receive 503. The REST service guide describes each bound.
Backup and restore¶
Use application-consistent backups: stop admission and the worker, wait for in-flight work to finish, then capture PostgreSQL and the artifact volume as one named recovery point. pg_dump --format=custom is preferred for logical database backups. Use the storage platform's snapshot or backup tool for openmed-cache; never copy a live volume with a generic recursive command.
Record, outside the backup payload, the OpenMed image digest, PostgreSQL major version, Journey schema version, artifact snapshot identity, and UTC recovery point. Encrypt the backup and test restore into a separate namespace. After restore, run openmed-journey migrate, then journey-golden, before admitting traffic. Never run a restore over the active database or artifact volume.
For local SQLite Journey stores, job metadata, registry state, and audit chains, openmed recovery creates encrypted, integrity-checked recovery points and restores them into an inactive directory before an explicit activation; see Encrypted Service Backup and Restore.
Upgrade and rollback¶
Pin immutable image digests in production. Before an upgrade:
- take and verify one application-consistent backup;
- read the target release's schema compatibility window;
- pull/build images before the outage window;
- let the one-shot migration gate finish before replacing API or worker processes;
- run the golden journey and inspect all five component states.
Journey migrations are additive and checksum-verified. Roll back only to an image whose documented compatibility major accepts the current persisted schema. A container rollback does not reverse durable migrations. If the old image is incompatible, keep traffic stopped and restore the paired database and artifact recovery point into new volumes.
Database secret rotation¶
Use overlapping credentials so a secret rotation does not strand old containers:
- create a second least-privilege PostgreSQL role with the same schema grants;
- update the host secret source for
OPENMED_POSTGRES_PASSWORDandOPENMED_JOURNEY_POSTGRES_DSNand recreate migration, worker, and API containers in that order so Compose rewrites the secret files; - verify the component health report and golden journey;
- revoke the old role, then remove it after the rollback window.
Do not log either credential or place it on a command line visible to other host users. Rotation changes authentication only; it must not change the Journey schema or delete the old recovery point.
This deployment mechanism is operational packaging, not a compliance certification or a clinical decision guarantee.