My search engine's public server put Caddy in front of everything to get Let's Encrypt certificates automatically. While setting it up, I used Let's Encrypt's staging service, to avoid burning the production rate limit on failed attempts, and switched to production by removing the setting from .env. Caddy then refused to start. The setting had a default in two places, and neither one applied, because "not set" and "set to nothing" are different things.
Two defaults, one empty string
The Caddyfile's global block chose the certificate authority from an environment variable, with a default:
acme_ca {$ACME_CA:https://acme-v02.api.letsencrypt.org/directory}
And the Docker Compose file passed the variable into the container:
- ACME_CA=${ACME_CA:-}
Both look like they say "use production unless told otherwise". They don't fit together.
Compose's documentation defines ${VAR:-default} as the value of VAR if it's set and non-empty, otherwise the default. Here the default was empty. So with ACME_CA removed from .env, Compose put ACME_CA= into the container's environment: a variable that exists, with an empty value.
Caddy's documentation is precise about its own defaults: the value after the colon is used when the environment variable is not found. An empty variable is found. And Caddy substitutes environment variables before it parses the Caddyfile, so they can expand to empty values. The line became acme_ca with no argument at all, and the directive requires one.
Reproduced
I ran the same global block through caddy adapt in Caddy 2.11 with the variable in three states:
- set to an empty string: "wrong argument count or unexpected line ending after 'acme_ca'", and no config
- not set at all: the Let's Encrypt production directory, from the Caddyfile's default
- set to the staging URL: the staging directory
So the Caddyfile's default was fine on its own. It could only work if the variable was absent from the container, and the Compose line made sure it never was.
The fix
The fix moved the real default into Compose, where it applies to both unset and empty values:
- ACME_CA=${ACME_CA:-https://acme-v02.api.letsencrypt.org/directory}
Now the container always gets a real URL: production by default, or whatever .env sets while testing against staging. A comment above the line explains why it must never default to empty, because the empty default looks harmless and was written that way for a reason that made sense at the time. The old comment said: "Optional: ACME directory URL. Unset -> Let's Encrypt production."
The general trap
Any time a value passes through two layers that each have a notion of "default", check what each layer does with an empty string. The common shapes:
- Compose's
${VAR:-x}treats empty as missing;${VAR-x}only treats unset as missing. - A
KEY=${VAR:-}line in a Composeenvironment:list always setsKEYin the container, empty or not. - Caddy's
{$VAR:x}usesxonly when the variable doesn't exist.
The simplest rule is to put the real default in exactly one place, the outermost layer that always runs, and make sure every layer after it receives a real value. "Optional" settings that are passed through as empty strings are where defaults go to die.
Leave a comment
Comments are reviewed before they appear.