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.

## Module composition and availability

Official immutable API and WebUI images carry the verified `full` package
profile. This is package availability, not runtime activation and not a license
or tenant entitlement. The signed distribution manifest records the complete
package composition; the desired module graph selects which installed modules
are active; tenant module policy applies unavailable/available/forced ceilings;
and Views/Policy control group and user presentation.

Local and single-host profiles may use the supervised installer to download a
signed catalog artifact into a private digest cache and mutate the local package
environment during maintenance. A multi-host/shared-state profile must never
change one replica in place. Its Admin install plan is a composition request:
publish and roll out a new signed image whose package lock contains the target,
then activate the module graph after all replicas report the same composition.

## 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`.