git.stella-ops.org/docs/operations/deployment/docker.md

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 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[]
Compose bundles	devops/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	devops/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

   mkdir stella-console && cd stella-console
   cp /path/to/repo/devops/compose/env/dev.env.example .env
   

2. Add console configuration -- append the following to .env (adjust per environment):

   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 orch:operate findings:read advisory:read vex:read aoc:verify"
   AUTHORITY_DPOP_ENABLED=true
   

   Optional extras from docs/deploy/console.md:

   CONSOLE_FEATURE_FLAGS=runs,downloads,policies
   CONSOLE_METRICS_ENABLED=true
   CONSOLE_LOG_LEVEL=Information
   

3. Verify bundle provenance

   cosign verify-blob \
     --key https://stella-ops.org/keys/cosign.pub \
     --signature /path/to/repo/devops/compose/docker-compose.dev.yaml.sig \
     /path/to/repo/devops/compose/docker-compose.dev.yaml
   

4. Launch infrastructure + console

   docker compose --env-file .env -f /path/to/repo/devops/compose/docker-compose.dev.yaml up -d postgres valkey rustfs
   docker compose --env-file .env -f /path/to/repo/devops/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

   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):

   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 orch:operate 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

   helm template stella-console ./devops/helm/stellaops -f console-values.yaml | \
     grep -A2 'name: stellaops-web-ui' -A6 'image:'
   

3. Deploy

   helm upgrade --install stella-console ./devops/helm/stellaops \
     -f devops/helm/stellaops/values-dev.yaml \
     -f console-values.yaml
   

4. Post-deploy checks

   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

   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

   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

   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):

   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 - Mirror distribution configuration

The Excititor service (advisory VEX export engine) supports mirror distribution for syncing advisory data to downstream environments and air-gapped deployments. Mirror configuration is applied via environment variables or config file sections under Excititor:Mirror.

Environment variables

Variable	Default	Description
Excititor__Mirror__Enabled	true	Global enable flag for mirror distribution surfaces and bundle generation.
Excititor__Mirror__OutputRoot	(artifact store default)	Filesystem root where mirror artefacts are written.
Excititor__Mirror__DirectoryName	mirror	Subdirectory under OutputRoot for mirror artifacts.
Excititor__Mirror__TargetRepository	--	Human-readable hint for downstream mirrors (e.g., s3://mirror/excititor).
Excititor__Mirror__RefreshIntervalMinutes	60	How often the MirrorExportScheduler checks for stale bundles and regenerates them. Minimum 1 minute.
Excititor__Mirror__AutoRefreshEnabled	true	Set to false to disable the background scheduler. Required for air-gap deployments where bundles are imported rather than generated.
Excititor__Mirror__Signing__Enabled	false	Enable detached JWS signing for mirror bundle payloads.
Excititor__Mirror__Signing__Algorithm	ES256	Signing algorithm identifier.
Excititor__Mirror__Signing__KeyId	--	Signing key identifier resolved via the crypto provider registry. Required when signing is enabled.
Excititor__Mirror__Signing__Provider	--	Optional provider hint for key resolution.
Excititor__Mirror__Signing__KeyPath	--	Optional PEM file path for key seeding.

Domain configuration via env vars

Mirror domains can be configured through structured env vars (array indexing):

Excititor__Mirror__Domains__0__Id=primary
Excititor__Mirror__Domains__0__DisplayName=Primary Mirror
Excititor__Mirror__Domains__0__RequireAuthentication=false
Excititor__Mirror__Domains__0__MaxIndexRequestsPerHour=600
Excititor__Mirror__Domains__0__MaxDownloadRequestsPerHour=1200
Excititor__Mirror__Domains__0__Exports__0__Key=all-advisories
Excititor__Mirror__Domains__0__Exports__0__Format=json
Excititor__Mirror__Domains__0__Exports__0__Filters__sourceCategory=Distribution

Alternatively, domains can be managed through the Mirror Domain Management API (/api/v1/mirror/domains) or the Console UI wizard (Advisory & VEX Sources > Mirror). Database-configured domains take precedence over env-var domains when both define the same domain ID.

Filter shorthands for exports

Export filters support category and tag shorthands that resolve to source IDs at export time:

• sourceCategory=Distribution -- resolves to all distribution sources (Debian, Ubuntu, Alpine, etc.)
• sourceCategory=Exploit,Container,Ics -- comma-separated categories (OR semantics)
• sourceTag=linux -- resolves to all sources tagged linux
• sourceVendor=debian,ubuntu,alpine -- explicit comma-separated source IDs

See docs/modules/excititor/mirrors.md for the full mirror architecture documentation.

---

8 - References

• deploy/releases/<channel>.yaml -- Release manifest (digests, SBOM metadata).
• devops/compose/README.md -- Compose profile overview.
• devops/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.
• docs/modules/excititor/mirrors.md -- Mirror distribution architecture and configuration.
• docs/modules/concelier/connectors.md -- Full connector index (75 sources, 14 categories).

---

Last updated: 2026-03-15 (Sprint 007).