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

Setup Wizard Guide

This guide covers the current stella setup command set for installation-scoped control-plane bootstrap.

Overview

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

# Run the installation bootstrap
stella setup run

# Resume the current installation session
stella setup resume

# 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

Supported Steps

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.

Deprecated setup aliases still accepted:

• valkey -> cache
• authority -> admin
• users -> admin

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.

Command Surface

stella setup

Runs the same flow as stella setup run.

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

stella setup run

Run the installation bootstrap from the beginning or continue from the active installation-scoped session.

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

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.

stella setup resume

Resume the current setup session or a specific one.

Options:

• --session - explicit setup session ID

stella setup status

Show the current installation-scoped session.

Options:

• --session - explicit setup session ID
• --json - machine-readable output

stella setup reset

Reset one step or the whole installation session.

Options:

• --step, -s - reset one control-plane step
• --all - start a fresh installation-scoped session
• --force, -f - skip confirmation when used with --all

stella setup validate

Validate a configuration file, then run the setup flow in probe-only mode.

Options:

• --config, -c - required YAML configuration path

Configuration File Shape

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.

database:
  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: stellaops
  password: ${DB_PASSWORD}

cache:
  host: cache.stella-ops.local
  port: 6379
  password: ${CACHE_PASSWORD}
  database: 0

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

authority:
  provider: standard

crypto:
  provider: default

What Happens After Setup

When stella setup finishes, the next work is tenant onboarding, not more bootstrap steps.

Typical next commands:

# Discover writable secret-authority targets
stella config integrations secrets targets

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

# 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 probe fails

stella setup run --step database --dry-run --config ./setup.yaml

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 probe fails

stella setup run --step cache --dry-run --config ./setup.yaml

Check:

• the runtime cache service is reachable
• the host/port/password values are correct

Setup reports that vault or scm is no longer a supported step

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 setup status --json
• stella config integrations providers
• stella config integrations secrets targets
• stella config integrations secrets upsert-bundle
• stella system migrations-status --module all