28 KiB
28 KiB
Setup Wizard - UX Flow Specification
This document defines the user experience flows for both CLI and UI implementations of the Setup Wizard, ensuring feature parity across surfaces.
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") |
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 |
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