Setup Wizard — UX Flow Specification
Audience: designers and engineers implementing the Stella Ops Setup Wizard across CLI and UI.
This document defines the user experience flows for both the CLI and UI implementations of the Stella Ops Setup Wizard, ensuring feature parity across surfaces. Stella Ops is the self-hosted DevOps vulnerability-scanner and release control plane; the wizard bootstraps a fresh installation’s core control-plane services and seeds initial advisory/VEX sources.
Scope note. Section 1.3 records the current implemented boundary of the live browser wizard. Sections 2 onward include broader product/backlog design material (multi-connector and tenant-onboarding flows) that is not all shipped — treat §1.3 as authoritative for what runs today.
1. Design Principles
1.1 Core UX Goals
- Self-serve clarity - Users should complete setup without reading external documentation
- Progressive disclosure - Show only relevant options at each step
- Fail-forward - Guide users through errors with actionable fixes
- Parity - CLI and UI offer identical capabilities
- Resume-friendly - Support interruption and resumption
1.2 Terminology
| Term | Definition |
|---|---|
| Step | A discrete configuration unit (e.g., “Database Setup”) |
| Check | A Doctor diagnostic that validates a step |
| 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. - On a completed installation, anonymous entry to
/setup-wizard/*no longer pretends bootstrap is still open. The first setup-session create/read returns401, then the same route can continue as an authenticated reconfiguration session once the operator signs in. - Fresh compose bootstrap no longer pre-seeds
SetupComplete=true; a clean local database now lands in the setup wizard until the control-plane steps are actually finalized. Legacy local volumes are auto-converged by Platform release migration064_EnvironmentSettingsInstallationScopeConvergence.sql. - The current live browser step inventory includes the five required control-plane steps the running platform can truthfully validate and converge, plus two optional steps:
database,valkey,migrations,admin,crypto,assurance, andsources. - The
assurancestep is optional, defaults to no pack enabled, and is currently a Web read-only preflight because Authority pack enablement and the owning readiness APIs do not yet expose a setup-save contract. The step must route operators to/assurance, Trust & Signing, Evidence exports, Notify, and Identity & Access instead of persisting settings in browser state. - Assurance copy must say that packs configure evidence support and readiness workflows, not legal compliance certification.
- The
assurancestep shows evidence scope lanes. NIS2 and DORA must be described as software-estate Assurance over Stella-monitored/deployed software plus operator-supplied legal, governance, contract, and filing gaps. - The
sourcesstep defaults to StellaOps Mirror only. Operators can switch to manual advisory/VEX feed selection or skip the step explicitly. - Skipping
sourcesleaves advisories and VEX off. The Advisory & VEX Sources integrations page then surfaces that disabled state and offers a one-click StellaOps Mirror enable path without rerunning bootstrap. - Using
sourcesnow performs a live reachability check of the selected mirror/source configuration before the step can complete. Operators must fix the mirror URL or skip the step if the endpoint is unreachable. - Local browser automation may ignore local dev certificates, but product advisory aggregation still requires a hostname-valid certificate and will report TLS/certificate failures directly in the setup step and integrations UI.
- The
adminstep now seeds only non-secret local standard-provider and superuser defaults into wizard draft state. Username and email can stay prefilled, but the operator must deliberately enter the initial admin password instead of inheriting a baked-in demo value. - Session reads now separate sanitized
draftValuesfromsecretDraftsmetadata. Secret-bearing inputs such as admin or database passwords are retained only in protected server-side companion storage, can survive resume, and are rendered as retained placeholders rather than round-tripping plaintext back into the browser or CLI. probeandapplyare now distinct backend operations. Successful probes do not complete steps.stella setupis 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, environments, agents, and branding lives on
/setup/*and other authenticated module surfaces, not inside the bootstrap wizard. - Advisory/VEX onboarding is the one intentional exception: the wizard can seed initial source configuration because it directly governs whether aggregation starts at all on a fresh install.
- Secret material is no longer an out-of-band prerequisite for GitLab-class UI onboarding. The Integrations Hub can stage credentials through the Secret Authority API and then bind the returned
authref://...URI to the created 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
2.1 Command Structure
# Interactive setup (default)
stella setup
# Non-interactive with config file
stella setup --config setup.yaml
# Reconfigure existing installation
stella setup --reconfigure
# Resume interrupted setup
stella setup --resume
# Specific step only
stella setup --step database
# Skip optional steps
stella setup --skip vault,scm
2.2 Global Options
| Option | Type | Description |
|---|---|---|
--config | path | YAML configuration file |
--non-interactive | flag | Fail on missing required input |
--reconfigure | flag | Re-run on existing installation |
--resume | flag | Continue from last incomplete step |
--step <id> | string | Run specific step only |
--skip <ids> | string | Comma-separated steps to skip |
--verbose | flag | Show detailed progress |
--output <format> | enum | text, json, yaml |
2.3 Interactive Flow
$ stella setup
____ _ _ _ ___
/ ___|| |_ ___| | | __ _ / _ \ _ __ ___
\___ \| __/ _ \ | |/ _` | | | | '_ \/ __|
___) | || __/ | | (_| | |_| | |_) \__ \
|____/ \__\___|_|_|\__,_|\___/| .__/|___/
|_|
Setup Wizard v2026.01
This wizard will guide you through the initial configuration.
Press Ctrl+C at any time to exit. Progress is saved automatically.
Detected environment:
- Platform: linux-x64
- Docker: available
- PostgreSQL: not detected
- Valkey: not detected
[1/10] Database Setup
----------------------
? PostgreSQL host: localhost
? PostgreSQL port: [5432]
? Database name: [stellaops]
? Username: stellaops_admin
? Password: ********
Testing connection...
[OK] Connected to PostgreSQL 16.2
[OK] User has CREATE SCHEMA permission
[OK] Database 'stellaops' accessible
Running Doctor checks...
[PASS] check.database.connectivity
[PASS] check.database.permissions
[PASS] check.database.version
Database setup complete.
[2/10] Valkey/Redis Setup
-------------------------
...
2.4 Error Handling Flow
Testing connection...
[FAIL] Could not connect to PostgreSQL
Likely causes:
1. PostgreSQL is not running
2. Firewall blocking port 5432
3. Incorrect host/port
Suggested fixes:
# If using Docker Compose:
docker compose -f devops/compose/docker-compose.yml up -d postgres
# If using systemd:
sudo systemctl start postgresql
sudo systemctl enable postgresql
# Verify connectivity:
pg_isready -h localhost -p 5432
? Retry connection? [Y/n]
2.5 Multi-Connector Flow
[6/10] Vault Integration (Optional)
-----------------------------------
? Configure a secrets provider? [Y/n] Y
Detected: VAULT_ADDR=https://vault.example.com:8200
? Use detected HashiCorp Vault? [Y/n] Y
? Vault address: [https://vault.example.com:8200]
? Authentication method:
> Token
AppRole
Kubernetes
? Vault token: ********
Testing connection...
[OK] Vault connected (version 1.15.0)
[OK] KV v2 mount 'secret' accessible
? Add another secrets provider? [y/N] y
? Select provider:
HashiCorp Vault
> Azure Key Vault
AWS Secrets Manager
File Provider
...
2.6 Skip Flow
[7/10] SCM Integration (Optional)
---------------------------------
? Configure source control integration? [Y/n] n
Skipping SCM integration.
Note: You can configure this later via 'stella setup --step scm'
Skipped steps can be completed from:
- CLI: stella setup --reconfigure
- UI: Settings > Configuration Wizard
2.7 Non-Interactive Mode
# setup.yaml
database:
host: postgres.example.com
port: 5432
database: stellaops
username: stellaops_admin
password: ${POSTGRES_PASSWORD} # Environment variable
valkey:
host: valkey.example.com
port: 6379
password: ${VALKEY_PASSWORD}
vault:
- type: hashicorp
address: https://vault.example.com:8200
authMethod: kubernetes
role: stellaops
scm:
- type: github-app
appId: "123456"
installationId: "789012"
privateKeyPath: /etc/stellaops/github-app.pem
notifications:
- type: slack
name: engineering
webhookUrl: ${SLACK_WEBHOOK_URL}
environments:
- name: dev
displayName: Development
orderIndex: 0
- name: staging
displayName: Staging
orderIndex: 1
- name: prod
displayName: Production
orderIndex: 2
isProduction: true
requiredApprovals: 2
$ stella setup --config setup.yaml --non-interactive
[1/10] Database Setup.............. [OK]
[2/10] Valkey/Redis Setup.......... [OK]
[3/10] Database Migrations......... [OK]
[4/10] Admin Bootstrap............. [OK]
[5/10] Crypto Profile.............. [OK]
[6/10] Vault Integration........... [OK]
[7/10] SCM Integration............. [OK]
[8/10] Notification Channels....... [OK]
[9/10] Environment Definition...... [OK]
[10/10] Agent Registration......... [SKIP] (no agents defined)
Setup complete. System status: Operational
Run 'stella doctor run' for full diagnostics.
2.8 Completion Output
Setup Complete!
===============
Status: Operational
Completed steps:
[x] Database Setup
[x] Valkey/Redis Setup
[x] Database Migrations
[x] Admin Bootstrap
[x] Crypto Profile
[x] Vault Integration
[x] SCM Integration
[x] Notification Channels
Skipped steps:
[ ] Identity Provider (OIDC/LDAP)
[ ] Environment Definition
[ ] Agent Registration
[ ] Vulnerability Feeds
To reach Production-Ready status, configure:
- Identity Provider: stella setup --step identity
- Environments: stella setup --step environments
- Agents: stella setup --step agents
Next steps:
1. Run first scan: stella scan image --image <digest>
2. View dashboard: https://localhost:8080
3. Full diagnostics: stella doctor run --mode full
Setup report saved to: ~/.stellaops/setup-report-2026-01-13.md
3. UI Flow
3.1 First-Run Blocking
When the system detects first-run (no database connection or admin user):
- Intercept all routes - Redirect to
/setup - Show blocking modal - Cannot dismiss without completing required steps
- Progress indicator - Show completion percentage
3.2 Wizard Layout
+------------------------------------------------------------------+
| [StellaOps Logo] [?] Help [X] Exit |
+------------------------------------------------------------------+
| |
| SETUP WIZARD Step 1 of 10|
| |
| +------------+ +------------+ +------------+ +------------+ |
| | Database | | Valkey | | Migrations | | Admin | |
| | [1] | | [2] | | [3] | | [4] | |
| | [CURRENT] | | [PENDING] | | [PENDING] | | [PENDING] | |
| +------------+ +------------+ +------------+ +------------+ |
| |
| +------------+ +------------+ +------------+ +------------+ |
| | Crypto | | Vault | | SCM | | Notify | |
| | [5] | | [6] | | [7] | | [8] | |
| | [PENDING] | | [OPTIONAL] | | [OPTIONAL] | | [OPTIONAL] | |
| +------------+ +------------+ +------------+ +------------+ |
| |
| +------------+ +------------+ |
| | Environments| | Agents | |
| | [9] | | [10] | |
| | [OPTIONAL] | | [OPTIONAL] | |
| +------------+ +------------+ |
| |
+------------------------------------------------------------------+
| |
| DATABASE SETUP |
| --------------- |
| |
| Configure PostgreSQL connection for Stella Ops data storage. |
| |
| +----------------------------------------------------------+ |
| | Host [localhost ] | |
| | Port [5432 ] | |
| | Database [stellaops ] | |
| | Username [ ] | |
| | Password [ ] | |
| | SSL Mode [prefer v ] | |
| +----------------------------------------------------------+ |
| |
| [Test Connection] |
| |
| Connection Status: Not tested |
| |
+------------------------------------------------------------------+
| [Skip] [Continue] |
+------------------------------------------------------------------+
3.3 Step States
| State | Icon | Color | Description |
|---|---|---|---|
| PENDING | Circle | Gray | Not yet started |
| CURRENT | Circle+Ring | Blue | Currently active |
| PASSED | Checkmark | Green | Completed successfully |
| FAILED | X | Red | Failed validation |
| SKIPPED | Dash | Orange | Explicitly skipped |
| OPTIONAL | Circle+O | Gray | Can be skipped |
3.4 Connection Test Flow
+------------------------------------------------------------------+
| |
| [Test Connection] |
| |
| +----------------------------------------------------------+ |
| | Testing connection... | |
| | [=========> ] 30% | |
| | | |
| | [OK] TCP connection to localhost:5432 | |
| | [ ] Authenticating... | |
| | [ ] Checking permissions... | |
| +----------------------------------------------------------+ |
| |
+------------------------------------------------------------------+
3.5 Error State with Fixes
+------------------------------------------------------------------+
| |
| CONNECTION FAILED |
| |
| +----------------------------------------------------------+ |
| | [!] Could not connect to PostgreSQL | |
| | | |
| | Error: Connection refused (ECONNREFUSED) | |
| | | |
| | LIKELY CAUSES: | |
| | 1. PostgreSQL is not running | |
| | 2. Firewall blocking port 5432 | |
| | 3. Incorrect host or port | |
| | | |
| | SUGGESTED FIXES: | |
| | | |
| | If using Docker Compose: | |
| | +------------------------------------------------------+ | |
| | | docker compose up -d postgres [Copy]| | |
| | +------------------------------------------------------+ | |
| | | |
| | If using systemd: | |
| | +------------------------------------------------------+ | |
| | | sudo systemctl start postgresql [Copy]| | |
| | +------------------------------------------------------+ | |
| | | |
| | Verify connectivity: | |
| | +------------------------------------------------------+ | |
| | | pg_isready -h localhost -p 5432 [Copy]| | |
| | +------------------------------------------------------+ | |
| +----------------------------------------------------------+ |
| |
| [Retry] [Edit Configuration] |
+------------------------------------------------------------------+
3.6 Multi-Connector Interface
+------------------------------------------------------------------+
| |
| VAULT INTEGRATION (Optional) |
| --------------------------- |
| |
| Configure secrets management providers. |
| |
| CONFIGURED PROVIDERS: |
| +----------------------------------------------------------+ |
| | [V] HashiCorp Vault [Edit] [X] | |
| | https://vault.example.com:8200 | |
| | Status: Connected | |
| +----------------------------------------------------------+ |
| |
| [+ Add Another Provider] |
| |
| +----------------------------------------------------------+ |
| | SELECT PROVIDER TYPE: | |
| | | |
| | [HashiCorp Vault] [Azure Key Vault] | |
| | [AWS Secrets Mgr] [File Provider] | |
| +----------------------------------------------------------+ |
| |
| Note: You can add up to 5 vault integrations. |
| |
+------------------------------------------------------------------+
| [Skip] [Continue] |
+------------------------------------------------------------------+
3.7 Doctor Check Results Panel
+------------------------------------------------------------------+
| |
| VALIDATION RESULTS |
| ------------------ |
| |
| +----------------------------------------------------------+ |
| | [PASS] check.database.connectivity | |
| | PostgreSQL connection successful | |
| | | |
| | [PASS] check.database.permissions | |
| | User has required permissions | |
| | | |
| | [PASS] check.database.version | |
| | PostgreSQL 16.2 (minimum: 16.0) | |
| | | |
| | [WARN] check.database.poolsize | |
| | Pool size 10 is below recommended 50 | |
| | [Show Fix] | |
| +----------------------------------------------------------+ |
| |
| All required checks passed. |
| |
+------------------------------------------------------------------+
3.8 Skip Confirmation Dialog
+------------------------------------------------------------------+
| |
| +----------------------------------------------------------+ |
| | | |
| | SKIP VAULT INTEGRATION? | |
| | ----------------------- | |
| | | |
| | Without a secrets provider: | |
| | - Credentials stored in local keyring | |
| | - Air-gap deployments may require manual setup | |
| | - Production deployments not recommended | |
| | | |
| | You can configure this later from: | |
| | Settings > Configuration Wizard > Vault | |
| | | |
| | +----------------------------------------------------+ | |
| | | Reason for skipping (optional): | | |
| | | [Will configure after infrastructure ready ] | | |
| | +----------------------------------------------------+ | |
| | | |
| | [Cancel] [Skip This Step] | |
| +----------------------------------------------------------+ |
| |
+------------------------------------------------------------------+
3.9 Completion Screen
+------------------------------------------------------------------+
| |
| +----------------------------------------------------------+ |
| | | |
| | [Checkmark Icon] | |
| | | |
| | SETUP COMPLETE | |
| | | |
| | Status: OPERATIONAL | |
| | | |
| +----------------------------------------------------------+ |
| |
| COMPLETED STEPS: |
| +----------------------------------------------------------+ |
| | [x] Database Setup | |
| | [x] Valkey/Redis Setup | |
| | [x] Database Migrations | |
| | [x] Admin Bootstrap | |
| | [x] Crypto Profile | |
| | [x] Vault Integration | |
| | [x] SCM Integration | |
| | [x] Notification Channels | |
| +----------------------------------------------------------+ |
| |
| SKIPPED STEPS: |
| +----------------------------------------------------------+ |
| | [ ] Identity Provider (OIDC/LDAP) | |
| | [ ] Environment Definition | |
| | [ ] Agent Registration | |
| +----------------------------------------------------------+ |
| |
| NEXT STEPS: |
| +----------------------------------------------------------+ |
| | 1. Run your first scan | |
| | 2. Configure identity provider for SSO | |
| | 3. Set up environments for deployments | |
| +----------------------------------------------------------+ |
| |
| [Download Setup Report] [Go to Dashboard] |
| |
+------------------------------------------------------------------+
4. Configuration Pane (Post-Setup)
4.1 Access Points
| Surface | Path | Menu Location |
|---|---|---|
| UI | /settings/configuration | Settings > Configuration Wizard |
| CLI | stella setup --reconfigure | N/A |
4.2 Configuration Pane Layout
+------------------------------------------------------------------+
| CONFIGURATION WIZARD |
+------------------------------------------------------------------+
| |
| Last configured: January 13, 2026 at 10:30 AM |
| Status: Production-Ready |
| |
| INFRASTRUCTURE |
| +----------------------------------------------------------+ |
| | Database Setup [Healthy] [Reconfigure] | |
| | PostgreSQL 16.2 at localhost:5432 | |
| +----------------------------------------------------------+ |
| +----------------------------------------------------------+ |
| | Valkey/Redis Setup [Healthy] [Reconfigure] | |
| | Valkey at localhost:6379 | |
| +----------------------------------------------------------+ |
| |
| INTEGRATIONS |
| +----------------------------------------------------------+ |
| | Vault (2 providers) [Healthy] [Manage] | |
| | HashiCorp Vault, Azure Key Vault | |
| +----------------------------------------------------------+ |
| +----------------------------------------------------------+ |
| | SCM (1 provider) [Healthy] [Manage] | |
| | GitHub App | |
| +----------------------------------------------------------+ |
| +----------------------------------------------------------+ |
| | Notifications (3 channels) [Healthy] [Manage] | |
| | Slack, Email, PagerDuty | |
| +----------------------------------------------------------+ |
| |
| ORCHESTRATION |
| +----------------------------------------------------------+ |
| | Environments (3) [Healthy] [Manage] | |
| | dev, staging, prod | |
| +----------------------------------------------------------+ |
| +----------------------------------------------------------+ |
| | Agents (2) [1 Stale] [Manage] | |
| | docker-prod-01, docker-prod-02 | |
| +----------------------------------------------------------+ |
| |
| [Run Diagnostics] [Export Configuration] |
+------------------------------------------------------------------+
5. Wording Guidelines
5.1 Step Titles
| Step | Title | Subtitle |
|---|---|---|
database | Database Setup | Configure PostgreSQL connection |
valkey | Valkey/Redis Setup | Configure caching and message queue |
migrations | Database Migrations | Apply schema updates |
admin | Admin Bootstrap | Create administrator account |
crypto | Crypto Profile | Configure signing keys |
assurance | Assurance Packs | Review optional evidence-pack prerequisites |
sources | Advisory & VEX Sources | Enable StellaOps Mirror or manual feeds |
vault | Vault Integration | Configure secrets management |
scm | SCM Integration | Connect source control |
notifications | Notification Channels | Configure alerts and notifications |
environments | Environment Definition | Define deployment environments |
agents | Agent Registration | Register deployment agents |
5.2 Button Labels
| Action | Label |
|---|---|
| Proceed to next step | Continue |
| Skip optional step | Skip |
| Test configuration | Test Connection |
| Retry after failure | Retry |
| Add another connector | + Add Another |
| Edit existing | Edit |
| Remove | Remove |
| Complete wizard | Finish Setup |
5.3 Status Messages
| Status | Message |
|---|---|
| Testing | Testing connection… |
| Success | Connection successful |
| Failure | Could not connect |
| Timeout | Connection timed out |
| Permission denied | Permission denied |
5.4 Error Messages
Format: [What happened]. [Why it matters]. [What to do]
Example:
Could not connect to PostgreSQL. The database is required for all Stella Ops operations. Check that PostgreSQL is running and the connection details are correct.
6. Keyboard Navigation (UI)
| Key | Action |
|---|---|
Tab | Move to next field |
Shift+Tab | Move to previous field |
Enter | Submit form / Continue |
Escape | Cancel / Close dialog |
Ctrl+C | Copy command to clipboard |
1-9 | Jump to step number |
7. Accessibility Requirements
- Screen reader support - All form fields have labels
- Focus indicators - Visible focus rings on all interactive elements
- Color contrast - WCAG 2.1 AA compliance
- Keyboard navigation - Full functionality without mouse
- Error announcements - Errors announced to screen readers