Move old docs into _old_structure dir. Create blank GETTING_STARTED.md document

2026-08-10 14:53:21 -05:00
parent 1655b1579a
commit cd4409abc3
273 changed files with 278 additions and 247 deletions
@@ -0,0 +1,67 @@
+# Deployment Guide
+
+> **Status: non-operative for PostgreSQL, federated, 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.
+
+## 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:
+
+```bash
+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 route, or
+start Gateway/Web until KBN-101-02 supplies fail-closed local-tier/DSN isolation.
+
+## Held future procedure
+
+PostgreSQL local, federated, 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 deployment, or production readiness.