1

Repo docs SYSTEM ADMINISTRATOR LIFECYCLE USER STORY

Albrecht Degering edited this page 2026-07-28 12:48:59 +02:00

Table of Contents

• System Administrator Lifecycle User Story
• Story
• Terms
• Acceptance journeys
• One-command first installation
• Module selection, installation, and update
• Horizontal scaling
• Development, test, and production promotion
• Safety and governance requirements
• Implementation slices
• Explicit non-goals for the first distribution slice

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.

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.