stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

docs: UI-driven local setup sprints + module dossier sync

Browse Source 
Add SPRINT_20260413_004 (platform UI-only setup bootstrap closure)
with BOOTSTRAP-001..006 delivery tracker, and update sprint 003 and
sprint 20260410-001 execution logs to reflect the completed
persistence / orchestrator / secret-authority work.

Sync module dossiers and operator guides with the new reality: setup
wizard UX, platform-service architecture, CLI setup guide, integrations
architecture + local services, release-orchestrator architecture,
install guide, and compose README.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-04-14 07:56:45 +03:00
parent 286c1f758a
commit 398d0659eb
12 changed files with 648 additions and 262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

322
docs/modules/cli/guides/setup-guide.md
View File

@@ -1,269 +1,215 @@
# Setup Wizard Guide
This guide covers the `stella setup` command for initial configuration of Stella Ops.
This guide covers the current `stella setup` command set for installation-scoped control-plane bootstrap.
## 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.
`stella setup` is no longer an all-in-one platform onboarding wizard.
- It owns only the five control-plane steps the running platform can truthfully validate and converge: `database`, `cache`, `migrations`, `admin`, `crypto`.
- It uses the Platform setup session APIs as the source of truth. Local files are not the authoritative setup state.
- Tenant onboarding such as integrations, secrets providers, advisory sources, environments, agents, and notifications happens on the authenticated `/setup/*` surfaces and the corresponding CLI command groups.
## Quick Start
```bash
# Interactive setup
# Run the installation bootstrap
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
# Resume the current installation session
stella setup resume
# Reconfigure a specific step
stella setup --step vault
# Show the current installation-scoped session
stella setup status
# JSON status for automation
stella setup status --json
# Probe a specific step only
stella setup run --step database --dry-run
# Reset a specific step
stella setup reset --step cache
# Reset the whole installation session
stella setup reset --all --force
```
## Setup Steps
## Supported Steps
Steps are organized in phases. Required steps must be completed; optional steps can be skipped.
| Step | Purpose | Notes |
| --- | --- | --- |
| `database` | Verify the PostgreSQL runtime connection and record convergence | Machine-level DB provisioning remains outside `stella setup`. |
| `cache` | Verify the cache runtime connection and record convergence | `valkey` remains a compatibility alias. |
| `migrations` | Converge required schema migrations | Uses the backend migration-admin path. |
| `admin` | Ensure the bootstrap administrator exists | `authority` and `users` remain compatibility aliases. |
| `crypto` | Validate and apply the selected crypto profile | Uses live provider health rather than optimistic local state. |
### Phase 1: Core Infrastructure (Required)
Deprecated setup aliases still accepted:
- `valkey -> cache`
- `authority -> admin`
- `users -> admin`
| Step | Description |
|------|-------------|
| **database** | PostgreSQL connection for persistent storage |
| **cache** | Valkey/Redis connection for caching and distributed locks |
| **migrations** | Apply database schema migrations |
Former setup targets such as `vault`, `registry`, `scm`, `sources`, `notify`, `telemetry`, `llm`, `settingsstore`, `environments`, and `agents` now return explicit handoff guidance instead of pretending they are bootstrap steps.
### Phase 2: Security Foundation (Required)
## Command Surface
| 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) |
### `stella setup`
### Phase 3: Secrets Management (Optional)
Runs the same flow as `stella setup run`.
| 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.*` |
Global options:
- `--config`, `-c` - path to YAML configuration used to seed draft values before probe/apply
- `--non-interactive`, `-y` - do not prompt for missing values
### Phase 4: Integrations (Optional)
### `stella setup run`
| 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.*` |
Run the installation bootstrap from the beginning or continue from the active installation-scoped session.
### Phase 5: Observability (Optional)
Options:
- `--step`, `-s` - run one supported control-plane step only
- `--skip` - skip selected steps for this invocation
- `--dry-run` - probe only; do not apply
- `--force`, `-f` - start a fresh setup session even if one already exists
- `--config`, `-c`
- `--non-interactive`, `-y`
| 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.*` |
Notes:
- `probe` is diagnostic only. A successful probe does not complete a step.
- Only `apply` transitions performed by `run` without `--dry-run` can converge a step.
### Phase 6: AI Features (Optional)
### `stella setup resume`
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **llm** | AI/LLM provider for AdvisoryAI (OpenAI, Claude, Gemini, Ollama) | Settings > Integrations > AdvisoryAI, or `stella config set llm.*` |
Resume the current setup session or a specific one.
### Phase 7: Configuration Store (Optional)
Options:
- `--session` - explicit setup session ID
| Step | Description | Configure Later |
|------|-------------|-----------------|
| **settingsStore** | External configuration store (Consul, etcd, Azure App Config, AWS Parameter Store) | Settings > System, or `stella config set settingsStore.*` |
### `stella setup status`
### Phase 8: Release Orchestration (Optional)
Show the current installation-scoped session.
| 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` |
Options:
- `--session` - explicit setup session ID
- `--json` - machine-readable output
## Multiple Integrations
### `stella setup reset`
The **registry**, **scm**, and **notify** steps support configuring multiple instances. For example:
Reset one step or the whole installation session.
```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"
Options:
- `--step`, `-s` - reset one control-plane step
- `--all` - start a fresh installation-scoped session
- `--force`, `-f` - skip confirmation when used with `--all`
stella config set registry.instances.1.name "Docker Hub"
stella config set registry.instances.1.provider "docker"
### `stella setup validate`
# Add multiple SCM connections
stella config set scm.instances.0.name "GitHub Main"
stella config set scm.instances.0.provider "github"
Validate a configuration file, then run the setup flow in probe-only mode.
# Add multiple notification channels
stella config set notify.instances.0.name "Ops Slack"
stella config set notify.instances.0.provider "slack"
Options:
- `--config`, `-c` - required YAML configuration path
stella config set notify.instances.1.name "Security Email"
stella config set notify.instances.1.provider "email"
```
## Configuration File Shape
## 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:
`stella setup` consumes only the values relevant to the five control-plane steps. The CLI forwards these as backend draft values rather than directly mutating local infrastructure.
```yaml
# setup.yaml
database:
host: localhost
connectionString: Host=postgres.stella-ops.local;Port=5432;Database=stellaops;Username=stellaops;Password=${DB_PASSWORD}
host: postgres.stella-ops.local
port: 5432
database: stellaops
user: postgres
password: ${DB_PASSWORD} # Environment variable substitution
ssl: true
user: stellaops
password: ${DB_PASSWORD}
cache:
host: localhost
host: cache.stella-ops.local
port: 6379
password: ${CACHE_PASSWORD}
ssl: true
authority:
provider: standard # or 'ldap'
database: 0
users:
superuser:
username: admin
email: admin@example.com
password: ${ADMIN_PASSWORD}
displayName: Stella Admin
authority:
provider: standard
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
provider: default
```
## Validation Commands
## What Happens After Setup
When `stella setup` finishes, the next work is tenant onboarding, not more bootstrap steps.
Typical next commands:
```bash
# Validate current configuration
stella setup validate
# Discover writable secret-authority targets
stella config integrations secrets targets
# Validate specific step
stella setup validate --step database
# Stage a GitLab access token into a secret-authority target
stella config integrations secrets upsert-bundle \
--bundle gitlab-server \
--target <vault-integration-id> \
--path gitlab/server \
--entry access-token=glpat-...
# Show current setup status
stella setup status
# Create the GitLab server integration with the returned authref
stella config integrations create \
--name local-gitlab \
--type scm \
--provider gitlabserver \
--endpoint http://gitlab.stella-ops.local:8929 \
--authref authref://vault/gitlab/server#access-token
```
UI handoff surfaces:
- `/setup/integrations/secrets`
- `/setup/integrations/scm`
- `/setup/integrations/ci`
- `/setup/integrations/registries`
## Troubleshooting
### Database Connection Failed
### Database probe fails
```bash
# Test PostgreSQL connectivity
stella setup validate --step database --verbose
stella setup run --step database --dry-run --config ./setup.yaml
```
Verify:
- PostgreSQL is running and accessible
- Credentials are correct
- SSL settings match server configuration
Check:
- the runtime PostgreSQL service is reachable
- the connection string or host/user/password values are correct
- the machine/bootstrap layer already provisioned PostgreSQL
### Cache Connection Failed
### Cache probe fails
```bash
# Test Valkey/Redis connectivity
stella setup validate --step cache --verbose
stella setup run --step cache --dry-run --config ./setup.yaml
```
### SCM Authentication Failed
Check:
- the runtime cache service is reachable
- the host/port/password values are correct
```bash
# Test SCM connectivity
stella setup validate --step scm --verbose
```
### Setup reports that `vault` or `scm` is no longer a supported step
Ensure your token has the required scopes:
- GitHub: `repo`, `workflow`
- GitLab: `api`, `read_repository`
- Azure DevOps: `Code (Read)`, `Build (Read & Execute)`
That is expected. Those flows moved out of installation bootstrap.
Use:
- `stella config integrations secrets *`
- `stella config integrations create`
- the authenticated `/setup/integrations/*` UI
## 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
- `stella setup status --json`
- `stella config integrations providers`
- `stella config integrations secrets targets`
- `stella config integrations secrets upsert-bundle`
- `stella system migrations-status --module all`