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

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

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

### 2.2 Base installation

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

```yaml
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:

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

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