270 lines
8.0 KiB
Markdown
270 lines
8.0 KiB
Markdown
# 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
|