git.stella-ops.org/docs/setup/setup-wizard-capabilities.md

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
• Bootstraps the initial admin and crypto profile
• Exposes a truthful required-readiness summary for setup completion
• Hands tenant onboarding to authenticated /setup/* and integration command surfaces instead of pretending they are bootstrap steps

---

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: Setup status and finalize gate only on this operational threshold. Optional post-boot services may still be degraded and are surfaced through health diagnostics instead of blocking bootstrap completion.

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

Only these five core steps are current runtime setup step IDs. The integration and orchestration catalogs below are historical handoff targets and are no longer accepted by the current setup APIs or stella setup command group.

3.2 Integration Handoffs (Not current setup 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 Handoffs (Not current setup 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

Sections 4.1-4.5 describe the current installation-scoped setup steps. Sections 4.6 and later remain useful as onboarding capability notes, but those inputs now belong to authenticated post-bootstrap surfaces rather than the setup wizard step catalog.

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:

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:

{
  "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)