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. Some domains also have CLI command groups, but environment lifecycle is deliberately Console/API-only for RC1; there is no stella env create command.

Retained Secrets

Setup session draftValues remain sanitized. Passwords and similar secret-bearing fields are not echoed back through normal session reads.
When the backend needs a secret to survive resume/apply, it retains that value in protected companion storage and exposes only secretDrafts metadata in stella setup status --json.
Re-running or resuming setup without re-entering a retained secret keeps the server-retained value for probe/apply.
Supplying a new secret value replaces the retained one for that setup session.
Backend protection key precedence is Platform:Setup:SecretProtectionKey, STELLAOPS_SECRETS_ENCRYPTION_KEY, then STELLAOPS_BOOTSTRAP_KEY.

Operational Readiness

stella setup status reports required control-plane readiness only.
Text output prints an Operational readiness section with the current required counts, blocker summary, and any blocking dependencies.
stella setup status --json includes a readiness object for automation. This payload is intentionally required-only; optional post-boot services are not mixed into setup gating.
stella setup run finalization stops with an explicit error if any required readiness dependency is still blocked.
Optional post-boot services belong to stella admin diagnostics health, not to setup completion.

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

Released deployments must be operable without a source checkout. Release engineering publishes a dedicated stellaops/cli:<version> image built from devops/docker/Dockerfile.cli; operators run it through the opt-in compose overlay devops/compose/docker-compose.cli.yml.

The image contains the core CLI plus all current restart-time CLI plug-in payloads under /app/plugins/cli: Aoc, GroundTruth, NonCore, Policy, Symbols, Timestamp, Verdict, and Vex. The loader skips duplicate root tokens already served by core and activates non-conflicting plug-in additions. Before publishing a release tag, validate that plug-in-only commands are present in container help, for example stella runtime --help, stella excititor --help, and stella offline kit --help.

The runner mounts STELLAOPS_CLI_WORKDIR at /workspace and forwards the normal CLI environment variables, including:

Variable	Purpose
`STELLAOPS_CLI_IMAGE`	Released CLI image to run, for example `registry.example.com/stellaops/cli:2026.05.31`
`STELLAOPS_CLI_WORKDIR`	Host directory mounted at `/workspace` for `setup.yaml` and other operator inputs
`STELLAOPS_BACKEND_URL`	Platform/router URL reachable from inside the CLI container
`STELLAOPS_AUTHORITY_URL`	Authority URL reachable from inside the CLI container
`STELLAOPS_AUTHORITY_CLIENT_ID`	Human or automation CLI client id
`STELLAOPS_AUTHORITY_CLIENT_SECRET`	Automation client secret when using client credentials
`STELLAOPS_AUTHORITY_USERNAME` / `STELLAOPS_AUTHORITY_PASSWORD`	Non-interactive human/bootstrap login where allowed
`STELLAOPS_AUTHORITY_SCOPE`	Scope request for token acquisition
`API_KEY`	Legacy API-key path for commands that still read `API_KEY`

Reference compose stack:

cd devops/compose
export STELLAOPS_CLI_IMAGE=registry.example.com/stellaops/cli:2026.05.31
export STELLAOPS_CLI_WORKDIR="$PWD"
export STELLAOPS_BACKEND_URL=http://router.stella-ops.local:8080
export STELLAOPS_AUTHORITY_URL=http://authority.stella-ops.local:8440

./scripts/stella-cli.sh setup status --json
./scripts/stella-cli.sh setup run --config /workspace/setup.yaml --non-interactive
./scripts/stella-cli.sh runtime --help
./scripts/stella-cli.sh excititor --help
./scripts/stella-cli.sh offline kit --help

Windows operators use the PowerShell wrapper with the same variables:

cd devops/compose
$env:STELLAOPS_CLI_IMAGE = 'registry.example.com/stellaops/cli:2026.05.31'
$env:STELLAOPS_CLI_WORKDIR = (Resolve-Path .).Path
$env:STELLAOPS_BACKEND_URL = 'http://router.stella-ops.local:8080'
$env:STELLAOPS_AUTHORITY_URL = 'http://authority.stella-ops.local:8440'

.\scripts\stella-cli.ps1 setup status --json
.\scripts\stella-cli.ps1 setup run --config /workspace/setup.yaml --non-interactive

For non-compose targets, run the image directly and mount the setup workdir:

docker run --rm -it \
  -e STELLAOPS_BACKEND_URL \
  -e STELLAOPS_AUTHORITY_URL \
  -e STELLAOPS_AUTHORITY_CLIENT_ID \
  -e STELLAOPS_AUTHORITY_CLIENT_SECRET \
  -v "$PWD:/workspace" \
  registry.example.com/stellaops/cli:2026.05.31 \
  setup status --json

First Auth After Setup

Fresh local/dev installs seed first-party CLI auth clients through etc/authority/plugins/standard.yaml.

Human operators:

stella auth login

Use the Authority username/password created during the setup wizard; no demo admin is pre-seeded.
The CLI defaults to the seeded human client stellaops-cli.
In a fresh interactive shell, if no Authority username/password is preconfigured, the CLI prompts and uses the current password-grant bootstrap path.

Automation:

export STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli-automation
export STELLAOPS_AUTHORITY_CLIENT_SECRET=stellaops-local-cli-automation-secret
stella auth login --json

Production deployments should replace local/dev secrets and can tighten the allowed grants for these first-party clients.

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 including sanitized draftValues and retained-secret secretDrafts metadata

Notes:

The status surface carries required-only readiness because setup is allowed to finish before optional post-boot services come online.
Use stella admin diagnostics health when you need the full required-plus-optional platform readiness view.

`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 reset resets setup-session state only. It does not rotate, unlock, or replace an existing Authority admin password. For local compose source-checkout recovery, use devops/compose/scripts/authority-password-set.ps1 or authority-password-set.sh so the password update goes through the Stella CLI and Authority password hashing path.

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

If you are bringing up the Stella-owned local compose fixture lane, authenticate first and use the owned fixture bootstrap command:

# Authenticate into the target tenant if needed
stella auth login

# Bootstrap the default 13-entry local fixture catalog
stella config integrations bootstrap local

# Add the owned local GitLab SCM and CI fixtures
stella config integrations bootstrap local --include-gitlab

# Also add the optional local GitLab registry fixture
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry

The local bootstrap contract is explicit:

default mode creates or updates the 13 deterministic local compose entries and verifies their health
--include-gitlab mints the owned local GitLab PAT, stages it through Secret Authority into Vault, then binds GitLab Server and GitLab CI with the returned authref://... values
--include-gitlab-registry adds the optional GitLab container registry entry for the heavy GitLab compose profile with registry enabled via GITLAB_ENABLE_REGISTRY=true

For production or customer-managed third-party systems, use bring-your-own-secret onboarding instead of the local fixture bootstrap:

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

# Stage an operator-provided 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 customer-gitlab \
  --type scm \
  --provider gitlabserver \
  --endpoint https://gitlab.example.com \
  --secret-ref authref://vault/gitlab/server#access-token

--authref remains accepted for older automation, but new scripts should use --secret-ref. The CLI validates the URL with the shared SecretReference parser before calling the backend, so misspelled schemes fail locally.

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 finalization is blocked by operational readiness

stella setup status --json
stella admin diagnostics health --detail

Check:

which required dependency is still reported as blocked in the setup status readiness payload
whether frontdoor or authority is failing its live probe
whether optional post-boot service degradation is being mistaken for a setup blocker

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 bootstrap local for the Stella-owned local compose fixture lane
stella config integrations secrets *
stella config integrations create
the authenticated /setup/integrations/* UI

stella setup status --json
stella config integrations bootstrap local
stella config integrations providers
stella config integrations secrets targets
stella config integrations secrets upsert-bundle
stella system migrations-status --module all