Recipes — Config layout

Quick patterns for organizing config across files. For the full picture — where doze stores everything, what to commit vs ignore, and resetting state — see the Files & storage guide.

Split config across *.doze.hcl files

doze.hcl is the anchor (it holds root settings); every sibling *.doze.hcl file beside it is merged automatically, sorted and deterministic. Split by concern:

my-app/
  doze.hcl              # root settings (listen/defaults/tls) + variables/outputs
  databases.doze.hcl    # postgres / valkey / kvrocks
  aws.doze.hcl          # s3 / sqs / sns

doze.hcl

defaults { idle_timeout = "5m" }

postgres "app" {
  version = 16
  role "app" { password = "app" }
}

aws.doze.hcl

s3 "media" {
  bucket "uploads" {}
}
sqs "jobs" {
  queue "emails" {}
}

doze status     # shows app (doze.hcl) + media, jobs (aws.doze.hcl)
doze doctor     # validates the merged whole

Instance names must be unique across all files; root settings (listen, defaults, tls, …) belong only in doze.hcl. A plain *.hcl sibling is not merged — only *.doze.hcl — so unrelated HCL files in the folder are left alone. Errors are reported with the file, line, and a snippet.

Or merge every *.hcl in a directory:

doze --config ./config status

Per-developer overrides

Shared instances stay committed in doze.hcl (and friends); each developer adds personal ones in a gitignored local.doze.hcl:

# local.doze.hcl  (gitignored — yours alone)
postgres "scratch" {
  version = 17
  role "me" { password = "me" }
}

.gitignore

.doze/
local.doze.hcl

For tweaking values (not adding instances), a gitignored *.auto.doze.vars file overrides variables without touching the config.

Versions & TLS

These root-level concerns are covered in the reference:

• Versions & the lockfile — major vs exact, doze.lock, doze binaries available.
• TLS — auto self-signed or bring your own cert.