From 7b0ab31adf981cd6d772ae68a836f21fc5ffa87c Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Wed, 5 Aug 2026 22:42:27 +0200 Subject: [PATCH] Document GovOPlaN deployment profiles --- README.md | 4 + dev/production-like/README.md | 4 + docs/DEPLOYMENT_PROFILES.md | 104 ++++++++++++++++++ ...NSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md | 4 + docs/README.md | 1 + 5 files changed, 117 insertions(+) create mode 100644 docs/DEPLOYMENT_PROFILES.md diff --git a/README.md b/README.md index 2d3c2ac..02411f7 100644 --- a/README.md +++ b/README.md @@ -171,6 +171,10 @@ Create and validate a private, declarative installation bundle: The current executable slice and remaining production gates are documented in [Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md). +The canonical distinction between local source development, split source +integration, immutable single-host rehearsal, one-host production and +multi-host Kubernetes production is in +[Deployment Profiles](docs/DEPLOYMENT_PROFILES.md). Same-host replica balancing and the multi-host promotion boundary are documented in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md). Create, update, pause, resume, verify and remove a local or multi-hypervisor K3s diff --git a/dev/production-like/README.md b/dev/production-like/README.md index 759b25e..9605801 100644 --- a/dev/production-like/README.md +++ b/dev/production-like/README.md @@ -2,6 +2,10 @@ This profile runs the shared services that production depends on while keeping API, worker, scheduler, and WebUI code in the editable local repositories. +It is the **split source integration** profile defined in +[`docs/DEPLOYMENT_PROFILES.md`](../../docs/DEPLOYMENT_PROFILES.md). It does not +exercise signed application images. Use an installer-generated evaluation +Compose bundle for an immutable Dockerized whole-product rehearsal. It provides: diff --git a/docs/DEPLOYMENT_PROFILES.md b/docs/DEPLOYMENT_PROFILES.md new file mode 100644 index 0000000..1f68e19 --- /dev/null +++ b/docs/DEPLOYMENT_PROFILES.md @@ -0,0 +1,104 @@ +# GovOPlaN Deployment Profiles + +## Purpose + +GovOPlaN distinguishes how code is executed, where it is placed, and how mature +the target is. These are separate concerns: + +- **execution basis:** editable source trees or an immutable signed release; +- **topology:** local processes, one-host containers, or a multi-host + orchestrator; +- **component ownership:** installer-managed or externally supplied state and + infrastructure services; and +- **assurance state:** development, rehearsal/acceptance, or approved + production. + +PostgreSQL, Redis, object storage, mail and ingress choices are component +bindings inside a profile. They do not create a new application topology by +themselves. + +## Canonical Profiles + +| Profile | Entry point | Application execution | State services | Intended use | Explicit boundary | +| --- | --- | --- | --- | --- | --- | +| Local source development | `tools/launch/launch-dev.sh` | Editable Uvicorn/Vite processes with reload | Local development bindings, optionally the shared PostgreSQL helper | Fast module and UI work | No production packaging, isolation, availability or capacity claim | +| Split source integration | `tools/launch/launch-production-like-dev.sh` | Editable API, WebUI, worker and scheduler processes | Containerized PostgreSQL/Redis by default; environment bindings may point at developer-owned services | Queue, migration, Redis and split-role integration while retaining source reload | “Production-like” describes behavior, not immutable artifacts or a production security boundary | +| Immutable single-host rehearsal | `govoplan-deploy init/apply --profile evaluation` | Signed API/WebUI images and generated Compose roles | Bounded managed components or explicit external bindings | Test the downloadable artifacts, installer, migrations, load balancer and component choices | All containers and managed services may share one host and failure domain; evaluation conveniences are not production controls | +| Single-host production | `govoplan-deploy init/apply --profile self-hosted` | Signed API/WebUI images behind generated HAProxy and selected TLS ingress | Durable local/single-node managed services where accepted, or external services | Small and medium installations whose accepted availability boundary is one host | Multiple containers add capacity and rolling-process resilience, but do not survive host loss | +| Multi-host Kubernetes production | `govoplan-deploy render-kubernetes` or the guarded K3s lab/acceptance workflow | Immutable API, WebUI and queue-specific worker Deployments across failure domains | External PostgreSQL, Redis and S3-compatible storage; external secret and ingress control | Institution-scale availability and horizontal application-tier capacity | Production claims require independent nodes, HA state services, load/capacity evidence and signed recovery evidence | + +Docker Compose services are containers or replicas, not Kubernetes pods. The +immutable single-host rehearsal is the appropriate Dockerized whole-product +test when source reload is not required. + +The K3s VM lab has two modes over the same Kubernetes profile: + +- `rehearsal` may place VMs on one physical hypervisor and proves bounded + orchestration behavior; +- `acceptance` requires independently controlled worker failure domains and can + contribute target evidence. + +## Component Choices + +The installer may manage a component where its bounded profile is appropriate, +or consume an operator-provided service: + +| Component | Managed boundary | External/BYO boundary | +| --- | --- | --- | +| PostgreSQL | Single-host Compose database | Stable primary-aware endpoint supplied by a PostgreSQL provider/operator | +| Redis | Single-host persistent Redis | Tested HA Redis endpoint compatible with queues, throttling and coordination | +| File/object storage | Durable local storage or single-node Garage | Shared, redundant S3-compatible storage | +| Mail | Development GreenMail only | Institution/provider SMTP and IMAP services | +| Ingress/TLS | Generated Caddy on one host | Existing reverse proxy or Kubernetes ingress and secret management | + +Switching to an external component changes ownership and evidence requirements; +it does not remove GovOPlaN's health, capacity, backup and recovery checks. + +## Scaling Responsibilities + +GovOPlaN scales application roles, while the infrastructure control plane owns +machines and state-service replication: + +| Concern | Scaling model | Owner | +| --- | --- | --- | +| API and WebUI | Increase replicas behind health-aware Services/Ingress | GovOPlaN deployment desired state, reconciled by Compose or Kubernetes | +| Background work | Add queue-specific worker replicas and bounded concurrency | GovOPlaN deployment desired state and worker-pool configuration | +| Scheduler, migrations and module lifecycle | Singleton execution protected by database leases/fencing | GovOPlaN; these roles are never scaled as unfenced active-active workers | +| Kubernetes worker/control nodes | Add, drain, replace and upgrade machines; optionally use a cluster autoscaler | Kubernetes/platform operator, not the GovOPlaN application | +| PostgreSQL | Replication, failover, backups, connection pooling and stable writer endpoint | Database operator/provider; GovOPlaN currently consumes the stable endpoint and does not route arbitrary reads to replicas | +| Redis | Replication/failover, persistence, eviction and TLS/authentication | Redis operator/provider | +| S3-compatible storage | Placement, replication, repair and capacity | Storage operator/provider | + +Administrators should eventually be able to review and change permitted +application replica and worker-pool desired state through the Ops surface. +Creating physical machines, database replicas or storage members remains an +orchestrator/provider action. GovOPlaN must observe their health and block unsafe +changes rather than becoming a second infrastructure scheduler. + +Every scale change must recalculate the database connection budget, preserve +queue coverage, verify software/module-composition consistency and respect +drain and fencing state. + +## What Has Been Proven + +The current implementation and the signed `v0.1.18` rehearsal prove that the +application tier can run as stateless API, WebUI and worker replicas against +logically shared state. Two Kubernetes worker VMs hosted API and WebUI replicas, +and an API pod was replaced without an observed public-readiness failure. + +This is not yet proof of general “large organization fit.” That claim also +requires: + +- representative concurrent-user, dataset, report and background-job load + tests with latency and saturation budgets; +- independent physical failure domains and real ingress/network behavior; +- HA PostgreSQL, Redis and object storage with failover drills; +- session, accepted-job and provider-effect continuity under node and service + loss; +- coordinated backup/isolated restore, measured RTO/RPO and semantic recovery; +- observability, alerting, capacity forecasting and sustained soak evidence. + +The profile therefore proves the architecture is horizontally deployable. A +specific institution is production-fit only after its target topology and load +envelope have produced the governed evidence described in +`TARGET_MATURITY_EVIDENCE_RUNBOOK.md`. diff --git a/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md b/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md index 8c46f18..accf1e3 100644 --- a/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md +++ b/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md @@ -10,6 +10,10 @@ reconfigures that installation instead of creating unrelated state. The canonical product journey remains [System Administrator Lifecycle User Story](SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md). This document defines the deployer boundary and the first executable slice. +The execution, topology, component-ownership and assurance modes are defined +canonically in [Deployment Profiles](DEPLOYMENT_PROFILES.md). In particular, +the editable production-like developer launcher is distinct from both an +immutable Compose rehearsal and a supported one-host production deployment. ## First Executable Slice diff --git a/docs/README.md b/docs/README.md index f43e5de..3f0c615 100644 --- a/docs/README.md +++ b/docs/README.md @@ -39,6 +39,7 @@ second live status page. - [Platform Control Plane](PLATFORM_CONTROL_PLANE.md) - [Installation and Deployment Architecture](INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md) - [Kubernetes VM Test Lab](KUBERNETES_TEST_LAB.md) +- [Deployment Profiles](DEPLOYMENT_PROFILES.md) - [Scaling and Multi-Host Deployment](SCALING_AND_MULTI_HOST_DEPLOYMENT.md) - [Recovery and Rollback Guarantees](RECOVERY_AND_ROLLBACK_GUARANTEES.md) - [Recovery Ledger Adoption](RECOVERY_LEDGER_ADOPTION.md)