stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
fa4a98dfef353e6065bb8daaa43c05943205fd49
git.stella-ops.org/docs/setup/setup-wizard-inventory.md

494 lines
18 KiB
Markdown
Raw Blame History

# Setup Wizard - Repository Inventory
This document captures the current state of setup-related components in the Stella Ops codebase, providing evidence for the Setup Wizard design.
## 1. CLI Architecture
### 1.1 Framework & Entry Points
| Component | Path | Description |
|-----------|------|-------------|
| **CLI Entry** | `src/Cli/StellaOps.Cli/Program.cs` | Main entry point using System.CommandLine |
| **Command Factory** | `src/Cli/StellaOps.Cli/Commands/CommandFactory.cs` | Central command registration (53+ command groups) |
| **Bootstrapper** | `src/Cli/StellaOps.Cli/Configuration/CliBootstrapper.cs` | Configuration loading and DI setup |
| **Options** | `src/Cli/StellaOps.Cli/Configuration/StellaOpsCliOptions.cs` | CLI configuration POCOs |
| **Profile Manager** | `src/Cli/StellaOps.Cli/Configuration/CliProfile.cs` | Multi-profile support |
### 1.2 Existing Admin Commands
**File:** `src/Cli/StellaOps.Cli/Commands/Admin/AdminCommandGroup.cs`
Current `stella admin` subcommands:
- `admin policy export|import|validate|list` - Policy management
- `admin users list|add|revoke|update` - User management
- `admin feeds list|status|refresh|history` - Feed management
- `admin system status|info` - System health and info
### 1.3 Doctor Commands
**File:** `src/Cli/StellaOps.Cli/Commands/DoctorCommandGroup.cs`
```bash
stella doctor run [--mode quick|normal|full] [--category <cat>] [--format text|json|markdown]
stella doctor list [--category <cat>] [--verbose]
stella doctor export --output <path>.zip [--include-logs]
```
### 1.4 Configuration System
**Priority Resolution (CliBootstrapper.cs):**
1. Command-line arguments (highest)
2. Environment variables (`STELLAOPS_*` prefix)
3. Configuration files (`appsettings.json`, `appsettings.yaml`)
4. Code defaults (lowest)
**Key Environment Variables:**
- `STELLAOPS_BACKEND_URL` - Backend API URL
- `STELLAOPS_AUTHORITY_URL` - Authority service URL
- `STELLAOPS_POSTGRES_CONNECTION` - Database connection
- `STELLAOPS_OFFLINE_KITS_DIRECTORY` - Offline kit path
---
## 2. Doctor System (Diagnostic Framework)
### 2.1 Core Engine
| Component | Path |
|-----------|------|
| **Engine** | `src/__Libraries/StellaOps.Doctor/Engine/DoctorEngine.cs` |
| **Registry** | `src/__Libraries/StellaOps.Doctor/Engine/CheckRegistry.cs` |
| **Executor** | `src/__Libraries/StellaOps.Doctor/Engine/CheckExecutor.cs` |
| **Models** | `src/__Libraries/StellaOps.Doctor/Models/` |
### 2.2 Plugin System (9 Plugins, 48+ Checks)
| Plugin | Path | Category | Checks |
|--------|------|----------|--------|
| **Core** | `StellaOps.Doctor.Plugins.Core` | Core | 9 checks (config, disk, memory, crypto) |
| **Database** | `StellaOps.Doctor.Plugins.Database` | Database | 8 checks (connectivity, migrations, schema) |
| **ServiceGraph** | `StellaOps.Doctor.Plugins.ServiceGraph` | ServiceGraph | 6 checks (gateway, Valkey) |
| **Security** | `StellaOps.Doctor.Plugins.Security` | Security | 9 checks (OIDC, TLS, Vault) |
| **Integration** | `StellaOps.Doctor.Plugins.Integration` | Integration | 8+ checks (GitHub, GitLab, registries) |
| **Observability** | `StellaOps.Doctor.Plugins.Observability` | Observability | 4 checks (OTLP, metrics) |
| **Cryptography** | `StellaOps.Doctor.Plugins.Cryptography` | Cryptography | 8+ checks (FIPS, eIDAS, HSM) |
| **Docker** | `StellaOps.Doctor.Plugins.Docker` | Docker | 5 checks (daemon, network) |
| **AI** | `StellaOps.Doctor.Plugins.AI` | AI | 4+ checks (LLM providers) |
| **Notify** | `StellaOps.Doctor.Plugin.Notify` | Notify | 5 checks (email, Slack, webhooks) |
### 2.3 Doctor Web Service
| Component | Path |
|-----------|------|
| **Web Service** | `src/Doctor/StellaOps.Doctor.WebService/` |
| **Endpoints** | `src/Doctor/StellaOps.Doctor.WebService/Endpoints/DoctorEndpoints.cs` |
| **Angular UI** | `src/Web/StellaOps.Web/src/app/features/doctor/` |
**REST API:**
- `POST /api/v1/doctor/run` - Start diagnostic run
- `GET /api/v1/doctor/run/{runId}` - Get run results
- `GET /api/v1/doctor/checks` - List available checks
- `WebSocket /api/v1/doctor/stream` - Real-time streaming
### 2.4 Check ID Convention
```
check.{category}.{subcategory}.{specific}
```
Examples:
- `check.config.required`
- `check.database.migrations.pending`
- `check.integration.scm.github.auth`
- `check.services.valkey.connectivity`
---
## 3. Database & Migrations
### 3.1 Migration Framework
| Component | Path |
|-----------|------|
| **Runner** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationRunner.cs` |
| **Startup Host** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/StartupMigrationHost.cs` |
| **Categories** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationCategory.cs` |
| **CLI Service** | `src/Cli/StellaOps.Cli/Services/MigrationCommandService.cs` |
### 3.2 Migration Categories
| Category | Prefix | Execution | Purpose |
|----------|--------|-----------|---------|
| **Startup** | 001-099 | Automatic at boot | Schema creation (idempotent) |
| **Release** | 100-199 | Manual CLI | Breaking changes (blocks boot if pending) |
| **Seed** | S001-S999 | Automatic at boot | Initial data (idempotent) |
| **Data** | DM001-DM999 | Background jobs | Data migrations |
### 3.3 Schema Isolation (Per-Module)
| Module | Schema | Migration Path |
|--------|--------|----------------|
| Authority | `authority` | `src/Authority/__Libraries/StellaOps.Authority.Persistence/Migrations/` |
| Concelier | `vuln` | `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Migrations/` |
| Scheduler | `scheduler` | `src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Migrations/` |
| Notify | `notify` | `src/Notify/__Libraries/StellaOps.Notify.Persistence/Migrations/` |
| Scanner | `scanner` | `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/` |
| Attestor | `attestor` | `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/Migrations/` |
| Policy | `policy` | `src/Policy/__Libraries/StellaOps.Policy.Persistence/Migrations/` |
| ReleaseOrchestrator | `release` | `src/ReleaseOrchestrator/__Libraries/.../Persistence/Migrations/` |
### 3.4 Existing CLI Commands
```bash
stella migrations-run --module <Module> --category <Category> [--dry-run] [--force]
```
---
## 4. Redis/Valkey Infrastructure
### 4.1 Connection Configuration
| Component | Path |
|-----------|------|
| **Primary Factory** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyConnectionFactory.cs` |
| **Options** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/Options/ValkeyTransportOptions.cs` |
| **Transport Plugin** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyTransportPlugin.cs` |
### 4.2 Usage Patterns
| Usage | Component | Purpose |
|-------|-----------|---------|
| **Message Queues** | `ValkeyMessageQueue` | Redis Streams with consumer groups |
| **Distributed Cache** | `ValkeyCacheStore` | TTL-based caching |
| **Rate Limiting** | `ValkeyRateLimitStore` | Token bucket algorithm |
| **Idempotency** | `ValkeyIdempotencyStore` | Duplicate prevention |
| **DPoP Nonces** | `RedisDpopNonceStore` | Auth token security |
### 4.3 Health Checks
**File:** `src/__Libraries/StellaOps.Doctor.Plugins.ServiceGraph/Checks/ValkeyConnectivityCheck.cs`
Configuration sources checked:
- `Valkey:ConnectionString`
- `Redis:ConnectionString`
- `ConnectionStrings:Valkey`
- `ConnectionStrings:Redis`
---
## 5. Integrations System
### 5.1 Core Architecture
| Component | Path |
|-----------|------|
| **Web Service** | `src/Integrations/StellaOps.Integrations.WebService/` |
| **Core Models** | `src/Integrations/__Libraries/StellaOps.Integrations.Core/` |
| **Contracts** | `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/` |
| **Persistence** | `src/Integrations/__Libraries/StellaOps.Integrations.Persistence/` |
### 5.2 Integration Types
**File:** `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationEnums.cs`
| Type | Range | Examples |
|------|-------|----------|
| **Registry** | 100-109 | Harbor, ECR, GCR, ACR, Docker Hub, Quay |
| **SCM** | 200-204 | GitHub App, GitLab Server, Bitbucket, Gitea |
| **CI/CD** | 300-306 | GitHub Actions, GitLab CI, Jenkins, Argo |
| **RepoSource** | 400-405 | npm, PyPI, Maven, NuGet, Crates.io |
| **RuntimeHost** | 500-502 | eBPF Agent, ETW Agent |
| **FeedMirror** | 600-602 | StellaOps Mirror, NVD, OSV |
### 5.3 Plugin Contract
**File:** `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs`
```csharp
public interface IIntegrationConnectorPlugin : IAvailabilityPlugin
{
IntegrationType Type { get; }
IntegrationProvider Provider { get; }
Task<TestConnectionResult> TestConnectionAsync(IntegrationConfig config, CancellationToken ct);
Task<HealthCheckResult> CheckHealthAsync(IntegrationConfig config, CancellationToken ct);
}
```
### 5.4 Existing Plugins
| Plugin | Path |
|--------|------|
| **GitHub App** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/` |
| **Harbor** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.Harbor/` |
| **InMemory** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.InMemory/` |
---
## 6. Notification System
### 6.1 Core Components
| Component | Path |
|-----------|------|
| **Web Service** | `src/Notify/StellaOps.Notify.WebService/` |
| **Engine** | `src/Notify/__Libraries/StellaOps.Notify.Engine/` |
| **Models** | `src/Notify/__Libraries/StellaOps.Notify.Models/` |
| **Queue** | `src/Notify/__Libraries/StellaOps.Notify.Queue/` |
### 6.2 Channel Types
**File:** `src/Notify/__Libraries/StellaOps.Notify.Models/NotifyChannel.cs`
- **Slack** - Incoming webhooks
- **Teams** - Incoming webhooks
- **Email** - SMTP
- **Webhook** - Generic HTTP POST
- **PagerDuty** / **OpsGenie** - Incident management
- **InApp** - In-application inbox
### 6.3 Channel Configuration
```csharp
public sealed record NotifyChannelConfig
{
public string SecretRef { get; } // authref:// URI
public string? Target { get; } // Channel/email list
public string? Endpoint { get; } // Webhook URL
public ImmutableDictionary<string, string> Properties { get; }
}
```
---
## 7. Vault/Secrets System
### 7.1 Vault Connectors
| Connector | Path |
|-----------|------|
| **HashiCorp Vault** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/HashiCorpVaultConnector.cs` |
| **Azure Key Vault** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/AzureKeyVaultConnector.cs` |
| **AWS Secrets Manager** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/AwsSecretsManagerConnector.cs` |
### 7.2 Secret Resolution
**File:** `src/ReleaseOrchestrator/__Libraries/.../Plugin/Integration/ITenantSecretResolver.cs`
```csharp
public interface ITenantSecretResolver : ISecretResolver
{
ITenantSecretResolver ForTenant(Guid tenantId);
Task<string?> ResolveFromVaultAsync(Guid integrationId, string secretPath, CancellationToken ct);
}
```
### 7.3 Credential Provider Schemes
**File:** `src/ReleaseOrchestrator/__Agents/StellaOps.Agent.Core/Credentials/CredentialResolver.cs`
- `env://VAR_NAME` - Environment variable
- `file:///path/to/secret` - File system
- `vault://integration-id/path` - Vault lookup
---
## 8. Environment & Agent System
### 8.1 Environment Model
**File:** `src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Environment/Models/Environment.cs`
```csharp
public sealed record Environment
{
public Guid Id { get; init; }
public Guid TenantId { get; init; }
public string Name { get; set; } // "dev", "staging", "prod"
public string DisplayName { get; set; }
public int OrderIndex { get; init; } // Pipeline order
public bool IsProduction { get; init; }
public int RequiredApprovals { get; set; }
public bool RequireSeparationOfDuties { get; set; }
public Guid? AutoPromoteFrom { get; set; }
}
```
### 8.2 Target Model (Deployment Target)
**File:** `src/ReleaseOrchestrator/__Libraries/.../Environment/Models/Target.cs`
| Target Type | Description |
|-------------|-------------|
| **DockerHost** | Docker Engine |
| **ComposeHost** | Docker Compose project |
| **EcsService** | AWS ECS service |
| **NomadJob** | HashiCorp Nomad job |
### 8.3 Agent Model
**File:** `src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Agent/Models/Agent.cs`
```csharp
public sealed record Agent
{
public Guid Id { get; init; }
public string Name { get; init; }
public AgentStatus Status { get; set; } // Pending, Active, Inactive, Stale, Revoked
public AgentCapability[] Capabilities { get; init; } // Docker, Compose, Ssh, WinRm
public string? CertificateThumbprint { get; set; } // mTLS
public DateTimeOffset? LastHeartbeatAt { get; set; }
}
```
### 8.4 Agent Registration
**File:** `src/ReleaseOrchestrator/__Libraries/.../Agent/Registration/RegistrationTokenService.cs`
- One-time tokens with 24-hour expiry
- mTLS certificate issuance on registration
- Heartbeat monitoring (30-second intervals, 90-second stale timeout)
---
## 9. Existing Onboarding System
### 9.1 Platform Onboarding Service
**File:** `src/Platform/StellaOps.Platform.WebService/Services/PlatformOnboardingService.cs`
**Default Steps:**
1. `connect-scanner`
2. `configure-policy`
3. `first-scan`
4. `review-findings`
5. `invite-team`
**Endpoints:**
- `GET /api/v1/platform/onboarding/status`
- `POST /api/v1/platform/onboarding/complete/{step}`
- `POST /api/v1/platform/onboarding/skip`
### 9.2 Quickstart Documentation
| Document | Path |
|----------|------|
| **Quickstart** | `docs/quickstart.md` |
| **CLI Quickstart** | `docs/CONCELIER_CLI_QUICKSTART.md` |
| **Install Guide** | `docs/INSTALL_GUIDE.md` |
| **Developer Onboarding** | `docs/DEVELOPER_ONBOARDING.md` |
---
## 10. UI Architecture
### 10.1 Angular Application
| Component | Path |
|-----------|------|
| **Root** | `src/Web/StellaOps.Web/src/app/app.component.ts` |
| **Routes** | `src/Web/StellaOps.Web/src/app/app.routes.ts` |
| **Config** | `src/Web/StellaOps.Web/src/app/app.config.ts` |
### 10.2 Existing Settings Pages
| Page | Path |
|------|------|
| **AI Preferences** | `src/Web/StellaOps.Web/src/app/features/settings/ai-preferences.component.ts` |
| **Environment Settings** | `src/Web/StellaOps.Web/src/app/features/release-orchestrator/environments/components/environment-settings/` |
| **Trivy DB Settings** | `src/Web/StellaOps.Web/src/app/features/trivy-db-settings/` |
### 10.3 Wizard Reference Implementation
**SBOM Source Wizard** (6-step multi-form wizard):
**File:** `src/Web/StellaOps.Web/src/app/features/sbom-sources/components/source-wizard/source-wizard.component.ts`
Features:
- Signal-based state management
- Step-by-step validation
- Connection testing
- Multi-form with conditional rendering
- TypeScript 1204 lines
---
## 11. Configuration Samples
| Sample | Path |
|--------|------|
| **Concelier** | `etc/concelier.yaml.sample` |
| **Authority** | `etc/authority.yaml.sample` |
| **Docker Compose** | `devops/compose/dev.env.example` |
| **Air-gap** | `devops/compose/airgap.env.example` |
---
## 12. Setup Wizard Backend (Platform Service)
### 12.1 API Endpoints
The Platform Service now exposes setup wizard endpoints at `/api/v1/setup/*`:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/setup/sessions` | GET | Get current setup session for tenant |
| `/api/v1/setup/sessions` | POST | Create new setup session |
| `/api/v1/setup/sessions/resume` | POST | Resume existing or create new session |
| `/api/v1/setup/sessions/finalize` | POST | Finalize setup session |
| `/api/v1/setup/steps/execute` | POST | Execute a setup step |
| `/api/v1/setup/steps/skip` | POST | Skip an optional setup step |
| `/api/v1/setup/definitions/steps` | GET | List all step definitions |
### 12.2 Backend Components
| Component | Path | Description |
|-----------|------|-------------|
| **Contracts** | `src/Platform/StellaOps.Platform.WebService/Contracts/SetupWizardModels.cs` | Step definitions, session state, API models |
| **Service** | `src/Platform/StellaOps.Platform.WebService/Services/PlatformSetupService.cs` | Session management, step execution, Doctor integration |
| **Store** | `src/Platform/StellaOps.Platform.WebService/Services/PlatformSetupService.cs` | In-memory tenant-scoped session store |
| **Endpoints** | `src/Platform/StellaOps.Platform.WebService/Endpoints/SetupEndpoints.cs` | HTTP endpoint handlers with Problem+JSON errors |
| **Policies** | `src/Platform/StellaOps.Platform.WebService/Constants/PlatformPolicies.cs` | Setup-specific authorization policies |
### 12.3 Scopes and Authorization
| Scope | Policy | Usage |
|-------|--------|-------|
| `platform.setup.read` | `SetupRead` | Read session state and step definitions |
| `platform.setup.write` | `SetupWrite` | Create/resume sessions, execute/skip steps |
| `platform.setup.admin` | `SetupAdmin` | Admin operations (list all sessions) |
---
## 13. Gaps Identified
### 13.1 Missing Components
| Gap | Description |
|-----|-------------|
| **`stella setup` command** | No dedicated interactive setup command exists |
| **First-run detection** | No blocking wizard on first launch |
| **Wizard UI wiring** | UI mock exists, needs wiring to backend endpoints |
| **Doctor integration** | Backend service has placeholder, needs real Doctor calls |
### 13.2 Partial Implementations
| Component | Current State | Gap |
|-----------|---------------|-----|
| **Setup Service** | In-memory store | Postgres persistence not implemented |
| **Doctor checks** | 48+ checks exist | Step execution uses mock pass results |
| **Migrations** | Automatic at startup | No interactive verification step |
| **Integrations** | Plugin architecture exists | No default suggestion logic |
---
## 14. Key Architectural Patterns to Follow
1. **System.CommandLine** for CLI commands
2. **Signal-based state** in Angular components
3. **IOptions<T> with validation** for configuration
4. **Plugin contracts** for extensibility
5. **Doctor checks** for health validation
6. **ITenantSecretResolver** for secret access
7. **HLC timestamps** for audit ordering
Reference in New Issue View Git Blame Copy Permalink