210 lines
7.2 KiB
Markdown
210 lines
7.2 KiB
Markdown
# UI Setup Wizard Guide
|
|
|
|
This guide covers the web-based Setup Wizard for initial configuration of Stella Ops.
|
|
|
|
## Overview
|
|
|
|
The Setup Wizard guides you through configuring all required and optional components. Both CLI and UI setup wizards follow the same **Infrastructure-First** order and provide identical capabilities.
|
|
|
|
## Accessing the Setup Wizard
|
|
|
|
Navigate to `/setup` in your browser to access the Setup Wizard. The wizard is available when:
|
|
- First-time installation (no configuration exists)
|
|
- Explicitly navigating to `/setup` as an administrator
|
|
- Using reconfiguration mode to modify existing settings
|
|
|
|
## Setup Steps
|
|
|
|
Steps are organized in phases. Required steps must be completed; optional steps can be skipped.
|
|
|
|
### Phase 1: Core Infrastructure (Required)
|
|
|
|
| Step | Description |
|
|
|------|-------------|
|
|
| **Database** | PostgreSQL connection for persistent storage |
|
|
| **Cache** | Valkey/Redis connection for caching and distributed locks |
|
|
| **Migrations** | Apply database schema migrations |
|
|
|
|
### Phase 2: Security Foundation (Required)
|
|
|
|
| Step | Description |
|
|
|------|-------------|
|
|
| **Authority** | Authentication provider (Standard or LDAP) |
|
|
| **Users** | Initial super user account (skipped if LDAP selected) |
|
|
| **Crypto** | Cryptographic provider for signing/encryption |
|
|
|
|
### Phase 3: Secrets Management (Optional)
|
|
|
|
| Step | Description | Configure Later |
|
|
|------|-------------|-----------------|
|
|
| **Vault** | External secrets vault (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager, GCP Secret Manager) | Settings > Trust & Signing |
|
|
|
|
### Phase 4: Integrations (Optional)
|
|
|
|
| Step | Description | Configure Later |
|
|
|------|-------------|-----------------|
|
|
| **Registry** | Container registries for image scanning (supports multiple) | Settings > Integrations |
|
|
| **SCM** | Source control connections (supports multiple) | Settings > Integrations |
|
|
| **Sources** | Advisory data sources (NVD, GHSA, OSV, VEX feeds, custom mirrors) | Settings > Security Data |
|
|
|
|
### Phase 5: Observability (Optional)
|
|
|
|
| Step | Description | Configure Later |
|
|
|------|-------------|-----------------|
|
|
| **Telemetry** | OpenTelemetry configuration | Settings > System > Telemetry |
|
|
| **Notify** | Notification channels (supports multiple) | Settings > Notifications |
|
|
|
|
### Phase 6: AI Features (Optional)
|
|
|
|
| Step | Description | Configure Later |
|
|
|------|-------------|-----------------|
|
|
| **LLM** | AI/LLM provider for AdvisoryAI (OpenAI, Claude, Gemini, Ollama) | Settings > Integrations > AdvisoryAI |
|
|
|
|
### Phase 7: Configuration Store (Optional)
|
|
|
|
| Step | Description | Configure Later |
|
|
|------|-------------|-----------------|
|
|
| **Settings Store** | External configuration store (Consul, etcd, Azure App Config, AWS) | Settings > System |
|
|
|
|
### Phase 8: Release Orchestration (Optional)
|
|
|
|
| Step | Description | Configure Later |
|
|
|------|-------------|-----------------|
|
|
| **Environments** | Define deployment environments (dev, staging, production) | Settings > Environments |
|
|
| **Agents** | Register deployment agents | Settings > Agents |
|
|
|
|
## Multiple Integrations
|
|
|
|
The **Registry**, **SCM**, and **Notify** steps support configuring multiple instances:
|
|
|
|
### Container Registries
|
|
Add multiple registries for different purposes:
|
|
- Production registry (e.g., ECR, GCR)
|
|
- Development registry (e.g., Harbor)
|
|
- Third-party images (e.g., Docker Hub)
|
|
|
|
One registry can be marked as **Primary** for default operations.
|
|
|
|
### Source Control Connections
|
|
Add connections to multiple SCM providers:
|
|
- Main organization GitHub
|
|
- Internal GitLab instance
|
|
- Partner organization Bitbucket
|
|
|
|
One connection can be marked as **Primary** for default operations.
|
|
|
|
### Notification Channels
|
|
Add multiple notification destinations:
|
|
- Operations team Slack channel
|
|
- Security team email distribution
|
|
- Custom webhook for SIEM integration
|
|
|
|
All channels can receive notifications based on event rules.
|
|
|
|
## Wizard Navigation
|
|
|
|
### Progress Indicator
|
|
The left sidebar shows:
|
|
- Completed steps (green checkmark)
|
|
- Current step (highlighted)
|
|
- Pending steps (gray)
|
|
- Skipped steps (dash)
|
|
|
|
### Step Actions
|
|
Each step provides:
|
|
- **Test Connection**: Validate configuration without applying
|
|
- **Apply Configuration**: Save and validate the step
|
|
- **Skip this step**: Available for optional steps
|
|
|
|
### Skip Warnings
|
|
When skipping optional steps, warnings explain the implications:
|
|
|
|
| Skipped Step | Warning |
|
|
|--------------|---------|
|
|
| Vault | Secrets stored in configuration files (less secure) |
|
|
| Registry | Container scanning capabilities limited |
|
|
| SCM | Pipeline integration unavailable |
|
|
| Sources | Advisory feeds require manual updates |
|
|
| Telemetry | System observability limited |
|
|
| LLM | AdvisoryAI features unavailable |
|
|
| Environments | Manual deployment tracking only |
|
|
| Agents | Release orchestration unavailable |
|
|
|
|
## Cryptographic Provider Selection
|
|
|
|
The **Crypto** step allows selecting regional cryptographic standards:
|
|
|
|
| Provider | Standards | Use Case |
|
|
|----------|-----------|----------|
|
|
| **Default** | AES-256-GCM, SHA-256/512, Ed25519, ECDSA P-256 | General use |
|
|
| **FIPS 140-2** | FIPS-compliant algorithms with optional HSM | US government compliance |
|
|
| **GOST R 34.10-2012** | Kuznechik/Magma, Streebog, GOST signatures | Russian compliance |
|
|
| **SM2/SM3** | SM4, SM3, SM2 | Chinese national standards |
|
|
|
|
## Advisory Data Sources
|
|
|
|
The **Sources** step supports multiple feed types:
|
|
|
|
### CVE/Vulnerability Feeds
|
|
- NVD (NIST National Vulnerability Database)
|
|
- GHSA (GitHub Security Advisories)
|
|
- OSV (Open Source Vulnerabilities)
|
|
- Distribution feeds (Red Hat, Ubuntu, Debian, Alpine, Wolfi)
|
|
|
|
### VEX Sources
|
|
- CSAF VEX feeds from vendors
|
|
- OpenVEX format feeds
|
|
- CycloneDX BOM with embedded VEX
|
|
|
|
### Custom Mirrors
|
|
- Self-hosted advisory mirrors for air-gapped environments
|
|
- Supports Basic Auth, Bearer Token, or mTLS authentication
|
|
- Configurable sync intervals
|
|
|
|
## Environment Patterns
|
|
|
|
The **Environments** step provides quick-start patterns:
|
|
|
|
| Pattern | Environments | Description |
|
|
|---------|--------------|-------------|
|
|
| **Standard** | Dev > Staging > Production | Common three-tier pipeline |
|
|
| **Simple** | Staging > Production | Minimal two-tier setup |
|
|
| **Extended** | Dev > QA > Staging > Pre-Prod > Production | Enterprise pipeline |
|
|
| **Custom** | User-defined | Flexible custom configuration |
|
|
|
|
## Resuming Setup
|
|
|
|
If setup is interrupted:
|
|
1. Return to `/setup` to resume where you left off
|
|
2. Session state is preserved automatically
|
|
3. Completed steps remain configured
|
|
|
|
## Reconfiguration Mode
|
|
|
|
To modify existing configuration:
|
|
1. Navigate to `/setup?mode=reconfigure`
|
|
2. Previously configured steps show current values
|
|
3. Modify and re-apply any step as needed
|
|
|
|
## Keyboard Navigation
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| Tab | Move between form fields |
|
|
| Enter | Submit current form / Activate button |
|
|
| Escape | Cancel current operation |
|
|
|
|
## Accessibility
|
|
|
|
The Setup Wizard follows WCAG 2.1 AA guidelines:
|
|
- All form fields have associated labels
|
|
- Error messages are announced to screen readers
|
|
- Focus is managed through step transitions
|
|
- Color is not the only indicator of status
|
|
|
|
## Related Documentation
|
|
|
|
- [CLI Setup Guide](../../cli/guides/setup-guide.md) - Command-line setup
|
|
- [Settings Architecture](../architecture.md) - Settings page structure
|
|
- [API Strategy](../api-strategy.md) - Backend API contracts
|