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.

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

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

• 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 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 \
  --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 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

Related Commands

• 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