Operate Caracal

Use this section when you own a Caracal deployment. These runbooks describe behavior present in this repository; they do not promise an availability level, managed service, or compliance outcome.

Choose a Runbook

The runbooks follow the deployment lifecycle. Work down the phases for a new deployment; jump straight to a phase for day-to-day operations.

Deploy - pick a substrate and stand the stack up:

Need	Runbook
Choose a substrate	Choose a Deployment Profile
Review measured performance, sizing, and failure results	Performance and Scalability
Run one Docker host	Deploy with Docker Compose
Deploy the repository chart	Deploy with Helm
Provision chart or VM bootstrap declaratively	Provision with OpenTofu
Map managed cloud services to the chart	Choose a Cloud Profile and Deploy on Managed Kubernetes
Hand a reviewed deployment package to another team	Package an Install Kit

Configure and secure - before real credentials or traffic:

Need	Runbook
Set service variables and secrets	Configure Service Environment
Choose where sealed credentials are stored	Configure Secret Backends
Pass the pre-production hardening checklist	Harden Production
Rotate keys, HMACs, and service tokens	Rotate Keys and Secrets
Operate the durable stores	Operate PostgreSQL and Operate Redis Streams
Size and scale services	Scale Capacity

Observe - know the deployment is healthy before users tell you it is not:

Need	Runbook
Wire health, readiness, and metrics	Monitor Health and Metrics
Alert on measured thresholds	Configure Alerts
Diagnose a failed request	Troubleshoot by Symptom
Diagnose unhealthy infrastructure	Debug Infrastructure Issues

Recover - when something is wrong or before it can be:

Need	Runbook
Recover a known failure	Recover from Failures
Prove recovery works before you need it	Run Failure Drills
Back up or restore Compose state	Back Up and Retain Data
Handle a security or availability incident	Respond to Incidents

Change - roll out versions, policy, and responsibility:

Need	Runbook
Change versions	Upgrade Caracal
Roll out infrastructure changes	Plan a Platform Rollout
Activate policy changes safely	Deploy Policy Changes
Export audit evidence for compliance tooling	Export Audit Evidence
Transfer operational ownership	Hand Off to Platform Teams

Operating Invariants

• Postgres is the durable system of record. Redis carries streams and correctness-critical revocation state.
• dev is local-development posture. rc and stable enforce published-mode configuration; rc is not a production stability claim.
• Compose publishes service ports on loopback. Expose them only through an operator-owned TLS proxy.
• Helm and OpenTofu are deployment assets, not a managed Kubernetes, HA, backup, or SLO service.
• Runtime lifecycle belongs to caracal up, down, status, upgrade, and purge. Product administration belongs to the web console, Admin SDK, or Control API.

Baseline Verification

For Compose, run caracal status --ready. For Kubernetes, inspect Jobs and pod readiness, then test required service endpoints. /health proves liveness; only /ready is a traffic gate.

Recovery Boundary

Before a risky change, retain the current version, configuration, data backup, and secrets backup. Database migrations are forward-only; application rollback is safe only when the older version accepts the migrated schema.

Next Step

Choose the substrate in Choose a Deployment Profile.