# Setup Wizard Guide

This guide covers the `stella setup` command 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.

## Quick Start

```bash
# Interactive setup
stella setup run

# Non-interactive with config file
stella setup run --config setup.yaml --non-interactive

# Dry-run mode (validate without applying)
stella setup run --dry-run

# Resume interrupted setup
stella setup resume

# Reconfigure a specific step
stella setup --step vault
```

## 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 (Default, FIPS, GOST, SM2/SM3) |

### 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, or `stella config set vault.*` |

### Phase 4: Integrations (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **registry** | Container registry for image scanning | Settings > Integrations, or `stella config set registry.*` |
| **scm** | Source control integration (GitHub, GitLab, Gitea, Bitbucket, Azure DevOps) | Settings > Integrations, or `stella config set scm.*` |
| **sources** | Advisory data sources (NVD, GHSA, OSV, distribution feeds) | Settings > Security Data, or `stella config set sources.*` |

### Phase 5: Observability (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **telemetry** | OpenTelemetry configuration for tracing, metrics, and logging | Settings > System > Telemetry, or `stella config set telemetry.*` |
| **notify** | Notification channels (Email, Slack, Teams, Webhook) | Settings > Notifications, or `stella config set notify.*` |

### Phase 6: AI Features (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **llm** | AI/LLM provider for AdvisoryAI (OpenAI, Claude, Gemini, Ollama) | Settings > Integrations > AdvisoryAI, or `stella config set llm.*` |

### Phase 7: Configuration Store (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **settingsStore** | External configuration store (Consul, etcd, Azure App Config, AWS Parameter Store) | Settings > System, or `stella config set settingsStore.*` |

### Phase 8: Release Orchestration (Optional)

| Step | Description | Configure Later |
|------|-------------|-----------------|
| **environments** | Define deployment environments (dev, staging, production) | Settings > Environments, or `stella env create` |
| **agents** | Register deployment agents for release execution | Settings > Agents, or `stella agent register` |

## Multiple Integrations

The **registry**, **scm**, and **notify** steps support configuring multiple instances. For example:

```bash
# Add multiple container registries
stella config set registry.instances.0.name "Production ECR"
stella config set registry.instances.0.provider "ecr"
stella config set registry.instances.0.isPrimary "true"

stella config set registry.instances.1.name "Docker Hub"
stella config set registry.instances.1.provider "docker"

# Add multiple SCM connections
stella config set scm.instances.0.name "GitHub Main"
stella config set scm.instances.0.provider "github"

# Add multiple notification channels
stella config set notify.instances.0.name "Ops Slack"
stella config set notify.instances.0.provider "slack"

stella config set notify.instances.1.name "Security Email"
stella config set notify.instances.1.provider "email"
```

## Skip Warnings

When skipping optional steps, the wizard displays warnings about implications:

| Skipped Step | Warning |
|--------------|---------|
| vault | Secrets stored in configuration files (less secure for production) |
| registry | Container scanning capabilities limited |
| scm | Pipeline integration and automated workflows unavailable |
| sources | CVE/VEX advisory feeds require manual updates |
| telemetry | System observability limited; tracing and metrics unavailable |
| llm | AdvisoryAI features unavailable |
| environments | Manual deployment tracking only |
| agents | Release orchestration unavailable without registered agents |

## 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** | AES-256-GCM (FIPS 197), SHA-256/384/512 (FIPS 180-4), ECDSA P-256/P-384 (FIPS 186-4) | US government compliance |
| **GOST R 34.10-2012** | Kuznechik/Magma, Streebog, GOST R 34.10-2012 | Russian compliance |
| **SM2/SM3** | SM4, SM3, SM2 | Chinese national standards |

FIPS mode supports HSM integration via PKCS#11, AWS CloudHSM, Azure Key Vault HSM, or GCP Cloud HSM.

## SCM Integration

The **scm** step connects Stella Ops to your source control system:

| Provider | Authentication |
|----------|----------------|
| GitHub | Personal Access Token (ghp_...) |
| GitLab | Personal Access Token (glpat-...) |
| Gitea | Access Token |
| Bitbucket | Username + App Password |
| Azure DevOps | Personal Access Token |

## Configuration File Format

For non-interactive setup, provide a YAML configuration file:

```yaml
# setup.yaml
database:
  host: localhost
  port: 5432
  database: stellaops
  user: postgres
  password: ${DB_PASSWORD}  # Environment variable substitution
  ssl: true

cache:
  host: localhost
  port: 6379
  password: ${CACHE_PASSWORD}
  ssl: true

authority:
  provider: standard  # or 'ldap'

users:
  superuser:
    username: admin
    email: admin@example.com
    password: ${ADMIN_PASSWORD}

crypto:
  provider: default  # or 'fips', 'gost', 'sm'

vault:
  provider: hashicorp
  address: https://vault.example.com:8200
  token: ${VAULT_TOKEN}

scm:
  provider: github
  url: https://github.com
  token: ${GITHUB_TOKEN}
  organization: my-org

sources:
  enabled: nvd,ghsa,osv
  nvd:
    apiKey: ${NVD_API_KEY}

telemetry:
  otlpEndpoint: http://localhost:4317
  enableTracing: true
  enableMetrics: true

notify:
  provider: slack
  slack:
    webhookUrl: ${SLACK_WEBHOOK_URL}

llm:
  provider: openai
  openai:
    apiKey: ${OPENAI_API_KEY}
    model: gpt-4o
```

## Validation Commands

```bash
# Validate current configuration
stella setup validate

# Validate specific step
stella setup validate --step database

# Show current setup status
stella setup status
```

## Troubleshooting

### Database Connection Failed

```bash
# Test PostgreSQL connectivity
stella setup validate --step database --verbose
```

Verify:
- PostgreSQL is running and accessible
- Credentials are correct
- SSL settings match server configuration

### Cache Connection Failed

```bash
# Test Valkey/Redis connectivity
stella setup validate --step cache --verbose
```

### SCM Authentication Failed

```bash
# Test SCM connectivity
stella setup validate --step scm --verbose
```

Ensure your token has the required scopes:
- GitHub: `repo`, `workflow`
- GitLab: `api`, `read_repository`
- Azure DevOps: `Code (Read)`, `Build (Read & Execute)`

## Related Commands

- `stella config get` - View current configuration
- `stella config set` - Modify individual settings
- `stella doctor run` - Run diagnostic checks
- `stella admin db migrate` - Run database migrations