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..ffb94b0 --- /dev/null +++ b/Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY.-.md @@ -0,0 +1,186 @@ + + +> 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 without optional modules. 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/add-ideas/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. No optional GovOPlaN module package is installed. +- **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. No optional module is installed or enabled at this point. + +### 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 + +1. **Reproducible Core-only distribution.** Publish pinned multi-architecture + images, signed distribution manifest, Core-only 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.** Move the existing catalog and module + directory contracts into the installed Core WebUI with compatibility, + provenance, release-note, and update-state presentation. +4. **Durable module plan and install.** Reuse the existing installer queue, + locks, signed-package validator, rollback drill, and run evidence behind a + plan/confirm/progress UI. Add initial catalog-entry synthesis and artifact + acquisition where the current release console still assumes local sources. +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.** Remove remaining local-runtime assumptions, + expose role-specific commands/images, implement worker registration/drain, + and prove multiple API and worker replicas against 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 + +- Shipping optional modules in the Core image. +- 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.