git.stella-ops.org/docs/deploy/console.md

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 (pending) - CSP and Authority scopes.
• /docs/24_OFFLINE_KIT.md - Offline kit packaging and verification.
• /docs/ops/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).