GovOPlaN/govoplan
1
0
Fork 0
Code Issues 10 Pull Requests Actions 3 Packages Projects Releases Wiki Activity

Sync Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY from project files

zemion
2026-07-21 16:34:26 +02:00
parent 636c17c2a4
commit 226bd773f2
1 changed files with 186 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY.-.md Normal file

@@ -0,0 +1,186 @@
<!-- codex-wiki-sync:afd3fc9c99763c56738e3dbe -->
> 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.