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

```bash
# 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:

```bash
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:

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

```yaml
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:

```bash
# 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:

```bash
# 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

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

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

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