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

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

# 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:

# 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:

# 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

# 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

# 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

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

SCM Authentication Failed

# 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