Configuration Order
Runtime Workload Config
Section titled “Runtime Workload Config”caracal run and SDK loaders use this order:
CARACAL_CONFIG, when set and the file exists.- Environment runtime config.
$XDG_CONFIG_HOME/caracal/caracal.toml.~/.config/caracal/caracal.toml.
The runtime does not read ./caracal.toml from the current working directory.
Environment Runtime Config Detection
Section titled “Environment Runtime Config Detection”Environment config is considered when workload identity variables are present.
Local dev and stable launches use CARACAL_ZONE_ID and
CARACAL_APPLICATION_ID, then auto-detect credential files from the OS Caracal
config directory. Cloud and custom deployments can provide explicit
CARACAL_APP_CLIENT_SECRET_FILE, CARACAL_RUN_CREDENTIALS,
CARACAL_RUN_CREDENTIALS_FILE, or CARACAL_RESOURCES_FILE values when mounted
secret or config paths differ from the local convention.
Set only one of CARACAL_RUN_CREDENTIALS and CARACAL_RUN_CREDENTIALS_FILE.
Resource bindings resolve from profile credentials, then
CARACAL_RESOURCES_FILE, then CARACAL_RESOURCES. Later bindings with the
same resource ID override earlier bindings, so a short environment override can
replace one entry from a mounted JSON file without duplicating the file.
File-Secret Resolution
Section titled “File-Secret Resolution”Services support *_FILE variants for configured secret keys. File values are resolved before validation so deployment templates can mount secrets instead of placing sensitive material directly in environment variables.
Deployment Values
Section titled “Deployment Values”| Deployment path | Precedence model |
|---|---|
| Docker Compose | Shell environment overrides defaults in compose files; secrets are mounted from files. |
| Helm | CLI --set and later values files override earlier chart values; runtime Secret keys feed mounted service env. |
| Console generated profile | Explicit values from guided setup write a profile and secret file when file writing is enabled. |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| Expected profile is ignored | CARACAL_CONFIG may point elsewhere or environment runtime config may be winning. |
| Service fails with missing secret | Confirm the *_FILE variable name is supported by that service and the file is readable. |
| Helm values render unexpected defaults | Check values file order and CLI overrides. |
Next Step
Section titled “Next Step”Use Defaults and Limits to confirm ports, TTLs, request limits, and stream defaults.