Caddy Best Practices for Production
Most Caddy configurations that work on a laptop are still fine in production, and the ones that are not usually fail for the same handful of reasons: the configuration is one enormous file nobody dares to edit, secrets are pasted into it, routing is decided by whichever directive happened to be written first, and changing anything means restarting the server. None of these are limitations of Caddy. They are habits. By the end of this page you will have a production configuration that is organised, reversible, secret-free, and safe to change while traffic is flowing.
Four properties separate a configuration that works in production from one that merely works.
It is readable by someone who did not write it. Names carry meaning, blocks are small, and the structure of the file mirrors the structure of the service.
It can be changed without downtime. A change is validated, then applied to the running process, and the old configuration stays alive until in-flight requests finish.
It does not contain secrets. Credentials live in environment variables or in a secret store, never in a file that is committed to a repository.
It fails loudly and recovers quietly. Errors are visible in the logs, and the failure of one upstream does not become the failure of the whole site.
Caddy can import other files, and the import path may contain glob patterns. A common production layout keeps one file per concern and one file that pulls them together.
# /etc/caddy/Caddyfile
{
email admin@example.com
}
import /etc/caddy/sites/*.caddy
import /etc/caddy/snippets/*.caddy
The path in an import is always relative to the file that contains the import line, and it may point at a directory as well as a single file. Splitting the configuration this way means a change to one site never requires editing a file that also contains twenty other sites, and it makes code review meaningful.
Two rules keep this from turning into a mess. Every file must be independently parseable, because the adapter reads the result as one document. And there must be exactly one place that decides global options, because global options are a property of the process, not of a site.
The global options block sets process-wide behaviour: the ACME contact address, the admin endpoint, the log configuration, the storage backend, the default bind address, the grace period.
{
email admin@example.com
admin localhost:2019
storage file_system {
root /var/lib/caddy/storage
}
default_bind 127.0.0.1
}
A few of these are worth understanding before you rely on them.
email is the contact address used for ACME. Setting it is what allows the CA to warn you before a certificate expires.
storage chooses where certificates and the saved configuration live. The default is a filesystem storage under the data directory of the process user. Making it explicit is worthwhile when the data directory is mounted from elsewhere or when the server is containerised.
default_bind changes the address that site blocks bind to when they do not specify one. Binding to 127.0.0.1 is the correct choice for a server that sits behind a load balancer or a cloud ingress; it is a mistake to leave 0.0.0.0 in place for a service that should never be directly reachable.
grace_period bounds how long the server waits for in-flight requests when a configuration is replaced. The default is effectively unlimited, which is correct for a graceful shutdown but means a stuck client can hold a reload open indefinitely.
{
grace_period 30s
shutdown_delay 5s
}
shutdown_delay delays the start of the grace period by a fixed duration, during which the server keeps serving normally. It exists so that a load balancer can be told the server is going away before it stops accepting work.
A snippet is a named block of directives. It is the correct unit of reuse inside one file, and it is much better than copy-pasting the same four lines into forty site blocks.
(common_headers) {
header {
X-Content-Type-Options nosniff
Referrer-Policy strict-origin-when-cross-origin
-Server
}
}
(compression) {
encode zstd gzip
}
example.com {
import common_headers
import compression
root * /srv/www
file_server
}
Name snippets after what they do, not after where they are used. common_headers survives a refactor; site_two_headers does not. A snippet can also take arguments, which turns it into a small template.
(redirect_to_https) {
@not_https {
not protocol https
}
redir @not_https https://{host}{uri} permanent
}
Caddy substitutes environment variables into the configuration at parse time with the {$NAME} syntax. The value is resolved once, when the configuration is loaded, and the result becomes part of the running JSON.
reverse_proxy api.internal:8443 {
header_up Authorization "Bearer {$API_TOKEN}"
}
The values come from the process environment or from a file loaded at startup.
caddy run --config /etc/caddy/Caddyfile --envfile /etc/caddy/env
The env file uses KEY=VALUE lines, supports comments beginning with #, allows an export prefix, and accepts double-quoted values.
# /etc/caddy/env
API_TOKEN=eyJhbGciOi...
Two cautions follow from the substitution being at parse time. First, the substituted value is visible in GET /config/ on the admin endpoint, so the endpoint must stay on the loopback interface or on a unix socket. Second, a secret in an environment variable is still a secret in a file on disk, so the env file needs the same permissions as the configuration file and should be owned by the service account rather than by a human being.
For credentials that must not be visible in the running configuration at all, put them behind a forward-auth service instead of a header, or use a module that reads them from a secret manager.
The Caddyfile adapter sorts directives into a canonical order, which means the order you write them in is often not the order they run in. When a configuration depends on order, say so explicitly.
Use handle when exactly one of several rules should win. The blocks are mutually exclusive and are evaluated in the order written.
example.com {
handle /api/* {
reverse_proxy localhost:9000
}
handle {
root * /srv/www
file_server
}
}
Use handle_path when the upstream should not see the matched prefix. It strips the prefix before the inner handlers run, which is why /api/orders arrives upstream as /orders.
Use route when several handlers must all apply, or when one must run before another.
example.com {
route {
header X-Request-Id "{http.request.uuid}"
reverse_proxy localhost:9000
}
}
Name the conditions. A named matcher can be referenced by any directive, which keeps the routing rules readable and lets the same condition drive several handlers.
example.com {
@api {
path /api/*
method GET POST
}
@health {
path /healthz
}
handle @health {
respond "ok" 200
}
handle @api {
reverse_proxy localhost:9000
}
}
The reverse_proxy directive has good defaults, but the defaults are not what most production setups want.
Pick a load balancing policy deliberately. The default is random, and retries are disabled by default. With several upstreams and no health checks, a request that lands on a dead upstream simply fails.
reverse_proxy backend-1:8080 backend-2:8080 {
lb_policy round_robin
lb_try_duration 5s
lb_retries 3
lb_try_interval 250ms
}
lb_try_duration is the window during which a failing request may be retried against another upstream. It must be longer than the time the upstream needs to restart, or the retry never helps.
Turn on active health checks. This is what makes failover real.
reverse_proxy backend-1:8080 backend-2:8080 {
lb_policy first
health_uri /healthz
health_interval 10s
health_timeout 5s
health_passes 2
health_fails 2
}
With lb_policy first, traffic goes to the first upstream in the list until it fails its health check, at which point the next one takes over. This is the primary and secondary pattern, and it only works if health checks are enabled.
Add passive health checks as a backstop. Active checks detect a dead backend on a timer. Passive checks notice a backend returning errors right now.
reverse_proxy backend-1:8080 {
fail_duration 30s
max_fails 3
unhealthy_status 500
unhealthy_latency 10s
}
Set the Host header when the upstream expects it. Most applications validate the Host header and reject a request whose Host is the public domain if they were deployed for a different name.
reverse_proxy backend-1:8080 {
header_up Host {http.reverse_proxy.upstream.hostport}
}
Bound the round trip. A transport with no timeouts will hold a connection open indefinitely when the upstream stops responding.
reverse_proxy backend-1:8080 {
transport http {
read_timeout 30s
write_timeout 30s
}
}
A small set of headers should be present on every response. Expressing them once as a snippet and importing it everywhere is the practical way to guarantee that.
(security_headers) {
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options nosniff
X-Frame-Options SAMEORIGIN
Referrer-Policy strict-origin-when-cross-origin
-Server
}
}
The -Server form removes a header rather than setting it, which is worth doing because the default Server header advertises the software and its version to anyone who asks.
Compression is enabled with encode. With no format named, zstd and gzip are both enabled and the client picks.
example.com {
encode zstd gzip
root * /srv/www
file_server
}
Two refinements matter in production. The encode directive only compresses responses above minimum_length, which defaults to 512 bytes, so small responses are not worth compressing. And the default match block restricts compression to content types that benefit from it; a JSON API benefits, a JPEG does not.
For static assets, serving precompressed files is faster than compressing on every request.
example.com {
root * /srv/www
file_server {
precompressed zstd br gzip
}
}
This is the habit that matters most in production. Stopping and starting the server to apply a configuration change causes downtime for no good reason.
caddy validate --config /etc/caddy/Caddyfile
caddy reload --config /etc/caddy/Caddyfile
caddy reload sends the new configuration to the running process through the admin API. The new configuration is provisioned first, and if it fails, the old one stays in place. Requests that are already in flight finish on the old configuration. There is no window in which the server is not serving.
Note the ordering: validate first, because validate provisions the modules without starting them and therefore catches errors that only appear at provision time, such as a certificate file that does not exist.
For the systemd unit, wire this up so that a restart of the service reloads rather than restarts.
[Service]
Type=notify
User=caddy
ExecStart=/usr/local/bin/caddy run --config /etc/caddy/Caddyfile
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile --force
Restart=on-failure
Caddy is a foreground process. It expects something else to keep it alive, and it expects that supervisor to send it the right signals.
[Unit]
Description=Caddy
After=network-online.target
Wants=network-online.target
[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/local/bin/caddy run --config /etc/caddy/Caddyfile
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile --force
Restart=on-failure
RestartSec=5s
LimitNOFILE=1048576
[Install]
WantedBy=multi.target
Type=notify matters: Caddy tells systemd when it has finished starting, so systemd reports the unit as active only once the listeners really accept connections. LimitNOFILE matters because a proxy under load holds a file descriptor per connection, and the default limit of 1024 is reached quickly.
Run the process as an unprivileged user. Caddy needs to bind ports 80 and 443 for Automatic HTTPS, which on most systems is arranged with capabilities rather than with root.
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/caddy
| Area | Check |
|---|---|
| Global options | ACME email set, admin endpoint on loopback or a unix socket, storage explicit |
| Files | One entry point, one file per site, secrets in a separate env file with tight permissions |
| Routing | Named matchers, route wherever order matters, handle_path used knowingly |
| Proxy | Load balancing policy chosen, health checks enabled, transport timeouts set |
| Headers | Security headers applied site-wide, Server header removed |
| Compression | encode with explicit formats, precompressed for static assets |
| Deployment | validate before reload, systemd unit with Type=notify, unprivileged user |
| Observability | Access logs to a file with rotation, metrics enabled, dashboards and alerts defined |
| Mistake | Why it hurts | Correction |
|---|---|---|
| Editing the Caddyfile on a running server | The change never reaches the process | caddy reload after caddy validate |
| Restarting the service to apply a change | Causes downtime for a change that does not need it | Use reload, and wire ExecReload in the unit |
| Secrets in the Caddyfile | The file is usually copied around, backed up, and committed | {$VAR} with a protected env file |
| Relying on file order for handler order | The adapter sorts directives | Use route or handle |
| No health checks on a pooled upstream | Failures reach the user instead of another backend | health_uri plus lb_try_duration |
| Admin endpoint on a public address | Anyone who reaches it owns the server | Keep it on loopback or a unix socket |
Approach:
The task is to turn a working but fragile single-site configuration into something a team can operate: the file must be safe to edit, the secrets must not live in it, the proxy must survive a backend restart, and applying a change must not take the site down. Each of those is a separate concern with a separate mechanism, so the work is broken into four independent fixes rather than one rewrite.
Steps:
- Move the settings that belong to the process rather than to a site into a single global options block at the top of the entry point file, and split the remaining configuration into one file per site imported by that entry point.
- Replace every copy-pasted block of response headers with a named snippet, and import the snippet into each site block so that a future change is made in one place.
- Move each credential out of the configuration and into an environment file, referenced through the
{$NAME}substitution syntax, with the env file owned by the service account and readable only by it. - Make the routing explicit by naming the matchers, and by using
routefor the one case where two handlers must run in a defined order. - Configure the proxy so that a dead backend is not a user-visible error: choose a load balancing policy, enable active health checks against a real endpoint, add a retry window longer than the time the backend needs to restart, and set transport timeouts.
- Validate the result before it is applied, with
caddy validate, which provisions the modules without starting the server and therefore catches errors that only appear at provision time. - Apply it without downtime, with
caddy reload, which provisions the new configuration first and rolls back to the old one if anything fails. - Confirm the outcome from the running process rather than from the file, by reading the effective configuration through the admin API and by making a real request to each site.
Answer:
The finished configuration looks like this.
{
email admin@example.com
admin localhost:2019
storage file_system {
root /var/lib/caddy/storage
}
}
(security_headers) {
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options nosniff
X-Frame-Options SAMEORIGIN
-Server
}
}
(health) {
respond "ok" 200
}
import /etc/caddy/sites/*.caddyAnd one site file looks like this.
example.com {
import security_headers
encode zstd gzip
@health path /healthz
handle @health {
import health
}
@api path /api/*
handle @api {
reverse_proxy backend-1:8080 backend-2:8080 {
lb_policy round_robin
lb_try_duration 5s
lb_retries 3
health_uri /healthz
health_interval 10s
health_timeout 5s
transport http {
read_timeout 30s
write_timeout 30s
}
}
}
handle {
root * /srv/www
file_server
}
}The deployment is then two commands, with no restart and therefore no downtime.
caddy validate --config /etc/caddy/Caddyfile
caddy reload --config /etc/caddy/CaddyfileThe result is a configuration that a colleague can read, edit, and deploy safely: the secrets are not in it, the backend can be restarted without users seeing errors, and every change is reversible because the previous configuration stays live until the new one has been proven.
