stack/docs/guides/deployment.md

kind, status

kind	status
guide	active

Deployment Guide

Status: non-operative for PostgreSQL, federated (federation is frozen — PRD rev1 D3 as amended; not a v1 route), and bare-metal production. The checked-in Compose PostgreSQL service mounts legacy initialization SQL and the KBN-101 bootstrap, runner, secret-renderer, and process-exec interfaces do not exist yet. This page does not authorize a production deployment, database initialization, manual DDL, secret provisioning, or service activation.

Relationship to the PRD (D15)

Per PRD rev1 Decision D15 (docs/PRD.md), the compose standalone tier — docker compose up — is the canonical v1 deployment topology; this guide describes the interim path to that bar, not a competing one. The KBN-101 holds documented below (bootstrap, runner, secret-renderer, process-exec) are operational gates on the road to the standalone-tier bar, not an alternative or federated topology. They remain fully binding: nothing in this guide authorizes PostgreSQL, federated, or bare-metal production activation until the named KBN-101-00/03/05 artifacts land, pass review, and satisfy the order specified below. Federation M1–M3 references elsewhere in this guide are historical/frozen (PRD rev1 D3 as amended) and do not describe a live or v1-bound route.

Current safe local route

Use PGlite only for current in-process data-layer work; it requires no PostgreSQL. A Gateway/Web local process is held because its unguarded dotenv loader can inherit a daemon PostgreSQL DSN and reach runtime DDL. If a local queue service is useful, start only Valkey:

docker compose up -d valkey

This command intentionally does not start PostgreSQL. Do not run a broad Compose start, use its PostgreSQL initialization mount, infer that current Compose is a production/federated (federation is frozen — PRD rev1 D3 as amended; not a v1 route) route, or start Gateway/Web until KBN-101-02 supplies fail-closed local-tier/DSN isolation.

Held future procedure

PostgreSQL local, federated (federation is frozen — PRD rev1 D3 as amended; not a v1 route), Compose, and bare-metal production activation are held until these artifacts land and pass their independent gates:

1. KBN-101-00 external privileged bootstrap artifact;
2. KBN-101-03 sole mosaic-db-migrator runner and verified-readiness artifact; and
3. KBN-101-05 Vault/secret-renderer-backed deployment and consumer-isolation artifact.

The required future order is external bootstrap → TLS/roles → mosaic-db-migrator --run → mosaic-db-migrator --verify → Gateway/Compose readiness.

This is a held, non-operative future activation specification with no current command authority. Do not invoke the named runner, start PostgreSQL, or substitute a Compose/init/manual-SQL route until the owned artifacts are implemented and reviewed.

Future production secret and unit boundary (schematic only)

No current bare-metal production unit or command is published. KBN-101-05 must supply a reviewed, generation-pinned Vault renderer and a process-exec or systemd LoadCredential interface before production units can exist. The interface must preserve these exact consumer boundaries:

Consumer	May receive	Must never receive
Gateway/runtime	Its own runtime URL and DB client CA at process exec	Migrator URL, importer URL/version, attestation material, signing key, PostgreSQL private key
One-shot migrator	Its own migration URL, DB client CA, and runner-only signing capability	Runtime URL, importer consumer copy, Gateway/private PostgreSQL keys
Data importer	Its own immutable URL/version copies, importer CA, pinned public key, and sealed attestation	Runtime/migrator URLs, signing key, shared writable mount
PostgreSQL	Its own server certificate/key and only its approved server material	Application, migrator, importer, or Gateway secrets

A future unit specification is non-executable until KBN-101-05 supplies it. It must obtain credentials through the renderer’s Vault generation and process-exec/LoadCredential boundary; it must not place credentials in a production environment file, a monorepo auto-load path, a shell export, command arguments, logs, or a manual secret-activation lifecycle instruction. Rotation and process replacement semantics must be delivered by the reviewed renderer/interface with generation, consumer-isolation, mode/owner, and no-mixed-generation evidence—not improvised in this guide.

Readiness and troubleshooting status

Until the future procedure is implemented, do not diagnose PostgreSQL with ad hoc SQL, connection strings, or initialization scripts. The future sanitized runner-verification readiness artifact is the required PostgreSQL readiness authority after its bootstrap/TLS prerequisites pass. For local PGlite development, diagnose application behavior without introducing a PostgreSQL connection.

Non-database local services may be inspected with their ordinary local health/log tools. Those checks do not certify PostgreSQL, federated (federation is frozen — PRD rev1 D3 as amended; not a v1 route) deployment, or production readiness.