Environment variables

Environment variables that change Caddy's behavior at startup. These complement (rather than replace) the JSON config — most knobs are still in the config document.

Variable	Effect	Where it's read
CADDY_ADMIN	Override the default admin endpoint listen address (DefaultAdminListen).	admin.go: init()
CADDY_DATA_DIR	Override the data directory (where storage and other persistent data live).	storage.go: DataDir
CADDY_CONFIG_DIR	Override the config directory.	storage.go: ConfigDir
XDG_DATA_HOME, XDG_CONFIG_HOME	Standard XDG fallbacks for the above on Linux.	storage.go
HOME (Unix), USERPROFILE (Windows)	Fallback for HomeDir() if XDG is unset.	storage.go: HomeDir
USERAGENT	Prefix for the User-Agent string Caddy sends to ACME endpoints. The version is appended automatically.	cmd/main.go: init()
GOFLAGS (build-time)	The default build excludes some optional code paths via nobadger, nomysql, nopgx build tags (set in CI's GOFLAGS).	.github/workflows/ci.yml

Replacer-accessible env vars

Inside any Caddy config field, you can reference any environment variable through the placeholder {env.NAME} (handled by replacer.go's globalDefaultReplacementProvider). This is the recommended way to pass secrets:

example.com {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
}

{env.NAME} is resolved at provision time, so reload-on-env-change requires a restart or a graceful reload triggered by SIGUSR1 / caddy reload.

Service / init integration

When Caddy runs under systemd, the following are set or honored automatically:

• INVOCATION_ID — used to detect that Caddy is being run by systemd.
• NOTIFY_SOCKET — notify/ package sends READY=1, RELOADING=1, STOPPING=1 notifications via this socket.
• JOURNAL_STREAM — checked when deciding whether stdout/stderr are already connected to the journal (affects log encoder defaults).

notify/ wraps these in a small package so the rest of the codebase doesn't need to import systemd-specific code.

Memory / CPU autotuning

cmd/main.go imports two libraries that read environment-style cgroup metadata at startup:

• automaxprocs — sets GOMAXPROCS from the cgroup CPU quota; honors GOMAXPROCS if set explicitly.
• automemlimit — sets GOMEMLIMIT from the cgroup memory limit; honors GOMEMLIMIT if set.

These are useful when running in containers that don't pass their resource limits through to the Go runtime by default.

Related pages

• Configuration
• Storage
• Replacer