govoplan/docs/DEPLOYMENT_PROFILES.md

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.