stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

docs consolidation and others

Browse Source
This commit is contained in:
master
2026-01-06 19:02:21 +02:00
parent d7bdca6d97
commit 4789027317
849 changed files with 16551 additions and 66770 deletions
Download Patch File Download Diff File Expand all files Collapse all files

295
docs/operations/deployment/VERSION_MATRIX.md Normal file
View File

@@ -0,0 +1,295 @@
# StellaOps Deployment Version Matrix
> **Last Updated:** 2025-12-04
> **Purpose:** Single source of truth for service versions across deployment environments
> **Unblocks:** COMPOSE-44-001, 44-001, 44-002, 44-003, 45-001, 45-002, 45-003 (7 tasks)
## Quick Reference
| Environment | Core Version | Status |
|-------------|-------------|--------|
| **Development** | `2025.10.0-edge` | Active |
| **Staging** | `2025.09.2` | Stable |
| **Production** | `2025.09.2` | Stable |
| **Air-Gap** | `2025.09.2-airgap` | Certified |
---
## Service Version Matrix
### Core Services
| Service | Dev | Staging | Prod | Air-Gap | Notes |
|---------|-----|---------|------|---------|-------|
| Authority | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | OAuth 2.1 / mTLS |
| Signer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | ECDSA/RSA/EdDSA |
| Attestor | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | in-toto/DSSE |
| Concelier | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Advisory ingestion |
| Scanner | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | SBOM/Vuln scanning |
| Excititor | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | VEX export |
| Policy | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | OPA/Rego engine |
| Scheduler | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Job scheduling |
| Notify | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Notifications |
### Platform Services
| Service | Dev | Staging | Prod | Air-Gap | Notes |
|---------|-----|---------|------|---------|-------|
| Orchestrator Web | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | API Gateway |
| Orchestrator Worker | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Background jobs |
| Graph API | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Graph queries |
| Graph Indexer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Graph ingest |
| Timeline Indexer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Event timeline |
| Findings Ledger | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Finding storage |
### Infrastructure Dependencies
| Component | Version | Digest | Notes |
|-----------|---------|--------|-------|
| PostgreSQL | `16-alpine` | N/A | Primary database (REQUIRED) |
| Valkey | `8.0` | N/A | Cache, DPoP security (REQUIRED) |
| RustFS | `2025.10.0-edge` | N/A | Object storage (REQUIRED) |
| NATS | `2.10` | `sha256:c82559e4476289481a8a5196e675ebfe67eea81d95e5161e3e78eccfe766608e` | Message queue (optional) |
---
## Container Image Registry
### Primary Registry
```
registry.stella-ops.org/stellaops/<service>:<version>
```
### Image Naming Convention
| Pattern | Example | Use Case |
|---------|---------|----------|
| `<service>:<version>` | `authority:2025.09.2` | Tagged releases |
| `<service>:<version>-<variant>` | `authority:2025.09.2-airgap` | Environment variants |
| `<service>:edge` | `authority:edge` | Latest dev build |
| `<service>@sha256:<digest>` | `authority@sha256:abc123...` | Immutable reference |
### Air-Gap Bundle Images
Air-gap deployments use pre-bundled images with all dependencies:
```
registry.stella-ops.org/stellaops/airgap-bundle:2025.09.2
```
Bundle contents:
- All core services at matching version
- Infrastructure containers (PostgreSQL, Valkey, RustFS, NATS)
- CLI tools and migration utilities
- Offline kit documentation
---
## Version Promotion Workflow
### Stages
```
Dev (edge) → Staging → Production → Air-Gap (certified)
```
### Promotion Criteria
| Stage | Criteria |
|-------|----------|
| Dev → Staging | All unit tests pass, integration tests pass |
| Staging → Prod | E2E tests pass, security scan clean, performance benchmarks pass |
| Prod → Air-Gap | Offline validation complete, bundle integrity verified, documentation updated |
### Promotion Commands
```bash
# Promote dev to staging
./scripts/promote.sh --from dev --to staging --version 2025.10.0
# Promote staging to production
./scripts/promote.sh --from staging --to prod --version 2025.10.0
# Create air-gap certified bundle
./scripts/create-airgap-bundle.sh --version 2025.09.2
```
---
## Helm Chart Values
### Development (`values-dev.yaml`)
```yaml
global:
imageTag: "2025.10.0-edge"
imagePullPolicy: Always
environment: development
services:
authority:
replicaCount: 1
resources:
requests:
memory: "256Mi"
cpu: "100m"
```
### Production (`values-prod.yaml`)
```yaml
global:
imageTag: "2025.09.2"
imagePullPolicy: IfNotPresent
environment: production
services:
authority:
replicaCount: 3
resources:
requests:
memory: "512Mi"
cpu: "250m"
```
### Air-Gap (`values-airgap.yaml`)
```yaml
global:
imageTag: "2025.09.2-airgap"
imagePullPolicy: Never # Images pre-loaded
environment: airgap
offlineMode: true
airgap:
enabled: true
bundleVersion: "2025.09.2"
stalenessThresholdSeconds: 604800 # 7 days
```
---
## Docker Compose Reference
### Quick Start (Development)
```yaml
# docker-compose.dev.yaml
version: "3.8"
services:
authority:
image: registry.stella-ops.org/stellaops/authority:2025.10.0-edge
concelier:
image: registry.stella-ops.org/stellaops/concelier:2025.10.0-edge
scanner:
image: registry.stella-ops.org/stellaops/scanner:2025.10.0-edge
```
### Production
```yaml
# docker-compose.prod.yaml
version: "3.8"
services:
authority:
image: registry.stella-ops.org/stellaops/authority@sha256:...
deploy:
replicas: 3
concelier:
image: registry.stella-ops.org/stellaops/concelier@sha256:...
deploy:
replicas: 2
```
---
## Service Dependencies
### Startup Order
```
1. Infrastructure (PostgreSQL, Valkey, RustFS, NATS)
↓
2. Core Auth (Authority, Signer)
↓
3. Data Services (Concelier, Excititor)
↓
4. Compute Services (Scanner, Policy, Scheduler)
↓
5. Platform Services (Orchestrator, Graph, Timeline)
↓
6. UI/CLI
```
### Health Check Endpoints
| Service | Health Endpoint | Ready Endpoint |
|---------|-----------------|----------------|
| All | `/health` | `/ready` |
| Authority | `/health` | `/ready` (includes JWKS) |
| Scanner | `/health` | `/ready` (includes analyzer check) |
---
## Breaking Changes Log
### 2025.10.0 (Upcoming)
- **Authority:** New OAuth 2.1 endpoints (backward compatible)
- **Scanner:** Analyzer plugin format v2 (migration required)
- **Concelier:** LNM API v2 (v1 deprecated, removed in 2025.11.0)
### 2025.09.2 (Current Stable)
- **All:** Initial GA release
- **Air-Gap:** First certified offline bundle
---
## Rollback Procedure
### Helm Rollback
```bash
# List releases
helm history stellaops -n stellaops
# Rollback to previous
helm rollback stellaops 1 -n stellaops
```
### Compose Rollback
```bash
# Stop current
docker-compose down
# Edit .env to previous version
# VERSION=2025.09.1
# Start previous
docker-compose up -d
```
---
## Related Documents
- [Helm Chart Documentation](../deploy/helm/stellaops/README.md)
- [Compose Quickstart](../deploy/compose/README.md)
- [Offline Kit Guide](./OFFLINE_KIT.md)
- [Air-Gap Provenance](../modules/findings-ledger/airgap-provenance.md)
- [Staleness Schema](../schemas/ledger-airgap-staleness.schema.json)
---
## Changelog
| Date | Change | Author |
|------|--------|--------|
| 2025-12-04 | Initial version matrix created | Claude |
| 2025-12-04 | Added air-gap certification workflow | Claude |

228
docs/operations/deployment/console.md Normal file
View File

@@ -0,0 +1,228 @@
# Deploying the StellaOps Console
> **Audience:** Deployment Guild, Console Guild, operators rolling out the web console.
> **Scope:** Helm and Docker Compose deployment steps, ingress/TLS configuration, required environment variables, health checks, offline/air-gap operation, and compliance checklist (Sprint 23).
The StellaOps Console ships as part of the `stellaops` stack Helm chart and Compose bundles maintained under `deploy/`. This guide describes the supported deployment paths, the configuration surface, and operational checks needed to run the console in connected or air-gapped environments.
---
## 1. Prerequisites
- Kubernetes cluster (v1.28+) with ingress controller (NGINX, Traefik, or equivalent) and Cert-Manager for automated TLS, or Docker host for Compose deployments.
- Container registry access to `registry.stella-ops.org` (or mirrored registry) for all images listed in `deploy/releases/*.yaml`.
- Authority service configured with console client (`aud=ui`, scopes `ui.read`, `ui.admin`).
- DNS entry pointing to the console hostname (for example, `console.acme.internal`).
- Cosign public key for manifest verification (`deploy/releases/manifest.json.sig`).
- Optional: Offline Kit bundle for air-gapped sites (`stella-ops-offline-kit-<ver>.tar.gz`).
---
## 2. Helm deployment (recommended)
### 2.1 Install chart repository
```bash
helm repo add stellaops https://downloads.stella-ops.org/helm
helm repo update stellaops
```
If operating offline, copy the chart archive from the Offline Kit (`deploy/helm/stellaops-<ver>.tgz`) and run:
```bash
helm install stellaops ./stellaops-<ver>.tgz --namespace stellaops --create-namespace
```
### 2.2 Base installation
```bash
helm install stellaops stellaops/stellaops \
--namespace stellaops \
--create-namespace \
--values deploy/helm/stellaops/values-prod.yaml
```
The chart deploys Authority, Console web/API gateway, Scanner API, Scheduler, and supporting services. The console frontend pod is labelled `app=stellaops-web-ui`.
### 2.3 Helm values highlights
Key sections in `deploy/helm/stellaops/values-prod.yaml`:
| Path | Description |
|------|-------------|
| `console.ingress.host` | Hostname served by the console (`console.example.com`). |
| `console.ingress.tls.secretName` | Kubernetes secret containing TLS certificate (generated by Cert-Manager or uploaded manually). |
| `console.config.apiGateway.baseUrl` | Internal base URL the UI uses to reach the gateway (defaults to `https://stellaops-web`). |
| `console.env.AUTHORITY_ISSUER` | Authority issuer URL (for example, `https://authority.example.com`). |
| `console.env.AUTHORITY_CLIENT_ID` | Authority client ID for the console UI. |
| `console.env.AUTHORITY_SCOPES` | Space-separated scopes required by UI (`ui.read ui.admin`). |
| `console.resources` | CPU/memory requests and limits (default 250m CPU / 512Mi memory). |
| `console.podAnnotations` | Optional annotations for service mesh or monitoring. |
Use `values-stage.yaml`, `values-dev.yaml`, or `values-airgap.yaml` as templates for other environments.
### 2.4 TLS and ingress
Example ingress override:
```yaml
console:
ingress:
enabled: true
className: nginx
host: console.acme.internal
tls:
enabled: true
secretName: console-tls
```
Generate certificates using Cert-Manager or provide an existing secret. For air-gapped deployments, pre-create the secret with the mirrored CA chain.
### 2.5 Health checks
Console pods expose:
| Path | Purpose | Notes |
|------|---------|-------|
| `/health/live` | Liveness probe | Confirms process responsive. |
| `/health/ready` | Readiness probe | Verifies configuration bootstrap and Authority reachability. |
| `/metrics` | Prometheus metrics | Enabled when `console.metrics.enabled=true`. |
Helm chart sets default probes (`initialDelaySeconds: 10`, `periodSeconds: 15`). Adjust via `console.livenessProbe` and `console.readinessProbe`.
---
## 3. Docker Compose deployment
Located in `deploy/compose/docker-compose.console.yaml`. Quick start:
```bash
cd deploy/compose
docker compose -f docker-compose.console.yaml --env-file console.env up -d
```
`console.env` should define:
```
CONSOLE_PUBLIC_BASE_URL=https://console.acme.internal
AUTHORITY_ISSUER=https://authority.acme.internal
AUTHORITY_CLIENT_ID=console-ui
AUTHORITY_CLIENT_SECRET=<if using confidential client>
AUTHORITY_SCOPES=ui.read ui.admin
CONSOLE_GATEWAY_BASE_URL=https://api.acme.internal
```
The compose bundle includes Traefik as reverse proxy with TLS termination. Update `traefik/dynamic/console.yml` for custom certificates or additional middlewares (CSP headers, rate limits).
---
## 4. Environment variables
| Variable | Description | Default |
|----------|-------------|---------|
| `CONSOLE_PUBLIC_BASE_URL` | External URL used for redirects, deep links, and telemetry. | None (required). |
| `CONSOLE_GATEWAY_BASE_URL` | URL of the web gateway that proxies API calls (`/console/*`). | Chart service name. |
| `AUTHORITY_ISSUER` | Authority issuer (`https://authority.example.com`). | None (required). |
| `AUTHORITY_CLIENT_ID` | OIDC client configured in Authority. | None (required). |
| `AUTHORITY_SCOPES` | Space-separated scopes assigned to the console client. | `ui.read ui.admin`. |
| `AUTHORITY_DPOP_ENABLED` | Enables DPoP challenge/response (recommended true). | `true`. |
| `CONSOLE_FEATURE_FLAGS` | Comma-separated feature flags (`runs`, `downloads.offline`, etc.). | `runs,downloads,policies`. |
| `CONSOLE_LOG_LEVEL` | Minimum log level (`Information`, `Debug`, etc.). | `Information`. |
| `CONSOLE_METRICS_ENABLED` | Expose `/metrics` endpoint. | `true`. |
| `CONSOLE_SENTRY_DSN` | Optional error reporting DSN. | Blank. |
When running behind additional proxies, set `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` to honour `X-Forwarded-*` headers.
---
## 5. Security headers and CSP
The console serves a strict Content Security Policy (CSP) by default:
```
default-src 'self';
connect-src 'self' https://*.stella-ops.local;
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data:;
font-src 'self';
frame-ancestors 'none';
```
Adjust via `console.config.cspOverrides` if additional domains are required. For integrations embedding the console, update OIDC redirect URIs and Authority scopes accordingly.
TLS recommendations:
- Use TLS 1.2+ with modern cipher suite policy.
- Enable HSTS (`Strict-Transport-Security: max-age=31536000; includeSubDomains`).
- Provide custom trust bundles via `console.config.trustBundleSecret` when using private CAs.
---
## 6. Logging and metrics
- Structured logs emitted to stdout with correlation IDs. Configure log shipping via Fluent Bit or similar.
- Metrics available at `/metrics` in Prometheus format. Key metrics include `ui_request_duration_seconds`, `ui_tenant_switch_total`, and `ui_download_manifest_refresh_seconds`.
- Enable OpenTelemetry exporter by setting `OTEL_EXPORTER_OTLP_ENDPOINT` and associated headers in environment variables.
---
## 7. Offline and air-gap deployment
- Mirror container images using the Downloads workspace or Offline Kit manifest. Example:
```bash
oras copy registry.stella-ops.org/stellaops/web-ui@sha256:<digest> \
registry.airgap.local/stellaops/web-ui:2025.10.0
```
- Import Offline Kit using `stella ouk import` before starting the console so manifest parity checks succeed.
- Use `values-airgap.yaml` to disable external telemetry endpoints and configure internal certificate chains.
- Run `helm upgrade --install` using the mirrored chart (`stellaops-<ver>.tgz`) and set `console.offlineMode=true` to surface offline banners.
---
## 8. Health checks and remediation
| Check | Command | Expected result |
|-------|---------|-----------------|
| Pod status | `kubectl get pods -n stellaops` | `Running` state with restarts = 0. |
| Liveness | `kubectl exec deploy/stellaops-web-ui -- curl -fsS http://localhost:8080/health/live` | Returns `{"status":"Healthy"}`. |
| Readiness | `kubectl exec deploy/stellaops-web-ui -- curl -fsS http://localhost:8080/health/ready` | Returns `{"status":"Ready"}`. |
| Gateway reachability | `curl -I https://console.example.com/api/console/status` | `200 OK` with CSP headers. |
| Static assets | `curl -I https://console.example.com/static/assets/app.js` | `200 OK` with long cache headers. |
Troubleshooting steps:
- **Authority unreachable:** readiness fails with `AUTHORITY_UNREACHABLE`. Check DNS, trust bundles, and Authority service health.
- **Manifest mismatch:** console logs `DOWNLOAD_MANIFEST_SIGNATURE_INVALID`. Verify cosign key and re-sync manifest.
- **Ingress 404:** ensure ingress controller routes host to `stellaops-web-ui` service; check TLS secret name.
- **SSE blocked:** confirm proxy allows HTTP/1.1 and disables buffering on `/console/runs/*`.
---
## 9. References
- `deploy/helm/stellaops/values-*.yaml` - environment-specific overrides.
- `deploy/compose/docker-compose.console.yaml` - Compose bundle.
- `docs/UI_GUIDE.md` - Console workflows and offline posture.
- `/docs/security/console-security.md` - CSP and Authority scopes.
- `/docs/OFFLINE_KIT.md` - Offline kit packaging and verification.
- `/docs/modules/devops/runbooks/deployment-runbook.md` (pending) - wider platform deployment steps.
---
## 10. Compliance checklist
- [ ] Helm and Compose instructions verified against `deploy/` assets.
- [ ] Ingress/TLS guidance aligns with Security Guild recommendations.
- [ ] Environment variables documented with defaults and required values.
- [ ] Health/liveness/readiness endpoints tested and listed.
- [ ] Offline workflow (mirrors, manifest parity) captured.
- [ ] Logging and metrics surface documented metrics.
- [ ] CSP and security header defaults stated alongside override guidance.
- [ ] Troubleshooting section linked to relevant runbooks.
---
*Last updated: 2025-10-27 (Sprint 23).*

158
docs/operations/deployment/containers.md Normal file
View File

@@ -0,0 +1,158 @@
# Container Deployment Guide — AOC Update
> **Audience:** DevOps Guild, platform operators deploying StellaOps services.
> **Scope:** Deployment configuration changes required by the Aggregation-Only Contract (AOC), including schema validators, guard environment flags, and verifier identities.
This guide supplements existing deployment manuals with AOC-specific configuration. It assumes familiarity with the base Compose/Helm manifests described in `ops/deployment/` and `docs/modules/devops/architecture.md`.
---
## 1 · Schema constraint enablement
### 1.1 PostgreSQL constraints
- Apply CHECK constraints and NOT NULL rules to `advisory_raw` and `vex_raw` tables before enabling AOC guards.
- Before enabling constraints or the idempotency index, run the duplicate audit helper to confirm no conflicting raw advisories remain:
```bash
psql -d concelier -f ops/devops/scripts/check-advisory-raw-duplicates.sql -v LIMIT=200
```
Resolve any reported rows prior to rollout.
- Use the migration script provided in `ops/devops/scripts/apply-aoc-constraints.sql`:
```bash
kubectl exec -n concelier deploy/concelier-postgres -- \
psql -d concelier -f ops/devops/scripts/apply-aoc-constraints.sql
kubectl exec -n excititor deploy/excititor-postgres -- \
psql -d excititor -f ops/devops/scripts/apply-aoc-constraints.sql
```
- Constraints enforce required fields (`tenant`, `source`, `upstream`, `linkset`) and reject forbidden keys at DB level.
- Rollback plan: constraints can be dropped via the same script with `--remove` if required.
### 1.2 Migration order
1. Deploy constraints in maintenance window.
2. Roll out Concelier/Excititor images with guard middleware enabled (`AOC_GUARD_ENABLED=true`).
3. Run smoke tests (`stella sources ingest --dry-run` fixtures) before resuming production ingestion.
### 1.3 Supersedes backfill verification
1. **Duplicate audit:** Confirm `psql -d concelier -f ops/devops/scripts/check-advisory-raw-duplicates.sql -v LIMIT=200` reports no conflicts before restarting Concelier with the new migrations.
2. **Post-migration check:** After the service restarts, validate that the `advisory` view points to `advisory_backup_20251028`:
```bash
psql -d concelier -c "SELECT viewname, definition FROM pg_views WHERE viewname = 'advisory';"
```
The definition should reference `advisory_backup_20251028`.
3. **Supersedes chain spot-check:** Inspect a sample set to ensure deterministic chaining:
```bash
psql -d concelier -c "
SELECT id, supersedes FROM advisory_raw
WHERE upstream_id IS NOT NULL
ORDER BY tenant, source_vendor, upstream_id, retrieved_at
LIMIT 5;"
```
Each revision should reference the previous `id` (or `null` for the first revision). Record findings in the change ticket before proceeding to production.
---
## 2 · Container environment flags
Add the following environment variables to Concelier/Excititor deployments:
| Variable | Default | Description |
|----------|---------|-------------|
| `AOC_GUARD_ENABLED` | `true` | Enables `AOCWriteGuard` interception. Set `false` only for controlled rollback. |
| `AOC_ALLOW_SUPERSEDES_RETROFIT` | `false` | Allows temporary supersedes backfill during migration. Remove after cutover. |
| `AOC_METRICS_ENABLED` | `true` | Emits `ingestion_write_total`, `aoc_violation_total`, etc. |
| `AOC_TENANT_HEADER` | `X-Stella-Tenant` | Header name expected from Gateway. |
| `AOC_VERIFIER_USER` | `stella-aoc-verify` | Read-only service user used by UI/CLI verification. |
Compose snippet:
```yaml
environment:
- AOC_GUARD_ENABLED=true
- AOC_ALLOW_SUPERSEDES_RETROFIT=false
- AOC_METRICS_ENABLED=true
- AOC_TENANT_HEADER=X-Stella-Tenant
- AOC_VERIFIER_USER=stella-aoc-verify
```
Ensure `AOC_VERIFIER_USER` exists in Authority with `aoc:verify` scope and no write permissions.
---
## 3 · Verifier identity
- Create a dedicated client (`stella-aoc-verify`) via Authority bootstrap:
```yaml
clients:
- clientId: stella-aoc-verify
grantTypes: [client_credentials]
scopes: [aoc:verify, advisory:read, vex:read]
tenants: [default]
```
- Store credentials in secret store (`Kubernetes Secret`, `Docker swarm secret`).
- Bind credentials to `stella aoc verify` CI jobs and Console verification service.
- Rotate quarterly; document in `ops/authority-key-rotation.md`.
---
## 4 · Deployment steps
1. **Pre-checks:** Confirm database backups, alerting in maintenance mode, and staging environment validated.
2. **Apply validators:** Run scripts per § 1.1.
3. **Update manifests:** Inject environment variables (§ 2) and mount guard configuration configmaps.
4. **Redeploy services:** Rolling restart Concelier/Excititor pods. Monitor `ingestion_write_total` for steady throughput.
5. **Seed verifier:** Deploy read-only verifier user and store credentials.
6. **Run verification:** Execute `stella aoc verify --since 24h` and ensure exit code `0`.
7. **Update dashboards:** Point Grafana panels to new metrics (`aoc_violation_total`).
8. **Record handoff:** Capture console screenshots and verification logs for release notes.
---
## 5 · Offline Kit updates
- Ship validator scripts with Offline Kit (`offline-kit/scripts/apply-aoc-validators.js`).
- Include pre-generated verification reports for air-gapped deployments.
- Document offline CLI workflow in bundle README referencing `docs/modules/cli/guides/cli-reference.md`.
- Ensure `stella-aoc-verify` credentials are scoped to offline tenant and rotated during bundle refresh.
---
## 6 · Rollback plan
1. Disable guard via `AOC_GUARD_ENABLED=false` on Concelier/Excititor and rollout.
2. Remove validators with the migration script (`--remove`).
3. Pause verification jobs to prevent noise.
4. Investigate and remediate upstream issues before re-enabling guards.
---
## 7 · References
- [Aggregation-Only Contract reference](../aoc/aggregation-only-contract.md)
- [Authority scopes & tenancy](../security/authority-scopes.md)
- [Observability guide](../observability/observability.md)
- [CLI AOC commands](../modules/cli/guides/cli-reference.md)
- [Concelier architecture](../modules/concelier/architecture.md)
- [Excititor architecture](../modules/excititor/architecture.md)
---
## 8 · Compliance checklist
- [ ] Validators documented and scripts referenced for online/offline deployments.
- [ ] Environment variables cover guard enablement, metrics, and tenant header.
- [ ] Read-only verifier user installation steps included.
- [ ] Offline kit instructions align with validator/verification workflow.
- [ ] Rollback procedure captured.
- [ ] Cross-links to AOC docs, Authority scopes, and observability guides present.
- [ ] DevOps Guild sign-off tracked (owner: @devops-guild, due 2025-10-29).
---
*Last updated: 2025-10-26 (Sprint 19).*

212
docs/operations/deployment/docker.md Normal file
View File

@@ -0,0 +1,212 @@
# StellaOps Console — Docker Install Recipes
> **Audience:** Deployment Guild, Console Guild, platform operators.
> **Scope:** Acquire the `stellaops/web-ui` image, run it with Compose or Helm, mirror it for air‑gapped environments, and keep parity with CLI workflows.
This guide focuses on the new **StellaOps Console** container. Start with the general [Installation Guide](../INSTALL_GUIDE.md) for shared prerequisites (Docker, registry access, TLS) and use the steps below to layer in the console.
---
## 1 · Release artefacts
| Artefact | Source | Verification |
|----------|--------|--------------|
| Console image | `registry.stella-ops.org/stellaops/web-ui@sha256:<digest>` | Listed in `deploy/releases/<channel>.yaml` (`yq '.services[] | select(.name=="web-ui") | .image'`). Signed with Cosign (`cosign verify --key https://stella-ops.org/keys/cosign.pub …`). |
| Compose bundles | `deploy/compose/docker-compose.{dev,stage,prod,airgap}.yaml` | Each profile already includes a `web-ui` service pinned to the release digest. Run `docker compose --env-file <env> -f docker-compose.<profile>.yaml config` to confirm the digest matches the manifest. |
| Helm values | `deploy/helm/stellaops/values-*.yaml` (`services.web-ui`) | CI lints the chart; use `helm template` to confirm the rendered Deployment/Service carry the expected digest and env vars. |
| Offline artefact (preview) | Generated via `oras copy registry.stella-ops.org/stellaops/web-ui@sha256:<digest> oci-archive:stellaops-web-ui-<channel>.tar` | Record SHA-256 in the downloads manifest (`DOWNLOADS-CONSOLE-23-001`) and sign with Cosign before shipping in the Offline Kit. |
> **Tip:** Keep Compose/Helm digests in sync with the release manifest to preserve determinism. `deploy/tools/validate-profiles.sh` performs a quick cross-check.
---
## 2 · Compose quickstart (connected host)
1. **Prepare workspace**
```bash
mkdir stella-console && cd stella-console
cp /path/to/repo/deploy/compose/env/dev.env.example .env
```
2. **Add console configuration** – append the following to `.env` (adjust per environment):
```bash
CONSOLE_PUBLIC_BASE_URL=https://console.dev.stella-ops.local
CONSOLE_GATEWAY_BASE_URL=https://api.dev.stella-ops.local
AUTHORITY_ISSUER=https://authority.dev.stella-ops.local
AUTHORITY_CLIENT_ID=console-ui
AUTHORITY_SCOPES="ui.read ui.admin findings:read advisory:read vex:read aoc:verify"
AUTHORITY_DPOP_ENABLED=true
```
Optional extras from [`docs/deploy/console.md`](../deploy/console.md):
```bash
CONSOLE_FEATURE_FLAGS=runs,downloads,policies
CONSOLE_METRICS_ENABLED=true
CONSOLE_LOG_LEVEL=Information
```
3. **Verify bundle provenance**
```bash
cosign verify-blob \
--key https://stella-ops.org/keys/cosign.pub \
--signature /path/to/repo/deploy/compose/docker-compose.dev.yaml.sig \
/path/to/repo/deploy/compose/docker-compose.dev.yaml
```
4. **Launch infrastructure + console**
```bash
docker compose --env-file .env -f /path/to/repo/deploy/compose/docker-compose.dev.yaml up -d postgres valkey rustfs
docker compose --env-file .env -f /path/to/repo/deploy/compose/docker-compose.dev.yaml up -d web-ui
```
The `web-ui` service exposes the console on port `8443` by default. Change the published port in the Compose file if you need to front it with an existing reverse proxy.
**Infrastructure notes:**
- **Postgres**: Primary database (v16+)
- **Valkey**: Redis-compatible cache for streams, queues, DPoP nonces
- **RustFS**: S3-compatible object store for SBOMs and artifacts
5. **Health check**
```bash
curl -k https://console.dev.stella-ops.local/health/ready
```
Expect `{"status":"Ready"}`. If the response is `401`, confirm Authority credentials and scopes.
---
## 3 · Helm deployment (cluster)
1. **Create an overlay** (example `console-values.yaml`):
```yaml
global:
release:
version: "2025.10.0-edge"
services:
web-ui:
image: registry.stella-ops.org/stellaops/web-ui@sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf
service:
port: 8443
env:
CONSOLE_PUBLIC_BASE_URL: "https://console.dev.stella-ops.local"
CONSOLE_GATEWAY_BASE_URL: "https://api.dev.stella-ops.local"
AUTHORITY_ISSUER: "https://authority.dev.stella-ops.local"
AUTHORITY_CLIENT_ID: "console-ui"
AUTHORITY_SCOPES: "ui.read ui.admin findings:read advisory:read vex:read aoc:verify"
AUTHORITY_DPOP_ENABLED: "true"
CONSOLE_FEATURE_FLAGS: "runs,downloads,policies"
CONSOLE_METRICS_ENABLED: "true"
```
2. **Render and validate**
```bash
helm template stella-console ./deploy/helm/stellaops -f console-values.yaml | \
grep -A2 'name: stellaops-web-ui' -A6 'image:'
```
3. **Deploy**
```bash
helm upgrade --install stella-console ./deploy/helm/stellaops \
-f deploy/helm/stellaops/values-dev.yaml \
-f console-values.yaml
```
4. **Post-deploy checks**
```bash
kubectl get pods -l app.kubernetes.io/name=stellaops-web-ui
kubectl port-forward deploy/stellaops-web-ui 8443:8443
curl -k https://localhost:8443/health/ready
```
---
## 4 · Offline packaging
1. **Mirror the image to an OCI archive**
```bash
DIGEST=$(yq '.services[] | select(.name=="web-ui") | .image' deploy/releases/2025.10-edge.yaml | cut -d@ -f2)
oras copy registry.stella-ops.org/stellaops/web-ui@${DIGEST} \
oci-archive:stellaops-web-ui-2025.10.0.tar
shasum -a 256 stellaops-web-ui-2025.10.0.tar
```
2. **Sign the archive**
```bash
cosign sign-blob --key ~/keys/offline-kit.cosign \
--output-signature stellaops-web-ui-2025.10.0.tar.sig \
stellaops-web-ui-2025.10.0.tar
```
3. **Load in the air-gap**
```bash
docker load --input stellaops-web-ui-2025.10.0.tar
docker tag stellaops/web-ui@${DIGEST} registry.airgap.local/stellaops/web-ui:2025.10.0
```
4. **Update the Offline Kit manifest** (once the downloads pipeline lands):
```bash
jq '.artifacts.console.webUi = {
"digest": "sha256:'"${DIGEST#sha256:}"'",
"archive": "stellaops-web-ui-2025.10.0.tar",
"signature": "stellaops-web-ui-2025.10.0.tar.sig"
}' downloads/manifest.json > downloads/manifest.json.tmp
mv downloads/manifest.json.tmp downloads/manifest.json
```
Re-run `stella offline kit import downloads/manifest.json` to validate signatures inside the air‑gapped environment.
---
## 5 · CLI parity
Console operations map directly to scriptable workflows:
| Action | CLI path |
|--------|----------|
| Fetch signed manifest entry | `stella downloads manifest show --artifact console/web-ui` *(CLI task `CONSOLE-DOC-23-502`, pending release)* |
| Mirror digest to OCI archive | `stella downloads mirror --artifact console/web-ui --to oci-archive:stellaops-web-ui.tar` *(planned alongside CLI AOC parity)* |
| Import offline kit | `stella offline kit import stellaops-web-ui-2025.10.0.tar` |
| Validate console health | `stella console status --endpoint https://console.dev.stella-ops.local` *(planned; fallback to `curl` as shown above)* |
Track progress for the CLI commands via `DOCS-CONSOLE-23-014` (CLI vs UI parity matrix).
---
## 6 · Compliance checklist
- [ ] Image digest validated against the current release manifest.
- [ ] Compose/Helm deployments verified with `docker compose config` / `helm template`.
- [ ] Authority issuer, scopes, and DPoP settings documented and applied.
- [ ] Offline archive mirrored, signed, and recorded in the downloads manifest.
- [ ] CLI parity notes linked to the upcoming `docs/cli-vs-ui-parity.md` matrix.
- [ ] References cross-checked with `docs/deploy/console.md` and `docs/security/console-security.md`.
- [ ] Health checks documented for connected and air-gapped installs.
---
## 7 · References
- `deploy/releases/<channel>.yaml` – Release manifest (digests, SBOM metadata).
- `deploy/compose/README.md` – Compose profile overview.
- `deploy/helm/stellaops/values-*.yaml` – Helm defaults per environment.
- `/docs/deploy/console.md` – Detailed environment variables, CSP, health checks.
- `/docs/security/console-security.md` – Auth flows, scopes, DPoP, monitoring.
- `docs/UI_GUIDE.md` – Console workflows and offline posture.
---
*Last updated: 2025-10-28 (Sprint 23).*