Sync Repo-docs-SYSTEM-ADMINISTRATOR-LIFECYCLE-USER-STORY from project files
@@ -0,0 +1,219 @@
|
||||
<!-- codex-wiki-sync:84d06b54e13da549e49ecaa6 -->
|
||||
|
||||
> 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.
|
||||
Reference in New Issue
Block a user