Provision with OpenTofu

caracalHost renders cloud-init; it does not create a VM. caracalStack creates a namespace, optionally a Secret, and a Helm release; it does not create a cluster, Postgres, Redis, ingress controller, or secret manager.

Prerequisites

Use OpenTofu >=1.8. Kubernetes also requires version >=1.30, kubeconfig access, external dependencies, and a complete runtime Secret.

Kubernetes Procedure

1. Copy the production tfvars example outside source control.
2. Pin chartVersion, set database and Redis hosts, and deliver caracal-runtime before apply.
3. Add reviewed chart overlays through extraValues.
4. Run:

cd infra/tofu/envs/production
tofu init
tofu plan -out caracal.plan
tofu apply caracal.plan

The module waits for Jobs and uses atomic Helm behavior by default. Remote state and locking are operator responsibilities; never put plaintext runtime secrets in variables or state.

VM Procedure

Attach caracalHost.userData or userDataBase64 to an operator-owned VM. It installs Docker when absent, installs a pinned release, writes non-secret overrides, and starts Caracal. Runtime secrets are generated on the host.

Verify and Recover

Run bash infra/tofu/scripts/validate.sh in a checkout. After apply, verify Jobs, readiness, and audit evidence; on a VM run caracal status --ready. Use Helm revision rollback only when schema-compatible. Restore VM data and secrets separately before rebuilding.

Next Step

Read Deploy with Helm or Deploy with Docker Compose.