docs: module dossier + install/quickstart sync for truthful cutover sprints
- API_CLI_REFERENCE.md, INSTALL_GUIDE.md, quickstart.md, architecture/integrations.md, dev/DEV_ENVIRONMENT_SETUP.md, integrations/LOCAL_SERVICES.md: reflect real-service wiring. - docs/modules/**: module dossier updates across the modules touched by SPRINT_20260415_001..007 + SPRINT_20260416_003..017 + SPRINT_20260417_018..024 + SPRINT_20260418_025 + SPRINT_20260419_026. - docs/features/checked/web/**: update feature notes where UI changed. - docs/qa/feature-checks/runs/web/evidence-presentation-ux/: QA evidence artifacts. - docs/setup/**, docs/technical/**: align with setup wizard contracts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -7,7 +7,7 @@ This document defines the functional requirements for the Stella Ops Setup Wizar
|
||||
The Setup Wizard provides a guided, step-by-step configuration experience that:
|
||||
- Validates infrastructure dependencies (PostgreSQL, Valkey)
|
||||
- Runs database migrations
|
||||
- Bootstraps the initial admin and crypto profile
|
||||
- Bootstraps the initial admin, crypto profile, and optional advisory/VEX source configuration
|
||||
- Exposes a truthful required-readiness summary for setup completion
|
||||
- Hands tenant onboarding to authenticated `/setup/*` and integration command surfaces instead of pretending they are bootstrap steps
|
||||
|
||||
@@ -57,8 +57,9 @@ The system reaches "Production-Ready" state when:
|
||||
| `migrations` | Database Migrations | Yes | No | Infrastructure |
|
||||
| `admin` | Admin Bootstrap | Yes | No | Security |
|
||||
| `crypto` | Crypto Profile | Yes | No | Security |
|
||||
| `sources` | Advisory & VEX Sources | No | Yes | Data |
|
||||
|
||||
Only these five core steps are current runtime setup step IDs. The integration and orchestration catalogs below are historical handoff targets and are no longer accepted by the current setup APIs or `stella setup` command group.
|
||||
Current runtime setup step IDs now include the five required control-plane steps plus the optional `sources` step. The integration and orchestration catalogs below are historical handoff targets and are no longer accepted by the current setup APIs or `stella setup` command group.
|
||||
|
||||
### 3.2 Integration Handoffs (Not current setup steps)
|
||||
|
||||
@@ -77,13 +78,11 @@ Only these five core steps are current runtime setup step IDs. The integration a
|
||||
|---------|------|----------|-----------|----------|
|
||||
| `environments` | Environment Definition | No | Yes | Orchestration |
|
||||
| `agents` | Agent Registration | No | Yes | Orchestration |
|
||||
| `feeds` | Vulnerability Feeds | No | Yes | Data |
|
||||
|
||||
---
|
||||
|
||||
## 4. Step Specifications
|
||||
|
||||
Sections 4.1-4.5 describe the current installation-scoped setup steps. Sections 4.6 and later remain useful as onboarding capability notes, but those inputs now belong to authenticated post-bootstrap surfaces rather than the setup wizard step catalog.
|
||||
Sections 4.1-4.5 and 4.5.1 describe the current installation-scoped setup steps. Sections 4.6 and later remain useful as onboarding capability notes, but those inputs now belong to authenticated post-bootstrap surfaces rather than the setup wizard step catalog.
|
||||
|
||||
### 4.1 Database Setup (`database`)
|
||||
|
||||
@@ -226,6 +225,39 @@ Sections 4.1-4.5 describe the current installation-scoped setup steps. Sections
|
||||
|
||||
---
|
||||
|
||||
### 4.5.1 Advisory & VEX Sources (`sources`)
|
||||
|
||||
**Purpose:** Optionally enable advisory and VEX aggregation during bootstrap without forcing operators through the full integrations catalog on first run.
|
||||
|
||||
**Inputs:**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `mode` | enum | Yes | `mirror` | `mirror` enables StellaOps Mirror only; `manual` exposes explicit source selection |
|
||||
| `mirror.url` | string | Required when `mode=mirror` | `https://mirror.stella-ops.org` | StellaOps Mirror base URL |
|
||||
| `mirror.apiKey` | secret | No | - | Optional StellaOps Mirror API key |
|
||||
| `enabled` | string[] | Required when `mode=manual` | `[]` | Advisory/VEX source IDs to enable |
|
||||
|
||||
**Outputs:**
|
||||
- Selected sources are persisted through Concelier durable source storage
|
||||
- `mirror` mode enables only `stella-mirror`
|
||||
- `manual` mode enables only the explicitly selected upstream sources
|
||||
- Initial aggregation is scheduled for newly enabled sources
|
||||
|
||||
**Validation:**
|
||||
- Mirror URL must be an absolute URI
|
||||
- Manual mode must select at least one real source
|
||||
- `stella-mirror` is reserved for mirror mode and cannot be mixed into manual selections
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.sources.feeds.configured`
|
||||
- `check.sources.feeds.connectivity`
|
||||
|
||||
**Skip behavior:**
|
||||
- Skipping this optional step leaves advisory and VEX aggregation off
|
||||
- The integrations Advisory & VEX Sources page must surface that off-state and offer later enablement without rerunning bootstrap
|
||||
|
||||
---
|
||||
|
||||
### 4.6 Vault Integration (`vault`)
|
||||
|
||||
**Purpose:** Configure secrets management provider.
|
||||
@@ -481,7 +513,7 @@ The wizard stores user preferences in the settings store:
|
||||
"notifications": "slack"
|
||||
},
|
||||
"completedAt": "2026-01-13T10:30:00Z",
|
||||
"skippedSteps": ["identity", "feeds"]
|
||||
"skippedSteps": ["identity", "sources"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -28,17 +28,34 @@ design material later in this document.
|
||||
|
||||
- The implemented UI bootstrap flow persists authoritative installation-scoped
|
||||
state in `platform.setup_sessions`.
|
||||
- On a completed installation, anonymous entry to `/setup-wizard/*` no longer
|
||||
pretends bootstrap is still open. The first setup-session create/read returns
|
||||
`401`, then the same route can continue as an authenticated reconfiguration
|
||||
session once the operator signs in.
|
||||
- Fresh compose bootstrap no longer pre-seeds `SetupComplete=true`; a clean
|
||||
local database now lands in the setup wizard until the control-plane steps
|
||||
are actually finalized. Legacy local volumes are auto-converged by Platform
|
||||
release migration `064_EnvironmentSettingsInstallationScopeConvergence.sql`.
|
||||
- The current live step inventory is limited to the five control-plane steps
|
||||
the running platform can truthfully validate and converge:
|
||||
`database`, `cache`, `migrations`, `admin`, and `crypto`.
|
||||
- The `admin` step now seeds the same local standard-provider and superuser
|
||||
defaults into wizard draft state that it renders in the visible form, so an
|
||||
operator can accept the prefilled values without retyping them and still get
|
||||
a truthful backend apply.
|
||||
- The current live step inventory includes the five required control-plane
|
||||
steps the running platform can truthfully validate and converge plus one
|
||||
optional data-onboarding step:
|
||||
`database`, `valkey`, `migrations`, `admin`, `crypto`, and `sources`.
|
||||
- The `sources` step defaults to StellaOps Mirror only. Operators can switch
|
||||
to manual advisory/VEX feed selection or skip the step explicitly.
|
||||
- Skipping `sources` leaves advisories and VEX off. The Advisory & VEX Sources
|
||||
integrations page then surfaces that disabled state and offers a one-click
|
||||
StellaOps Mirror enable path without rerunning bootstrap.
|
||||
- Using `sources` now performs a live reachability check of the selected
|
||||
mirror/source configuration before the step can complete. Operators must
|
||||
fix the mirror URL or skip the step if the endpoint is unreachable.
|
||||
- Local browser automation may ignore local dev certificates, but product
|
||||
advisory aggregation still requires a hostname-valid certificate and will
|
||||
report TLS/certificate failures directly in the setup step and integrations
|
||||
UI.
|
||||
- The `admin` step now seeds only non-secret local standard-provider and
|
||||
superuser defaults into wizard draft state. Username and email can stay
|
||||
prefilled, but the operator must deliberately enter the initial admin
|
||||
password instead of inheriting a baked-in demo value.
|
||||
- Session reads now separate sanitized `draftValues` from `secretDrafts`
|
||||
metadata. Secret-bearing inputs such as admin or database passwords are
|
||||
retained only in protected server-side companion storage, can survive resume,
|
||||
@@ -50,8 +67,11 @@ design material later in this document.
|
||||
installation-scoped setup session APIs rather than a separate local state
|
||||
machine.
|
||||
- Repeatable tenant onboarding work such as integrations, notifications,
|
||||
advisory sources, environments, agents, and branding lives on `/setup/*`
|
||||
and other authenticated module surfaces, not inside the bootstrap wizard.
|
||||
environments, agents, and branding lives on `/setup/*` and other
|
||||
authenticated module surfaces, not inside the bootstrap wizard.
|
||||
- Advisory/VEX onboarding is the one intentional exception: the wizard can
|
||||
seed initial source configuration because it directly governs whether
|
||||
aggregation starts at all on a fresh install.
|
||||
- Secret material is no longer an out-of-band prerequisite for GitLab-class UI
|
||||
onboarding. The Integrations Hub can stage credentials through the Secret
|
||||
Authority API and then bind the returned `authref://...` URI to the created
|
||||
@@ -678,6 +698,7 @@ When the system detects first-run (no database connection or admin user):
|
||||
| `migrations` | Database Migrations | Apply schema updates |
|
||||
| `admin` | Admin Bootstrap | Create administrator account |
|
||||
| `crypto` | Crypto Profile | Configure signing keys |
|
||||
| `sources` | Advisory & VEX Sources | Enable StellaOps Mirror or manual feeds |
|
||||
| `vault` | Vault Integration | Configure secrets management |
|
||||
| `scm` | SCM Integration | Connect source control |
|
||||
| `notifications` | Notification Channels | Configure alerts and notifications |
|
||||
|
||||
Reference in New Issue
Block a user