Deploying Caddy with Docker
Containers solve a real problem for a web server: they make the runtime reproducible. But Caddy has two pieces of state that must survive a container being replaced, namely the issued certificates and the ACME account, and both live in the image’s data directory. Get the volumes wrong and the server silently requests a new certificate on every deploy, which is slow at best and rate-limited at worst. By the end of this page you will be able to run Caddy in a container with persistent state, compose it with an application and a database, route traffic to services by name, and diagnose the failure modes that are specific to running a TLS-terminating proxy in Docker.
The Caddy project publishes images on Docker Hub. The tags follow the release stream.
docker pull caddy:2
docker pull caddy:2-alpine
docker pull caddy:2-builder
The caddy:2 tag is the default image, caddy:2-alpine is the same server on the smaller Alpine base, and caddy:2-builder is the toolchain image used to build a custom binary with plugins. The image already contains the standard module set, and the entrypoint starts Caddy with the Caddyfile at /etc/caddy/Caddyfile.
docker run --rm caddy:2 caddy version
docker run --rm caddy:2 caddy list-modules
The image uses two directories for state.
/dataholds the certificates, private keys, and the ACME account./configholds the runtime configuration, including the autosaved configuration and the generated assets.
Both must be volumes. Without a volume for /data, every restart produces a brand new account and a brand new certificate.
docker volume create caddy-data
docker volume create caddy-config
docker run -d \
--name caddy \
--restart unless-stopped \
-p 80:80 \
-p 443:443 \
-p 443:443/udp \
-v caddy-data:/data \
-v caddy-config:/config \
-v /srv/caddy/Caddyfile:/etc/caddy/Caddyfile:ro \
caddy:2-alpine
Three details in that command are easy to get wrong:
- Port 443 is published twice. The TCP mapping serves HTTP/2 and HTTP/1.1 over TLS. The UDP mapping serves HTTP/3 over QUIC. Without the UDP mapping, HTTP/3 silently does not work, and some clients will try and then fall back.
- The Caddyfile is mounted read-only. Caddy never needs to write to it, and a read-only mount makes an accidental overwrite impossible.
--restart unless-stoppedbrings the server back after a crash and after the host reboots.
The Caddyfile can also be baked into a custom image instead of being mounted, which is a better fit for a deployment pipeline.
A realistic deployment has Caddy in front of an application and a database. Compose describes all three.
services:
caddy:
image: caddy:2-alpine
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- caddy-data:/data
- caddy-config:/config
- ./Caddyfile:/etc/caddy/Caddyfile:ro
depends_on:
app:
condition: service_healthy
networks:
- edge
- backend
app:
image: example/app:1.4.2
restart: unless-stopped
environment:
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/healthz"]
interval: 15s
timeout: 5s
retries: 5
networks:
- backend
db:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_DB: app
POSTGRES_USER: app
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d app"]
interval: 15s
timeout: 5s
retries: 5
networks:
- backend
volumes:
caddy-data:
caddy-config:
db-data:
networks:
edge:
backend:
Two networks are used on purpose. The backend network is not attached to the host-facing side, so the database is reachable from the application but not from anything outside the Compose project. The edge network is where the published ports live.
The condition: service_healthy form of depends_on makes Compose wait for a container to report healthy before starting the one that depends on it, which removes the startup race that otherwise produces a container that crashes once and then works.
Inside a Compose project, the embedded DNS resolver resolves a service name to the container address, so the Caddyfile refers to the service name directly.
app.example.com {
reverse_proxy app:3000
}
The service name and its port are the upstream address. Because the name resolves to whichever container currently holds it, a scaled service is load balanced by Compose, and Caddy adds health checks on top of that if you configure them.
For a container that is not on the same network, use its address on the shared network rather than localhost, because localhost inside the container is the container itself.
The Caddyfile is plain text, so anything in it is visible to anyone who can read the file. Compose interpolates environment variables from a .env file next to the compose file, and the Caddyfile can consume them.
DB_PASSWORD=change-me
app.example.com {
reverse_proxy app:3000 {
header_up X-App-Token {env.APP_TOKEN}
}
}
Remember that a reverse_proxy to a service over plain HTTP inside a Docker network is normally acceptable, because the traffic never leaves the host. If it must leave the host, terminate TLS on the application as well.
A container health check tells Compose and the orchestrator whether the process inside is actually working. The Alpine-based image includes busybox, so wget is available without adding anything.
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:2019/config/"]
interval: 30s
timeout: 5s
retries: 3
The admin API on port 2019 answers with the running configuration, which proves that Caddy is up and serving, not merely that the process exists.
When you need a DNS provider or another third-party module, build the binary with xcaddy and copy it into a slim image.
FROM caddy:2-builder AS builder
RUN xcaddy build --with github.com/caddy-dns/cloudflare
FROM caddy:2-alpine
COPY --from=builder /usr/bin/caddy /usr/bin/caddy
docker build -t example/caddy:1.0.0 .
docker run --rm example/caddy:1.0.0 caddy list-modules
| Symptom | Cause | Fix |
|---|---|---|
| A new certificate is issued on every restart | /data is not a volume | Mount a volume at /data |
bind: address already in use | Another process holds port 80 or 443 | Stop it, or publish a different host port |
| The site works over HTTP but not HTTPS | The UDP mapping for HTTP/3 is missing, or 443 is blocked | Publish 443:443/udp |
reverse_proxy cannot reach the app | The service is on a different network, or the name is wrong | Put both on a shared network |
| ACME challenge fails | The domain does not point at the host | Point the record at the public IP of the Docker host |
Approach:
The deployment has three containers: Caddy, the application, and PostgreSQL. Caddy must be the only container exposed to the outside world, the application and the database must be reachable only from inside the project, and the certificates must survive every redeploy. That means two networks, three volumes, and health checks that let Compose order the startup instead of guessing.
Steps:
- Create a Compose file with three services and two networks. Put the database and the application on the
backendnetwork, and give thebackendnetwork no route to the host, so the database is not reachable from outside the project. - Attach Caddy to both networks. The
edgenetwork is what the published ports belong to, and thebackendnetwork is how Caddy reaches the application. - Declare a named volume for
/dataand a named volume for/config. The/datavolume is the one that matters: without it every container replacement means a new ACME account and a new certificate. - Publish port 80, port 443 over TCP, and port 443 over UDP. The UDP mapping is what makes HTTP/3 work; browsers that cannot use QUIC fall back to TCP on their own.
- Give the application and the database health checks, and use
depends_onwithcondition: service_healthyso that Caddy starts only after the application is genuinely able to serve, rather than merely started. - Point the Caddyfile at the application by service name, because the embedded DNS resolver maps the service name to the container address on the shared network.
- Keep the database password in the Compose
.envfile rather than in the Compose file itself, and reference it with the standard Compose variable interpolation.
Answer:
The finished Compose file is:
services:
caddy:
image: caddy:2-alpine
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- caddy-data:/data
- caddy-config:/config
- ./Caddyfile:/etc/caddy/Caddyfile:ro
depends_on:
app:
condition: service_healthy
networks:
- edge
- backend
volumes:
caddy-data:
caddy-config:
networks:
edge:
backend:The app and db services follow the pattern shown in section 4: they live on the backend network only, they each declare a health check, and the application waits for the database to report healthy. The Caddyfile that goes with it is:
app.example.com {
reverse_proxy app:3000 {
lb_policy least_conn
health_uri /healthz
health_interval 10s
}
}With this setup, docker compose up -d brings up the database first, then the application once the database reports healthy, then Caddy once the application reports healthy. Only Caddy is reachable from outside the project, the certificate is obtained once and reused across every later restart, and docker compose down followed by up -d does not trigger a new issuance because the caddy-data volume still holds the account and the key.
