DDX Install — Full-Stack Installer & Tenant Provisioner CLI

DDX Install — Full-Stack Installer & Tenant Provisioner CLI

ddx-install is a single Node CLI that brings the whole DDX HMS stack (8 infra services + the app tier + HAPI FHIR) up on a new server from a git clone. It is an orchestrator + wiring engine — it wraps the proven ddx-docker-full-hms scripts rather than reimplementing them — and its net-new value is a typed env-wiring engine that resolves the cross-module shared-key graph that otherwise fails silently.

Business Purpose

Standing up DDX HMS on a fresh host is hard not because any single step is hard, but because ~720 environment variables across 19 services collapse to ~36 shared logical keys, 17 of which are critical: a mismatch produces no error — just 401s, "Connecting…" hangs, or services that refuse to boot. ddx-install makes deployment reproducible and auditable: an operator (or an unattended JSON file) selects a trigram + port block, and the CLI mints secrets, wires every module's .env, validates the manifest, brings the compose stack up, migrates 5 schemas, seeds platform data, and prints the portal URL — gating on a parity check that catches the silent-mismatch class before any service starts.

This is the on-prem / partner-deployment workhorse. It is distinct from the in-API tenant-provisioner (which onboards a clinic inside an already-running stack); ddx-install brings the entire stack up.

Audiences

• Internal (ops/deployment): One command (ddx-install unattended <file>) takes a clean host to a live, seeded, FHIR-backed stack. Resumable — re-running skips completed steps; --force re-runs all.
• Developer: The wiring engine is the interesting part. wiring-graph.json is the data spine; wiring-engine.ts resolves it; execute.ts runs the 11-step pipeline and asserts 6 critical contracts before any mutation.
• Partner: Deploy DDX HMS into customer-owned infrastructure with a typed, validated wiring layer instead of hand-edited env files.

Architecture

The core principle (plan shard _index.md §3): wrap, do not reimplement. execute.ts shells out (via execa) to the existing validate-manifest.sh, generate-secrets.sh, manifest-to-env.sh, and docker compose — it never mints its own secrets or writes its own compose file.

Tech Stack & Choices

The 10 commands (cli.ts)

Data Flow

Attended vs unattended convergence

Both modes resolve to one ResolvedTenantConfig, then converge on runExecute():

env-journal/*.md → wiring-graph.json (curated, typed)
tenant-unattended.json (or wizard) → ResolvedTenantConfig
ResolvedTenantConfig → toManifest()/toSecretsSeed() → manifest.json + secrets.json
                     → wiring-engine.wire() → per-module .env / .env.local

Secrets are never inlined: external provider keys use ENV:VARNAME indirection; the CLI mints all internal hex32 secrets itself.

The 11-step EXECUTE pipeline (execute.ts:runExecute)

Computed up front: the wire + recap + 6 contract checks run BEFORE any mutation. If any contract fails, the run aborts before touching docker.

1. validate-manifest.sh (pre)
2. generate-secrets.sh (idempotent — keeps real values)
3. wiring-engine emit (per-module .env/.env.local, chmod 600)
4. validate-manifest.sh (post) 4b. manifest-to-env.sh → .env.<trigram> (the compose --env-file)
5. docker compose -p ddx-hms-<trigram> up -d --build
6. wait postgres-main healthy (pg_isready, 60s)
7. db-init (migrations owned by the compose db-init service)
8. wait ddx-api healthy (/api/v1/health, 60s)
9. ddx-seeder profile container (org + FHIR partition + MinIO buckets + phases)
10. optional profiles (voice / jitsi / vivoxx / calendar per capabilities)
11. print portal URL + health summary

The 6 critical contracts (assertContracts)

• C1 NEXT_PUBLIC-before-build — structural: wire (step 3) precedes compose build (step 5); the wiring-engine NEXT_PUBLIC guard rejects any secret-kind key emitted to a NEXT_PUBLIC_* var.
• C2 flowagent amd64 — ddx-flowagent pinned linux/amd64 (onnxruntime native).
• C3 pnpm 9.15.4 — pinned in all module Dockerfiles.
• C4 AC-7 voice-key parity — GATEWAY_API_KEY_VOICE (ddx-api) == DDX_API_KEY (ddx-flowagent), plus the other 16 critical edges.
• C5 RBAC=enforce — RBAC_ENFORCEMENT=enforce (graph forcedValue, and the ddx-docker-full-hms compose default ${RBAC_ENFORCEMENT:-enforce}). Only the bare application code-level fallback is warn, so the installer pins enforce explicitly.
• C6 on-prem saas=false — manifest.internal.saas=false → SAAS_ENABLED=false.

Implicated Code

• ddx-install/src/cli.ts:49 — COMMANDS catalogue; drives commander registration + interactive menu
• ddx-install/src/core/execute.ts:524 — runExecute(); the 11-step pipeline; assertContracts() at :254
• ddx-install/src/core/execute.ts:495 — apiHealthy(); unwraps {data,meta} envelope (body.data?.status ?? body.status)
• ddx-install/src/core/execute.ts:389 — authoritative 15-key internalKeys secrets contract (mirrors manifest-to-env.sh reads)
• ddx-install/src/core/wiring-engine.ts — loadWiringGraph() + wire(); parity + NEXT_PUBLIC guard
• ddx-install/src/core/map-unattended.ts — toManifest() / toSecretsSeed() (must satisfy canonical manifest.schema.json, additionalProperties:false)
• ddx-install/data/wiring-graph.json — 36 logical keys, 17 critical edges, 14 consumer modules
• ddx-docker-full-hms/scripts/provision-tenant.sh — the canonical 9-step provisioner the CLI wraps

Operational Notes

• It wraps, it doesn't build. ddx-install never writes its own compose file or mints secrets — bugs in the underlying scripts surface as installer failures. Schema lives at the umbrella root tenant-data/_template/manifest.schema.json.
• Docker-mode migrations are compose-owned. Step 7 is a no-op in Docker-first mode — the db-init compose service runs prisma migrate deploy ×5 in its own container. The host has no prisma toolchain; a host-side migrate would be redundant and broken (that path belongs to the v2 PM2 mode only).
• 15-key secrets contract. manifest-to-env.sh reads exactly 15 keys from secrets.json (minioRootPassword, pgPassword, jwtSecret, …). Any missing key emits the literal string "null" into .env.<trigram> → the service FATALs at boot (e.g. minio "MINIO_ROOT_PASSWORD length should be at least 8").
• AC-7 parity is the safety net. The recap shows PASS/FAIL for all 17 critical edges. Never trust a run that shows a FAIL — re-wire first.
• NEXT_PUBLIC guard. Never emit a secret to a NEXT_PUBLIC_* var (known offender: NEXT_PUBLIC_KOKORO_TTS_TOKEN bakes a bearer token into the client bundle — correct pattern is server-only KOKORO_TTS_TOKEN + a TTS proxy route).
• DDX_API_URL is a build-time edge. ddx-web's next build hard-throws "API_URL or DDX_API_URL must be set in production" — added to the graph as a Next.js logical key (docker → http://ddx-api:4100, host → http://localhost:<api port>).

Related Topics

• Go Live from Git Clone — the step-by-step runbook that drives this CLI end-to-end
• Tenant Provisioner — onboards a clinic inside a running stack (vs ddx-install which brings the whole stack up)
• Full HMS Compose Infrastructure — the 19-service compose backbone the installer wraps
• FHIR Partitions and Tenancy — per-tenant FHIR partition created during seeding
• Proxy Gateway — the gateway-key edges the wiring engine resolves