docs: UI-driven local setup sprints + module dossier sync
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
@@ -152,7 +152,7 @@ flows, Rekor, and static/platform bootstrap assets).
|
||||
|
||||
The local route table also carries a small set of explicit precedence rules that must stay ahead of the
|
||||
generic `^/api/v1/{service}` and `^/api/v2/{service}` matchers. Platform-owned surfaces such as
|
||||
`/api/v1/aoc/*`, `/api/v1/administration/*`, and the aggregated v2 read models
|
||||
`/api/v1/aoc/*`, `/api/v1/administration/*`, `/api/v1/stella-assistant/*`, and the aggregated v2 read models
|
||||
`/api/v2/context/*`, `/api/v2/releases/*`, `/api/v2/security/*`, `/api/v2/topology/*`,
|
||||
`/api/v2/evidence/*`, and `/api/v2/integrations/*` resolve directly to `platform`. Browser
|
||||
compatibility prefixes such as `/doctor/*` and `/scheduler/*` are segment-bound before they strip the
|
||||
@@ -316,6 +316,23 @@ powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1
|
||||
-BootstrapGitLabSecrets
|
||||
```
|
||||
|
||||
For a repeatable browser-driven proof of the Integrations Hub path itself, run:
|
||||
|
||||
```powershell
|
||||
node src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs
|
||||
```
|
||||
|
||||
It signs in to `https://stella-ops.local`, drives the live
|
||||
`/setup/integrations/onboarding/*` routes through Playwright, and writes
|
||||
evidence to
|
||||
`src/Web/StellaOps.Web/output/playwright/live-integrations-ui-bootstrap.json`.
|
||||
The harness now supports inline GitLab secret staging through the browser when
|
||||
`STELLAOPS_UI_BOOTSTRAP_GITLAB_ACCESS_TOKEN` and
|
||||
`STELLAOPS_UI_BOOTSTRAP_GITLAB_REGISTRY_BASIC` are supplied. The separate
|
||||
first-run setup wizard now reaches the Platform setup API through the
|
||||
frontdoor and uses persisted installation-scoped setup sessions for the five
|
||||
truthful control-plane steps.
|
||||
|
||||
**Hosts file entries** (add to `C:\Windows\System32\drivers\etc\hosts`):
|
||||
```
|
||||
127.1.2.1 gitea.stella-ops.local
|
||||
@@ -357,6 +374,16 @@ vault kv put secret/nexus admin-password="your-password"
|
||||
|
||||
Gitea is now bootstrapped by the compose service itself: a fresh `stellaops-gitea-data` volume creates the default local admin user and the repository root before the container reports healthy. Personal access tokens remain a manual step because Gitea only reveals the token value when it is created.
|
||||
|
||||
For UI/CLI-first onboarding, the Integrations Secret Authority API can now
|
||||
stage GitLab-class credentials and return the generated `authref://...`
|
||||
bindings without a manual Vault write. The browser flow uses this inline, and
|
||||
the CLI exposes the same path through:
|
||||
|
||||
```bash
|
||||
stella config integrations secrets targets
|
||||
stella config integrations secrets upsert-bundle --bundle gitlab-server --target <vault-integration-id> --path gitlab/server --entry access-token=glpat-...
|
||||
```
|
||||
|
||||
For GitLab, `scripts/bootstrap-local-gitlab-secrets.ps1` is the preferred local bootstrap path. It reuses a valid `secret/gitlab` secret when possible and otherwise rotates the local `stella-local-integration` PAT, then writes `authref://vault/gitlab#access-token` plus `authref://vault/gitlab#registry-basic` into the dev Vault. When you enable the optional GitLab registry surface (`GITLAB_ENABLE_REGISTRY=true`), register it through the `GitLabContainerRegistry` provider with `authref://vault/gitlab#registry-basic`. The local Docker registry connector now follows the registry's Bearer challenge and exchanges that `username:personal-access-token` secret against `jwt/auth` before retrying catalog and tag probes.
|
||||
|
||||
`docker-compose.testing.yml` is a separate infrastructure-test lane. It starts `postgres-test`, `valkey-test`, mocks, and an isolated Gitea profile on different ports; it does not start Consul or GitLab. Use `docker-compose.integrations.yml` only when you need real third-party providers for connector validation.
|
||||
|
||||
@@ -278,57 +278,76 @@ stella image inspect http://localhost:5000/myapp:1.0.0
|
||||
|
||||
## stella setup
|
||||
|
||||
Interactive setup wizard for configuring StellaOps components.
|
||||
Installation-scoped control-plane bootstrap for the running StellaOps platform.
|
||||
|
||||
### Synopsis
|
||||
|
||||
```bash
|
||||
stella setup [options]
|
||||
stella setup --step <step-id> [options]
|
||||
stella setup [--config <path>] [--non-interactive]
|
||||
stella setup run [options]
|
||||
stella setup resume [--session <id>]
|
||||
stella setup status [--session <id>] [--json]
|
||||
stella setup reset [--step <step-id> | --all] [--force]
|
||||
stella setup validate --config <path>
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Description |
|
||||
| --- | --- |
|
||||
| `--step`, `-s` | Run a specific setup step (e.g., `llm`, `notify`, `authority`). |
|
||||
| `--non-interactive` | Run in non-interactive mode using config values. |
|
||||
| `--dry-run` | Preview changes without applying them. |
|
||||
| `--config`, `-c` | Path to YAML configuration file. |
|
||||
| `--config`, `-c` | Path to the YAML configuration file used to seed setup draft values. |
|
||||
| `--non-interactive`, `-y` | Run without prompts. |
|
||||
| `--step`, `-s` | `run`/`reset` only. Limit the operation to one supported control-plane step. |
|
||||
| `--dry-run` | `run` only. Probe without applying. |
|
||||
| `--force`, `-f` | `run` starts a fresh session; `reset --all` skips confirmation. |
|
||||
| `--session` | `resume`/`status` only. Use an explicit session id. |
|
||||
| `--json` | `status` only. Emit machine-readable session state. |
|
||||
| `--verbose`, `-v` | Enable verbose output. |
|
||||
|
||||
### Available Steps
|
||||
|
||||
| Step ID | Name | Required | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `authority` | Authentication Provider | Yes | Configure authentication (Standard/LDAP). |
|
||||
| `users` | User Management | Yes | Create super user and additional users. |
|
||||
| `database` | PostgreSQL Database | Yes | Configure database connection. |
|
||||
| `cache` | Valkey/Redis Cache | Yes | Configure cache connection. |
|
||||
| `vault` | Secrets Vault | No | Configure secrets management (Vault/AWS/Azure). |
|
||||
| `settingsstore` | Settings Store | No | Configure settings backend (Consul/etcd). |
|
||||
| `registry` | Container Registry | No | Configure registry authentication. |
|
||||
| `telemetry` | OpenTelemetry | No | Configure observability. |
|
||||
| `notify` | Notifications | No | Configure notification channels. |
|
||||
| `llm` | AI/LLM Provider | No | Configure LLM for AdvisoryAI. |
|
||||
| `migrations` | Database Migrations | Yes | Converge the required schema migrations. |
|
||||
| `admin` | Admin Bootstrap | Yes | Ensure the bootstrap administrator exists. |
|
||||
| `crypto` | Crypto Profile | Yes | Validate and apply the selected crypto profile. |
|
||||
|
||||
Compatibility aliases still accepted:
|
||||
- `valkey -> cache`
|
||||
- `authority -> admin`
|
||||
- `users -> admin`
|
||||
|
||||
Former setup targets such as `vault`, `settingsstore`, `registry`, `scm`, `notify`, `telemetry`, `llm`, `sources`, `environments`, and `agents` now return explicit handoff guidance to the authenticated onboarding surfaces.
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Run full setup wizard
|
||||
stella setup
|
||||
# Run the installation bootstrap
|
||||
stella setup run
|
||||
|
||||
# Configure LLM provider only
|
||||
stella setup --step llm
|
||||
# Probe only
|
||||
stella setup run --step database --dry-run --config ./setup.yaml
|
||||
|
||||
# Preview database configuration
|
||||
stella setup --step database --dry-run
|
||||
# Resume and inspect status
|
||||
stella setup resume
|
||||
stella setup status --json
|
||||
|
||||
# Non-interactive with config file
|
||||
stella setup --step llm --non-interactive --config ./setup.yaml
|
||||
# Reset the installation session
|
||||
stella setup reset --all --force
|
||||
```
|
||||
|
||||
See also: `docs/modules/advisory-ai/llm-setup-guide.md` for LLM configuration details.
|
||||
After `stella setup`, use the authenticated integration/onboarding surfaces instead of more setup steps:
|
||||
|
||||
```bash
|
||||
stella config integrations secrets targets
|
||||
stella config integrations secrets upsert-bundle \
|
||||
--bundle gitlab-server \
|
||||
--target <vault-integration-id> \
|
||||
--path gitlab/server \
|
||||
--entry access-token=glpat-...
|
||||
```
|
||||
|
||||
## stella advise ask
|
||||
|
||||
@@ -364,7 +383,7 @@ An LLM provider must be configured. If not configured, the command will display:
|
||||
Error: AI/LLM provider not configured.
|
||||
|
||||
AdvisoryAI features require an LLM provider to be configured.
|
||||
Run 'stella setup --step llm' to configure an LLM provider.
|
||||
Use the AdvisoryAI integration surfaces to configure an LLM provider.
|
||||
|
||||
Alternatively, set one of these environment variables:
|
||||
- OPENAI_API_KEY for OpenAI
|
||||
|
||||
@@ -171,6 +171,56 @@ docker compose -f docker-compose.stella-ops.yml ps
|
||||
curl -k https://stella-ops.local # should return the Angular UI
|
||||
```
|
||||
|
||||
After the Angular UI is reachable, the supported local operator lanes are:
|
||||
|
||||
### Browser-driven operator lane
|
||||
|
||||
Use the live browser UI at `https://stella-ops.local` and open the
|
||||
Integrations Hub at `/setup/integrations`.
|
||||
|
||||
For a repeatable browser-driven run against the live frontdoor:
|
||||
|
||||
```powershell
|
||||
node src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs
|
||||
```
|
||||
|
||||
This harness signs in through the same frontdoor flow, drives the
|
||||
`/setup/integrations/onboarding/*` routes in a real browser, and writes
|
||||
evidence to
|
||||
`src/Web/StellaOps.Web/output/playwright/live-integrations-ui-bootstrap.json`.
|
||||
|
||||
For a repeatable browser-driven proof of the setup wizard’s truthful state model:
|
||||
|
||||
```powershell
|
||||
node src/Web/StellaOps.Web/scripts/live-setup-wizard-state-truth-check.mjs
|
||||
```
|
||||
|
||||
This harness signs in through the frontdoor, forces a fresh installation-scoped
|
||||
setup session, proves that database probe does not complete the step, proves
|
||||
that apply advances the backend state to the cache step, and proves that a page
|
||||
reload resumes the same persisted session. Evidence is written to
|
||||
`src/Web/StellaOps.Web/output/playwright/live-setup-wizard-state-truth-check.json`.
|
||||
|
||||
Verified current UI boundary on `2026-04-14`:
|
||||
- The browser flow can create the full 16-entry local integration catalog.
|
||||
- GitLab-class providers can now be created from the UI without a manual Vault
|
||||
write because the Integrations Hub stages credentials through Secret
|
||||
Authority before binding the returned `authref://...`.
|
||||
- The setup wizard now persists authoritative installation-scoped progress in
|
||||
`platform.setup_sessions` and owns only the five control-plane steps the
|
||||
running control plane can truthfully converge: PostgreSQL, Valkey, schema
|
||||
migrations, admin bootstrap, and crypto profile.
|
||||
- Tenant-scoped onboarding stays on `/setup/*` and other authenticated module
|
||||
surfaces instead of being duplicated inside the bootstrap wizard.
|
||||
- The inline GitLab path still needs real credential input from the operator.
|
||||
For repeatable automation, the Playwright harness reads those values from
|
||||
`STELLAOPS_UI_BOOTSTRAP_GITLAB_ACCESS_TOKEN` and
|
||||
`STELLAOPS_UI_BOOTSTRAP_GITLAB_REGISTRY_BASIC`.
|
||||
- `scripts/bootstrap-local-gitlab-secrets.ps1` remains the scripted fallback
|
||||
when you want to pre-stage the local GitLab authrefs without using the UI.
|
||||
|
||||
### Scripted convergence lane
|
||||
|
||||
For a fresh local developer install, populate the live integration catalog with:
|
||||
|
||||
```powershell
|
||||
|
||||
@@ -89,26 +89,73 @@ Completion criteria:
|
||||
- [x] Script create/update paths persist declared variables through the owning backend.
|
||||
- [x] Targeted backend tests cover the compatibility evaluator, variable persistence, and Platform alias mapping.
|
||||
|
||||
### NOMOCK-006 - Remove the remaining no-Postgres Platform script in-memory fallback
|
||||
Status: DONE
|
||||
Dependency: NOMOCK-005
|
||||
Owners: Developer
|
||||
Task description:
|
||||
- Replace the last runtime `InMemoryScriptService` registration in Platform with a real HTTP bridge to the owning Release Orchestrator `/api/v2/scripts` API so local/browser flows still hit the real scripts backend even when Platform itself is not wired directly to the scripts PostgreSQL schema.
|
||||
- Expand the owning Release Orchestrator scripts HTTP surface so the proxy path can remain contract-complete: expose entry-point/dependency/version metadata, publish total-count headers, and accept the dedicated `script:read` / `script:write` scopes that Platform already enforces.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Platform no longer registers `InMemoryScriptService` in its runtime path when PostgreSQL is absent.
|
||||
- [x] Release Orchestrator `/api/v2/scripts` returns the metadata needed to preserve the Platform scripts contract over HTTP.
|
||||
- [x] Targeted tests cover the remote Platform scripts client and serial backend builds/tests pass.
|
||||
|
||||
### NOMOCK-007 - Replace Platform release-environment in-memory compatibility stores and dead frontend jobengine path
|
||||
Status: DONE
|
||||
Dependency: NOMOCK-001
|
||||
Owners: Developer
|
||||
Task description:
|
||||
- Remove the runtime `InMemoryEnvironmentStore`, `InMemoryTargetStore`, and `InMemoryFreezeWindowStore` compatibility branch from Platform so release-environment flows hit either the PostgreSQL-backed Release Orchestrator environment services or the owning Release Orchestrator WebApi over HTTP.
|
||||
- Correct the Angular release-environment HTTP client to target the real `/api/v1/release-orchestrator` path, map real environment/target/freeze payloads, and send truthful target connection configuration instead of the retired `release-jobengine` path and partial target DTOs.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Platform no longer registers runtime in-memory release-environment stores when PostgreSQL is absent.
|
||||
- [x] Release Orchestrator WebApi owns `/api/v1/release-orchestrator/environments`, `/targets`, and `/freeze-windows` with startup migrations wired for the `release` schema.
|
||||
- [x] The Angular release-environment client targets `/api/v1/release-orchestrator`, translates real payloads, and submits type-specific target connection config.
|
||||
- [x] Serial backend/frontend verification passes with concrete evidence.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-04-10 | Sprint created to remove live production-path stubs, mock providers, and in-memory runtime bindings starting with the active Angular app configuration and Concelier feed-mirror surfaces. | Developer |
|
||||
| 2026-04-13 | Inventory extended beyond the initial Concelier slice. Confirmed `/ops/operations/feeds/mirror/*` now runs on persisted Concelier state, but found two still-live script-path fictions: Platform still registers `IScriptService` to `InMemoryScriptService` in `src/Platform/StellaOps.Platform.WebService/Program.cs`, and the owning Release Orchestrator `/api/v2/scripts/{id}/check-compatibility` endpoint still returns an unconditional stub success from `src/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/Endpoints/ScriptsEndpoints.cs`. Next implementation slice expands to `src/ReleaseOrchestrator/**` for script compatibility truthfulness and to the Platform alias only if still needed after the owning-service fix. | Developer |
|
||||
| 2026-04-13 | Completed the scripts runtime slice. Release Orchestrator now evaluates `/api/v2/scripts/{id}/check-compatibility` against persisted script language, variables, dependencies, target metadata, and available secrets; create/update requests now persist declared variables instead of dropping them; and Platform now binds `IScriptService` to the real Release Orchestrator scripts registry when PostgreSQL is configured. Targeted tests passed: `StellaOps.ReleaseOrchestrator.Integration.Tests` `20/20`, `StellaOps.Platform.WebService.Tests` class-targeted `ReleaseOrchestratorScriptServiceTests` `2/2`, and `ReleaseOrchestrator.WebApi` rebuilt cleanly. Live frontdoor verification was blocked in this shell because the local stack was not running (`docker ps` empty, `curl.exe -k https://stella-ops.local/` connection failure). | Developer |
|
||||
| 2026-04-13 | Removed the last Platform scripts in-memory runtime branch. When Platform lacks direct scripts PostgreSQL access it now calls the owning Release Orchestrator `/api/v2/scripts` API through a tenant/auth-aware HTTP client instead of falling back to `InMemoryScriptService`. Release Orchestrator scripts endpoints were expanded to expose entry point, dependency, version, and total-count metadata and to accept `script:read` / `script:write` in addition to the older orchestrator scopes. Serial verification passed: `dotnet build src/Platform/StellaOps.Platform.WebService/StellaOps.Platform.WebService.csproj` `0 errors`, `dotnet test src/Platform/__Tests/StellaOps.Platform.WebService.Tests/StellaOps.Platform.WebService.Tests.csproj -- --filter-class StellaOps.Platform.WebService.Tests.RemoteReleaseOrchestratorScriptServiceTests` `3/3`, `dotnet build src/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/StellaOps.ReleaseOrchestrator.WebApi.csproj` `0 errors`, `dotnet test src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Integration.Tests/StellaOps.ReleaseOrchestrator.Integration.Tests.csproj` `20/20`. | Developer |
|
||||
| 2026-04-13 | Post-change live sanity check: the local stack is back up (`platform`, `authority`, and `concelier` healthy; frontdoor `GET /` returned `200`), but `stellaops-router-gateway` still reports `unhealthy` and this sprint slice still lacks an authenticated live `/api/v2/scripts` proof after the remote-path change. | Developer |
|
||||
| 2026-04-13 | Completed the release-environment runtime slice. Platform now binds release-environment flows to the PostgreSQL-backed Release Orchestrator services when configured and otherwise proxies the owning `/api/v1/release-orchestrator` API over HTTP instead of registering runtime in-memory environment/target/freeze stores. The Angular release-environment client now targets `/api/v1/release-orchestrator`, maps real environment/target/freeze payloads, enriches environment summaries from live targets/freeze windows, and submits type-specific target connection configuration for Docker, Compose, ECS, Nomad, SSH, and WinRM targets. Serial verification passed: `dotnet build src/Platform/StellaOps.Platform.WebService/StellaOps.Platform.WebService.csproj` `0 errors`, `dotnet test src/Platform/__Tests/StellaOps.Platform.WebService.Tests/StellaOps.Platform.WebService.Tests.csproj -- --filter-class StellaOps.Platform.WebService.Tests.RemoteReleaseOrchestratorEnvironmentClientTests` `3/3`, `dotnet test src/Platform/__Tests/StellaOps.Platform.WebService.Tests/StellaOps.Platform.WebService.Tests.csproj -- --filter-class StellaOps.Platform.WebService.Tests.ReleaseOrchestratorEnvironmentEndpointsTests` `2/2`, `dotnet test src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Integration.Tests/StellaOps.ReleaseOrchestrator.Integration.Tests.csproj` `22/22`, `npm run build` in `src/Web/StellaOps.Web` succeeded, and a live authenticated browser probe confirmed the UI now issues `/api/v1/release-orchestrator/*` requests rather than `/api/v1/release-jobengine/*`. | Developer |
|
||||
| 2026-04-13 | Finished the live release-environment backend convergence. The browser-facing local slice had omitted `release-orchestrator`, so `/api/v1/release-orchestrator/environments` returned `503`; after rebuilding and starting the real service, authenticated UI traffic still failed with `400` because the environment PostgreSQL stores could not resolve `Func<Guid>` for tenant scope. `StellaOps.ReleaseOrchestrator.WebApi` now registers the tenant GUID provider from `ReleaseEnvironmentIdentityAccessor`, and the infrastructure registration test now resolves the environment stores from DI instead of only checking descriptor presence. Serial verification passed: `dotnet test src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Integration.Tests/StellaOps.ReleaseOrchestrator.Integration.Tests.csproj -- --filter-class StellaOps.ReleaseOrchestrator.Integration.Tests.ReleaseEnvironmentInfrastructureRegistrationTests`, `docker compose -f devops/compose/docker-compose.stella-ops.yml up -d release-orchestrator`, `curl.exe -k -i https://stella-ops.local/api/v1/release-orchestrator/environments` (`401` through frontdoor), and an authenticated Playwright probe of `/releases/environments?tenant=demo-prod®ions=apac,eu-west,us-east,us-west` that now reaches the real backend path and renders the truthful empty-state instead of a transport error. | Developer |
|
||||
| 2026-04-13 | Extended the live browser proof from read-only recovery to a real mutation round-trip. The authenticated UI created environment `e2e-238131` (`201`, backend id `08d0d89d-964e-4f84-90e8-04cad6f2a0ff`) through `/releases/environments`, rendered the new card from the persisted backend response, then deleted it through the same UI path (`204`) and returned to the truthful empty-state. | Developer |
|
||||
| 2026-04-13 | Fixed the remaining release-environment detail-flow contract drift. The owning Release Orchestrator environment/target/freeze models now serialize enum-backed target, health, known-hosts, and WinRM transport values with the Web JSON string-enum contract, and the Angular release-environment client now accepts PascalCase and numeric enum variants from the owning API while still emitting the canonical request shape. The freeze-window editor no longer toggles a dead `showAddDialog` flag; clicking `Add Freeze Window` now opens the real form path. Serial verification passed: `dotnet test src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Environment.Tests/StellaOps.ReleaseOrchestrator.Environment.Tests.csproj` `158/158`, `npx vitest run src/tests/environments/release-environment.client.contract.spec.ts src/tests/environments/freeze-window-editor.component.spec.ts --config vitest.codex.config.ts` `3/3`, and `npm run build` in `src/Web/StellaOps.Web` succeeded after the UI changes. | Developer |
|
||||
| 2026-04-13 | Completed live authenticated end-to-end proof for the persisted release-environment detail surface. Through `https://stella-ops.local/releases/environments` the browser created environment `e2e-728048` (`201`, id `0d1a9597-c30c-4a17-891a-9dcdfe1ccffa`), updated settings (`200`), created a target (`201`, id `2ab5b680-1c09-4149-b160-af08a614b19c`), deleted that target (`204`), created a freeze window (`201`, id `2377401c-425d-4277-a02b-ec5605cccf1a`), deleted that freeze window (`204`), and deleted the environment (`204`). The two leftover trial environments from earlier failed runs, `E2E e2e-792313` and `E2E e2e-543565`, were then cleaned up through the same authenticated backend path with `204` responses so the local stack did not retain stale verification data. | Developer |
|
||||
| 2026-04-14 | Closed an unrelated live frontdoor blocker uncovered during the authenticated dashboard rerun: `/api/v1/vulnerabilities/status` returned `503` because `scanner-web` was missing from the local compose runtime even though the gateway route still pointed at `scanner.stella-ops.local`. Built `stellaops/scanner-web:dev`, started `stellaops-scanner-web`, and verified the path now returns `401` unauthenticated through `https://stella-ops.local/api/v1/vulnerabilities/status`, proving the route is back on the real scanner service instead of failing as an unavailable target. | Developer |
|
||||
| 2026-04-14 | Replaced the live Release Control deployment seed path with persisted runtime state. `StellaOps.ReleaseOrchestrator.WebApi` now binds `IDeploymentCompatibilityStore` to a PostgreSQL-backed store, startup auto-migrates `release_orchestrator.deployments`, and the store no longer seeds fake `dep-001`..`dep-004` rows on first access. Serial verification passed: `dotnet test src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Integration.Tests/StellaOps.ReleaseOrchestrator.Integration.Tests.csproj` `24/24`, `npm run build` in `src/Web/StellaOps.Web`, live API proof that the deployments list starts empty (`200`, `totalCount=0`), `POST /api/v1/release-orchestrator/deployments` creates `dep-4536d81685ac` (`201`), the same deployment survives a `release-orchestrator` container recreate, and the live browser route `/releases/deployments` now mounts the real Angular deployment feature and renders the persisted `checkout-api` deployment card and detail view instead of the old hardcoded `DEP-2026-*` screens. | Developer |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision: this sprint prioritizes live runtime paths the browser can currently reach over test-only mock helpers.
|
||||
- Decision: unsupported operations must return truthful empty/problem responses rather than seeded demo success/error payloads.
|
||||
- Decision: after the feed-mirror cleanup, the next highest-value runtime slice is the scripts compatibility path because the browser uses the real `/api/v2/scripts` backend and its compatibility action still reports fabricated success.
|
||||
- Decision: the Platform direct scripts alias now reuses the Release Orchestrator scripts library and schema instead of keeping a separate in-memory implementation when PostgreSQL is configured.
|
||||
- Decision: Platform now uses the owning Release Orchestrator scripts backend on both runtime branches: direct library binding when PostgreSQL is configured locally, HTTP proxying to the Release Orchestrator WebApi when it is not.
|
||||
- Decision: Release Orchestrator scripts endpoints now accept the dedicated `script:read` / `script:write` scopes in addition to the older orchestrator scopes so the Platform proxy path does not need a privileged bypass.
|
||||
- Decision: Platform release-environment runtime branches now follow the same pattern as scripts: direct PostgreSQL-backed Release Orchestrator services when configured locally, otherwise tenant/auth-aware HTTP proxying to the owning Release Orchestrator WebApi.
|
||||
- Decision: the Angular release-environment client now treats `/api/v1/release-orchestrator` as the sole production backend path and maps the owning environment/target/freeze schema instead of relying on retired `release-jobengine` aliases or partial target DTOs.
|
||||
- Decision: the Release Orchestrator host now provides the environment stores with the same tenant GUID resolver used by the higher-level environment services, so authenticated browser traffic activates the real persisted backend instead of faulting during DI.
|
||||
- Decision: the owning Release Orchestrator environment surface now emits the environment-management enums with the standard Web JSON string-enum contract, and the Angular client accepts the owning API's PascalCase and numeric variants so detail/settings/targets/freeze-window flows remain compatible during rollout.
|
||||
- Decision: live deployment monitoring state now starts empty and becomes real only after `/api/v1/release-orchestrator/deployments` mutations persist to PostgreSQL; seeded compatibility rows are no longer acceptable on the browser path.
|
||||
- Decision: `/releases/deployments` now reuses the existing Release Orchestrator deployment store/components that call the real deployments API instead of the older standalone Angular stub pages with hardcoded `DEP-2026-*` payloads.
|
||||
- Risk: several modules outside the initial slice still boot with runtime in-memory stores (`Notify`, `Graph`, `Policy`, `Platform`, `Scheduler`, `Scanner`, `BinaryIndex`, `Signals`, `SbomService`, `Signer`, `PacksRegistry`, `AdvisoryAI`). They will need follow-on slices unless a real persistence path already exists and can be wired safely.
|
||||
- Risk: Platform still falls back to `InMemoryScriptService` when no PostgreSQL connection string is configured. That preserves non-database test/dev paths, but it means the cleanup is not repo-wide complete yet.
|
||||
- Risk: the live browser path for this slice could not be reverified from the shell because the local stack was down during close-out (`docker ps` returned no running containers). The code-level and project-level checks are green, but live redeploy verification still needs a running stack.
|
||||
- Risk: the code-level and project-level checks are green and the frontdoor is back up, but this sprint slice still lacks an authenticated live `/api/v2/scripts` verification after the remote-path change. `stellaops-router-gateway` remains `unhealthy`, so browser-level proof should wait for the router health follow-up.
|
||||
- Risk: some feed-mirror sub-features appear to have no real persisted backend contract yet, so removing fake data may temporarily surface explicit `501`/empty-state behavior in the UI until the owning backend is implemented.
|
||||
- Risk: the global Angular `ng test --watch=false --include ...` path is still blocked by unrelated compile failures outside this slice, so focused frontend verification for the release-environment detail flow currently depends on direct Vitest execution instead of the repo-wide Angular test target.
|
||||
- Risk: after recreating `release-orchestrator`, the router can transiently serve `503 No instances available` until the new instance state converges; one live verification pass required a router restart before the frontdoor resumed routing the environment-management path.
|
||||
- Risk: the deployment monitoring route is now truthful and persistent, but it is still a compatibility projection over deployment state rather than the full deployment engine and artifact/evidence pipeline. The browser no longer sees fake rows, but deeper deployment execution slices still need follow-on work.
|
||||
|
||||
## Next Checkpoints
|
||||
- Remove the active Angular VEX Hub mock provider.
|
||||
- Convert the Concelier feed-mirror endpoints from seeded data to real source/read-model state.
|
||||
- Replace the Release Orchestrator script compatibility stub with persisted script-aware evaluation.
|
||||
- Replace the remaining on-disk stub deployment pages under `src/Web/StellaOps.Web/src/app/features/deployments/` with thin wrappers or remove them once no legacy references remain.
|
||||
- Decide whether the real release-environment management feature should replace the current `/environments/overview` redirect path or continue to coexist with the topology inventory surface.
|
||||
- Re-run the live scripts UI and compatibility panel once the local stack is back up.
|
||||
- Re-test the live feed pages and record the next runtime cleanup slice.
|
||||
|
||||
@@ -21,7 +21,7 @@
|
||||
## Delivery Tracker
|
||||
|
||||
### UISETUP-001 - Reset the local Stella runtime to zero state
|
||||
Status: DOING
|
||||
Status: DONE
|
||||
Dependency: none
|
||||
Owners: Developer / QA
|
||||
Task description:
|
||||
@@ -29,12 +29,12 @@ Task description:
|
||||
- Re-run the documented setup entrypoint needed to bring the platform back to a reachable browser state.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Stella-owned containers, volumes, and networks are removed before the rerun.
|
||||
- [ ] The documented local setup entrypoint is executed successfully after the wipe.
|
||||
- [ ] `https://stella-ops.local` becomes reachable again for browser-driven setup.
|
||||
- [x] Stella-owned containers, volumes, and networks are removed before the rerun.
|
||||
- [x] The documented local setup entrypoint is executed successfully after the wipe.
|
||||
- [x] `https://stella-ops.local` becomes reachable again for browser-driven setup.
|
||||
|
||||
### UISETUP-002 - Drive the operator setup through the browser UI
|
||||
Status: DOING
|
||||
Status: DONE
|
||||
Dependency: UISETUP-001
|
||||
Owners: Developer / QA
|
||||
Task description:
|
||||
@@ -42,12 +42,12 @@ Task description:
|
||||
- Record which configuration steps are truly persisted/provisioned by the UI versus which ones are session-only or still backend-limited.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] The setup wizard is exercised through the live browser against the rebuilt stack.
|
||||
- [ ] The integrations UI is used for the available local integration onboarding flows.
|
||||
- [ ] Any step that is not truly UI-provisioned is captured explicitly with supporting evidence.
|
||||
- [x] The setup wizard is exercised through the live browser against the rebuilt stack.
|
||||
- [x] The integrations UI is used for the available local integration onboarding flows.
|
||||
- [x] Any step that is not truly UI-provisioned is captured explicitly with supporting evidence.
|
||||
|
||||
### UISETUP-003 - Close documentation and evidence gaps for the UI path
|
||||
Status: TODO
|
||||
Status: DONE
|
||||
Dependency: UISETUP-002
|
||||
Owners: Developer / Documentation
|
||||
Task description:
|
||||
@@ -55,9 +55,9 @@ Task description:
|
||||
- Record the final verified state, remaining non-UI gaps, and any follow-up implementation needs in the sprint log and linked docs.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Docs reflect the verified UI-driven setup reality.
|
||||
- [ ] Final health and integration results are logged in the execution log.
|
||||
- [ ] Remaining non-UI blockers are called out explicitly rather than glossed over.
|
||||
- [x] Docs reflect the verified UI-driven setup reality.
|
||||
- [x] Final health and integration results are logged in the execution log.
|
||||
- [x] Remaining non-UI blockers are called out explicitly rather than glossed over.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
@@ -69,13 +69,19 @@ Completion criteria:
|
||||
| 2026-04-13 | The initial `scripts/setup.ps1 -QaIntegrationFixtures` run failed in the repo-wide `.sln` preflight with `MSB4166` child-node exits on `src/Tools/StellaOps.Tools.sln`, `src/VexHub/StellaOps.VexHub.sln`, and `src/Zastava/StellaOps.Zastava.sln`; reran the documented setup entrypoint with `-SkipBuild` to continue the actual local stack bring-up. | Developer |
|
||||
| 2026-04-13 | Patched the Integrations Hub UI to expose the missing local onboarding categories (`Secrets`, `Feed Mirrors`, `Object Storage`) and aligned wizard validation with the backend contract so optional-auth / optional-scope local connectors can be created from the browser instead of being blocked by frontend-only rules. | Developer |
|
||||
| 2026-04-13 | Angular compile validation for the changed UI surfaces completed without new errors from the modified files; the remaining `ng test` failures are pre-existing audit-log and scheduler test breakages outside the Integrations working slice. | Developer |
|
||||
| 2026-04-13 | Rebuilt the Angular frontend, started the minimal browser-facing Stella slice (`console-builder`, `router-gateway`, `platform`, `authority`, `concelier`, `integrations-web`) plus the real-provider compose lane (`gitea`, `jenkins`, `nexus`, `vault`, `docker-registry`, `minio`, `consul`, `gitlab`) and the integration fixtures. | Developer |
|
||||
| 2026-04-13 | Live browser verification confirmed the first-run setup wizard shell loads at `/setup-wizard/wizard`, but the bootstrap POST to `/api/v1/setup/sessions` returns `503`, so the wizard is not yet a complete scratch local setup path in the minimal UI slice. | Developer |
|
||||
| 2026-04-13 | Added `src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs` as a reusable browser-driven harness that authenticates through frontdoor, creates integrations through the live onboarding UI routes, and persists evidence to `src/Web/StellaOps.Web/output/playwright/live-integrations-ui-bootstrap.json`. | Developer |
|
||||
| 2026-04-13 | The browser-driven onboarding run created all 16 local catalog entries through the UI. 13 providers converged healthy immediately; `Local GitLab Server`, `Local GitLab CI`, and `Local GitLab Container Registry` remained unhealthy because `authref://vault/gitlab#access-token` and `authref://vault/gitlab#registry-basic` were not present in Vault. | Developer |
|
||||
| 2026-04-13 | Updated `docs/INSTALL_GUIDE.md`, `docs/integrations/LOCAL_SERVICES.md`, and `devops/compose/README.md` to document the verified UI-driven path, the reusable Playwright harness, and the remaining product boundaries. | Developer |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision: this rerun uses the real browser UI as the operator surface and treats CLI/bootstrap helpers only as fallback evidence if the product lacks a true UI path.
|
||||
- Risk: the setup wizard backend may still persist parts of the flow only in-memory/session scope, which would make a strict UI-only bootstrap impossible without follow-on implementation work.
|
||||
- Risk: some local integrations may still require credentials to exist before the UI can complete onboarding, especially GitLab and Vault-backed secrets.
|
||||
- Decision: the reusable UI evidence path is `node src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs`; it uses the same browser onboarding routes as an operator and keeps API usage limited to idempotent lookup plus post-create verification.
|
||||
- Risk: the current product boundary for a full UI-only local convergence is explicit, not inferred. GitLab-backed integrations still need out-of-band Vault secret seeding, and `/setup-wizard/wizard` still depends on a backend setup-session endpoint that returns `503` in the minimal local slice.
|
||||
|
||||
## Next Checkpoints
|
||||
- Complete the zero-state wipe and restore the platform to a reachable browser state.
|
||||
- Drive the setup wizard and integrations flows through the UI.
|
||||
- Record the exact boundary between UI-complete setup and script/API-only gaps.
|
||||
- Follow-up product work should move GitLab authref seeding into a supported UI flow.
|
||||
- Follow-up product work should make `/api/v1/setup/sessions` reliable enough for the setup wizard to become the authoritative scratch-bootstrap path.
|
||||
|
||||
@@ -0,0 +1,132 @@
|
||||
# Sprint 20260413-004 -- UI-Only Setup Bootstrap Closure
|
||||
|
||||
## Topic & Scope
|
||||
- Close the gap between the current browser-driven onboarding demo path and a production-grade UI bootstrap flow.
|
||||
- Split machine/bootstrap concerns from tenant/onboarding concerns so the UI owns only the parts that can be truthfully provisioned from a running control plane.
|
||||
- Fix the current gateway and setup-backend defects that make `/setup-wizard/wizard` fail even though the Platform setup endpoints themselves are implemented.
|
||||
- Introduce a proper secrets staging and authref-binding flow so GitLab-class integrations can be completed from the UI without out-of-band Vault seeding.
|
||||
- Working directory: `.`.
|
||||
- Cross-module edits are expected in `devops/compose/`, `src/Platform/`, `src/Integrations/`, `src/Cli/`, and `src/Web/`.
|
||||
- Expected evidence: live frontdoor probes, targeted backend/frontend tests, Playwright evidence, and updated operator docs.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Required docs: `docs/setup/setup-wizard-ux.md`, `docs/INSTALL_GUIDE.md`, `docs/integrations/LOCAL_SERVICES.md`, `docs/modules/platform/architecture-overview.md`, `src/Web/StellaOps.Web/AGENTS.md`.
|
||||
- Builds on [SPRINT_20260413_003_Web_ui_driven_local_setup_rerun.md](/C:/dev/New%20folder/git.stella-ops.org/docs/implplan/SPRINT_20260413_003_Web_ui_driven_local_setup_rerun.md), which established the current UI boundary with live evidence.
|
||||
- Safe parallelism:
|
||||
- Gateway routing and smoke coverage can proceed independently first.
|
||||
- Setup backend persistence/provisioning can proceed in parallel with UI state cleanup only after the route defect is fixed.
|
||||
- Secret staging/authref work must align Platform and Integrations contracts before FE wiring goes DOING.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/setup/setup-wizard-ux.md`
|
||||
- `docs/INSTALL_GUIDE.md`
|
||||
- `docs/integrations/LOCAL_SERVICES.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
- `src/Web/StellaOps.Web/AGENTS.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### BOOTSTRAP-001 - Fix frontdoor dispatch for setup endpoints
|
||||
Status: DONE
|
||||
Dependency: none
|
||||
Owners: Developer / QA
|
||||
Task description:
|
||||
- The current gateway route for `/api/v1/setup` matches only the exact path, so `/api/v1/setup/sessions` falls through to the generic `^/api/v1/([^/]+)(.*)` route and the gateway tries to dispatch to a non-existent `setup` microservice.
|
||||
- Replace the current exact-path rule with a prefix-aware route that sends `/api/v1/setup*` to `platform`, and add a smoke check that proves the frontdoor path reaches the Platform setup endpoints.
|
||||
|
||||
Completion criteria:
|
||||
- [x] `https://stella-ops.local/api/v1/setup/sessions` is routed to `platform` instead of a synthetic `setup` microservice.
|
||||
- [x] A live smoke test covers both `GET /api/v1/setup/sessions` and `POST /api/v1/setup/sessions` through the frontdoor.
|
||||
- [x] Docs and sprint evidence record the routing fix and the previous failure mode.
|
||||
|
||||
### BOOTSTRAP-002 - Turn setup sessions into real provisioning state, not optimistic UI/session state
|
||||
Status: DONE
|
||||
Dependency: BOOTSTRAP-001
|
||||
Owners: Developer
|
||||
Task description:
|
||||
- The current `PlatformSetupService` kept setup sessions in an in-memory store and returned placeholder pass results. The wizard therefore tracked progress, but it did not act as the authority for real system configuration.
|
||||
- Replace the ephemeral session model with persisted setup state and explicit per-step draft/provision/apply semantics. Required steps must reflect real subsystem state, not optimistic client-side transitions.
|
||||
- `test-connection` must stay a probe. It must never be treated as step completion. Completion must happen only after an explicit backend apply/provision operation and a follow-up validation result.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Setup session state survives service restarts and can be resumed truthfully.
|
||||
- [x] Step execution uses real validations and real persisted changes rather than placeholder pass results.
|
||||
- [x] `Finalize` marks setup complete only after required steps have actually converged.
|
||||
- [x] Targeted backend tests cover resume, restart persistence, failed apply, and finalize semantics.
|
||||
|
||||
### BOOTSTRAP-003 - Separate control-plane bootstrap from tenant onboarding
|
||||
Status: DONE
|
||||
Dependency: BOOTSTRAP-002
|
||||
Owners: Product Manager / Developer / Documentation
|
||||
Task description:
|
||||
- In real deployments, setup from scratch has two different scopes:
|
||||
1. control-plane bootstrap: database, cache, migrations, authority reachability, admin bootstrap, crypto primitives
|
||||
2. tenant onboarding: integrations, feeds, environments, agents, branding, notifications
|
||||
- The wizard mixed these concerns into one linear flow. The correct implementation keeps infrastructure/bootstrap verification in the setup wizard and moves repeatable tenant-scoped operations into tenant onboarding surfaces backed by normal authenticated APIs.
|
||||
|
||||
Completion criteria:
|
||||
- [x] The product flow distinguishes one-time platform bootstrap from repeatable tenant onboarding.
|
||||
- [x] Required bootstrap steps are only the steps that can be truthfully owned by a running control plane.
|
||||
- [x] Tenant-scoped setup work reuses the existing Integration Hub / platform setup surfaces instead of duplicating logic in the bootstrap wizard.
|
||||
- [x] Operator docs describe the boundary explicitly.
|
||||
|
||||
### BOOTSTRAP-004 - Add UI-managed secret staging and authref binding
|
||||
Status: DONE
|
||||
Dependency: BOOTSTRAP-002
|
||||
Owners: Developer / Security / Documentation
|
||||
Task description:
|
||||
- The integrations UI stored only `authRefUri` on the connector, while the Integrations service only resolved authrefs; it did not provide a contract for creating secret material. This is why GitLab worked only after out-of-band Vault writes.
|
||||
- Add a backend contract that lets the UI submit secret material to the configured secret authority, receive or confirm the resulting authref path, and bind that authref to the integration without ever persisting the raw secret in the integration catalog.
|
||||
- The local dev implementation can target dev Vault first, but the contract remains provider-agnostic so production secret authorities fit the same UX.
|
||||
|
||||
Completion criteria:
|
||||
- [x] The UI can create and bind GitLab-class credentials without a separate script or manual Vault write.
|
||||
- [x] The integration catalog continues to store only `authref://...` references, never raw secrets.
|
||||
- [x] Secret staging has audit events, least-privilege policies, and clear failure messages.
|
||||
- [x] Playwright evidence path now supports GitLab SCM + CI + registry convergence through inline secret staging when operator-supplied credentials are available.
|
||||
|
||||
### BOOTSTRAP-005 - Remove optimistic FE completion semantics from the setup wizard
|
||||
Status: DONE
|
||||
Dependency: BOOTSTRAP-002
|
||||
Owners: Developer / QA
|
||||
Task description:
|
||||
- The Angular wizard marked steps completed locally after `testConnection()` and could also skip pending optional steps on navigation without a server-authoritative step transition.
|
||||
- Rework the frontend so the step UI is a projection of backend state. Local draft edits can exist client-side, but progress, completion, skip state, and next-step availability must come from backend transitions.
|
||||
|
||||
Completion criteria:
|
||||
- [x] `Test Connection` updates only probe state, not completion state.
|
||||
- [x] Step completion and skip state are reloaded from backend session state after every mutation.
|
||||
- [x] Frontend tests cover the probe-succeeds-but-step-is-not-yet-applied case.
|
||||
- [x] Playwright flow proves refresh/reload does not lose truthful wizard state.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-04-13 | Sprint created after the UI-driven local rerun proved that the Integrations Hub can create connectors through the browser, but the setup wizard and GitLab-backed flows still stop short of a true UI-only bootstrap. | Planning |
|
||||
| 2026-04-13 | Verified that `POST /api/v1/setup/sessions` succeeds directly against `http://platform.stella-ops.local/api/v1/setup/sessions`, while the same path through `https://stella-ops.local/api/v1/setup/sessions` returned `503 Target microservice unavailable` because the gateway dispatched to synthetic microservice `setup` instead of `platform`. | Developer |
|
||||
| 2026-04-13 | Code inspection confirmed three architectural gaps to close in order: exact-path gateway routing for `/api/v1/setup`, in-memory/mock provisioning semantics in `PlatformSetupService`, and missing UI-to-secret-authority write flow for authref-backed integrations. | Developer |
|
||||
| 2026-04-13 | Fixed `devops/compose/router-gateway-local.json` so `/api/v1/setup*` routes to `platform` as a regex prefix instead of falling through to the generic `^/api/v1/([^/]+)(.*)` microservice matcher. Added the route to `devops/compose/openapi_routeprefix_smoke.csv` for regression coverage. | Developer |
|
||||
| 2026-04-13 | After moving the setup route above the generic API catch-all and restarting `stellaops-router-gateway`, live frontdoor probes returned `200 GET /api/v1/setup/sessions` and `201 POST /api/v1/setup/sessions`, closing the routing defect. | Developer |
|
||||
| 2026-04-14 | Completed BOOTSTRAP-002 with persisted installation-scoped setup state in `platform.setup_sessions`, structured non-500 error handling for expected setup failures, and backend coverage for restart persistence, failed apply, and finalize convergence semantics. | Developer |
|
||||
| 2026-04-14 | Completed BOOTSTRAP-003/005 by constraining the live wizard to the five control-plane steps (`Database`, `Cache`, `Migrations`, `Admin`, `Crypto`), documenting tenant onboarding on `/setup/*`, and adding `src/Web/StellaOps.Web/scripts/live-setup-wizard-state-truth-check.mjs` to prove forced restart, probe-without-completion, apply advancement, and reload persistence through the authenticated frontdoor. | Developer |
|
||||
| 2026-04-14 | Added the Secret Authority API boundary on Integrations, CLI support for listing targets and staging bundles, and UI wiring that stages GitLab-class credentials inline before the integration create call binds the returned `authref://...` URI. | Developer |
|
||||
| 2026-04-14 | Updated `src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs` so the GitLab lane can exercise inline secret staging through the browser when `STELLAOPS_UI_BOOTSTRAP_GITLAB_ACCESS_TOKEN` and `STELLAOPS_UI_BOOTSTRAP_GITLAB_REGISTRY_BASIC` are supplied. | Developer |
|
||||
| 2026-04-14 | Rebuilt the Angular workspace after the secret-authority UI cutover and fixed downstream specs that still assumed the pre-cutover raw `CreateIntegrationRequest` wizard output. | Developer |
|
||||
| 2026-04-14 | Ran the live GitLab UI bootstrap proof with inline secret staging against the local stack after refreshing `secret/gitlab` in dev Vault. The resulting Playwright artifact `src/Web/StellaOps.Web/output/playwright/live-integrations-ui-bootstrap.json` recorded `16/16` healthy integrations, `16` successful test probes, and `0` failed integrations. | Developer |
|
||||
| 2026-04-14 | Closed the remaining web-suite caveat by synchronizing stale security/audit/settings/setup-wizard specs with the current shipped contracts and rerunning the deterministic web batches through the previously failing tail. Batch `27/33` passed with `79/79` tests, batch `28/33` passed with `65/65`, and batches `29-33/33` passed cleanly, leaving the default web batch lane green. | Developer |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision: a truthful UI setup starts only after the control plane is already reachable in the browser. Docker/host/runtime bring-up remains a machine bootstrap concern, not a browser concern.
|
||||
- Decision: `Test Connection` is a diagnostic probe, not a provisioning action. The product should never let successful probes masquerade as completed setup.
|
||||
- Decision: secret material belongs in a secret authority, not in the integration catalog and not in frontend-only state. The UI must talk to a backend secret-staging contract that returns an authref binding.
|
||||
- Decision: the first shipped Secret Authority writer targets Vault KV v2 only. Other secrets-manager providers fail explicitly with `501 not_implemented` instead of pretending write support exists.
|
||||
- Decision: installation-scoped wizard progress is now persisted in `platform.setup_sessions`, and only non-sensitive draft values are stored there.
|
||||
- Decision: the live UI bootstrap artifact is considered green when the integration catalog converges to `16/16` healthy entries and the per-integration create/test/health checks succeed, even if background assistant/context requests are aborted during route transitions.
|
||||
- Risk: if the setup wizard continues to mix installation-scoped and tenant-scoped concerns, it will keep drifting into a misleading all-in-one setup surface that cannot be made truthful.
|
||||
- Risk: adding a secret staging API without strong audit and scope controls would weaken the platform security posture.
|
||||
- Risk: if the gateway route fix is not covered by frontdoor smoke tests, the same bug can regress silently because direct service probes still pass.
|
||||
- Risk: local frontend changes do not become live until the rebuilt Angular bundle is copied into `compose_console-dist` or the dev-ui override is active; otherwise browser verification can observe stale UI behavior.
|
||||
- Risk: the live browser GitLab proof now runs green, but reruns still depend on real operator-supplied secret values; the Playwright harness expects those values through environment variables rather than minting them itself.
|
||||
|
||||
## Next Checkpoints
|
||||
- Triage the remaining optional `stella-assistant` tips `503` on `/setup-wizard/wizard` separately from the now-green bootstrap flow.
|
||||
@@ -88,9 +88,25 @@ docker compose -f docker-compose.integrations.yml ps gitea
|
||||
|
||||
### 4. Register the local integration catalog
|
||||
|
||||
After the core stack plus the local provider lanes are running, register the
|
||||
catalog entries that Stella Ops can exercise immediately from a fresh local
|
||||
install:
|
||||
After the core stack plus the local provider lanes are running, there are two
|
||||
supported local operator paths.
|
||||
|
||||
Browser-driven Integrations Hub path:
|
||||
|
||||
```powershell
|
||||
node src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs
|
||||
```
|
||||
|
||||
- Drives the live browser through `/setup/integrations/onboarding/*`.
|
||||
- Persists evidence to `src/Web/StellaOps.Web/output/playwright/live-integrations-ui-bootstrap.json`.
|
||||
- The harness now supports inline GitLab secret staging through the browser when
|
||||
`STELLAOPS_UI_BOOTSTRAP_GITLAB_ACCESS_TOKEN` and
|
||||
`STELLAOPS_UI_BOOTSTRAP_GITLAB_REGISTRY_BASIC` are supplied.
|
||||
- The separate first-run setup wizard (`/setup-wizard/wizard`) now reaches the
|
||||
Platform setup API through the frontdoor and uses persisted,
|
||||
installation-scoped setup sessions for the five truthful control-plane steps.
|
||||
|
||||
Scripted convergence path:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
|
||||
@@ -139,6 +155,17 @@ powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1
|
||||
-BootstrapGitLabSecrets
|
||||
```
|
||||
|
||||
For a repeatable browser-driven proof of the same Integrations Hub path, run:
|
||||
|
||||
```powershell
|
||||
node src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs
|
||||
```
|
||||
|
||||
It authenticates against `https://stella-ops.local`, creates integrations
|
||||
through the onboarding UI routes, and records the final catalog plus health
|
||||
results in
|
||||
`src/Web/StellaOps.Web/output/playwright/live-integrations-ui-bootstrap.json`.
|
||||
|
||||
`docker-compose.testing.yml` is the separate infrastructure-test lane. It starts `postgres-test`, `valkey-test`, mocks, and an isolated Gitea profile on different ports; it does not start Consul or GitLab.
|
||||
|
||||
---
|
||||
@@ -263,6 +290,14 @@ vault kv put secret/nexus admin-password="your-nexus-password"
|
||||
vault kv put secret/gitlab access-token="glpat-your-token" registry-basic="root:glpat-your-token"
|
||||
```
|
||||
|
||||
Inline secret staging no longer requires a manual Vault write for GitLab-class
|
||||
providers:
|
||||
|
||||
```bash
|
||||
stella config integrations secrets targets
|
||||
stella config integrations secrets upsert-bundle --bundle gitlab-server --target <vault-integration-id> --path gitlab/server --entry access-token=glpat-...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Consul (Optional KV / Settings Store)
|
||||
|
||||
@@ -1,269 +1,215 @@
|
||||
# Setup Wizard Guide
|
||||
|
||||
This guide covers the `stella setup` command for initial configuration of Stella Ops.
|
||||
This guide covers the current `stella setup` command set for installation-scoped control-plane bootstrap.
|
||||
|
||||
## Overview
|
||||
|
||||
The setup wizard guides you through configuring all required and optional components. Both CLI and UI setup wizards follow the same **Infrastructure-First** order and provide identical capabilities.
|
||||
`stella setup` is no longer an all-in-one platform onboarding wizard.
|
||||
|
||||
- It owns only the five control-plane steps the running platform can truthfully validate and converge: `database`, `cache`, `migrations`, `admin`, `crypto`.
|
||||
- It uses the Platform setup session APIs as the source of truth. Local files are not the authoritative setup state.
|
||||
- Tenant onboarding such as integrations, secrets providers, advisory sources, environments, agents, and notifications happens on the authenticated `/setup/*` surfaces and the corresponding CLI command groups.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Interactive setup
|
||||
# Run the installation bootstrap
|
||||
stella setup run
|
||||
|
||||
# Non-interactive with config file
|
||||
stella setup run --config setup.yaml --non-interactive
|
||||
|
||||
# Dry-run mode (validate without applying)
|
||||
stella setup run --dry-run
|
||||
|
||||
# Resume interrupted setup
|
||||
# Resume the current installation session
|
||||
stella setup resume
|
||||
|
||||
# Reconfigure a specific step
|
||||
stella setup --step vault
|
||||
# Show the current installation-scoped session
|
||||
stella setup status
|
||||
|
||||
# JSON status for automation
|
||||
stella setup status --json
|
||||
|
||||
# Probe a specific step only
|
||||
stella setup run --step database --dry-run
|
||||
|
||||
# Reset a specific step
|
||||
stella setup reset --step cache
|
||||
|
||||
# Reset the whole installation session
|
||||
stella setup reset --all --force
|
||||
```
|
||||
|
||||
## Setup Steps
|
||||
## Supported Steps
|
||||
|
||||
Steps are organized in phases. Required steps must be completed; optional steps can be skipped.
|
||||
| Step | Purpose | Notes |
|
||||
| --- | --- | --- |
|
||||
| `database` | Verify the PostgreSQL runtime connection and record convergence | Machine-level DB provisioning remains outside `stella setup`. |
|
||||
| `cache` | Verify the cache runtime connection and record convergence | `valkey` remains a compatibility alias. |
|
||||
| `migrations` | Converge required schema migrations | Uses the backend migration-admin path. |
|
||||
| `admin` | Ensure the bootstrap administrator exists | `authority` and `users` remain compatibility aliases. |
|
||||
| `crypto` | Validate and apply the selected crypto profile | Uses live provider health rather than optimistic local state. |
|
||||
|
||||
### Phase 1: Core Infrastructure (Required)
|
||||
Deprecated setup aliases still accepted:
|
||||
- `valkey -> cache`
|
||||
- `authority -> admin`
|
||||
- `users -> admin`
|
||||
|
||||
| Step | Description |
|
||||
|------|-------------|
|
||||
| **database** | PostgreSQL connection for persistent storage |
|
||||
| **cache** | Valkey/Redis connection for caching and distributed locks |
|
||||
| **migrations** | Apply database schema migrations |
|
||||
Former setup targets such as `vault`, `registry`, `scm`, `sources`, `notify`, `telemetry`, `llm`, `settingsstore`, `environments`, and `agents` now return explicit handoff guidance instead of pretending they are bootstrap steps.
|
||||
|
||||
### Phase 2: Security Foundation (Required)
|
||||
## Command Surface
|
||||
|
||||
| Step | Description |
|
||||
|------|-------------|
|
||||
| **authority** | Authentication provider (Standard or LDAP) |
|
||||
| **users** | Initial super user account (skipped if LDAP selected) |
|
||||
| **crypto** | Cryptographic provider for signing/encryption (Default, FIPS, GOST, SM2/SM3) |
|
||||
### `stella setup`
|
||||
|
||||
### Phase 3: Secrets Management (Optional)
|
||||
Runs the same flow as `stella setup run`.
|
||||
|
||||
| Step | Description | Configure Later |
|
||||
|------|-------------|-----------------|
|
||||
| **vault** | External secrets vault (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager, GCP Secret Manager) | Settings > Trust & Signing, or `stella config set vault.*` |
|
||||
Global options:
|
||||
- `--config`, `-c` - path to YAML configuration used to seed draft values before probe/apply
|
||||
- `--non-interactive`, `-y` - do not prompt for missing values
|
||||
|
||||
### Phase 4: Integrations (Optional)
|
||||
### `stella setup run`
|
||||
|
||||
| Step | Description | Configure Later |
|
||||
|------|-------------|-----------------|
|
||||
| **registry** | Container registry for image scanning | Settings > Integrations, or `stella config set registry.*` |
|
||||
| **scm** | Source control integration (GitHub, GitLab, Gitea, Bitbucket, Azure DevOps) | Settings > Integrations, or `stella config set scm.*` |
|
||||
| **sources** | Advisory data sources (NVD, GHSA, OSV, distribution feeds) | Settings > Security Data, or `stella config set sources.*` |
|
||||
Run the installation bootstrap from the beginning or continue from the active installation-scoped session.
|
||||
|
||||
### Phase 5: Observability (Optional)
|
||||
Options:
|
||||
- `--step`, `-s` - run one supported control-plane step only
|
||||
- `--skip` - skip selected steps for this invocation
|
||||
- `--dry-run` - probe only; do not apply
|
||||
- `--force`, `-f` - start a fresh setup session even if one already exists
|
||||
- `--config`, `-c`
|
||||
- `--non-interactive`, `-y`
|
||||
|
||||
| Step | Description | Configure Later |
|
||||
|------|-------------|-----------------|
|
||||
| **telemetry** | OpenTelemetry configuration for tracing, metrics, and logging | Settings > System > Telemetry, or `stella config set telemetry.*` |
|
||||
| **notify** | Notification channels (Email, Slack, Teams, Webhook) | Settings > Notifications, or `stella config set notify.*` |
|
||||
Notes:
|
||||
- `probe` is diagnostic only. A successful probe does not complete a step.
|
||||
- Only `apply` transitions performed by `run` without `--dry-run` can converge a step.
|
||||
|
||||
### Phase 6: AI Features (Optional)
|
||||
### `stella setup resume`
|
||||
|
||||
| Step | Description | Configure Later |
|
||||
|------|-------------|-----------------|
|
||||
| **llm** | AI/LLM provider for AdvisoryAI (OpenAI, Claude, Gemini, Ollama) | Settings > Integrations > AdvisoryAI, or `stella config set llm.*` |
|
||||
Resume the current setup session or a specific one.
|
||||
|
||||
### Phase 7: Configuration Store (Optional)
|
||||
Options:
|
||||
- `--session` - explicit setup session ID
|
||||
|
||||
| Step | Description | Configure Later |
|
||||
|------|-------------|-----------------|
|
||||
| **settingsStore** | External configuration store (Consul, etcd, Azure App Config, AWS Parameter Store) | Settings > System, or `stella config set settingsStore.*` |
|
||||
### `stella setup status`
|
||||
|
||||
### Phase 8: Release Orchestration (Optional)
|
||||
Show the current installation-scoped session.
|
||||
|
||||
| Step | Description | Configure Later |
|
||||
|------|-------------|-----------------|
|
||||
| **environments** | Define deployment environments (dev, staging, production) | Settings > Environments, or `stella env create` |
|
||||
| **agents** | Register deployment agents for release execution | Settings > Agents, or `stella agent register` |
|
||||
Options:
|
||||
- `--session` - explicit setup session ID
|
||||
- `--json` - machine-readable output
|
||||
|
||||
## Multiple Integrations
|
||||
### `stella setup reset`
|
||||
|
||||
The **registry**, **scm**, and **notify** steps support configuring multiple instances. For example:
|
||||
Reset one step or the whole installation session.
|
||||
|
||||
```bash
|
||||
# Add multiple container registries
|
||||
stella config set registry.instances.0.name "Production ECR"
|
||||
stella config set registry.instances.0.provider "ecr"
|
||||
stella config set registry.instances.0.isPrimary "true"
|
||||
Options:
|
||||
- `--step`, `-s` - reset one control-plane step
|
||||
- `--all` - start a fresh installation-scoped session
|
||||
- `--force`, `-f` - skip confirmation when used with `--all`
|
||||
|
||||
stella config set registry.instances.1.name "Docker Hub"
|
||||
stella config set registry.instances.1.provider "docker"
|
||||
### `stella setup validate`
|
||||
|
||||
# Add multiple SCM connections
|
||||
stella config set scm.instances.0.name "GitHub Main"
|
||||
stella config set scm.instances.0.provider "github"
|
||||
Validate a configuration file, then run the setup flow in probe-only mode.
|
||||
|
||||
# Add multiple notification channels
|
||||
stella config set notify.instances.0.name "Ops Slack"
|
||||
stella config set notify.instances.0.provider "slack"
|
||||
Options:
|
||||
- `--config`, `-c` - required YAML configuration path
|
||||
|
||||
stella config set notify.instances.1.name "Security Email"
|
||||
stella config set notify.instances.1.provider "email"
|
||||
```
|
||||
## Configuration File Shape
|
||||
|
||||
## Skip Warnings
|
||||
|
||||
When skipping optional steps, the wizard displays warnings about implications:
|
||||
|
||||
| Skipped Step | Warning |
|
||||
|--------------|---------|
|
||||
| vault | Secrets stored in configuration files (less secure for production) |
|
||||
| registry | Container scanning capabilities limited |
|
||||
| scm | Pipeline integration and automated workflows unavailable |
|
||||
| sources | CVE/VEX advisory feeds require manual updates |
|
||||
| telemetry | System observability limited; tracing and metrics unavailable |
|
||||
| llm | AdvisoryAI features unavailable |
|
||||
| environments | Manual deployment tracking only |
|
||||
| agents | Release orchestration unavailable without registered agents |
|
||||
|
||||
## Cryptographic Provider Selection
|
||||
|
||||
The **crypto** step allows selecting regional cryptographic standards:
|
||||
|
||||
| Provider | Standards | Use Case |
|
||||
|----------|-----------|----------|
|
||||
| **Default** | AES-256-GCM, SHA-256/512, Ed25519, ECDSA P-256 | General use |
|
||||
| **FIPS 140-2** | AES-256-GCM (FIPS 197), SHA-256/384/512 (FIPS 180-4), ECDSA P-256/P-384 (FIPS 186-4) | US government compliance |
|
||||
| **GOST R 34.10-2012** | Kuznechik/Magma, Streebog, GOST R 34.10-2012 | Russian compliance |
|
||||
| **SM2/SM3** | SM4, SM3, SM2 | Chinese national standards |
|
||||
|
||||
FIPS mode supports HSM integration via PKCS#11, AWS CloudHSM, Azure Key Vault HSM, or GCP Cloud HSM.
|
||||
|
||||
## SCM Integration
|
||||
|
||||
The **scm** step connects Stella Ops to your source control system:
|
||||
|
||||
| Provider | Authentication |
|
||||
|----------|----------------|
|
||||
| GitHub | Personal Access Token (ghp_...) |
|
||||
| GitLab | Personal Access Token (glpat-...) |
|
||||
| Gitea | Access Token |
|
||||
| Bitbucket | Username + App Password |
|
||||
| Azure DevOps | Personal Access Token |
|
||||
|
||||
## Configuration File Format
|
||||
|
||||
For non-interactive setup, provide a YAML configuration file:
|
||||
`stella setup` consumes only the values relevant to the five control-plane steps. The CLI forwards these as backend draft values rather than directly mutating local infrastructure.
|
||||
|
||||
```yaml
|
||||
# setup.yaml
|
||||
database:
|
||||
host: localhost
|
||||
connectionString: Host=postgres.stella-ops.local;Port=5432;Database=stellaops;Username=stellaops;Password=${DB_PASSWORD}
|
||||
host: postgres.stella-ops.local
|
||||
port: 5432
|
||||
database: stellaops
|
||||
user: postgres
|
||||
password: ${DB_PASSWORD} # Environment variable substitution
|
||||
ssl: true
|
||||
user: stellaops
|
||||
password: ${DB_PASSWORD}
|
||||
|
||||
cache:
|
||||
host: localhost
|
||||
host: cache.stella-ops.local
|
||||
port: 6379
|
||||
password: ${CACHE_PASSWORD}
|
||||
ssl: true
|
||||
|
||||
authority:
|
||||
provider: standard # or 'ldap'
|
||||
database: 0
|
||||
|
||||
users:
|
||||
superuser:
|
||||
username: admin
|
||||
email: admin@example.com
|
||||
password: ${ADMIN_PASSWORD}
|
||||
displayName: Stella Admin
|
||||
|
||||
authority:
|
||||
provider: standard
|
||||
|
||||
crypto:
|
||||
provider: default # or 'fips', 'gost', 'sm'
|
||||
|
||||
vault:
|
||||
provider: hashicorp
|
||||
address: https://vault.example.com:8200
|
||||
token: ${VAULT_TOKEN}
|
||||
|
||||
scm:
|
||||
provider: github
|
||||
url: https://github.com
|
||||
token: ${GITHUB_TOKEN}
|
||||
organization: my-org
|
||||
|
||||
sources:
|
||||
enabled: nvd,ghsa,osv
|
||||
nvd:
|
||||
apiKey: ${NVD_API_KEY}
|
||||
|
||||
telemetry:
|
||||
otlpEndpoint: http://localhost:4317
|
||||
enableTracing: true
|
||||
enableMetrics: true
|
||||
|
||||
notify:
|
||||
provider: slack
|
||||
slack:
|
||||
webhookUrl: ${SLACK_WEBHOOK_URL}
|
||||
|
||||
llm:
|
||||
provider: openai
|
||||
openai:
|
||||
apiKey: ${OPENAI_API_KEY}
|
||||
model: gpt-4o
|
||||
provider: default
|
||||
```
|
||||
|
||||
## Validation Commands
|
||||
## What Happens After Setup
|
||||
|
||||
When `stella setup` finishes, the next work is tenant onboarding, not more bootstrap steps.
|
||||
|
||||
Typical next commands:
|
||||
|
||||
```bash
|
||||
# Validate current configuration
|
||||
stella setup validate
|
||||
# Discover writable secret-authority targets
|
||||
stella config integrations secrets targets
|
||||
|
||||
# Validate specific step
|
||||
stella setup validate --step database
|
||||
# Stage a GitLab access token into a secret-authority target
|
||||
stella config integrations secrets upsert-bundle \
|
||||
--bundle gitlab-server \
|
||||
--target <vault-integration-id> \
|
||||
--path gitlab/server \
|
||||
--entry access-token=glpat-...
|
||||
|
||||
# Show current setup status
|
||||
stella setup status
|
||||
# Create the GitLab server integration with the returned authref
|
||||
stella config integrations create \
|
||||
--name local-gitlab \
|
||||
--type scm \
|
||||
--provider gitlabserver \
|
||||
--endpoint http://gitlab.stella-ops.local:8929 \
|
||||
--authref authref://vault/gitlab/server#access-token
|
||||
```
|
||||
|
||||
UI handoff surfaces:
|
||||
- `/setup/integrations/secrets`
|
||||
- `/setup/integrations/scm`
|
||||
- `/setup/integrations/ci`
|
||||
- `/setup/integrations/registries`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database Connection Failed
|
||||
### Database probe fails
|
||||
|
||||
```bash
|
||||
# Test PostgreSQL connectivity
|
||||
stella setup validate --step database --verbose
|
||||
stella setup run --step database --dry-run --config ./setup.yaml
|
||||
```
|
||||
|
||||
Verify:
|
||||
- PostgreSQL is running and accessible
|
||||
- Credentials are correct
|
||||
- SSL settings match server configuration
|
||||
Check:
|
||||
- the runtime PostgreSQL service is reachable
|
||||
- the connection string or host/user/password values are correct
|
||||
- the machine/bootstrap layer already provisioned PostgreSQL
|
||||
|
||||
### Cache Connection Failed
|
||||
### Cache probe fails
|
||||
|
||||
```bash
|
||||
# Test Valkey/Redis connectivity
|
||||
stella setup validate --step cache --verbose
|
||||
stella setup run --step cache --dry-run --config ./setup.yaml
|
||||
```
|
||||
|
||||
### SCM Authentication Failed
|
||||
Check:
|
||||
- the runtime cache service is reachable
|
||||
- the host/port/password values are correct
|
||||
|
||||
```bash
|
||||
# Test SCM connectivity
|
||||
stella setup validate --step scm --verbose
|
||||
```
|
||||
### Setup reports that `vault` or `scm` is no longer a supported step
|
||||
|
||||
Ensure your token has the required scopes:
|
||||
- GitHub: `repo`, `workflow`
|
||||
- GitLab: `api`, `read_repository`
|
||||
- Azure DevOps: `Code (Read)`, `Build (Read & Execute)`
|
||||
That is expected. Those flows moved out of installation bootstrap.
|
||||
|
||||
Use:
|
||||
- `stella config integrations secrets *`
|
||||
- `stella config integrations create`
|
||||
- the authenticated `/setup/integrations/*` UI
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `stella config get` - View current configuration
|
||||
- `stella config set` - Modify individual settings
|
||||
- `stella doctor run` - Run diagnostic checks
|
||||
- `stella admin db migrate` - Run database migrations
|
||||
- `stella setup status --json`
|
||||
- `stella config integrations providers`
|
||||
- `stella config integrations secrets targets`
|
||||
- `stella config integrations secrets upsert-bundle`
|
||||
- `stella system migrations-status --module all`
|
||||
|
||||
@@ -102,6 +102,54 @@ public interface IIntegrationPlugin
|
||||
- **Harbor** - Operators provide the Harbor base URL. Stella Ops probes the provider-specific `/api/v2.0/health` route for connection tests and health checks.
|
||||
- **Docker Registry / GitLab Container Registry** - Operators provide the registry base URL. When the registry responds with `WWW-Authenticate: Bearer ...`, the connector exchanges the configured secret against the advertised token realm and retries with the returned bearer token. The local GitLab registry uses `authref://vault/gitlab#registry-basic`, storing `username:personal-access-token`.
|
||||
|
||||
## Secret Authority
|
||||
|
||||
The Integrations service now exposes a provider-agnostic Secret Authority boundary for onboarding flows that need to stage credential material before creating an integration.
|
||||
|
||||
### Goals
|
||||
|
||||
- Keep raw secrets out of the integration catalog.
|
||||
- Let UI and CLI stage credentials once and receive `authref://...` bindings in return.
|
||||
- Audit secret bundle creation/update separately from integration CRUD.
|
||||
- Fail truthfully when a secrets-manager provider is visible but not writable in this release.
|
||||
|
||||
### API surface (`/api/v1/secret-authority`)
|
||||
|
||||
- `GET /targets`
|
||||
- Lists tenant-visible secrets-manager integrations that can be used as staging targets.
|
||||
- Returns integration metadata only: `integrationId`, `name`, `provider`, `endpoint`, `status`, `logicalPathHint`, `supportsWrite`.
|
||||
- `PUT /bundles/{bundleId}`
|
||||
- Stages or updates a credential bundle in the selected target.
|
||||
- Request body: `targetIntegrationId`, optional `logicalPath`, `entries[]`, optional `labels`, `overwrite`.
|
||||
- Response returns only metadata plus generated authrefs:
|
||||
- `bundleId`
|
||||
- `logicalPath`
|
||||
- `authRefs`
|
||||
- target provider and endpoint
|
||||
|
||||
### Current writer support
|
||||
|
||||
- Vault KV v2 is the first shipped writer.
|
||||
- Other secrets-manager providers remain visible in discovery, but write attempts fail explicitly with `501 not_implemented`.
|
||||
- For Vault targets, the service writes directly to the target secret engine and returns authrefs such as:
|
||||
- `authref://vault/gitlab/server#access-token`
|
||||
- `authref://vault/gitlab/registry#registry-basic`
|
||||
|
||||
### Security model
|
||||
|
||||
- Read policy: `integration:read` via `IntegrationPolicies.SecretAuthorityRead`
|
||||
- Write policy: `integration:write` via `IntegrationPolicies.SecretAuthorityWrite`
|
||||
- Secret bundle writes emit the `upsert_secret_bundle` audit action in the Integrations audit module.
|
||||
- The API never echoes raw secret values back to the caller.
|
||||
|
||||
### UI / CLI usage
|
||||
|
||||
- The Web Integrations Hub uses Secret Authority for inline GitLab Server, GitLab CI, and GitLab Container Registry onboarding.
|
||||
- The CLI exposes the same flow through:
|
||||
- `stella config integrations secrets targets`
|
||||
- `stella config integrations secrets upsert-bundle --bundle <id> --target <integration-id> --entry key=value`
|
||||
- Integration create/update operations still persist only `authRefUri`; the secret bundle and authref lifecycle are owned by the secret-authority target, not by the catalog row.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **AuthRef URI credential model:** Credentials are stored in an external vault (e.g., HashiCorp Vault, Azure Key Vault). The integration catalog stores only the URI reference (`authref://vault/path/to/secret`), never the raw secret.
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**Status:** Active Development (backend substantially implemented; API surface layer in progress)
|
||||
|
||||
> **Implementation reality (updated 2026-04-13):** The backend is substantially complete with 140,000+ lines of production code across 49 projects. Core libraries (Release, Promotion, Deployment, Workflow, Evidence, PolicyGate, Progressive, Federation, Compliance) are implemented with comprehensive tests (283 test files, 37K lines). Six agent types are operational (Compose, Docker, SSH, WinRM, ECS, Nomad). Compatibility HTTP surfaces now exist across Platform, JobEngine, and Scanner for environment management, deployment monitoring, evidence inspection, dashboard promotion decisions, and registry search. The standalone WebApi owns and auto-migrates the `scripts` PostgreSQL schema used by `/api/v2/scripts`, and the scripts compatibility endpoint now evaluates persisted script metadata, declared variables, dependency inventory, target metadata, and available secrets instead of returning a fabricated success response. **Remaining gaps:** the dedicated Release Orchestrator WebApi host is still incomplete, and many compatibility surfaces still rely on in-memory storage outside the scripts catalog and audit/first-signal persistence.
|
||||
> **Implementation reality (updated 2026-04-14):** The backend is substantially complete with 140,000+ lines of production code across 49 projects. Core libraries (Release, Promotion, Deployment, Workflow, Evidence, PolicyGate, Progressive, Federation, Compliance) are implemented with comprehensive tests (283 test files, 37K lines). Six agent types are operational (Compose, Docker, SSH, WinRM, ECS, Nomad). Compatibility HTTP surfaces now exist across Platform, JobEngine, and Scanner for environment management, deployment monitoring, evidence inspection, dashboard promotion decisions, and registry search. The standalone WebApi now owns `/api/v1/release-orchestrator/environments`, `/targets`, and `/freeze-windows` for the environment-management slice, with startup migrations wired into the `release` schema; Platform's no-PostgreSQL runtime now proxies this owning API instead of falling back to local in-memory environment stores. The standalone WebApi also owns and auto-migrates the `scripts` PostgreSQL schema used by `/api/v2/scripts`; that surface now exposes full entry-point/dependency/version metadata, emits `X-Total-Count` for list parity, accepts `script:read` / `script:write` alongside the older orchestrator scopes, and evaluates compatibility against persisted script metadata, declared variables, dependency inventory, target metadata, and available secrets instead of returning a fabricated success response. Platform's no-PostgreSQL scripts path now proxies this owning API instead of falling back to a local in-memory catalog. The real environment-management UI is now reachable at `/releases/environments`, with live authenticated detail/settings/targets/freeze-window flows backed by the owning persisted API; the older legacy release-management entry points redirect into that screen. The live `/releases/deployments` route now reads persisted state from the owning `release_orchestrator.deployments` table and survives service restarts instead of seeding fake compatibility rows on first access. **Remaining gaps:** the dedicated Release Orchestrator WebApi host is still incomplete, and some legacy compatibility surfaces still need full execution-engine backing rather than compatibility projections.
|
||||
|
||||
## Overview
|
||||
|
||||
|
||||
@@ -21,6 +21,38 @@ This document defines the user experience flows for both CLI and UI implementati
|
||||
| **Fix** | A remediation command generated by Doctor |
|
||||
| **Connector** | A specific integration provider (e.g., "HashiCorp Vault") |
|
||||
|
||||
### 1.3 Current implemented boundary (2026-04)
|
||||
|
||||
The live browser wizard is now intentionally narrower than some of the broader
|
||||
design material later in this document.
|
||||
|
||||
- The implemented UI bootstrap flow persists authoritative installation-scoped
|
||||
state in `platform.setup_sessions`.
|
||||
- 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`.
|
||||
- `probe` and `apply` are now distinct backend operations. Successful probes do
|
||||
not complete steps.
|
||||
- `stella setup` is a backend-authoritative client for the same
|
||||
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.
|
||||
- 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
|
||||
integration.
|
||||
- The live verification harness is
|
||||
`src/Web/StellaOps.Web/scripts/live-setup-wizard-state-truth-check.mjs`.
|
||||
- The live integrations harness is
|
||||
`src/Web/StellaOps.Web/scripts/live-integrations-ui-bootstrap.mjs`; it can
|
||||
exercise inline GitLab secret staging when the operator supplies the raw
|
||||
credential values through environment variables.
|
||||
- Sections below that describe broader multi-connector or tenant-onboarding
|
||||
flows remain product/backlog design material unless they are explicitly
|
||||
called out elsewhere as shipped.
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI Flow
|
||||
|
||||
Reference in New Issue
Block a user