git.stella-ops.org/docs/modules/ui/guides/setup-guide.md

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 - Command-line setup
• Settings Architecture - Settings page structure
• API Strategy - Backend API contracts