From e193717dc0cb23e6f360e133453e16531444ca02 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Thu, 6 Aug 2026 22:52:03 +0200 Subject: [PATCH] Sync Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY from project files --- ...EM-ADMINISTRATOR-LIFECYCLE-USER-STORY.-.md | 219 ++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY.-.md diff --git a/Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY.-.md b/Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY.-.md new file mode 100644 index 0000000..a49bfc4 --- /dev/null +++ b/Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY.-.md @@ -0,0 +1,219 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan/docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# System Administrator Lifecycle User Story + +## Story + +> As a system administrator, I can execute one shell command that downloads a +> verified GovOPlaN distribution and starts a completely configured Core control +> plane with the official package directory available but only the protected +> baseline active. In the WebUI I can browse compatible signed +> module releases, select the modules for this installation, and follow every +> download, validation, migration, installation, activation, and health-check +> step. When an update is available, I can review its impact and confirm it. +> +> I can add API or worker replicas on containers or other servers without +> copying mutable local state. I can operate development, test, and production +> systems, transfer a versioned configuration through the WebUI, undo an applied +> configuration version, test an update in one environment, and then apply the +> same immutable update recipe to another environment. + +This is a product-level story owned by the GovOPlaN platform rather than by an +individual domain module. It joins installation, module lifecycle, operations, +configuration packages, and release provenance into one administrator journey. +The canonical backlog item is +[GovOPlaN #13](https://git.add-ideas.de/GovOPlaN/govoplan/issues/13). + +## Terms + +- **Core control plane:** the smallest bootable distribution: Core API, Core + WebUI, PostgreSQL, Redis, installer worker, migration runner, and durable + storage configuration. An immutable image may carry the full verified package + profile, but optional modules are not active or tenant-entitled by implication. +- **Bootstrap administrator:** a single-use, time-limited installation identity + that may access only first-run and module-lifecycle functions. It is retired + when the selected identity/access configuration becomes healthy. +- **Module release:** an immutable, signed package plus manifest, compatibility + contract, migrations, WebUI contribution, checksums, and SBOM references. +- **Configuration revision:** an immutable, schema-versioned export of + non-secret system/module settings, policies, compositions, and secret + references. Secret values are never exported. +- **Update recipe:** the reviewed, immutable plan containing exact Core/module + versions, configuration revision, migration order, preflight results, + maintenance/drain requirements, health checks, and permitted rollback or + forward-recovery actions. + +## Acceptance journeys + +### One-command first installation + +1. The administrator runs one documented command on a supported host. +2. The bootstrapper verifies a signed distribution manifest before executing or + starting downloaded artifacts. +3. It checks container/runtime, ports, storage, entropy, memory, architecture, + and connectivity requirements; generates deployment-local secrets with + restrictive permissions; and never prints them. +4. It starts PostgreSQL, Redis, Core API/WebUI, one installer worker, and the + migration runner. Readiness does not pass until migrations and durable + dependencies are healthy. +5. It prints the local URL and one-time bootstrap credential. Re-running the + command is idempotent and shows or repairs the existing installation rather + than creating another identity or database. +6. Only the protected baseline is enabled. Installed package availability does + not grant permissions, tenant entitlement, View visibility, or capability + opt-in. + +### Module selection, installation, and update + +1. Core reads an approved signed catalog and trusted keyring through the shared + outbound-network policy. +2. The WebUI shows available, installed, compatible, blocked, withdrawn, and + update-available releases with their channel, provenance, contracts, + migrations, permissions, configuration requirements, and release notes. +3. Selecting modules produces a dependency/compatibility plan before any + mutation. The administrator can amend the selection or confirm the plan. +4. Installation executes durably in a worker. The UI receives persisted step + state and can reconnect without losing progress. +5. Package signature/checksum, version alignment, contract closure, migration + graph, configuration schema, and health checks are mandatory gates. +6. Remote artifacts are acquired by a deployment-owned downloader that permits + approved origins, pins the validated connection peer, enforces size and time + limits, and verifies signature/checksum before making a local immutable + artifact available. `pip`, `npm`, archive tools, and any compatibility Git + importer then run without unrestricted network access. A restricted-network + profile can satisfy the same contract through operator-prefetched artifacts. +7. A failed or interrupted operation reaches a visible retry, forward-recovery, + rollback, or manual-intervention state. It never reports success merely + because the initiating request returned. +8. An available update follows the same preview and confirmation path. Exact + repeated requests are idempotent. + +### Horizontal scaling + +1. API, WebUI, installer, scheduler, and ordinary worker roles are stateless + with respect to local container disks. Durable state uses PostgreSQL, Redis, + and configured shared file/object storage. +2. A documented command can add API or queue-specific worker replicas. The + default Compose profile supports local scale-out; an orchestrator profile + supplies equivalent health/readiness probes and rolling replacement. +3. Only one migration or module-lifecycle mutation may own the deployment lock, + while any healthy replica can serve read and normal domain traffic. +4. Workers announce identity, queues, software composition, heartbeat, and + drain state. Operators can see skew and safely retire a replica. +5. Sessions, throttling, idempotency, jobs, installer progress, and scheduled + work remain correct when requests move between replicas. + +### Development, test, and production promotion + +1. The administrator exports a configuration revision from development through + the WebUI. The package is versioned, checksummed, attributable, and contains + secret references or required-secret declarations, never secret values. +2. Test imports the package into a preview area. Core reports environment-bound + values, missing capabilities/secrets, compatibility changes, and the exact + apply plan. +3. Applying creates a new revision; the previous effective revision remains + addressable. Undo is a new audited revision that restores the earlier + configuration where contracts permit it. +4. After tests and health checks pass, Core emits an update recipe with exact + immutable release and configuration identifiers. +5. Production validates the recipe against its own environment, requires a new + confirmation, and executes the same ordered plan. Environment-specific + secret bindings and endpoints remain local. +6. Promotion never copies tenant/business data implicitly. Data migration, + anonymized fixtures, and backup/restore are separate explicit operations. + +## Safety and governance requirements + +- Catalogs, artifacts, recipes, and configuration revisions have signatures, + checksums, provenance, expiry/revocation semantics, and audit evidence. +- Catalog and artifact retrieval is not delegated to an unrestricted package + manager. Approved-origin and peer-pinned download, response bounds, + signature/checksum verification, extraction safety, offline installation, and + deployment egress policy form separate defenses. +- The installer has a dedicated narrow authority; normal domain permissions do + not imply host/package-management access. +- The UI distinguishes reversible configuration rollback from database or + package migrations that require forward recovery. +- Cluster-wide mutations use fencing/leases so an expired worker cannot later + commit a stale result. +- Update plans declare availability impact, worker draining, backup/restore + prerequisites, database compatibility windows, and post-change probes. +- Deployment profiles set secure headers, trusted proxies/hosts, body limits, + outbound-network policy, storage, TLS/cookie posture, and observability. +- Release publication requires aligned backend/frontend/manifest versions and + machine-readable dependency/SBOM provenance. + +## Implementation slices + +Implementation status as of the current source tree: + +- Slice 1 has a published production-artifact baseline. Immutable + [`v0.1.14`](https://git.add-ideas.de/GovOPlaN/govoplan/releases/tag/v0.1.14) + binds source commit `1f039dd39c1ce2672f4978c8abc6dff862ef1445`, a signed + one-file deployer, exact API/Web and managed-dependency image digests, + composition, SBOMs, and provenance. Runtime Distribution + [run #459](https://git.add-ideas.de/GovOPlaN/govoplan/actions/runs/459) + passed migrations, schema checks, non-root API/Web readiness, and worker + delivery/shutdown on both amd64 and arm64. Each future release must renew the + evidence, and a real installation must still produce topology-specific + ingress, failover, backup, and recovery receipts. +- Slice 6 has a working application-tier foundation: state profiles, shared + object storage, runtime node registration/heartbeats/drain, fenced scheduler, + migration serialization, exact-head startup waiting, Ops visibility, and a + Kubernetes export. Production acceptance still requires topology-specific + failover and restore drills. +- The recovery foundation for slices 4 and 5 is implemented as a Core recovery + ledger and deployment operation journal. Automatic database backup and broad + adoption by module-owned external effects remain open work. + +1. **Reproducible Core-baseline distribution.** Publish pinned multi-architecture + full-package images, signed distribution manifest, Core-baseline Compose profile, bootstrap + preflight, generated secrets, readiness, and idempotent rerun/repair. +2. **First-run control plane.** Add the restricted bootstrap administrator, + one-time enrollment, initial catalog/keyring configuration, and retirement + after durable administrator access is established. +3. **Read-only online module directory (implemented foundation).** Admin falls + back to the signed public stable directory, presents installed/update state, + searchable availability/blocker filters, immutable source/artifact + provenance, configuration requirements, release notes, and technical + compatibility. Withdrawn releases remain visible but cannot be planned. + Operator-configured catalogs remain an explicit override. +4. **Durable module plan and install (implemented local boundary).** Catalog + selection creates a reviewed plan; the installer queue, lock, preflight, + maintenance gate, digest-verified artifact cache, rollback drill, and run + evidence remain separate from the API process. Shared deployments convert + the same intent into a new immutable release composition instead of mutating + one replica. +5. **Safe module update.** Add drain/maintenance coordination, backup gate, + migration compatibility window, reconnectable progress, health verification, + retry/recovery, and update notification. +6. **Stateless replica profile.** Continue module adoption and operational + proof for the implemented role commands, shared-state validation, runtime + registration/drain, fenced scheduler, and Kubernetes application-tier + export. Prove multiple API and worker replicas against the target shared + dependencies. +7. **Configuration revision model.** Define provider export/import schemas, + canonical serialization, secret references, validation/diff, immutable + revision storage, audit, apply, and undo-as-new-revision. +8. **Environment promotion and recipes.** Add source/target fingerprints, + preview, environment bindings, acceptance evidence, exact recipe generation, + signed transfer, and independently confirmed application. +9. **Operational proof.** Exercise interrupted installs, stale locks, unavailable + catalogs, revoked keys, failed migrations, replica loss, configuration undo, + and development-to-test-to-production promotion in release CI and target + drills. + +## Explicit non-goals for the first distribution slice + +- Activating, tenant-entitling, or exposing optional modules merely because the + immutable image carries their verified packages. +- Exporting secrets or production business data with configuration. +- Pretending every schema migration can be reversed automatically. +- Building a proprietary orchestrator instead of supporting Compose and a + standard cluster scheduler through the same role/readiness contracts. +- Allowing the browser process to execute arbitrary shell commands.