diff --git a/README.md b/README.md index 62d3363..42a43f0 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,27 @@ Run the static cross-repository module contract check: ./tools/checks/check-contracts.sh ``` +Require backend, manifest, frontend, lockfile, and release-composition versions +to agree before a release: + +```sh +./.venv/bin/python tools/checks/check-version-alignment.py --release-composition +``` + +Generate the CycloneDX dependency inventory from a resolved release environment: + +```sh +./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python +``` + +For reproducible release artifacts, set `SOURCE_DATE_EPOCH` to the release +commit timestamp (or pass an explicit timezone-qualified `--timestamp`): + +```sh +SOURCE_DATE_EPOCH="$(git -C ../govoplan-core show -s --format=%ct HEAD)" \ + ./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python +``` + Run the consolidated focused verification suite: ```sh @@ -128,6 +149,9 @@ Frontend layout principles for module pages are documented in The cross-product destination, stakeholder visions, configuration archetypes, connected outcome stories, and capability horizons are documented in the [Connected Governance Platform Roadmap](docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md). +The administrator journey from Core-only bootstrap through online module +installation, scale-out, and reversible environment promotion is defined in +[System Administrator Lifecycle User Story](docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md). The first Campaign-centric capability and infrastructure fit assessment is in `docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`. diff --git a/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md b/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md index f88c4ad..d59bfe2 100644 --- a/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md +++ b/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md @@ -253,6 +253,12 @@ Operational access is distinct from permission to read all business content. Diagnostics minimize personal data and link to governed evidence when deeper inspection is authorized. +The complete installation and lifecycle journey is specified in the +[System Administrator Lifecycle User Story](SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md): +one-command Core-only bootstrap, signed online module installation and updates, +stateless scale-out, versioned configuration transfer, undo, and reproducible +environment-promotion recipes. + ### Integration owner and enterprise architect > As an integration owner, I can inventory external systems, declare direction @@ -871,23 +877,27 @@ checkouts. Priorities: -1. Pin and publish a compatible Core/WebUI/module composition and first +1. Deliver the first slices of the + [System Administrator Lifecycle User Story](SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md): + a verified Core-only distribution, first-run control plane, read-only online + module directory, and durable plan/confirm/install progress. +2. Pin and publish a compatible Core/WebUI/module composition and first reference configuration package. -2. Complete database, files, configuration, secrets, and audit backup/restore +3. Complete database, files, configuration, secrets, and audit backup/restore drills with measured recovery objectives. -3. Prove the providers required by the selected reference configurations, +4. Prove the providers required by the selected reference configurations, beginning with SMTP/IMAP, CalDAV, and the relevant broker/worker and file or directory adapters, including reconciliation behavior. -4. Add external monitoring, alerting, audit export/retention, deployment +5. Add external monitoring, alerting, audit export/retention, deployment hardening, and incident/runbook evidence. -5. Apply the interface pattern language first to Campaign, scheduling, and +6. Apply the interface pattern language first to Campaign, scheduling, and admin/configuration. Existing central components are mandatory; any custom control needs prior product-owner authorization and a narrow recorded scope. Extend central contracts only after a repeated need is demonstrated. -6. Align executable WebUI contributions with manifest/configured-system +7. Align executable WebUI contributions with manifest/configured-system metadata and make focused views manually/default selectable without waiting for Workflow. -7. Refresh the capability/infrastructure assessment and distinguish code-tested, +8. Refresh the capability/infrastructure assessment and distinguish code-tested, target-tested, package-integrated, pilot-approved, and production-approved evidence. diff --git a/docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md b/docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md new file mode 100644 index 0000000..bdbcfa6 --- /dev/null +++ b/docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md @@ -0,0 +1,169 @@ +# 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. 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.