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

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:

helm install stellaops ./stellaops-<ver>.tgz --namespace stellaops --create-namespace

2.2 Base installation

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:

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:

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:

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/downloads.md - manifest and offline bundle guidance.
/docs/security/console-security.md - CSP and Authority scopes.
/docs/24_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).