Use Operations when Caracal is running as infrastructure: Docker Compose for self-hosted installs, Helm for Kubernetes, managed Postgres and Redis, production secrets, rollout gates, observability, incident handling, upgrades, and platform handoff.
flowchart LR
Operator[Operator or platform team] --> Runtime[Runtime surface]
Runtime --> Compose[Docker Compose]
Runtime --> Helm[Helm release]
Runtime --> Secrets[Runtime secrets]
Runtime --> Checks[Health, readiness, smoke tests]
Checks --> Services[Web, API, STS, Gateway, Audit, Coordinator]
Services --> Postgres[(PostgreSQL)]
Services --> Redis[(Redis Streams)]
| Environment | Recommended path | Notes |
|---|
| Local development | caracal up / infra/docker/docker-compose.yml | Builds local images, binds service ports to 127.0.0.1, writes local secrets, and serves the packaged web console at http://localhost:3001. |
| Self-hosted runtime | infra/docker/runtime-compose.yml | Uses versioned GHCR images, mounted secrets, and the caracal-web browser entrypoint. |
| Kubernetes | infra/helm/caracal | Uses Deployments/StatefulSets, pre-install/pre-upgrade migration Job, ClusterIP Services, web Ingress by default, optional API/Gateway Ingress, NetworkPolicy, PDBs, HPAs, ServiceMonitor, and PrometheusRule. |
- Postgres is the durable control-plane store.
- Redis Streams move audit, policy invalidation, session revocation, key invalidation, agent, invocation, and delegation events.
- STS and Gateway keep audit replay directories so audit emission can drain after Redis/Audit recovery.
- Published modes are
rc and stable; they require production-grade HMAC keys and reject unsafe fallbacks.
- Product-management operations happen through the web console, Admin SDK, or Control API; the top-level runtime CLI only manages local lifecycle, the development web launcher, and
caracal run.
