294 lines
10 KiB
Markdown
294 lines
10 KiB
Markdown
# 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
|
|
```
|
|
|
|
- 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`
|