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](../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 | `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**

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

   ```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 orch:operate 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/devops/compose/docker-compose.dev.yaml.sig \
     /path/to/repo/devops/compose/docker-compose.dev.yaml
   ```

4. **Launch infrastructure + console**

   ```bash
   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**

   ```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 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**

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

3. **Deploy**

   ```bash
   helm upgrade --install stella-console ./devops/helm/stellaops \
     -f devops/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 - 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):

```bash
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).*