From b300273a551fcefd70e79f077089f0f4c7e87743 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Thu, 30 Jul 2026 15:27:44 +0200 Subject: [PATCH] Sync wiki from project files --- ...NSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md | 26 +++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md b/Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md index 783cac1..0d65a2d 100644 --- a/Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md +++ b/Repo-docs-INSTALLATION-AND-DEPLOYMENT-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md`. > Origin: `repository`. @@ -34,10 +34,16 @@ It currently supports: - Core, base, or full initial module selections; - deterministic Compose JSON accepted by Compose v2; - generated secrets stored in a private `0600` file; +- service-specific environment allowlists so infrastructure containers do not + receive unrelated application credentials; - plan, render, doctor, status, and apply commands; - an installation lock, migration-before-start ordering, readiness polling, and an applied-state receipt; - idempotent reconfiguration that preserves generated secrets; +- a keyed environment fingerprint that detects private binding changes without + writing secret values to plans or receipts; +- host CPU, memory, disk, entropy, architecture, Docker daemon, Compose, + listen-port, and external endpoint preflight checks; - service removal without implicit data-volume deletion. Create a local evaluation bundle: @@ -108,6 +114,10 @@ a production distribution: 5. **Deployment agent.** Web updates need a separate privileged reconciler with a typed command allowlist. The API and browser must never receive the Docker socket or arbitrary shell access. +6. **Ingress and certificates.** A self-hosted profile needs an explicit choice + between an existing reverse proxy and a supported managed ingress, including + trusted-proxy boundaries, TLS certificate issuance, renewal, and health + probing through the public route. `apply --allow-unverified-images` is therefore restricted to the evaluation profile. It explicitly acknowledges both mutable image identities and @@ -123,6 +133,10 @@ credentials. `external` requires an explicit `DATABASE_URL`; switching from managed to external cannot reuse the old `postgres` Docker hostname accidentally. +Interactive entry hides external URLs because they commonly contain +credentials. For unattended automation, provide them through a protected +operator mechanism and avoid storing secret-bearing flags in shell history. + Production policy should support external managed databases and local managed PostgreSQL equally at the application boundary. Backup, point-in-time recovery, high availability, and major-version upgrades remain deployment properties. @@ -133,6 +147,10 @@ high availability, and major-version upgrades remain deployment properties. requires an explicit `REDIS_URL`. `disabled` is evaluation-only and disables workers while recording the single-process login-throttle risk acknowledgement. +`doctor` performs a bounded TCP connection check for external PostgreSQL, +Redis, and S3 endpoints. This verifies DNS, routing, and that the port accepts a +connection; it is not an authentication or semantic health check. + Production base installations include Redis because durable queues, distributed throttling, notifications, scheduled work, and transactional event delivery must survive API restarts. @@ -172,6 +190,8 @@ applied state. `plan` compares their canonical hashes and service sets. deliberately destructive workflow. - Existing generated credentials are retained unless an explicit future rotate operation is requested. +- Private configuration changes are represented by a keyed fingerprint in the + plan and receipt; plaintext values are never copied there. - Managed-to-external transitions require the new endpoint in the same operation. - Migrations run as a one-shot service before API/worker replacement. @@ -230,4 +250,6 @@ Run the focused tests: The tests cover profile restrictions, secret persistence, external endpoint requirements, S3 policy, Compose service selection, secret non-disclosure, -private file modes, first-plan generation, and receipt-based idempotency. +service-specific environment isolation, private file modes, external endpoint +preflight, first-plan generation, apply ordering, and receipt-based +idempotency.