git.stella-ops.org/docs/install/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	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

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

   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:

   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/deploy/compose/docker-compose.dev.yaml.sig \
     /path/to/repo/deploy/compose/docker-compose.dev.yaml
   

4. Launch infrastructure + console

   docker compose --env-file .env -f /path/to/repo/deploy/compose/docker-compose.dev.yaml up -d mongo minio
   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.

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 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 ./deploy/helm/stellaops -f console-values.yaml | \
     grep -A2 'name: stellaops-web-ui' -A6 'image:'
   

3. Deploy

   helm upgrade --install stella-console ./deploy/helm/stellaops \
     -f deploy/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 · 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/downloads.md – Downloads manifest workflow and offline parity guidance.

---

Last updated: 2025-10-28 (Sprint 23).