stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

docs: UI-driven local setup sprints + module dossier sync

Browse Source 
Add SPRINT_20260413_004 (platform UI-only setup bootstrap closure)
with BOOTSTRAP-001..006 delivery tracker, and update sprint 003 and
sprint 20260410-001 execution logs to reflect the completed
persistence / orchestrator / secret-authority work.

Sync module dossiers and operator guides with the new reality: setup
wizard UX, platform-service architecture, CLI setup guide, integrations
architecture + local services, release-orchestrator architecture,
install guide, and compose README.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-04-14 07:56:45 +03:00
parent 286c1f758a
commit 398d0659eb
12 changed files with 648 additions and 262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
docs/modules/platform/platform-service.md
View File

@@ -74,7 +74,9 @@ Provide a single, deterministic aggregation layer for cross-service UX workflows
### Release Orchestrator compatibility
- Platform hosts `/api/v1/release-orchestrator/environments/*` as a compatibility facade for Console release-management flows.
- Supported families include environment CRUD plus `/settings`, per-environment `/targets` CRUD with `/health-check`, and `/freeze-windows` CRUD.
- The compatibility facade reuses the Release Orchestrator environment library and deterministic in-memory stores so local console flows work without a dedicated Release Orchestrator WebApi host.
- The compatibility facade no longer uses runtime in-memory environment stores. Platform now binds those flows to the PostgreSQL-backed Release Orchestrator environment services when the `release` schema is configured locally, and otherwise proxies the owning Release Orchestrator WebApi over tenant/auth-aware HTTP.
- Platform hosts `/api/v2/scripts*` against the real Release Orchestrator scripts backend on both runtime branches: direct library/schema binding when Platform has the scripts PostgreSQL connection, and an HTTP proxy to the owning Release Orchestrator WebApi when it does not.
- The scripts facade no longer falls back to a local in-memory catalog; list/count/detail/version/validation/compatibility flows all resolve against the owning Release Orchestrator service or schema.
## API surface (v2)
@@ -254,37 +256,70 @@ The Platform Service is exposed via Gateway and registered through Router discov
## Setup Wizard
The Platform Service exposes setup wizard endpoints to support first-run configuration and reconfiguration workflows. These endpoints replace UI-mock implementations with real backend state management.
The Platform Service owns the installation-scoped setup wizard used by
`/setup-wizard/wizard` for first-run control-plane bootstrap and later
reconfiguration checks.
Current runtime behavior:
- Authoritative wizard state is persisted in `platform.setup_sessions` via
migration `063_PlatformSetupSessions.sql`.
- The persisted store keeps only non-sensitive draft configuration plus step
state, timestamps, and check results. Secret material is still expected to be
staged through a secret authority rather than stored in wizard session state.
- The live wizard now owns only the five control-plane steps the running
control plane can truthfully validate and converge: `database`, `cache`,
`migrations`, `admin`, and `crypto`.
- Tenant onboarding remains outside the bootstrap wizard. Integrations, feeds,
notifications, environments, agents, branding, and related repeatable
operations continue on `/setup/*` and module-owned authenticated APIs.
- `probe` is diagnostic only. Only `apply` can move a step into the converged
state.
### API surface (v1)
#### Sessions
- `GET /api/v1/setup/sessions` - Get current setup session for tenant
- `POST /api/v1/setup/sessions` - Create new setup session
- `POST /api/v1/setup/sessions/resume` - Resume existing or create new session
- `POST /api/v1/setup/sessions/finalize` - Finalize setup session
- `GET /api/v1/setup/sessions` - Get the current installation-scoped setup session
- `GET /api/v1/setup/sessions/current` - Alias for the current installation-scoped session
- `GET /api/v1/setup/sessions/{sessionId}` - Read a specific persisted session by ID
- `POST /api/v1/setup/sessions` - Create a new session or force a restart
- `POST /api/v1/setup/sessions/resume` - Resume the current session or create one
- `PUT /api/v1/setup/sessions/{sessionId}/config` - Persist non-sensitive draft values
- `POST /api/v1/setup/sessions/{sessionId}/finalize` - Finalize the current session with convergence checks
- `POST /api/v1/setup/sessions/finalize` - Compatibility finalize path
#### Steps
- `POST /api/v1/setup/steps/execute` - Execute a setup step (runs Doctor checks)
- `POST /api/v1/setup/steps/skip` - Skip an optional setup step
- `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/probe` - Run a diagnostic probe without completing the step
- `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/apply` - Apply the current step and persist the new state
- `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/execute` - Compatibility mutation wrapper (`dryRun=true` maps to probe)
- `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/reset` - Reset a step to pending
- `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/skip` - Compatibility endpoint retained for older clients; the current control-plane steps are all required
- `GET /api/v1/setup/sessions/{sessionId}/steps/{stepId}/checks` - Read current check results
- `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/checks/run` - Re-run checks for a step
- `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/prerequisites` - Evaluate prerequisites for a step
- `POST /api/v1/setup/steps/{stepId}/test-connection` - Compatibility probe endpoint used by older clients
#### Definitions
- `GET /api/v1/setup/definitions/steps` - List all step definitions
- `GET /api/v1/setup/definitions/steps` - List the current live step definitions
### Setup step identifiers
| Step ID | Title | Required | Depends On |
|---------|-------|----------|------------|
| `Database` | Database Setup | Yes | - |
| `Valkey` | Valkey/Redis Setup | Yes | - |
| `Migrations` | Database Migrations | Yes | Database |
| `Admin` | Admin Bootstrap | Yes | Migrations |
| `Crypto` | Crypto Profile | Yes | Admin |
| `Vault` | Vault Integration | No | - |
| `Scm` | SCM Integration | No | - |
| `Notifications` | Notification Channels | No | - |
| `Environments` | Environment Definition | No | Admin |
| `Agents` | Agent Registration | No | Environments |
| Step ID | Title | Required | Depends On | Notes |
|---------|-------|----------|------------|-------|
| `database` | PostgreSQL Database | Yes | - | Probe verifies reachability. Apply records convergence against the current runtime connection. |
| `cache` | Cache / Valkey | Yes | - | Probe verifies cache reachability. Apply records convergence against the current runtime connection. |
| `migrations` | Database Migrations | Yes | `database` | Probe reports pending migration state. Apply runs the migration-admin path against the canonical `Platform` and `ReleaseOrchestrator` registry modules and re-validates convergence. |
| `admin` | Admin Bootstrap | Yes | `migrations` | Probe validates bootstrap prerequisites. Apply ensures the bootstrap admin exists. |
| `crypto` | Crypto Profile | Yes | `admin` | Probe validates the requested crypto profile. Apply records the converged profile selection. |
Legacy aliases accepted during the compatibility window:
- `valkey -> cache`
- `authority -> admin`
- `users -> admin`
Former tenant-onboarding steps such as `vault`, `scm`, `registry`, `sources`,
`notify`, `environments`, `agents`, `telemetry`, `llm`, and `settingsstore`
are no longer valid setup targets. Platform returns explicit handoff guidance
to the authenticated onboarding surfaces instead.
### Setup session states
@@ -302,11 +337,19 @@ The Platform Service exposes setup wizard endpoints to support first-run configu
| Status | Description |
|--------|-------------|
| `Pending` | Not yet started |
| `Current` | Currently active step |
| `Passed` | Completed successfully |
| `Failed` | Validation failed |
| `Skipped` | Explicitly skipped |
| `Blocked` | Blocked by dependency |
| `Skipped` | Explicitly skipped (optional steps only) |
| `Current` | Reserved contract value for active-step projections |
| `Blocked` | Reserved contract value for dependency failures |
### Anonymous posture
- Before installation setup is marked complete, setup session APIs may resolve
to the installation scope without an authenticated caller.
- After setup is marked complete, anonymous setup session reads and mutations
return `401` and the normal authenticated `platform.setup.*` policies apply.
- `Finalize` succeeds only after every required control-plane step has
converged.
### Security and scopes
- Read: `platform.setup.read`
@@ -320,5 +363,6 @@ The Platform Service exposes setup wizard endpoints to support first-run configu
### Related documentation
- UX flow specification: `docs/setup/setup-wizard-ux.md`
- Repository inventory: `docs/setup/setup-wizard-inventory.md`
- Doctor checks: `docs/setup/setup-wizard-doctor-contract.md`
- CLI guide: `docs/modules/cli/guides/setup-guide.md`
- Local operator runbook: `docs/INSTALL_GUIDE.md`
- Live proof: `src/Web/StellaOps.Web/scripts/live-setup-wizard-state-truth-check.mjs`