[User Story] One-command Core bootstrap, module lifecycle, scale-out, and environment promotion #13

New Issue

zemion · 2026-07-21T11:07:16+02:00

zemion commented

2026-07-21 11:07:16 +02:00

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.

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

The administrator runs one documented command on a supported host.
The bootstrapper verifies a signed distribution manifest before executing or
starting downloaded artifacts.
It checks container/runtime, ports, storage, entropy, memory, architecture,
and connectivity requirements; generates deployment-local secrets with
restrictive permissions; and never prints them.
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.
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.
No optional module is installed or enabled at this point.

Module selection, installation, and update

Core reads an approved signed catalog and trusted keyring through the shared
outbound-network policy.
The WebUI shows available, installed, compatible, blocked, withdrawn, and
update-available releases with their channel, provenance, contracts,
migrations, permissions, configuration requirements, and release notes.
Selecting modules produces a dependency/compatibility plan before any
mutation. The administrator can amend the selection or confirm the plan.
Installation executes durably in a worker. The UI receives persisted step
state and can reconnect without losing progress.
Package signature/checksum, version alignment, contract closure, migration
graph, configuration schema, and health checks are mandatory gates.
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.
An available update follows the same preview and confirmation path. Exact
repeated requests are idempotent.

Horizontal scaling

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.
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.
Only one migration or module-lifecycle mutation may own the deployment lock,
while any healthy replica can serve read and normal domain traffic.
Workers announce identity, queues, software composition, heartbeat, and
drain state. Operators can see skew and safely retire a replica.
Sessions, throttling, idempotency, jobs, installer progress, and scheduled
work remain correct when requests move between replicas.

Development, test, and production promotion

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.
Test imports the package into a preview area. Core reports environment-bound
values, missing capabilities/secrets, compatibility changes, and the exact
apply plan.
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.
After tests and health checks pass, Core emits an update recipe with exact
immutable release and configuration identifiers.
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.
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.
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

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.
First-run control plane. Add the restricted bootstrap administrator,
one-time enrollment, initial catalog/keyring configuration, and retirement
after durable administrator access is established.
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.
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.
Safe module update. Add drain/maintenance coordination, backup gate,
migration compatibility window, reconnectable progress, health verification,
retry/recovery, and update notification.
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.
Configuration revision model. Define provider export/import schemas,
canonical serialization, secret references, validation/diff, immutable
revision storage, audit, apply, and undo-as-new-revision.
Environment promotion and recipes. Add source/target fingerprints,
preview, environment bindings, acceptance evidence, exact recipe generation,
signed transfer, and independently confirmed application.
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.

# 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. ## 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. 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. 7. 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. - 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.

zemion commented

2026-07-21 16:34:41 +02:00

Codex State: note

Summary

Separated tenant connector egress from the deployment-owned installer artifact trust path.
Specified approved origins, connection-time peer pinning, size/time bounds, checksum/signature verification, safe extraction, offline package installation, and operator-prefetched restricted-network operation.

Changed Files

docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md
docs/REFERENCE_JOURNEY_PROGRAM.md

Verification

PYTHONPATH=. .venv/bin/python -m pytest -q -> 57 passed

Next / Blocked

Implementation remains in the staged administrator lifecycle slices; this update closes the artifact trust-model ambiguity only.

## Codex State: note ### Summary - Separated tenant connector egress from the deployment-owned installer artifact trust path. - Specified approved origins, connection-time peer pinning, size/time bounds, checksum/signature verification, safe extraction, offline package installation, and operator-prefetched restricted-network operation. ### Changed Files - `docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md` - `docs/REFERENCE_JOURNEY_PROGRAM.md` ### Verification - `PYTHONPATH=. .venv/bin/python -m pytest -q -> 57 passed` ### Next / Blocked - Implementation remains in the staged administrator lifecycle slices; this update closes the artifact trust-model ambiguity only.

zemion referenced this issue

2026-07-22 03:46:14 +02:00

[Feature] Make the Release Console guided, resumable, and repository-aware #15

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan#13