audit, advisories and doctors/setup work
This commit is contained in:
master
583
docs/setup/setup-wizard-capabilities.md
Normal file
583
docs/setup/setup-wizard-capabilities.md
Normal file
@@ -0,0 +1,583 @@
|
||||
# Setup Wizard - Capability Specification
|
||||
|
||||
This document defines the functional requirements for the Stella Ops Setup Wizard, covering both CLI and UI implementations.
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The Setup Wizard provides a guided, step-by-step configuration experience that:
|
||||
- Validates infrastructure dependencies (PostgreSQL, Valkey)
|
||||
- Runs database migrations
|
||||
- Configures required integrations
|
||||
- Sets up environments and agents
|
||||
- Verifies each step via Doctor checks
|
||||
|
||||
---
|
||||
|
||||
## 2. Completion Thresholds
|
||||
|
||||
### 2.1 Operational (Minimum Required)
|
||||
|
||||
The system enters "Operational" state when:
|
||||
|
||||
| Requirement | Description | Doctor Check |
|
||||
|-------------|-------------|--------------|
|
||||
| Database connected | PostgreSQL is reachable and authenticated | `check.database.connectivity` |
|
||||
| Migrations applied | All startup migrations complete, no pending release migrations | `check.database.migrations.applied` |
|
||||
| Core services healthy | Gateway, Router, Authority respond to health probes | `check.services.core.healthy` |
|
||||
| Admin user exists | At least one admin user with `admin:*` scope | `check.auth.admin.exists` |
|
||||
| Crypto profile valid | At least one signing key configured | `check.crypto.profile.valid` |
|
||||
|
||||
**Gating Behavior:** UI blocks access to operational features until Operational threshold met.
|
||||
|
||||
### 2.2 Production-Ready (Recommended)
|
||||
|
||||
The system reaches "Production-Ready" state when:
|
||||
|
||||
| Requirement | Description | Doctor Check |
|
||||
|-------------|-------------|--------------|
|
||||
| OIDC/LDAP configured | External identity provider integrated | `check.security.identity.configured` |
|
||||
| Vault connected | At least one secrets provider | `check.integration.vault.connected` |
|
||||
| SCM integrated | At least one SCM (GitHub/GitLab) | `check.integration.scm.connected` |
|
||||
| Notifications configured | At least one notification channel | `check.notify.channel.configured` |
|
||||
| Feed sync enabled | Vulnerability feed mirroring active | `check.feeds.sync.enabled` |
|
||||
| Environment defined | At least one environment created | `check.orchestrator.environment.exists` |
|
||||
| Agent registered | At least one healthy agent | `check.orchestrator.agent.healthy` |
|
||||
| TLS hardened | All endpoints using TLS 1.2+ | `check.security.tls.hardened` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Step Catalog
|
||||
|
||||
### 3.1 Core Steps
|
||||
|
||||
| Step ID | Name | Required | Skippable | Category |
|
||||
|---------|------|----------|-----------|----------|
|
||||
| `database` | Database Setup | Yes | No | Infrastructure |
|
||||
| `valkey` | Valkey/Redis Setup | Yes | No | Infrastructure |
|
||||
| `migrations` | Database Migrations | Yes | No | Infrastructure |
|
||||
| `admin` | Admin Bootstrap | Yes | No | Security |
|
||||
| `crypto` | Crypto Profile | Yes | No | Security |
|
||||
|
||||
### 3.2 Integration Steps
|
||||
|
||||
| Step ID | Name | Required | Skippable | Category |
|
||||
|---------|------|----------|-----------|----------|
|
||||
| `vault` | Secrets Provider | No | Yes | Integration |
|
||||
| `settingsstore` | Settings Store | No | Yes | Integration |
|
||||
| `scm` | Source Control | No | Yes | Integration |
|
||||
| `registry` | Container Registry | No | Yes | Integration |
|
||||
| `notifications` | Notification Channels | No | Yes | Integration |
|
||||
| `identity` | Identity Provider (OIDC/LDAP) | No | Yes | Security |
|
||||
|
||||
### 3.3 Orchestration Steps
|
||||
|
||||
| Step ID | Name | Required | Skippable | Category |
|
||||
|---------|------|----------|-----------|----------|
|
||||
| `environments` | Environment Definition | No | Yes | Orchestration |
|
||||
| `agents` | Agent Registration | No | Yes | Orchestration |
|
||||
| `feeds` | Vulnerability Feeds | No | Yes | Data |
|
||||
|
||||
---
|
||||
|
||||
## 4. Step Specifications
|
||||
|
||||
### 4.1 Database Setup (`database`)
|
||||
|
||||
**Purpose:** Configure PostgreSQL connection and verify accessibility.
|
||||
|
||||
**Inputs:**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `host` | string | Yes | `localhost` | PostgreSQL host |
|
||||
| `port` | number | Yes | `5432` | PostgreSQL port |
|
||||
| `database` | string | Yes | `stellaops` | Database name |
|
||||
| `username` | string | Yes | - | Database user |
|
||||
| `password` | secret | Yes | - | Database password |
|
||||
| `sslMode` | enum | No | `prefer` | SSL mode (disable, prefer, require, verify-ca, verify-full) |
|
||||
| `poolSize` | number | No | `100` | Connection pool size |
|
||||
|
||||
**Outputs:**
|
||||
- Connection string stored in settings store
|
||||
- Connection verified via `SELECT 1`
|
||||
- Schema creation permissions validated
|
||||
|
||||
**Validation:**
|
||||
- TCP connectivity to host:port
|
||||
- Authentication with credentials
|
||||
- `CREATE SCHEMA` permission check
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.database.connectivity`
|
||||
- `check.database.permissions`
|
||||
- `check.database.version` (PostgreSQL >= 16)
|
||||
|
||||
**Persistence:**
|
||||
- Environment: `STELLAOPS_POSTGRES_CONNECTION`
|
||||
- Config: `Storage:ConnectionString` in Authority options
|
||||
- Encrypted storage of password via configured Vault or local keyring
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Valkey/Redis Setup (`valkey`)
|
||||
|
||||
**Purpose:** Configure Valkey/Redis for caching, queues, and session storage.
|
||||
|
||||
**Inputs:**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `host` | string | Yes | `localhost` | Valkey host |
|
||||
| `port` | number | Yes | `6379` | Valkey port |
|
||||
| `password` | secret | No | - | Valkey password |
|
||||
| `database` | number | No | `0` | Database index (0-15) |
|
||||
| `useTls` | boolean | No | `false` | Enable TLS |
|
||||
| `abortOnConnectFail` | boolean | No | `false` | Fail fast on connection error |
|
||||
|
||||
**Outputs:**
|
||||
- Connection string stored in settings
|
||||
- PING response verified
|
||||
|
||||
**Validation:**
|
||||
- TCP connectivity
|
||||
- AUTH if password provided
|
||||
- PING response within 5 seconds
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.services.valkey.connectivity`
|
||||
- `check.services.valkey.ping`
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Database Migrations (`migrations`)
|
||||
|
||||
**Purpose:** Apply pending database migrations across all modules.
|
||||
|
||||
**Inputs:**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `modules` | string[] | No | `["all"]` | Modules to migrate |
|
||||
| `dryRun` | boolean | No | `false` | Preview without applying |
|
||||
| `force` | boolean | No | `false` | Allow release migrations |
|
||||
|
||||
**Outputs:**
|
||||
- List of applied migrations per module
|
||||
- Schema version recorded in `schema_migrations` table
|
||||
- Checksum verification results
|
||||
|
||||
**Validation:**
|
||||
- Advisory lock acquisition
|
||||
- Checksum match for already-applied migrations
|
||||
- No pending release migrations (unless force=true)
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.database.migrations.applied`
|
||||
- `check.database.migrations.checksums`
|
||||
- `check.database.schema.version`
|
||||
|
||||
---
|
||||
|
||||
### 4.4 Admin Bootstrap (`admin`)
|
||||
|
||||
**Purpose:** Create initial administrator account.
|
||||
|
||||
**Inputs:**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `username` | string | Yes | `admin` | Admin username |
|
||||
| `email` | string | Yes | - | Admin email |
|
||||
| `password` | secret | Yes | - | Admin password |
|
||||
| `displayName` | string | No | - | Display name |
|
||||
|
||||
**Validation:**
|
||||
- Password complexity (min 12 chars, mixed case, numbers, symbols)
|
||||
- Email format
|
||||
- Username uniqueness
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.auth.admin.exists`
|
||||
- `check.auth.password.policy`
|
||||
|
||||
---
|
||||
|
||||
### 4.5 Crypto Profile (`crypto`)
|
||||
|
||||
**Purpose:** Configure cryptographic signing keys for attestations.
|
||||
|
||||
**Inputs:**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `profileType` | enum | Yes | - | `local`, `kms`, `hsm`, `sigstore` |
|
||||
| `keyAlgorithm` | enum | No | `ecdsa-p256` | Key algorithm |
|
||||
| `keyId` | string | Conditional | - | KMS/HSM key identifier |
|
||||
| `certificatePath` | string | Conditional | - | Path to signing certificate |
|
||||
| `privateKeyPath` | string | Conditional | - | Path to private key |
|
||||
|
||||
**Validation:**
|
||||
- Key material accessible
|
||||
- Algorithm supported
|
||||
- Certificate chain valid (if provided)
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.crypto.profile.valid`
|
||||
- `check.crypto.signing.test`
|
||||
|
||||
---
|
||||
|
||||
### 4.6 Vault Integration (`vault`)
|
||||
|
||||
**Purpose:** Configure secrets management provider.
|
||||
|
||||
**Multi-Connector Support:** Yes - users can add multiple vault integrations.
|
||||
|
||||
**Connector Options:**
|
||||
|
||||
| Connector | Default | Description |
|
||||
|-----------|---------|-------------|
|
||||
| **HashiCorp Vault** | Yes (if detected) | KV v2 secrets engine |
|
||||
| **Azure Key Vault** | Yes (if Azure env) | Azure-native secrets |
|
||||
| **AWS Secrets Manager** | Yes (if AWS env) | AWS-native secrets |
|
||||
| **File Provider** | Fallback | Local file-based secrets |
|
||||
|
||||
**Inputs (HashiCorp Vault):**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `address` | string | Yes | - | Vault server URL |
|
||||
| `authMethod` | enum | Yes | `token` | token, approle, kubernetes |
|
||||
| `mountPoint` | string | No | `secret` | KV mount point |
|
||||
| `token` | secret | Conditional | - | Vault token |
|
||||
| `roleId` | string | Conditional | - | AppRole role ID |
|
||||
| `secretId` | secret | Conditional | - | AppRole secret ID |
|
||||
|
||||
**Default Selection Logic:**
|
||||
1. If `VAULT_ADDR` env var set → HashiCorp Vault
|
||||
2. If Azure IMDS available → Azure Key Vault
|
||||
3. If AWS metadata available → AWS Secrets Manager
|
||||
4. Otherwise → Prompt user
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.integration.vault.connected`
|
||||
- `check.integration.vault.auth`
|
||||
- `check.integration.vault.secrets.access`
|
||||
|
||||
---
|
||||
|
||||
### 4.7 Settings Store Integration (`settingsstore`)
|
||||
|
||||
**Purpose:** Configure application settings and feature flag providers.
|
||||
|
||||
**Multi-Connector Support:** Yes - users can add multiple settings stores for different purposes.
|
||||
|
||||
**Connector Options:**
|
||||
|
||||
| Connector | Priority | Write | Watch | Feature Flags | Labels |
|
||||
|-----------|----------|-------|-------|---------------|--------|
|
||||
| **Consul KV** | P0 | Configurable | Yes | No | No |
|
||||
| **etcd** | P0 | Configurable | Yes | No | No |
|
||||
| **Azure App Configuration** | P1 | Read-only | Yes | Yes (native) | Yes |
|
||||
| **AWS Parameter Store** | P1 | Configurable | No | No | Via path |
|
||||
| **AWS AppConfig** | P2 | Read-only | Yes | Yes (native) | Yes |
|
||||
| **ZooKeeper** | P2 | Configurable | Yes | No | No |
|
||||
| **GCP Runtime Config** | P2 | Read-only | Yes | No | No |
|
||||
|
||||
**Inputs (Consul KV):**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `address` | string | Yes | - | Consul server URL |
|
||||
| `token` | secret | No | - | ACL token |
|
||||
| `tokenSecretRef` | string | No | - | Vault path to ACL token |
|
||||
| `writeEnabled` | boolean | No | `false` | Enable write operations |
|
||||
|
||||
**Inputs (etcd):**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `address` | string | Conditional | - | Single endpoint URL |
|
||||
| `endpoints` | string[] | Conditional | - | Multiple endpoint URLs |
|
||||
| `username` | string | No | - | Authentication username |
|
||||
| `password` | secret | No | - | Authentication password |
|
||||
| `passwordSecretRef` | string | No | - | Vault path to password |
|
||||
| `writeEnabled` | boolean | No | `false` | Enable write operations |
|
||||
|
||||
**Default Selection Logic:**
|
||||
1. If `CONSUL_HTTP_ADDR` env var set -> Consul KV
|
||||
2. If `ETCD_ENDPOINTS` env var set -> etcd
|
||||
3. If Azure IMDS + App Config connection available -> Azure App Configuration
|
||||
4. If AWS metadata + `/stellaops/` path exists -> AWS Parameter Store
|
||||
5. Otherwise -> Prompt user
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.integration.settingsstore.connectivity`
|
||||
- `check.integration.settingsstore.auth`
|
||||
- `check.integration.settingsstore.read`
|
||||
- `check.integration.settingsstore.write` (if write enabled)
|
||||
- `check.integration.settingsstore.latency`
|
||||
|
||||
---
|
||||
|
||||
### 4.8 SCM Integration (`scm`)
|
||||
|
||||
**Purpose:** Configure source control management integrations.
|
||||
|
||||
**Multi-Connector Support:** Yes - users can add GitHub AND GitLab simultaneously.
|
||||
|
||||
**Connector Options:**
|
||||
|
||||
| Connector | Description |
|
||||
|-----------|-------------|
|
||||
| **GitHub App** | GitHub.com or GHES via App installation |
|
||||
| **GitLab Server** | GitLab.com or self-hosted |
|
||||
| **Bitbucket** | Bitbucket Cloud or Server |
|
||||
| **Gitea** | Self-hosted Gitea |
|
||||
| **Azure DevOps** | Azure Repos |
|
||||
|
||||
**Inputs (GitHub App):**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `appId` | string | Yes | - | GitHub App ID |
|
||||
| `installationId` | string | Yes | - | Installation ID |
|
||||
| `privateKey` | secret | Yes | - | App private key (PEM) |
|
||||
| `apiUrl` | string | No | `https://api.github.com` | API endpoint |
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.integration.scm.github.auth`
|
||||
- `check.integration.scm.github.permissions`
|
||||
|
||||
---
|
||||
|
||||
### 4.9 Notification Channels (`notifications`)
|
||||
|
||||
**Purpose:** Configure notification delivery channels.
|
||||
|
||||
**Multi-Connector Support:** Yes - multiple channels per type allowed.
|
||||
|
||||
**Channel Options:**
|
||||
|
||||
| Channel | Description |
|
||||
|---------|-------------|
|
||||
| **Slack** | Incoming webhook |
|
||||
| **Teams** | Incoming webhook |
|
||||
| **Email** | SMTP server |
|
||||
| **Webhook** | Generic HTTP POST |
|
||||
| **PagerDuty** | Incident alerts |
|
||||
|
||||
**Inputs (Slack):**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `name` | string | Yes | - | Channel display name |
|
||||
| `webhookUrl` | secret | Yes | - | Slack incoming webhook URL |
|
||||
| `channel` | string | No | - | Default channel override |
|
||||
| `username` | string | No | `StellaOps` | Bot username |
|
||||
| `iconEmoji` | string | No | `:shield:` | Bot icon |
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.notify.channel.configured`
|
||||
- `check.notify.slack.webhook`
|
||||
- `check.notify.delivery.test`
|
||||
|
||||
---
|
||||
|
||||
### 4.10 Environment Definition (`environments`)
|
||||
|
||||
**Purpose:** Define deployment environments (dev, staging, prod).
|
||||
|
||||
**Inputs:**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `name` | string | Yes | - | Environment slug (lowercase) |
|
||||
| `displayName` | string | Yes | - | Display name |
|
||||
| `orderIndex` | number | Yes | - | Pipeline position (0=first) |
|
||||
| `isProduction` | boolean | No | `false` | Production flag |
|
||||
| `requiredApprovals` | number | No | `0` | Approval count |
|
||||
| `requireSeparationOfDuties` | boolean | No | `false` | SoD enforcement |
|
||||
| `autoPromoteFrom` | string | No | - | Auto-promote source |
|
||||
|
||||
**Validation:**
|
||||
- Production environments require `requiredApprovals >= 1`
|
||||
- `autoPromoteFrom` must reference existing environment with lower orderIndex
|
||||
- Name must match `^[a-z][a-z0-9-]{1,31}$`
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.orchestrator.environment.exists`
|
||||
- `check.orchestrator.environment.valid`
|
||||
|
||||
---
|
||||
|
||||
### 4.11 Agent Registration (`agents`)
|
||||
|
||||
**Purpose:** Register deployment agents with the orchestrator.
|
||||
|
||||
**Inputs:**
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `name` | string | Yes | - | Agent name |
|
||||
| `capabilities` | string[] | Yes | - | `docker`, `compose`, `ssh`, `winrm` |
|
||||
| `labels` | map | No | `{}` | Agent labels for selection |
|
||||
|
||||
**Outputs:**
|
||||
- Registration token (one-time, 24-hour expiry)
|
||||
- Agent installation command
|
||||
|
||||
**Generated Command:**
|
||||
```bash
|
||||
stella-agent register --token <token> --name <name> --orchestrator-url <url>
|
||||
```
|
||||
|
||||
**Doctor Checks:**
|
||||
- `check.orchestrator.agent.registered`
|
||||
- `check.orchestrator.agent.healthy`
|
||||
- `check.orchestrator.agent.certificate`
|
||||
|
||||
---
|
||||
|
||||
## 5. Multi-Connector Model
|
||||
|
||||
### 5.1 Connector Categories
|
||||
|
||||
Each integration category supports multiple instances:
|
||||
|
||||
| Category | Max Instances | Use Case |
|
||||
|----------|---------------|----------|
|
||||
| **Vault** | 5 | Separate vaults per environment |
|
||||
| **Settings Store** | 5 | Config from Azure App Config + feature flags from Consul |
|
||||
| **SCM** | 10 | GitHub + GitLab + internal Gitea |
|
||||
| **Registry** | 10 | ECR + Harbor + internal registry |
|
||||
| **Notifications** | 20 | Slack per team + email + PagerDuty |
|
||||
|
||||
### 5.2 Default Connector Selection
|
||||
|
||||
The wizard suggests a default connector based on:
|
||||
|
||||
1. **Environment Detection:**
|
||||
- `VAULT_ADDR` -> HashiCorp Vault
|
||||
- `CONSUL_HTTP_ADDR` -> Consul KV
|
||||
- `ETCD_ENDPOINTS` -> etcd
|
||||
- Azure IMDS -> Azure Key Vault / Azure App Configuration
|
||||
- AWS metadata -> AWS Secrets Manager / AWS Parameter Store
|
||||
- `GITHUB_TOKEN` -> GitHub
|
||||
- `GITLAB_TOKEN` -> GitLab
|
||||
|
||||
2. **Configuration Files:**
|
||||
- Existing `etc/*.yaml` samples
|
||||
- Docker Compose environment files
|
||||
|
||||
3. **Repository Defaults:**
|
||||
- Harbor (most commonly used registry)
|
||||
- Slack (most common notification)
|
||||
|
||||
### 5.3 Last Selected Connector Persistence
|
||||
|
||||
The wizard stores user preferences in the settings store:
|
||||
|
||||
```json
|
||||
{
|
||||
"setupWizard": {
|
||||
"lastConnectors": {
|
||||
"vault": "hashicorp-vault",
|
||||
"settingsstore": "consul-kv",
|
||||
"scm": "github-app",
|
||||
"registry": "harbor",
|
||||
"notifications": "slack"
|
||||
},
|
||||
"completedAt": "2026-01-13T10:30:00Z",
|
||||
"skippedSteps": ["identity", "feeds"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Resume/Re-run Behavior
|
||||
|
||||
### 6.1 Idempotency Requirements
|
||||
|
||||
All steps must be safe to re-run:
|
||||
|
||||
| Step | Re-run Behavior |
|
||||
|------|-----------------|
|
||||
| `database` | Verify connection; no changes if already configured |
|
||||
| `migrations` | Skip already-applied; apply only pending |
|
||||
| `admin` | Skip if admin exists; offer password reset |
|
||||
| `vault` | Add new integration; don't duplicate |
|
||||
| `settingsstore` | Add new integration; don't duplicate |
|
||||
| `scm` | Add new integration; don't duplicate |
|
||||
|
||||
### 6.2 Configuration Pane Access
|
||||
|
||||
After initial setup, the wizard is available from:
|
||||
- **CLI:** `stella setup --reconfigure`
|
||||
- **UI:** Settings > Configuration Wizard
|
||||
|
||||
Pre-populated with:
|
||||
- Current configuration values
|
||||
- Last selected connector per category
|
||||
- Health status from Doctor checks
|
||||
|
||||
---
|
||||
|
||||
## 7. Security Posture
|
||||
|
||||
### 7.1 Secret Storage
|
||||
|
||||
| Secret Type | Storage Location |
|
||||
|-------------|------------------|
|
||||
| Database password | Vault (if configured) or local keyring |
|
||||
| Valkey password | Vault (if configured) or local keyring |
|
||||
| API tokens | Vault integration |
|
||||
| Private keys | File system with 0600 permissions |
|
||||
|
||||
### 7.2 Redaction Rules
|
||||
|
||||
The wizard must never display:
|
||||
- Full passwords
|
||||
- API tokens
|
||||
- Private key contents
|
||||
- Vault tokens
|
||||
|
||||
Display format for sensitive fields:
|
||||
- Masked: `********`
|
||||
- Partial: `ghp_****1234` (first 4 + last 4)
|
||||
|
||||
### 7.3 Audit Trail
|
||||
|
||||
All wizard actions are logged to:
|
||||
- Timeline service with HLC timestamps
|
||||
- Authority audit log for admin operations
|
||||
- Doctor run history for check results
|
||||
|
||||
---
|
||||
|
||||
## 8. Error Handling
|
||||
|
||||
### 8.1 Validation Errors
|
||||
|
||||
| Error Type | Behavior |
|
||||
|------------|----------|
|
||||
| Invalid input | Inline error message; prevent progression |
|
||||
| Connection failure | Show error; offer retry with different params |
|
||||
| Permission denied | Show required permissions; offer skip (if skippable) |
|
||||
| Timeout | Show timeout; offer retry with increased timeout |
|
||||
|
||||
### 8.2 Partial Completion
|
||||
|
||||
If wizard exits mid-flow:
|
||||
- Completed steps are persisted
|
||||
- Resume shows current state
|
||||
- Doctor checks identify incomplete setup
|
||||
|
||||
---
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
### 9.1 Successful Completion
|
||||
|
||||
The wizard completes successfully when:
|
||||
- All required steps pass Doctor checks
|
||||
- User has explicitly skipped or completed all steps
|
||||
- Operational threshold is met
|
||||
|
||||
### 9.2 Completion Actions
|
||||
|
||||
On completion:
|
||||
1. Run full Doctor diagnostic
|
||||
2. Generate setup report (Markdown)
|
||||
3. Emit `setup.completed` timeline event
|
||||
4. Clear first-run flag
|
||||
5. Redirect to dashboard (UI) or exit with success (CLI)
|
||||
608
docs/setup/setup-wizard-doctor-contract.md
Normal file
608
docs/setup/setup-wizard-doctor-contract.md
Normal file
@@ -0,0 +1,608 @@
|
||||
# Setup Wizard - Doctor Integration Contract
|
||||
|
||||
This document defines how the Setup Wizard integrates with the Doctor diagnostic system to validate each step and provide actionable remediation guidance.
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The Setup Wizard relies on Doctor checks to:
|
||||
1. **Validate** each configuration step
|
||||
2. **Detect** existing configuration (for resume/reconfigure)
|
||||
3. **Generate** runtime-specific fix commands
|
||||
4. **Verify** that fixes were applied correctly
|
||||
|
||||
---
|
||||
|
||||
## 2. Step-to-Check Mapping
|
||||
|
||||
### 2.1 Required Steps
|
||||
|
||||
| Step ID | Doctor Check ID | Severity | Blocks Progression |
|
||||
|---------|-----------------|----------|-------------------|
|
||||
| `database` | `check.database.connectivity` | Critical | Yes |
|
||||
| `database` | `check.database.permissions` | Critical | Yes |
|
||||
| `database` | `check.database.version` | Warning | No |
|
||||
| `valkey` | `check.services.valkey.connectivity` | Critical | Yes |
|
||||
| `valkey` | `check.services.valkey.ping` | Critical | Yes |
|
||||
| `migrations` | `check.database.migrations.applied` | Critical | Yes |
|
||||
| `migrations` | `check.database.migrations.checksums` | Critical | Yes |
|
||||
| `migrations` | `check.database.schema.version` | Info | No |
|
||||
| `admin` | `check.auth.admin.exists` | Critical | Yes |
|
||||
| `admin` | `check.auth.password.policy` | Warning | No |
|
||||
| `crypto` | `check.crypto.profile.valid` | Critical | Yes |
|
||||
| `crypto` | `check.crypto.signing.test` | Warning | No |
|
||||
|
||||
### 2.2 Optional Steps
|
||||
|
||||
| Step ID | Doctor Check ID | Severity | Blocks Progression |
|
||||
|---------|-----------------|----------|-------------------|
|
||||
| `vault` | `check.integration.vault.connected` | Warning | No |
|
||||
| `vault` | `check.integration.vault.auth` | Warning | No |
|
||||
| `vault` | `check.integration.vault.secrets.access` | Info | No |
|
||||
| `scm` | `check.integration.scm.github.auth` | Info | No |
|
||||
| `scm` | `check.integration.scm.github.permissions` | Info | No |
|
||||
| `scm` | `check.integration.scm.gitlab.auth` | Info | No |
|
||||
| `registry` | `check.integration.registry.connected` | Info | No |
|
||||
| `notifications` | `check.notify.channel.configured` | Info | No |
|
||||
| `notifications` | `check.notify.slack.webhook` | Info | No |
|
||||
| `notifications` | `check.notify.email.smtp` | Info | No |
|
||||
| `identity` | `check.security.identity.configured` | Info | No |
|
||||
| `identity` | `check.security.oidc.provider` | Info | No |
|
||||
| `environments` | `check.orchestrator.environment.exists` | Info | No |
|
||||
| `environments` | `check.orchestrator.environment.valid` | Info | No |
|
||||
| `agents` | `check.orchestrator.agent.registered` | Info | No |
|
||||
| `agents` | `check.orchestrator.agent.healthy` | Info | No |
|
||||
| `feeds` | `check.feeds.sync.enabled` | Info | No |
|
||||
|
||||
---
|
||||
|
||||
## 3. Check Output Model
|
||||
|
||||
### 3.1 CheckResult Schema
|
||||
|
||||
```csharp
|
||||
public sealed record CheckResult
|
||||
{
|
||||
public required string CheckId { get; init; }
|
||||
public required CheckStatus Status { get; init; } // Pass, Warn, Fail
|
||||
public required string Message { get; init; }
|
||||
public required TimeSpan Duration { get; init; }
|
||||
public ImmutableDictionary<string, object> Evidence { get; init; }
|
||||
public ImmutableArray<LikelyCause> LikelyCauses { get; init; }
|
||||
public ImmutableArray<RemediationCommand> Remediations { get; init; }
|
||||
public string? VerificationCommand { get; init; }
|
||||
}
|
||||
|
||||
public enum CheckStatus { Pass, Warn, Fail }
|
||||
|
||||
public sealed record LikelyCause
|
||||
{
|
||||
public required int Priority { get; init; } // 1 = most likely
|
||||
public required string Description { get; init; }
|
||||
public string? DocumentationUrl { get; init; }
|
||||
}
|
||||
|
||||
public sealed record RemediationCommand
|
||||
{
|
||||
public required RuntimeEnvironment Runtime { get; init; }
|
||||
public required string Command { get; init; }
|
||||
public required string Description { get; init; }
|
||||
public bool RequiresSudo { get; init; }
|
||||
public bool IsDangerous { get; init; } // Requires confirmation
|
||||
public ImmutableDictionary<string, string> Placeholders { get; init; }
|
||||
}
|
||||
|
||||
public enum RuntimeEnvironment
|
||||
{
|
||||
DockerCompose,
|
||||
Kubernetes,
|
||||
Systemd,
|
||||
WindowsService,
|
||||
Bare,
|
||||
Any
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Evidence Dictionary
|
||||
|
||||
The `Evidence` dictionary contains check-specific data:
|
||||
|
||||
| Check Category | Evidence Keys |
|
||||
|----------------|---------------|
|
||||
| **Database** | `host`, `port`, `database`, `version`, `user`, `sslMode` |
|
||||
| **Valkey** | `host`, `port`, `version`, `usedMemory`, `maxMemory` |
|
||||
| **Migrations** | `pendingCount`, `appliedCount`, `lastMigration`, `failedMigrations` |
|
||||
| **Auth** | `adminCount`, `adminUsername`, `passwordLastChanged` |
|
||||
| **Vault** | `provider`, `version`, `mountPoints`, `authMethod` |
|
||||
| **SCM** | `provider`, `rateLimit`, `remainingCalls`, `organization` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Remediation Command Generation
|
||||
|
||||
### 4.1 Runtime Detection
|
||||
|
||||
The wizard detects the runtime environment via:
|
||||
|
||||
```csharp
|
||||
public interface IRuntimeDetector
|
||||
{
|
||||
RuntimeEnvironment Detect();
|
||||
bool IsDockerAvailable();
|
||||
bool IsKubernetesContext();
|
||||
bool IsSystemdManaged(string serviceName);
|
||||
string GetComposeProjectPath();
|
||||
string GetKubernetesNamespace();
|
||||
}
|
||||
```
|
||||
|
||||
Detection logic:
|
||||
1. Check for `/.dockerenv` file → Docker container
|
||||
2. Check for `KUBERNETES_SERVICE_HOST` → Kubernetes
|
||||
3. Check for `docker compose` command → Docker Compose
|
||||
4. Check for `systemctl` command → systemd
|
||||
5. Check for Windows services → Windows Service
|
||||
6. Default → Bare (manual)
|
||||
|
||||
### 4.2 Command Templates
|
||||
|
||||
#### Database Connection Failure
|
||||
|
||||
```yaml
|
||||
check.database.connectivity:
|
||||
likelyCauses:
|
||||
- priority: 1
|
||||
description: "PostgreSQL is not running"
|
||||
- priority: 2
|
||||
description: "Firewall blocking port 5432"
|
||||
- priority: 3
|
||||
description: "Incorrect host or port"
|
||||
- priority: 4
|
||||
description: "Network connectivity issue"
|
||||
|
||||
remediations:
|
||||
- runtime: DockerCompose
|
||||
description: "Start PostgreSQL container"
|
||||
command: "docker compose -f {{COMPOSE_FILE}} up -d postgres"
|
||||
placeholders:
|
||||
COMPOSE_FILE: "devops/compose/docker-compose.yml"
|
||||
|
||||
- runtime: Kubernetes
|
||||
description: "Check PostgreSQL pod status"
|
||||
command: "kubectl get pods -n {{NAMESPACE}} -l app=postgres"
|
||||
placeholders:
|
||||
NAMESPACE: "stellaops"
|
||||
|
||||
- runtime: Systemd
|
||||
description: "Start PostgreSQL service"
|
||||
command: "sudo systemctl start postgresql"
|
||||
requiresSudo: true
|
||||
|
||||
- runtime: Any
|
||||
description: "Verify PostgreSQL is listening"
|
||||
command: "pg_isready -h {{HOST}} -p {{PORT}}"
|
||||
placeholders:
|
||||
HOST: "localhost"
|
||||
PORT: "5432"
|
||||
|
||||
verificationCommand: "pg_isready -h {{HOST}} -p {{PORT}}"
|
||||
```
|
||||
|
||||
#### Valkey Connection Failure
|
||||
|
||||
```yaml
|
||||
check.services.valkey.connectivity:
|
||||
likelyCauses:
|
||||
- priority: 1
|
||||
description: "Valkey/Redis is not running"
|
||||
- priority: 2
|
||||
description: "Firewall blocking port 6379"
|
||||
- priority: 3
|
||||
description: "Authentication required but not configured"
|
||||
|
||||
remediations:
|
||||
- runtime: DockerCompose
|
||||
description: "Start Valkey container"
|
||||
command: "docker compose -f {{COMPOSE_FILE}} up -d valkey"
|
||||
placeholders:
|
||||
COMPOSE_FILE: "devops/compose/docker-compose.yml"
|
||||
|
||||
- runtime: Kubernetes
|
||||
description: "Check Valkey pod status"
|
||||
command: "kubectl get pods -n {{NAMESPACE}} -l app=valkey"
|
||||
placeholders:
|
||||
NAMESPACE: "stellaops"
|
||||
|
||||
- runtime: Systemd
|
||||
description: "Start Valkey service"
|
||||
command: "sudo systemctl start valkey"
|
||||
requiresSudo: true
|
||||
|
||||
- runtime: Any
|
||||
description: "Test Valkey connection"
|
||||
command: "redis-cli -h {{HOST}} -p {{PORT}} PING"
|
||||
placeholders:
|
||||
HOST: "localhost"
|
||||
PORT: "6379"
|
||||
|
||||
verificationCommand: "redis-cli -h {{HOST}} -p {{PORT}} PING"
|
||||
```
|
||||
|
||||
#### Pending Migrations
|
||||
|
||||
```yaml
|
||||
check.database.migrations.applied:
|
||||
likelyCauses:
|
||||
- priority: 1
|
||||
description: "Pending release migrations require manual execution"
|
||||
- priority: 2
|
||||
description: "Startup migrations not yet applied"
|
||||
|
||||
remediations:
|
||||
- runtime: Any
|
||||
description: "Run pending migrations (dry-run first)"
|
||||
command: "stella migrations-run --module all --dry-run"
|
||||
|
||||
- runtime: Any
|
||||
description: "Apply all pending migrations"
|
||||
command: "stella migrations-run --module all"
|
||||
isDangerous: true
|
||||
|
||||
- runtime: DockerCompose
|
||||
description: "Run migrations in container"
|
||||
command: "docker compose exec api stella migrations-run --module all"
|
||||
|
||||
- runtime: Kubernetes
|
||||
description: "Run migrations job"
|
||||
command: "kubectl apply -f devops/k8s/jobs/migrations.yaml"
|
||||
|
||||
verificationCommand: "stella migrations-run --module all --dry-run"
|
||||
```
|
||||
|
||||
#### Vault Authentication Failure
|
||||
|
||||
```yaml
|
||||
check.integration.vault.auth:
|
||||
likelyCauses:
|
||||
- priority: 1
|
||||
description: "Vault token expired or revoked"
|
||||
- priority: 2
|
||||
description: "AppRole credentials invalid"
|
||||
- priority: 3
|
||||
description: "Kubernetes service account not configured"
|
||||
- priority: 4
|
||||
description: "Vault server unreachable"
|
||||
|
||||
remediations:
|
||||
- runtime: Any
|
||||
description: "Test Vault connectivity"
|
||||
command: "curl -s {{VAULT_ADDR}}/v1/sys/health"
|
||||
placeholders:
|
||||
VAULT_ADDR: "https://vault.example.com:8200"
|
||||
|
||||
- runtime: Any
|
||||
description: "Verify token validity"
|
||||
command: "vault token lookup"
|
||||
|
||||
- runtime: Kubernetes
|
||||
description: "Check Kubernetes auth configuration"
|
||||
command: "kubectl get serviceaccount -n {{NAMESPACE}} stellaops-vault-auth"
|
||||
placeholders:
|
||||
NAMESPACE: "stellaops"
|
||||
|
||||
verificationCommand: "vault token lookup"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Placeholder Resolution
|
||||
|
||||
### 5.1 Placeholder Sources
|
||||
|
||||
Placeholders in commands are resolved from:
|
||||
|
||||
| Source | Priority | Example |
|
||||
|--------|----------|---------|
|
||||
| User input | 1 (highest) | `{{HOST}}` from form field |
|
||||
| Environment | 2 | `{{VAULT_ADDR}}` from env |
|
||||
| Detection | 3 | `{{NAMESPACE}}` from context |
|
||||
| Default | 4 (lowest) | Fallback value |
|
||||
|
||||
### 5.2 Placeholder Syntax
|
||||
|
||||
```
|
||||
{{PLACEHOLDER_NAME}}
|
||||
{{PLACEHOLDER_NAME:-default_value}}
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `{{HOST}}` - Required placeholder
|
||||
- `{{PORT:-5432}}` - Optional with default
|
||||
- `{{COMPOSE_FILE:-docker-compose.yml}}` - File path default
|
||||
|
||||
### 5.3 Secret Redaction
|
||||
|
||||
Commands containing secrets are never displayed with actual values:
|
||||
|
||||
| Placeholder | Display | Actual |
|
||||
|-------------|---------|--------|
|
||||
| `{{PASSWORD}}` | `{{PASSWORD}}` | Never resolved in display |
|
||||
| `{{TOKEN}}` | `{{TOKEN}}` | Never resolved in display |
|
||||
| `{{SECRET_KEY}}` | `{{SECRET_KEY}}` | Never resolved in display |
|
||||
|
||||
The user must copy and manually substitute secrets.
|
||||
|
||||
---
|
||||
|
||||
## 6. Verification Flow
|
||||
|
||||
### 6.1 Post-Fix Verification
|
||||
|
||||
After the user applies a fix, the wizard:
|
||||
|
||||
1. **Wait** - Pause for user confirmation ("I've run this command")
|
||||
2. **Verify** - Run the verification command
|
||||
3. **Re-check** - Run the original Doctor check
|
||||
4. **Report** - Show success or next steps
|
||||
|
||||
### 6.2 Verification Command Execution
|
||||
|
||||
```csharp
|
||||
public interface IVerificationExecutor
|
||||
{
|
||||
Task<VerificationResult> ExecuteAsync(
|
||||
string command,
|
||||
TimeSpan timeout,
|
||||
CancellationToken ct);
|
||||
}
|
||||
|
||||
public sealed record VerificationResult
|
||||
{
|
||||
public required bool Success { get; init; }
|
||||
public required int ExitCode { get; init; }
|
||||
public required string Output { get; init; }
|
||||
public required TimeSpan Duration { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 Re-Check Behavior
|
||||
|
||||
```
|
||||
[FAIL] check.database.connectivity
|
||||
|
||||
Suggested fix applied. Verifying...
|
||||
|
||||
[RUN] pg_isready -h localhost -p 5432
|
||||
localhost:5432 - accepting connections
|
||||
|
||||
Re-running check...
|
||||
|
||||
[PASS] check.database.connectivity
|
||||
PostgreSQL connection successful
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Check Aggregation
|
||||
|
||||
### 7.1 Step Completion Criteria
|
||||
|
||||
A step is complete when:
|
||||
- All **Critical** checks pass
|
||||
- No **Fail** status on any check
|
||||
- User has acknowledged all **Warning** checks
|
||||
|
||||
### 7.2 Aggregated Status
|
||||
|
||||
```csharp
|
||||
public enum StepValidationStatus
|
||||
{
|
||||
NotStarted, // No checks run
|
||||
InProgress, // Checks running
|
||||
Passed, // All critical pass, no failures
|
||||
PassedWithWarns, // All critical pass, some warnings
|
||||
Failed, // Any critical failure
|
||||
Skipped // User explicitly skipped
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 Status Rollup for Thresholds
|
||||
|
||||
```
|
||||
Operational Threshold:
|
||||
[x] check.database.connectivity PASS
|
||||
[x] check.database.permissions PASS
|
||||
[x] check.database.migrations.applied PASS
|
||||
[x] check.services.valkey.connectivity PASS
|
||||
[x] check.auth.admin.exists PASS
|
||||
[x] check.crypto.profile.valid PASS
|
||||
|
||||
Status: OPERATIONAL (6/6 required checks passed)
|
||||
|
||||
Production-Ready Threshold:
|
||||
[x] check.security.identity.configured PASS
|
||||
[x] check.integration.vault.connected PASS
|
||||
[x] check.integration.scm.connected PASS
|
||||
[x] check.notify.channel.configured PASS
|
||||
[ ] check.orchestrator.agent.healthy SKIP
|
||||
[ ] check.feeds.sync.enabled SKIP
|
||||
|
||||
Status: NOT PRODUCTION-READY (4/6 recommended, 2 skipped)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Doctor Engine Integration
|
||||
|
||||
### 8.1 Wizard-Specific Check Context
|
||||
|
||||
The wizard provides context to Doctor checks:
|
||||
|
||||
```csharp
|
||||
public sealed record WizardCheckContext
|
||||
{
|
||||
public required string StepId { get; init; }
|
||||
public required RuntimeEnvironment DetectedRuntime { get; init; }
|
||||
public required ImmutableDictionary<string, string> UserInputs { get; init; }
|
||||
public bool GenerateRemediations { get; init; } = true;
|
||||
public bool IncludePlaceholders { get; init; } = true;
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 Check Invocation
|
||||
|
||||
```csharp
|
||||
public interface IWizardDoctorClient
|
||||
{
|
||||
Task<ImmutableArray<CheckResult>> RunStepChecksAsync(
|
||||
string stepId,
|
||||
WizardCheckContext context,
|
||||
CancellationToken ct);
|
||||
|
||||
Task<CheckResult> RunSingleCheckAsync(
|
||||
string checkId,
|
||||
WizardCheckContext context,
|
||||
CancellationToken ct);
|
||||
|
||||
Task<VerificationResult> RunVerificationAsync(
|
||||
string command,
|
||||
WizardCheckContext context,
|
||||
CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
### 8.3 Check Timeout
|
||||
|
||||
| Check Category | Default Timeout | Max Timeout |
|
||||
|----------------|-----------------|-------------|
|
||||
| Connectivity | 10 seconds | 30 seconds |
|
||||
| Authentication | 15 seconds | 60 seconds |
|
||||
| Migrations | 60 seconds | 300 seconds |
|
||||
| Full validation | 30 seconds | 120 seconds |
|
||||
|
||||
---
|
||||
|
||||
## 9. Remediation Safety
|
||||
|
||||
### 9.1 Dangerous Commands
|
||||
|
||||
Commands marked `isDangerous: true` require user confirmation:
|
||||
|
||||
```
|
||||
WARNING: This command will modify your database schema.
|
||||
|
||||
Command:
|
||||
stella migrations-run --module all
|
||||
|
||||
This action:
|
||||
- Applies 5 pending migrations
|
||||
- Cannot be automatically rolled back
|
||||
- May take several minutes
|
||||
|
||||
Type 'apply' to confirm: _
|
||||
```
|
||||
|
||||
### 9.2 Sudo Requirements
|
||||
|
||||
Commands requiring `sudo` show a notice:
|
||||
|
||||
```
|
||||
This command requires administrator privileges.
|
||||
|
||||
Command:
|
||||
sudo systemctl start postgresql
|
||||
|
||||
[Copy Command]
|
||||
|
||||
Note: You may be prompted for your password.
|
||||
```
|
||||
|
||||
### 9.3 Secret Substitution Notice
|
||||
|
||||
```
|
||||
This command contains placeholders for sensitive values.
|
||||
|
||||
Command:
|
||||
vault write auth/approle/login role_id={{ROLE_ID}} secret_id={{SECRET_ID}}
|
||||
|
||||
Before running:
|
||||
1. Replace {{ROLE_ID}} with your AppRole Role ID
|
||||
2. Replace {{SECRET_ID}} with your AppRole Secret ID
|
||||
|
||||
[Copy Command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Check Plugin Requirements
|
||||
|
||||
### 10.1 New Checks for Setup Wizard
|
||||
|
||||
The following checks may need to be added to existing plugins:
|
||||
|
||||
| Plugin | New Check ID | Purpose |
|
||||
|--------|--------------|---------|
|
||||
| Core | `check.auth.admin.exists` | Verify admin user exists |
|
||||
| Core | `check.auth.password.policy` | Verify password complexity |
|
||||
| Core | `check.crypto.signing.test` | Test signing operation |
|
||||
| Database | `check.database.migrations.checksums` | Verify migration integrity |
|
||||
| Integration | `check.integration.vault.secrets.access` | Test secret retrieval |
|
||||
| Integration | `check.orchestrator.environment.valid` | Validate environment config |
|
||||
| Notify | `check.notify.delivery.test` | Test notification delivery |
|
||||
|
||||
### 10.2 Check Implementation Contract
|
||||
|
||||
Each check must implement:
|
||||
|
||||
```csharp
|
||||
public interface ISetupWizardAwareCheck : IDoctorCheck
|
||||
{
|
||||
// Standard check execution
|
||||
Task<CheckResult> ExecuteAsync(CheckContext context, CancellationToken ct);
|
||||
|
||||
// Generate runtime-specific remediations
|
||||
ImmutableArray<RemediationCommand> GetRemediations(
|
||||
CheckResult result,
|
||||
RuntimeEnvironment runtime);
|
||||
|
||||
// Verification command for this check
|
||||
string? GetVerificationCommand(RuntimeEnvironment runtime);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Audit Trail
|
||||
|
||||
### 11.1 Setup Event Logging
|
||||
|
||||
All wizard actions are logged to the Timeline service:
|
||||
|
||||
```csharp
|
||||
public sealed record SetupWizardEvent
|
||||
{
|
||||
public required string EventType { get; init; } // step.started, step.completed, check.failed, etc.
|
||||
public required string StepId { get; init; }
|
||||
public required string? CheckId { get; init; }
|
||||
public required CheckStatus? Status { get; init; }
|
||||
public required DateTimeOffset OccurredAt { get; init; }
|
||||
public required string? UserId { get; init; }
|
||||
public ImmutableDictionary<string, string> Metadata { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
### 11.2 Event Types
|
||||
|
||||
| Event Type | Description |
|
||||
|------------|-------------|
|
||||
| `setup.started` | Wizard initiated |
|
||||
| `setup.completed` | Wizard finished successfully |
|
||||
| `setup.aborted` | Wizard cancelled |
|
||||
| `step.started` | Step configuration began |
|
||||
| `step.completed` | Step passed all checks |
|
||||
| `step.failed` | Step failed validation |
|
||||
| `step.skipped` | User skipped optional step |
|
||||
| `check.passed` | Individual check passed |
|
||||
| `check.failed` | Individual check failed |
|
||||
| `check.warned` | Individual check warned |
|
||||
| `remediation.copied` | User copied fix command |
|
||||
| `remediation.verified` | Fix verification succeeded |
|
||||
458
docs/setup/setup-wizard-inventory.md
Normal file
458
docs/setup/setup-wizard-inventory.md
Normal file
@@ -0,0 +1,458 @@
|
||||
# Setup Wizard - Repository Inventory
|
||||
|
||||
This document captures the current state of setup-related components in the Stella Ops codebase, providing evidence for the Setup Wizard design.
|
||||
|
||||
## 1. CLI Architecture
|
||||
|
||||
### 1.1 Framework & Entry Points
|
||||
|
||||
| Component | Path | Description |
|
||||
|-----------|------|-------------|
|
||||
| **CLI Entry** | `src/Cli/StellaOps.Cli/Program.cs` | Main entry point using System.CommandLine |
|
||||
| **Command Factory** | `src/Cli/StellaOps.Cli/Commands/CommandFactory.cs` | Central command registration (53+ command groups) |
|
||||
| **Bootstrapper** | `src/Cli/StellaOps.Cli/Configuration/CliBootstrapper.cs` | Configuration loading and DI setup |
|
||||
| **Options** | `src/Cli/StellaOps.Cli/Configuration/StellaOpsCliOptions.cs` | CLI configuration POCOs |
|
||||
| **Profile Manager** | `src/Cli/StellaOps.Cli/Configuration/CliProfile.cs` | Multi-profile support |
|
||||
|
||||
### 1.2 Existing Admin Commands
|
||||
|
||||
**File:** `src/Cli/StellaOps.Cli/Commands/Admin/AdminCommandGroup.cs`
|
||||
|
||||
Current `stella admin` subcommands:
|
||||
- `admin policy export|import|validate|list` - Policy management
|
||||
- `admin users list|add|revoke|update` - User management
|
||||
- `admin feeds list|status|refresh|history` - Feed management
|
||||
- `admin system status|info` - System health and info
|
||||
|
||||
### 1.3 Doctor Commands
|
||||
|
||||
**File:** `src/Cli/StellaOps.Cli/Commands/DoctorCommandGroup.cs`
|
||||
|
||||
```bash
|
||||
stella doctor run [--mode quick|normal|full] [--category <cat>] [--format text|json|markdown]
|
||||
stella doctor list [--category <cat>] [--verbose]
|
||||
stella doctor export --output <path>.zip [--include-logs]
|
||||
```
|
||||
|
||||
### 1.4 Configuration System
|
||||
|
||||
**Priority Resolution (CliBootstrapper.cs):**
|
||||
1. Command-line arguments (highest)
|
||||
2. Environment variables (`STELLAOPS_*` prefix)
|
||||
3. Configuration files (`appsettings.json`, `appsettings.yaml`)
|
||||
4. Code defaults (lowest)
|
||||
|
||||
**Key Environment Variables:**
|
||||
- `STELLAOPS_BACKEND_URL` - Backend API URL
|
||||
- `STELLAOPS_AUTHORITY_URL` - Authority service URL
|
||||
- `STELLAOPS_POSTGRES_CONNECTION` - Database connection
|
||||
- `STELLAOPS_OFFLINE_KITS_DIRECTORY` - Offline kit path
|
||||
|
||||
---
|
||||
|
||||
## 2. Doctor System (Diagnostic Framework)
|
||||
|
||||
### 2.1 Core Engine
|
||||
|
||||
| Component | Path |
|
||||
|-----------|------|
|
||||
| **Engine** | `src/__Libraries/StellaOps.Doctor/Engine/DoctorEngine.cs` |
|
||||
| **Registry** | `src/__Libraries/StellaOps.Doctor/Engine/CheckRegistry.cs` |
|
||||
| **Executor** | `src/__Libraries/StellaOps.Doctor/Engine/CheckExecutor.cs` |
|
||||
| **Models** | `src/__Libraries/StellaOps.Doctor/Models/` |
|
||||
|
||||
### 2.2 Plugin System (9 Plugins, 48+ Checks)
|
||||
|
||||
| Plugin | Path | Category | Checks |
|
||||
|--------|------|----------|--------|
|
||||
| **Core** | `StellaOps.Doctor.Plugins.Core` | Core | 9 checks (config, disk, memory, crypto) |
|
||||
| **Database** | `StellaOps.Doctor.Plugins.Database` | Database | 8 checks (connectivity, migrations, schema) |
|
||||
| **ServiceGraph** | `StellaOps.Doctor.Plugins.ServiceGraph` | ServiceGraph | 6 checks (gateway, Valkey) |
|
||||
| **Security** | `StellaOps.Doctor.Plugins.Security` | Security | 9 checks (OIDC, TLS, Vault) |
|
||||
| **Integration** | `StellaOps.Doctor.Plugins.Integration` | Integration | 8+ checks (GitHub, GitLab, registries) |
|
||||
| **Observability** | `StellaOps.Doctor.Plugins.Observability` | Observability | 4 checks (OTLP, metrics) |
|
||||
| **Cryptography** | `StellaOps.Doctor.Plugins.Cryptography` | Cryptography | 8+ checks (FIPS, eIDAS, HSM) |
|
||||
| **Docker** | `StellaOps.Doctor.Plugins.Docker` | Docker | 5 checks (daemon, network) |
|
||||
| **AI** | `StellaOps.Doctor.Plugins.AI` | AI | 4+ checks (LLM providers) |
|
||||
| **Notify** | `StellaOps.Doctor.Plugin.Notify` | Notify | 5 checks (email, Slack, webhooks) |
|
||||
|
||||
### 2.3 Doctor Web Service
|
||||
|
||||
| Component | Path |
|
||||
|-----------|------|
|
||||
| **Web Service** | `src/Doctor/StellaOps.Doctor.WebService/` |
|
||||
| **Endpoints** | `src/Doctor/StellaOps.Doctor.WebService/Endpoints/DoctorEndpoints.cs` |
|
||||
| **Angular UI** | `src/Web/StellaOps.Web/src/app/features/doctor/` |
|
||||
|
||||
**REST API:**
|
||||
- `POST /api/v1/doctor/run` - Start diagnostic run
|
||||
- `GET /api/v1/doctor/run/{runId}` - Get run results
|
||||
- `GET /api/v1/doctor/checks` - List available checks
|
||||
- `WebSocket /api/v1/doctor/stream` - Real-time streaming
|
||||
|
||||
### 2.4 Check ID Convention
|
||||
|
||||
```
|
||||
check.{category}.{subcategory}.{specific}
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `check.config.required`
|
||||
- `check.database.migrations.pending`
|
||||
- `check.integration.scm.github.auth`
|
||||
- `check.services.valkey.connectivity`
|
||||
|
||||
---
|
||||
|
||||
## 3. Database & Migrations
|
||||
|
||||
### 3.1 Migration Framework
|
||||
|
||||
| Component | Path |
|
||||
|-----------|------|
|
||||
| **Runner** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationRunner.cs` |
|
||||
| **Startup Host** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/StartupMigrationHost.cs` |
|
||||
| **Categories** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationCategory.cs` |
|
||||
| **CLI Service** | `src/Cli/StellaOps.Cli/Services/MigrationCommandService.cs` |
|
||||
|
||||
### 3.2 Migration Categories
|
||||
|
||||
| Category | Prefix | Execution | Purpose |
|
||||
|----------|--------|-----------|---------|
|
||||
| **Startup** | 001-099 | Automatic at boot | Schema creation (idempotent) |
|
||||
| **Release** | 100-199 | Manual CLI | Breaking changes (blocks boot if pending) |
|
||||
| **Seed** | S001-S999 | Automatic at boot | Initial data (idempotent) |
|
||||
| **Data** | DM001-DM999 | Background jobs | Data migrations |
|
||||
|
||||
### 3.3 Schema Isolation (Per-Module)
|
||||
|
||||
| Module | Schema | Migration Path |
|
||||
|--------|--------|----------------|
|
||||
| Authority | `authority` | `src/Authority/__Libraries/StellaOps.Authority.Persistence/Migrations/` |
|
||||
| Concelier | `vuln` | `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Migrations/` |
|
||||
| Scheduler | `scheduler` | `src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Migrations/` |
|
||||
| Notify | `notify` | `src/Notify/__Libraries/StellaOps.Notify.Persistence/Migrations/` |
|
||||
| Scanner | `scanner` | `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/` |
|
||||
| Attestor | `attestor` | `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/Migrations/` |
|
||||
| Policy | `policy` | `src/Policy/__Libraries/StellaOps.Policy.Persistence/Migrations/` |
|
||||
| ReleaseOrchestrator | `release` | `src/ReleaseOrchestrator/__Libraries/.../Persistence/Migrations/` |
|
||||
|
||||
### 3.4 Existing CLI Commands
|
||||
|
||||
```bash
|
||||
stella migrations-run --module <Module> --category <Category> [--dry-run] [--force]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Redis/Valkey Infrastructure
|
||||
|
||||
### 4.1 Connection Configuration
|
||||
|
||||
| Component | Path |
|
||||
|-----------|------|
|
||||
| **Primary Factory** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyConnectionFactory.cs` |
|
||||
| **Options** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/Options/ValkeyTransportOptions.cs` |
|
||||
| **Transport Plugin** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyTransportPlugin.cs` |
|
||||
|
||||
### 4.2 Usage Patterns
|
||||
|
||||
| Usage | Component | Purpose |
|
||||
|-------|-----------|---------|
|
||||
| **Message Queues** | `ValkeyMessageQueue` | Redis Streams with consumer groups |
|
||||
| **Distributed Cache** | `ValkeyCacheStore` | TTL-based caching |
|
||||
| **Rate Limiting** | `ValkeyRateLimitStore` | Token bucket algorithm |
|
||||
| **Idempotency** | `ValkeyIdempotencyStore` | Duplicate prevention |
|
||||
| **DPoP Nonces** | `RedisDpopNonceStore` | Auth token security |
|
||||
|
||||
### 4.3 Health Checks
|
||||
|
||||
**File:** `src/__Libraries/StellaOps.Doctor.Plugins.ServiceGraph/Checks/ValkeyConnectivityCheck.cs`
|
||||
|
||||
Configuration sources checked:
|
||||
- `Valkey:ConnectionString`
|
||||
- `Redis:ConnectionString`
|
||||
- `ConnectionStrings:Valkey`
|
||||
- `ConnectionStrings:Redis`
|
||||
|
||||
---
|
||||
|
||||
## 5. Integrations System
|
||||
|
||||
### 5.1 Core Architecture
|
||||
|
||||
| Component | Path |
|
||||
|-----------|------|
|
||||
| **Web Service** | `src/Integrations/StellaOps.Integrations.WebService/` |
|
||||
| **Core Models** | `src/Integrations/__Libraries/StellaOps.Integrations.Core/` |
|
||||
| **Contracts** | `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/` |
|
||||
| **Persistence** | `src/Integrations/__Libraries/StellaOps.Integrations.Persistence/` |
|
||||
|
||||
### 5.2 Integration Types
|
||||
|
||||
**File:** `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationEnums.cs`
|
||||
|
||||
| Type | Range | Examples |
|
||||
|------|-------|----------|
|
||||
| **Registry** | 100-109 | Harbor, ECR, GCR, ACR, Docker Hub, Quay |
|
||||
| **SCM** | 200-204 | GitHub App, GitLab Server, Bitbucket, Gitea |
|
||||
| **CI/CD** | 300-306 | GitHub Actions, GitLab CI, Jenkins, Argo |
|
||||
| **RepoSource** | 400-405 | npm, PyPI, Maven, NuGet, Crates.io |
|
||||
| **RuntimeHost** | 500-502 | eBPF Agent, ETW Agent |
|
||||
| **FeedMirror** | 600-602 | StellaOps Mirror, NVD, OSV |
|
||||
|
||||
### 5.3 Plugin Contract
|
||||
|
||||
**File:** `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs`
|
||||
|
||||
```csharp
|
||||
public interface IIntegrationConnectorPlugin : IAvailabilityPlugin
|
||||
{
|
||||
IntegrationType Type { get; }
|
||||
IntegrationProvider Provider { get; }
|
||||
Task<TestConnectionResult> TestConnectionAsync(IntegrationConfig config, CancellationToken ct);
|
||||
Task<HealthCheckResult> CheckHealthAsync(IntegrationConfig config, CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
### 5.4 Existing Plugins
|
||||
|
||||
| Plugin | Path |
|
||||
|--------|------|
|
||||
| **GitHub App** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/` |
|
||||
| **Harbor** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.Harbor/` |
|
||||
| **InMemory** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.InMemory/` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Notification System
|
||||
|
||||
### 6.1 Core Components
|
||||
|
||||
| Component | Path |
|
||||
|-----------|------|
|
||||
| **Web Service** | `src/Notify/StellaOps.Notify.WebService/` |
|
||||
| **Engine** | `src/Notify/__Libraries/StellaOps.Notify.Engine/` |
|
||||
| **Models** | `src/Notify/__Libraries/StellaOps.Notify.Models/` |
|
||||
| **Queue** | `src/Notify/__Libraries/StellaOps.Notify.Queue/` |
|
||||
|
||||
### 6.2 Channel Types
|
||||
|
||||
**File:** `src/Notify/__Libraries/StellaOps.Notify.Models/NotifyChannel.cs`
|
||||
|
||||
- **Slack** - Incoming webhooks
|
||||
- **Teams** - Incoming webhooks
|
||||
- **Email** - SMTP
|
||||
- **Webhook** - Generic HTTP POST
|
||||
- **PagerDuty** / **OpsGenie** - Incident management
|
||||
- **InApp** - In-application inbox
|
||||
|
||||
### 6.3 Channel Configuration
|
||||
|
||||
```csharp
|
||||
public sealed record NotifyChannelConfig
|
||||
{
|
||||
public string SecretRef { get; } // authref:// URI
|
||||
public string? Target { get; } // Channel/email list
|
||||
public string? Endpoint { get; } // Webhook URL
|
||||
public ImmutableDictionary<string, string> Properties { get; }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Vault/Secrets System
|
||||
|
||||
### 7.1 Vault Connectors
|
||||
|
||||
| Connector | Path |
|
||||
|-----------|------|
|
||||
| **HashiCorp Vault** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/HashiCorpVaultConnector.cs` |
|
||||
| **Azure Key Vault** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/AzureKeyVaultConnector.cs` |
|
||||
| **AWS Secrets Manager** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/AwsSecretsManagerConnector.cs` |
|
||||
|
||||
### 7.2 Secret Resolution
|
||||
|
||||
**File:** `src/ReleaseOrchestrator/__Libraries/.../Plugin/Integration/ITenantSecretResolver.cs`
|
||||
|
||||
```csharp
|
||||
public interface ITenantSecretResolver : ISecretResolver
|
||||
{
|
||||
ITenantSecretResolver ForTenant(Guid tenantId);
|
||||
Task<string?> ResolveFromVaultAsync(Guid integrationId, string secretPath, CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 Credential Provider Schemes
|
||||
|
||||
**File:** `src/ReleaseOrchestrator/__Agents/StellaOps.Agent.Core/Credentials/CredentialResolver.cs`
|
||||
|
||||
- `env://VAR_NAME` - Environment variable
|
||||
- `file:///path/to/secret` - File system
|
||||
- `vault://integration-id/path` - Vault lookup
|
||||
|
||||
---
|
||||
|
||||
## 8. Environment & Agent System
|
||||
|
||||
### 8.1 Environment Model
|
||||
|
||||
**File:** `src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Environment/Models/Environment.cs`
|
||||
|
||||
```csharp
|
||||
public sealed record Environment
|
||||
{
|
||||
public Guid Id { get; init; }
|
||||
public Guid TenantId { get; init; }
|
||||
public string Name { get; set; } // "dev", "staging", "prod"
|
||||
public string DisplayName { get; set; }
|
||||
public int OrderIndex { get; init; } // Pipeline order
|
||||
public bool IsProduction { get; init; }
|
||||
public int RequiredApprovals { get; set; }
|
||||
public bool RequireSeparationOfDuties { get; set; }
|
||||
public Guid? AutoPromoteFrom { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 Target Model (Deployment Target)
|
||||
|
||||
**File:** `src/ReleaseOrchestrator/__Libraries/.../Environment/Models/Target.cs`
|
||||
|
||||
| Target Type | Description |
|
||||
|-------------|-------------|
|
||||
| **DockerHost** | Docker Engine |
|
||||
| **ComposeHost** | Docker Compose project |
|
||||
| **EcsService** | AWS ECS service |
|
||||
| **NomadJob** | HashiCorp Nomad job |
|
||||
|
||||
### 8.3 Agent Model
|
||||
|
||||
**File:** `src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Agent/Models/Agent.cs`
|
||||
|
||||
```csharp
|
||||
public sealed record Agent
|
||||
{
|
||||
public Guid Id { get; init; }
|
||||
public string Name { get; init; }
|
||||
public AgentStatus Status { get; set; } // Pending, Active, Inactive, Stale, Revoked
|
||||
public AgentCapability[] Capabilities { get; init; } // Docker, Compose, Ssh, WinRm
|
||||
public string? CertificateThumbprint { get; set; } // mTLS
|
||||
public DateTimeOffset? LastHeartbeatAt { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### 8.4 Agent Registration
|
||||
|
||||
**File:** `src/ReleaseOrchestrator/__Libraries/.../Agent/Registration/RegistrationTokenService.cs`
|
||||
|
||||
- One-time tokens with 24-hour expiry
|
||||
- mTLS certificate issuance on registration
|
||||
- Heartbeat monitoring (30-second intervals, 90-second stale timeout)
|
||||
|
||||
---
|
||||
|
||||
## 9. Existing Onboarding System
|
||||
|
||||
### 9.1 Platform Onboarding Service
|
||||
|
||||
**File:** `src/Platform/StellaOps.Platform.WebService/Services/PlatformOnboardingService.cs`
|
||||
|
||||
**Default Steps:**
|
||||
1. `connect-scanner`
|
||||
2. `configure-policy`
|
||||
3. `first-scan`
|
||||
4. `review-findings`
|
||||
5. `invite-team`
|
||||
|
||||
**Endpoints:**
|
||||
- `GET /api/v1/platform/onboarding/status`
|
||||
- `POST /api/v1/platform/onboarding/complete/{step}`
|
||||
- `POST /api/v1/platform/onboarding/skip`
|
||||
|
||||
### 9.2 Quickstart Documentation
|
||||
|
||||
| Document | Path |
|
||||
|----------|------|
|
||||
| **Quickstart** | `docs/quickstart.md` |
|
||||
| **CLI Quickstart** | `docs/CONCELIER_CLI_QUICKSTART.md` |
|
||||
| **Install Guide** | `docs/INSTALL_GUIDE.md` |
|
||||
| **Developer Onboarding** | `docs/DEVELOPER_ONBOARDING.md` |
|
||||
|
||||
---
|
||||
|
||||
## 10. UI Architecture
|
||||
|
||||
### 10.1 Angular Application
|
||||
|
||||
| Component | Path |
|
||||
|-----------|------|
|
||||
| **Root** | `src/Web/StellaOps.Web/src/app/app.component.ts` |
|
||||
| **Routes** | `src/Web/StellaOps.Web/src/app/app.routes.ts` |
|
||||
| **Config** | `src/Web/StellaOps.Web/src/app/app.config.ts` |
|
||||
|
||||
### 10.2 Existing Settings Pages
|
||||
|
||||
| Page | Path |
|
||||
|------|------|
|
||||
| **AI Preferences** | `src/Web/StellaOps.Web/src/app/features/settings/ai-preferences.component.ts` |
|
||||
| **Environment Settings** | `src/Web/StellaOps.Web/src/app/features/release-orchestrator/environments/components/environment-settings/` |
|
||||
| **Trivy DB Settings** | `src/Web/StellaOps.Web/src/app/features/trivy-db-settings/` |
|
||||
|
||||
### 10.3 Wizard Reference Implementation
|
||||
|
||||
**SBOM Source Wizard** (6-step multi-form wizard):
|
||||
|
||||
**File:** `src/Web/StellaOps.Web/src/app/features/sbom-sources/components/source-wizard/source-wizard.component.ts`
|
||||
|
||||
Features:
|
||||
- Signal-based state management
|
||||
- Step-by-step validation
|
||||
- Connection testing
|
||||
- Multi-form with conditional rendering
|
||||
- TypeScript 1204 lines
|
||||
|
||||
---
|
||||
|
||||
## 11. Configuration Samples
|
||||
|
||||
| Sample | Path |
|
||||
|--------|------|
|
||||
| **Concelier** | `etc/concelier.yaml.sample` |
|
||||
| **Authority** | `etc/authority.yaml.sample` |
|
||||
| **Docker Compose** | `devops/compose/dev.env.example` |
|
||||
| **Air-gap** | `devops/compose/airgap.env.example` |
|
||||
|
||||
---
|
||||
|
||||
## 12. Gaps Identified
|
||||
|
||||
### 12.1 Missing Components
|
||||
|
||||
| Gap | Description |
|
||||
|-----|-------------|
|
||||
| **`stella setup` command** | No dedicated interactive setup command exists |
|
||||
| **First-run detection** | No blocking wizard on first launch |
|
||||
| **Wizard UI entry** | No configuration wizard in Angular UI |
|
||||
| **Admin bootstrap** | Admin creation via env vars only, not interactive |
|
||||
| **Integration wizard** | No guided multi-connector setup |
|
||||
|
||||
### 12.2 Partial Implementations
|
||||
|
||||
| Component | Current State | Gap |
|
||||
|-----------|---------------|-----|
|
||||
| **Onboarding Service** | In-memory, 5-step user flow | No infrastructure setup steps |
|
||||
| **Doctor checks** | 48+ checks exist | No wizard integration for fix commands |
|
||||
| **Migrations** | Automatic at startup | No interactive verification step |
|
||||
| **Integrations** | Plugin architecture exists | No default suggestion logic |
|
||||
|
||||
---
|
||||
|
||||
## 13. Key Architectural Patterns to Follow
|
||||
|
||||
1. **System.CommandLine** for CLI commands
|
||||
2. **Signal-based state** in Angular components
|
||||
3. **IOptions<T> with validation** for configuration
|
||||
4. **Plugin contracts** for extensibility
|
||||
5. **Doctor checks** for health validation
|
||||
6. **ITenantSecretResolver** for secret access
|
||||
7. **HLC timestamps** for audit ordering
|
||||
811
docs/setup/setup-wizard-sprint-plan.md
Normal file
811
docs/setup/setup-wizard-sprint-plan.md
Normal file
@@ -0,0 +1,811 @@
|
||||
# Setup Wizard - Sprint Plan
|
||||
|
||||
This document defines the implementation plan for the Stella Ops Setup Wizard feature.
|
||||
|
||||
## 1. Epic Overview
|
||||
|
||||
| Epic ID | Name | Description | Priority |
|
||||
|---------|------|-------------|----------|
|
||||
| **E1** | Doctor Remediation Engine | Extend Doctor to generate runtime-specific fix commands | P0 |
|
||||
| **E2** | CLI Setup Command | Implement `stella setup` interactive command | P0 |
|
||||
| **E3** | UI Setup Wizard | Angular wizard component with first-run blocking | P1 |
|
||||
| **E4** | Integration Connectors | Multi-connector support with default suggestions | P1 |
|
||||
| **E5** | Configuration Pane | Post-setup reconfiguration UI | P2 |
|
||||
|
||||
---
|
||||
|
||||
## 2. Sprint Sequence
|
||||
|
||||
### Sprint 1: Foundation (E1)
|
||||
**Focus:** Doctor remediation engine and runtime detection
|
||||
|
||||
### Sprint 2: CLI Core (E2)
|
||||
**Focus:** CLI setup command with infrastructure steps
|
||||
|
||||
### Sprint 3: CLI Integrations (E2, E4)
|
||||
**Focus:** CLI integration steps and multi-connector support
|
||||
|
||||
### Sprint 4: UI Wizard (E3)
|
||||
**Focus:** Angular wizard component and first-run blocking
|
||||
|
||||
### Sprint 5: UI Integrations (E3, E4)
|
||||
**Focus:** UI integration steps with connector management
|
||||
|
||||
### Sprint 6: Polish (E5)
|
||||
**Focus:** Configuration pane and documentation
|
||||
|
||||
---
|
||||
|
||||
## 3. Epic 1: Doctor Remediation Engine
|
||||
|
||||
### 3.1 Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| F1.1 | Runtime environment detection |
|
||||
| F1.2 | Remediation command templates |
|
||||
| F1.3 | Placeholder resolution system |
|
||||
| F1.4 | Verification command execution |
|
||||
| F1.5 | Secret redaction |
|
||||
|
||||
### 3.2 User Stories
|
||||
|
||||
#### F1.1 Runtime Detection
|
||||
|
||||
**US-1.1.1: Detect Docker Compose environment**
|
||||
```
|
||||
As a setup wizard
|
||||
I need to detect Docker Compose environments
|
||||
So that I can suggest Docker Compose-specific fix commands
|
||||
|
||||
Acceptance Criteria:
|
||||
- Detect presence of docker compose command
|
||||
- Detect docker-compose.yml in standard locations
|
||||
- Detect COMPOSE_PROJECT_NAME environment variable
|
||||
- Return DockerCompose runtime type
|
||||
|
||||
Files to modify:
|
||||
- src/__Libraries/StellaOps.Doctor/Detection/RuntimeDetector.cs (new)
|
||||
- src/__Libraries/StellaOps.Doctor/Detection/IRuntimeDetector.cs (new)
|
||||
```
|
||||
|
||||
**US-1.1.2: Detect Kubernetes context**
|
||||
```
|
||||
As a setup wizard
|
||||
I need to detect Kubernetes environments
|
||||
So that I can suggest kubectl-based fix commands
|
||||
|
||||
Acceptance Criteria:
|
||||
- Detect KUBERNETES_SERVICE_HOST environment variable
|
||||
- Detect kubeconfig file presence
|
||||
- Extract current namespace from context
|
||||
- Return Kubernetes runtime type
|
||||
```
|
||||
|
||||
**US-1.1.3: Detect systemd-managed services**
|
||||
```
|
||||
As a setup wizard
|
||||
I need to detect systemd-managed PostgreSQL/Valkey
|
||||
So that I can suggest systemctl commands
|
||||
|
||||
Acceptance Criteria:
|
||||
- Detect systemctl command availability
|
||||
- Check if postgresql.service exists
|
||||
- Check if valkey.service or redis.service exists
|
||||
- Return Systemd runtime type
|
||||
```
|
||||
|
||||
#### F1.2 Remediation Templates
|
||||
|
||||
**US-1.2.1: Define remediation command model**
|
||||
```
|
||||
As a setup wizard
|
||||
I need a data model for remediation commands
|
||||
So that checks can return actionable fixes
|
||||
|
||||
Acceptance Criteria:
|
||||
- RemediationCommand record with runtime, command, description
|
||||
- Support for placeholders in commands
|
||||
- Support for sudo flag
|
||||
- Support for dangerous flag
|
||||
|
||||
Files to modify:
|
||||
- src/__Libraries/StellaOps.Doctor/Models/RemediationCommand.cs (new)
|
||||
- src/__Libraries/StellaOps.Doctor/Models/CheckResult.cs (extend)
|
||||
```
|
||||
|
||||
**US-1.2.2: Implement database connectivity remediations**
|
||||
```
|
||||
As a user with database connection failure
|
||||
I need runtime-specific fix commands
|
||||
So that I can quickly resolve the issue
|
||||
|
||||
Acceptance Criteria:
|
||||
- Docker Compose: docker compose up -d postgres
|
||||
- Kubernetes: kubectl get pods -l app=postgres
|
||||
- Systemd: sudo systemctl start postgresql
|
||||
- Bare: pg_isready verification command
|
||||
```
|
||||
|
||||
**US-1.2.3: Implement Valkey connectivity remediations**
|
||||
```
|
||||
As a user with Valkey connection failure
|
||||
I need runtime-specific fix commands
|
||||
So that I can quickly resolve the issue
|
||||
|
||||
Acceptance Criteria:
|
||||
- Docker Compose: docker compose up -d valkey
|
||||
- Kubernetes: kubectl get pods -l app=valkey
|
||||
- Systemd: sudo systemctl start valkey
|
||||
- Bare: redis-cli PING verification
|
||||
```
|
||||
|
||||
#### F1.3 Placeholder Resolution
|
||||
|
||||
**US-1.3.1: Implement placeholder resolver**
|
||||
```
|
||||
As a setup wizard
|
||||
I need to resolve placeholders in commands
|
||||
So that users see contextual values
|
||||
|
||||
Acceptance Criteria:
|
||||
- Resolve {{HOST}}, {{PORT}} from user input
|
||||
- Resolve {{NAMESPACE}} from Kubernetes context
|
||||
- Resolve {{COMPOSE_FILE}} from detection
|
||||
- Support default values with {{VAR:-default}} syntax
|
||||
|
||||
Files to modify:
|
||||
- src/__Libraries/StellaOps.Doctor/Remediation/PlaceholderResolver.cs (new)
|
||||
```
|
||||
|
||||
#### F1.4 Verification Execution
|
||||
|
||||
**US-1.4.1: Execute verification commands**
|
||||
```
|
||||
As a setup wizard
|
||||
I need to run verification commands
|
||||
So that I can confirm fixes were applied
|
||||
|
||||
Acceptance Criteria:
|
||||
- Execute shell command with timeout
|
||||
- Capture exit code and output
|
||||
- Return success/failure result
|
||||
- Handle command not found gracefully
|
||||
```
|
||||
|
||||
#### F1.5 Secret Redaction
|
||||
|
||||
**US-1.5.1: Redact secrets in displayed commands**
|
||||
```
|
||||
As a setup wizard
|
||||
I must never display actual secret values
|
||||
So that secrets are not exposed in logs or UI
|
||||
|
||||
Acceptance Criteria:
|
||||
- PASSWORD, TOKEN, SECRET_KEY placeholders never resolved for display
|
||||
- Display shows placeholder syntax
|
||||
- Copy-to-clipboard preserves placeholders
|
||||
- Log output redacts secrets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Epic 2: CLI Setup Command
|
||||
|
||||
### 4.1 Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| F2.1 | Command registration and structure |
|
||||
| F2.2 | Interactive prompts for each step |
|
||||
| F2.3 | Non-interactive mode with config file |
|
||||
| F2.4 | Resume and reconfigure support |
|
||||
| F2.5 | Step validation with Doctor checks |
|
||||
|
||||
### 4.2 User Stories
|
||||
|
||||
#### F2.1 Command Registration
|
||||
|
||||
**US-2.1.1: Register stella setup command**
|
||||
```
|
||||
As a CLI user
|
||||
I need a stella setup command
|
||||
So that I can configure Stella Ops interactively
|
||||
|
||||
Acceptance Criteria:
|
||||
- Command registered in CommandFactory
|
||||
- Global options: --config, --non-interactive, --resume, --reconfigure
|
||||
- Step selection options: --step, --skip
|
||||
- Help text describes all options
|
||||
|
||||
Files to modify:
|
||||
- src/Cli/StellaOps.Cli/Commands/Setup/SetupCommandGroup.cs (new)
|
||||
- src/Cli/StellaOps.Cli/Commands/CommandFactory.cs
|
||||
```
|
||||
|
||||
**US-2.1.2: Implement setup command handler**
|
||||
```
|
||||
As a CLI user
|
||||
I need the setup command to orchestrate all steps
|
||||
So that I can complete configuration end-to-end
|
||||
|
||||
Acceptance Criteria:
|
||||
- Detect first-run vs reconfigure mode
|
||||
- Load existing configuration if present
|
||||
- Execute steps in sequence
|
||||
- Save progress after each step
|
||||
|
||||
Files to modify:
|
||||
- src/Cli/StellaOps.Cli/Commands/Setup/SetupCommandHandler.cs (new)
|
||||
```
|
||||
|
||||
#### F2.2 Interactive Prompts
|
||||
|
||||
**US-2.2.1: Implement database setup prompts**
|
||||
```
|
||||
As a CLI user
|
||||
I need interactive prompts for database configuration
|
||||
So that I can enter connection details
|
||||
|
||||
Acceptance Criteria:
|
||||
- Prompt for host, port, database, username, password
|
||||
- Password input masked
|
||||
- Default values shown in brackets
|
||||
- Input validation before proceeding
|
||||
```
|
||||
|
||||
**US-2.2.2: Implement Valkey setup prompts**
|
||||
```
|
||||
As a CLI user
|
||||
I need interactive prompts for Valkey configuration
|
||||
So that I can enter connection details
|
||||
|
||||
Acceptance Criteria:
|
||||
- Prompt for host, port, password (optional)
|
||||
- TLS toggle option
|
||||
- Database index selection
|
||||
```
|
||||
|
||||
**US-2.2.3: Implement admin bootstrap prompts**
|
||||
```
|
||||
As a CLI user
|
||||
I need prompts to create admin user
|
||||
So that I can access the system after setup
|
||||
|
||||
Acceptance Criteria:
|
||||
- Prompt for username, email, password
|
||||
- Password confirmation
|
||||
- Password complexity validation
|
||||
- Display created user info
|
||||
```
|
||||
|
||||
**US-2.2.4: Implement vault integration prompts**
|
||||
```
|
||||
As a CLI user
|
||||
I need prompts to configure vault integration
|
||||
So that I can set up secrets management
|
||||
|
||||
Acceptance Criteria:
|
||||
- Show detected vault (if any)
|
||||
- Prompt for vault type selection
|
||||
- Type-specific prompts (token, AppRole, etc.)
|
||||
- Test connection before saving
|
||||
```
|
||||
|
||||
**US-2.2.5: Implement SCM integration prompts**
|
||||
```
|
||||
As a CLI user
|
||||
I need prompts to configure SCM integration
|
||||
So that I can connect source control
|
||||
|
||||
Acceptance Criteria:
|
||||
- Provider selection (GitHub, GitLab, etc.)
|
||||
- Provider-specific prompts
|
||||
- Support for adding multiple providers
|
||||
- Test connection before saving
|
||||
```
|
||||
|
||||
#### F2.3 Non-Interactive Mode
|
||||
|
||||
**US-2.3.1: Parse YAML configuration file**
|
||||
```
|
||||
As a DevOps engineer
|
||||
I need to provide configuration via YAML file
|
||||
So that I can automate setup in CI/CD
|
||||
|
||||
Acceptance Criteria:
|
||||
- Parse setup.yaml with all step configurations
|
||||
- Support environment variable substitution
|
||||
- Validate required fields present
|
||||
- Fail on missing required values
|
||||
|
||||
Files to modify:
|
||||
- src/Cli/StellaOps.Cli/Commands/Setup/SetupConfigParser.cs (new)
|
||||
```
|
||||
|
||||
**US-2.3.2: Execute non-interactive setup**
|
||||
```
|
||||
As a DevOps engineer
|
||||
I need non-interactive mode to fail on missing input
|
||||
So that automated setups don't hang
|
||||
|
||||
Acceptance Criteria:
|
||||
- --non-interactive flag enables mode
|
||||
- Exit with error if required input missing
|
||||
- Progress output shows step completion
|
||||
- Final status summary
|
||||
```
|
||||
|
||||
#### F2.4 Resume Support
|
||||
|
||||
**US-2.4.1: Save setup progress**
|
||||
```
|
||||
As a CLI user
|
||||
I need my progress saved automatically
|
||||
So that I can resume if interrupted
|
||||
|
||||
Acceptance Criteria:
|
||||
- Save completed steps to ~/.stellaops/setup-state.json
|
||||
- Save step-specific configuration
|
||||
- Track skipped steps with reasons
|
||||
- Save timestamp of last update
|
||||
|
||||
Files to modify:
|
||||
- src/Cli/StellaOps.Cli/Commands/Setup/SetupStateStore.cs (new)
|
||||
```
|
||||
|
||||
**US-2.4.2: Resume interrupted setup**
|
||||
```
|
||||
As a CLI user
|
||||
I need to resume from where I left off
|
||||
So that I don't repeat completed steps
|
||||
|
||||
Acceptance Criteria:
|
||||
- --resume flag loads previous state
|
||||
- Show completed steps as already done
|
||||
- Start from first incomplete step
|
||||
- Allow going back to previous steps
|
||||
```
|
||||
|
||||
#### F2.5 Step Validation
|
||||
|
||||
**US-2.5.1: Run Doctor checks after each step**
|
||||
```
|
||||
As a CLI user
|
||||
I need validation after configuration
|
||||
So that I know if setup succeeded
|
||||
|
||||
Acceptance Criteria:
|
||||
- Run step-specific Doctor checks
|
||||
- Display pass/warn/fail for each check
|
||||
- On failure, show remediations
|
||||
- Block progression on critical failures
|
||||
```
|
||||
|
||||
**US-2.5.2: Display remediation commands**
|
||||
```
|
||||
As a CLI user
|
||||
I need to see fix commands when checks fail
|
||||
So that I can resolve issues
|
||||
|
||||
Acceptance Criteria:
|
||||
- Display likely causes numbered by priority
|
||||
- Show runtime-specific commands
|
||||
- Include copy-pasteable command text
|
||||
- Prompt for retry after fix
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Epic 3: UI Setup Wizard
|
||||
|
||||
### 5.1 Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| F3.1 | First-run detection and blocking |
|
||||
| F3.2 | Wizard component with stepper |
|
||||
| F3.3 | Step form components |
|
||||
| F3.4 | Connection testing UI |
|
||||
| F3.5 | Doctor check results panel |
|
||||
| F3.6 | Remediation display with copy |
|
||||
|
||||
### 5.2 User Stories
|
||||
|
||||
#### F3.1 First-Run Blocking
|
||||
|
||||
**US-3.1.1: Detect first-run state**
|
||||
```
|
||||
As the UI application
|
||||
I need to detect if setup is incomplete
|
||||
So that I can redirect to the wizard
|
||||
|
||||
Acceptance Criteria:
|
||||
- Call backend setup status endpoint
|
||||
- Check for Operational threshold met
|
||||
- Store state in session
|
||||
|
||||
Files to modify:
|
||||
- src/Web/StellaOps.Web/src/app/core/services/setup-status.service.ts (new)
|
||||
```
|
||||
|
||||
**US-3.1.2: Implement first-run route guard**
|
||||
```
|
||||
As the UI application
|
||||
I need to block access to main app until setup complete
|
||||
So that users configure before using
|
||||
|
||||
Acceptance Criteria:
|
||||
- CanActivate guard on main routes
|
||||
- Redirect to /setup if not Operational
|
||||
- Allow /setup route always
|
||||
- Clear guard after setup complete
|
||||
```
|
||||
|
||||
#### F3.2 Wizard Component
|
||||
|
||||
**US-3.2.1: Create wizard container component**
|
||||
```
|
||||
As a UI user
|
||||
I need a wizard interface
|
||||
So that I can complete setup step by step
|
||||
|
||||
Acceptance Criteria:
|
||||
- Stepper showing all steps
|
||||
- Current step highlighted
|
||||
- Completed steps show checkmark
|
||||
- Skipped steps show dash
|
||||
- Click to navigate (completed steps only)
|
||||
|
||||
Files to modify:
|
||||
- src/Web/StellaOps.Web/src/app/features/setup-wizard/setup-wizard.component.ts (new)
|
||||
- src/Web/StellaOps.Web/src/app/features/setup-wizard/setup-wizard.routes.ts (new)
|
||||
```
|
||||
|
||||
**US-3.2.2: Implement step navigation**
|
||||
```
|
||||
As a UI user
|
||||
I need navigation controls
|
||||
So that I can move between steps
|
||||
|
||||
Acceptance Criteria:
|
||||
- Continue button proceeds to next step
|
||||
- Skip button (optional steps) moves forward
|
||||
- Back button returns to previous step
|
||||
- Keyboard navigation support
|
||||
```
|
||||
|
||||
#### F3.3 Step Forms
|
||||
|
||||
**US-3.3.1: Database setup form component**
|
||||
```
|
||||
As a UI user
|
||||
I need a form to configure database connection
|
||||
So that I can set up PostgreSQL
|
||||
|
||||
Acceptance Criteria:
|
||||
- Form fields for host, port, database, username, password
|
||||
- SSL mode dropdown
|
||||
- Password field with show/hide toggle
|
||||
- Field validation
|
||||
- Test Connection button
|
||||
|
||||
Files to modify:
|
||||
- src/Web/StellaOps.Web/src/app/features/setup-wizard/steps/database-step.component.ts (new)
|
||||
```
|
||||
|
||||
**US-3.3.2: Valkey setup form component**
|
||||
```
|
||||
As a UI user
|
||||
I need a form to configure Valkey connection
|
||||
So that I can set up caching and queues
|
||||
|
||||
Acceptance Criteria:
|
||||
- Form fields for host, port, password
|
||||
- TLS toggle
|
||||
- Database index selector
|
||||
- Test Connection button
|
||||
```
|
||||
|
||||
**US-3.3.3: Admin bootstrap form component**
|
||||
```
|
||||
As a UI user
|
||||
I need a form to create admin account
|
||||
So that I can access the system
|
||||
|
||||
Acceptance Criteria:
|
||||
- Form fields for username, email, password, confirm password
|
||||
- Password strength indicator
|
||||
- Validation messages
|
||||
```
|
||||
|
||||
**US-3.3.4: Vault integration form component**
|
||||
```
|
||||
As a UI user
|
||||
I need a form to configure vault
|
||||
So that I can set up secrets management
|
||||
|
||||
Acceptance Criteria:
|
||||
- Provider type selector (cards)
|
||||
- Dynamic form based on provider
|
||||
- Add another provider button
|
||||
- List of configured providers
|
||||
```
|
||||
|
||||
**US-3.3.5: SCM integration form component**
|
||||
```
|
||||
As a UI user
|
||||
I need a form to configure SCM
|
||||
So that I can connect source control
|
||||
|
||||
Acceptance Criteria:
|
||||
- Provider type selector
|
||||
- Dynamic form based on provider
|
||||
- Multiple providers support
|
||||
- Test connection for each
|
||||
```
|
||||
|
||||
#### F3.4 Connection Testing
|
||||
|
||||
**US-3.4.1: Connection test component**
|
||||
```
|
||||
As a UI user
|
||||
I need visual feedback during connection tests
|
||||
So that I know the status
|
||||
|
||||
Acceptance Criteria:
|
||||
- Loading spinner during test
|
||||
- Progress steps shown
|
||||
- Success state with details
|
||||
- Failure state with error message
|
||||
```
|
||||
|
||||
#### F3.5 Doctor Results Panel
|
||||
|
||||
**US-3.5.1: Check results display**
|
||||
```
|
||||
As a UI user
|
||||
I need to see validation results
|
||||
So that I know if configuration is correct
|
||||
|
||||
Acceptance Criteria:
|
||||
- List of checks with pass/warn/fail icons
|
||||
- Expandable details per check
|
||||
- Evidence data shown
|
||||
- Filter by status
|
||||
```
|
||||
|
||||
#### F3.6 Remediation Display
|
||||
|
||||
**US-3.6.1: Remediation command display**
|
||||
```
|
||||
As a UI user
|
||||
I need to see fix commands when checks fail
|
||||
So that I can resolve issues
|
||||
|
||||
Acceptance Criteria:
|
||||
- Likely causes listed
|
||||
- Commands in code blocks
|
||||
- Copy button per command
|
||||
- Runtime-specific tabs
|
||||
- Retry button after applying fix
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Epic 4: Integration Connectors
|
||||
|
||||
### 6.1 Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| F4.1 | Default connector detection |
|
||||
| F4.2 | Multi-connector management |
|
||||
| F4.3 | Connector preference persistence |
|
||||
|
||||
### 6.2 User Stories
|
||||
|
||||
**US-4.1.1: Detect default vault provider**
|
||||
```
|
||||
As a setup wizard
|
||||
I need to detect the most likely vault provider
|
||||
So that I can suggest it to the user
|
||||
|
||||
Acceptance Criteria:
|
||||
- Check VAULT_ADDR environment variable
|
||||
- Check Azure IMDS endpoint
|
||||
- Check AWS metadata endpoint
|
||||
- Return detected provider or null
|
||||
```
|
||||
|
||||
**US-4.2.1: Support multiple vault integrations**
|
||||
```
|
||||
As a user
|
||||
I need to configure multiple vault providers
|
||||
So that I can use different vaults for different purposes
|
||||
|
||||
Acceptance Criteria:
|
||||
- Add up to 5 vault integrations
|
||||
- Each has unique name
|
||||
- List shows all configured
|
||||
- Edit/remove individual integrations
|
||||
```
|
||||
|
||||
**US-4.3.1: Persist connector preferences**
|
||||
```
|
||||
As a user
|
||||
I need my last selected connector saved
|
||||
So that reconfiguration shows my preferences
|
||||
|
||||
Acceptance Criteria:
|
||||
- Save last used connector per category
|
||||
- Load preferences on reconfigure
|
||||
- Pre-select last used connector
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Epic 5: Configuration Pane
|
||||
|
||||
### 7.1 Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| F5.1 | Configuration pane route and component |
|
||||
| F5.2 | Health status display |
|
||||
| F5.3 | Reconfigure individual steps |
|
||||
|
||||
### 7.2 User Stories
|
||||
|
||||
**US-5.1.1: Configuration pane component**
|
||||
```
|
||||
As a user
|
||||
I need a configuration pane in settings
|
||||
So that I can reconfigure after initial setup
|
||||
|
||||
Acceptance Criteria:
|
||||
- Route: /settings/configuration
|
||||
- Menu entry in Settings
|
||||
- Show all configuration categories
|
||||
- Last configured timestamp
|
||||
```
|
||||
|
||||
**US-5.2.1: Display current health status**
|
||||
```
|
||||
As a user
|
||||
I need to see health status per configuration
|
||||
So that I know if anything needs attention
|
||||
|
||||
Acceptance Criteria:
|
||||
- Health badge per category (Healthy, Degraded, Unhealthy)
|
||||
- Click to see Doctor check details
|
||||
- Refresh button to re-run checks
|
||||
```
|
||||
|
||||
**US-5.3.1: Reconfigure individual step**
|
||||
```
|
||||
As a user
|
||||
I need to reconfigure a specific step
|
||||
So that I can update settings without full wizard
|
||||
|
||||
Acceptance Criteria:
|
||||
- Manage button per category
|
||||
- Opens step form pre-populated
|
||||
- Test and save functionality
|
||||
- Run Doctor checks after save
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Technical Spikes
|
||||
|
||||
| Spike | Question | Output |
|
||||
|-------|----------|--------|
|
||||
| **TS-1** | How should setup state be persisted across CLI sessions? | Design doc for state storage |
|
||||
| **TS-2** | How to share validation logic between CLI and UI? | Shared library design |
|
||||
| **TS-3** | How to handle long-running migrations in wizard? | Progress reporting design |
|
||||
| **TS-4** | How to test runtime detection across platforms? | Test strategy doc |
|
||||
|
||||
---
|
||||
|
||||
## 9. Definition of Done
|
||||
|
||||
### 9.1 Code Quality
|
||||
|
||||
- [ ] All new code has unit tests (>80% coverage)
|
||||
- [ ] Integration tests for Doctor check integration
|
||||
- [ ] E2E tests for CLI interactive flow (Playwright)
|
||||
- [ ] E2E tests for UI wizard (Playwright)
|
||||
- [ ] No new compiler warnings
|
||||
- [ ] Code reviewed and approved
|
||||
|
||||
### 9.2 Documentation
|
||||
|
||||
- [ ] CLI help text complete and accurate
|
||||
- [ ] Quickstart guide updated with wizard
|
||||
- [ ] API documentation for new endpoints
|
||||
- [ ] Architecture doc updated
|
||||
|
||||
### 9.3 Accessibility
|
||||
|
||||
- [ ] UI meets WCAG 2.1 AA
|
||||
- [ ] Keyboard navigation works
|
||||
- [ ] Screen reader tested
|
||||
|
||||
### 9.4 Feature Flags
|
||||
|
||||
- [ ] Wizard behind feature flag initially
|
||||
- [ ] Flag documented in operations guide
|
||||
- [ ] Rollout plan defined
|
||||
|
||||
---
|
||||
|
||||
## 10. Test Strategy
|
||||
|
||||
### 10.1 Unit Tests
|
||||
|
||||
| Component | Test Focus |
|
||||
|-----------|------------|
|
||||
| RuntimeDetector | Mock file system and environment |
|
||||
| PlaceholderResolver | Various placeholder patterns |
|
||||
| SetupStateStore | State persistence and loading |
|
||||
| SetupConfigParser | YAML parsing and validation |
|
||||
|
||||
### 10.2 Integration Tests
|
||||
|
||||
| Scenario | Setup |
|
||||
|----------|-------|
|
||||
| Database check flow | Testcontainers PostgreSQL |
|
||||
| Valkey check flow | Testcontainers Valkey |
|
||||
| Migration execution | In-memory database |
|
||||
| Vault integration | Mock vault server |
|
||||
|
||||
### 10.3 E2E Tests
|
||||
|
||||
| Flow | Tool |
|
||||
|------|------|
|
||||
| CLI interactive setup | Bash script with expect |
|
||||
| CLI non-interactive | YAML config files |
|
||||
| UI wizard complete | Playwright |
|
||||
| UI first-run blocking | Playwright |
|
||||
|
||||
---
|
||||
|
||||
## 11. Rollout Strategy
|
||||
|
||||
### Phase 1: Internal Testing
|
||||
- Feature flag enabled for dev team
|
||||
- Dogfooding in internal environments
|
||||
- Bug fixes and polish
|
||||
|
||||
### Phase 2: Beta
|
||||
- Feature flag enabled for opt-in users
|
||||
- Documentation available
|
||||
- Feedback collection
|
||||
|
||||
### Phase 3: General Availability
|
||||
- Feature flag removed
|
||||
- Default wizard enabled
|
||||
- Migration guide for existing installations
|
||||
|
||||
---
|
||||
|
||||
## 12. Dependencies
|
||||
|
||||
| Dependency | Status | Owner |
|
||||
|------------|--------|-------|
|
||||
| Doctor Plugin API stable | Done | Platform team |
|
||||
| Authority admin bootstrap API | In progress | Auth team |
|
||||
| Integration connectors API | Done | Integration team |
|
||||
| Notify channel test endpoint | Needed | Notify team |
|
||||
|
||||
---
|
||||
|
||||
## 13. Risks and Mitigations
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
| Runtime detection unreliable | Medium | High | Fallback to "Bare" with manual commands |
|
||||
| Long migration blocking UI | Medium | Medium | Background job with progress |
|
||||
| Secret handling complexity | Low | High | Strict redaction policy, security review |
|
||||
| Cross-platform CLI issues | Medium | Medium | CI matrix testing on all platforms |
|
||||
693
docs/setup/setup-wizard-ux.md
Normal file
693
docs/setup/setup-wizard-ux.md
Normal file
@@ -0,0 +1,693 @@
|
||||
# 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
|
||||
|
||||
1. **Self-serve clarity** - Users should complete setup without reading external documentation
|
||||
2. **Progressive disclosure** - Show only relevant options at each step
|
||||
3. **Fail-forward** - Guide users through errors with actionable fixes
|
||||
4. **Parity** - CLI and UI offer identical capabilities
|
||||
5. **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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
# 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
|
||||
```
|
||||
|
||||
```bash
|
||||
$ 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):
|
||||
|
||||
1. **Intercept all routes** - Redirect to `/setup`
|
||||
2. **Show blocking modal** - Cannot dismiss without completing required steps
|
||||
3. **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
|
||||
|
||||
1. **Screen reader support** - All form fields have labels
|
||||
2. **Focus indicators** - Visible focus rings on all interactive elements
|
||||
3. **Color contrast** - WCAG 2.1 AA compliance
|
||||
4. **Keyboard navigation** - Full functionality without mouse
|
||||
5. **Error announcements** - Errors announced to screen readers
|
||||
Reference in New Issue
Block a user