# UI Setup Wizard Guide

This guide covers the web-based Setup Wizard for initial configuration of Stella Ops.

## Overview

The Setup Wizard guides you through configuring all required and optional components. Both CLI and UI setup wizards follow the same **Infrastructure-First** order and provide identical capabilities.

## Accessing the Setup Wizard

Navigate to `/setup` in your browser to access the Setup Wizard. The wizard is available when:
- First-time installation (no configuration exists)
- Explicitly navigating to `/setup` as an administrator
- Using reconfiguration mode to modify existing settings

## Setup Steps

Steps are organized in phases. Required steps must be completed; optional steps can be skipped.

### Phase 1: Core Infrastructure (Required)

| Step | Description |
|------|-------------|
| **Database** | PostgreSQL connection for persistent storage |
| **Cache** | Valkey/Redis connection for caching and distributed locks |
| **Migrations** | Apply database schema migrations |

### Phase 2: Security Foundation (Required)

| Step | Description |
|------|-------------|
| **Authority** | Authentication provider (Standard or LDAP) |
| **Users** | Initial super user account (skipped if LDAP selected) |
| **Crypto** | Cryptographic provider for signing/encryption |

### Phase 3: Secrets Management (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Vault** | External secrets vault (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager, GCP Secret Manager) | Settings > Trust & Signing |

### Phase 4: Integrations (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Registry** | Container registries for image scanning (supports multiple) | Settings > Integrations |
| **SCM** | Source control connections (supports multiple) | Settings > Integrations |
| **Sources** | Advisory data sources (NVD, GHSA, OSV, VEX feeds, custom mirrors) | Settings > Security Data |

### Phase 5: Observability (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Telemetry** | OpenTelemetry configuration | Settings > System > Telemetry |
| **Notify** | Notification channels (supports multiple) | Settings > Notifications |

### Phase 6: AI Features (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **LLM** | AI/LLM provider for AdvisoryAI (OpenAI, Claude, Gemini, Ollama) | Settings > Integrations > AdvisoryAI |

### Phase 7: Configuration Store (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Settings Store** | External configuration store (Consul, etcd, Azure App Config, AWS) | Settings > System |

### Phase 8: Release Orchestration (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **Environments** | Define deployment environments (dev, staging, production) | Settings > Environments |
| **Agents** | Register deployment agents | Settings > Agents |

## Multiple Integrations

The **Registry**, **SCM**, and **Notify** steps support configuring multiple instances:

### Container Registries
Add multiple registries for different purposes:
- Production registry (e.g., ECR, GCR)
- Development registry (e.g., Harbor)
- Third-party images (e.g., Docker Hub)

One registry can be marked as **Primary** for default operations.

### Source Control Connections
Add connections to multiple SCM providers:
- Main organization GitHub
- Internal GitLab instance
- Partner organization Bitbucket

One connection can be marked as **Primary** for default operations.

### Notification Channels
Add multiple notification destinations:
- Operations team Slack channel
- Security team email distribution
- Custom webhook for SIEM integration

All channels can receive notifications based on event rules.

## Wizard Navigation

### Progress Indicator
The left sidebar shows:
- Completed steps (green checkmark)
- Current step (highlighted)
- Pending steps (gray)
- Skipped steps (dash)

### Step Actions
Each step provides:
- **Test Connection**: Validate configuration without applying
- **Apply Configuration**: Save and validate the step
- **Skip this step**: Available for optional steps

### Skip Warnings
When skipping optional steps, warnings explain the implications:

| Skipped Step | Warning |
|--------------|---------|
| Vault | Secrets stored in configuration files (less secure) |
| Registry | Container scanning capabilities limited |
| SCM | Pipeline integration unavailable |
| Sources | Advisory feeds require manual updates |
| Telemetry | System observability limited |
| LLM | AdvisoryAI features unavailable |
| Environments | Manual deployment tracking only |
| Agents | Release orchestration unavailable |

## Cryptographic Provider Selection

The **Crypto** step allows selecting regional cryptographic standards:

| Provider | Standards | Use Case |
|----------|-----------|----------|
| **Default** | AES-256-GCM, SHA-256/512, Ed25519, ECDSA P-256 | General use |
| **FIPS 140-2** | FIPS-compliant algorithms with optional HSM | US government compliance |
| **GOST R 34.10-2012** | Kuznechik/Magma, Streebog, GOST signatures | Russian compliance |
| **SM2/SM3** | SM4, SM3, SM2 | Chinese national standards |

## Advisory Data Sources

The **Sources** step supports multiple feed types:

### CVE/Vulnerability Feeds
- NVD (NIST National Vulnerability Database)
- GHSA (GitHub Security Advisories)
- OSV (Open Source Vulnerabilities)
- Distribution feeds (Red Hat, Ubuntu, Debian, Alpine, Wolfi)

### VEX Sources
- CSAF VEX feeds from vendors
- OpenVEX format feeds
- CycloneDX BOM with embedded VEX

### Custom Mirrors
- Self-hosted advisory mirrors for air-gapped environments
- Supports Basic Auth, Bearer Token, or mTLS authentication
- Configurable sync intervals

## Environment Patterns

The **Environments** step provides quick-start patterns:

| Pattern | Environments | Description |
|---------|--------------|-------------|
| **Standard** | Dev > Staging > Production | Common three-tier pipeline |
| **Simple** | Staging > Production | Minimal two-tier setup |
| **Extended** | Dev > QA > Staging > Pre-Prod > Production | Enterprise pipeline |
| **Custom** | User-defined | Flexible custom configuration |

## Resuming Setup

If setup is interrupted:
1. Return to `/setup` to resume where you left off
2. Session state is preserved automatically
3. Completed steps remain configured

## Reconfiguration Mode

To modify existing configuration:
1. Navigate to `/setup?mode=reconfigure`
2. Previously configured steps show current values
3. Modify and re-apply any step as needed

## Keyboard Navigation

| Key | Action |
|-----|--------|
| Tab | Move between form fields |
| Enter | Submit current form / Activate button |
| Escape | Cancel current operation |

## Accessibility

The Setup Wizard follows WCAG 2.1 AA guidelines:
- All form fields have associated labels
- Error messages are announced to screen readers
- Focus is managed through step transitions
- Color is not the only indicator of status

## Related Documentation

- [CLI Setup Guide](../../cli/guides/setup-guide.md) - Command-line setup
- [Settings Architecture](../architecture.md) - Settings page structure
- [API Strategy](../api-strategy.md) - Backend API contracts