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.

1. The official image

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

2. The two volumes that matter

The image uses two directories for state.

  • /data holds the certificates, private keys, and the ACME account.
  • /config holds 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

3. A minimal container

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-stopped brings 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.

4. Docker Compose

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.

5. Routing to services by name

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.

6. Configuration and secrets

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.

7. Health checks

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.

8. Building a custom image with plugins

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

9. Common container problems

SymptomCauseFix
A new certificate is issued on every restart/data is not a volumeMount a volume at /data
bind: address already in useAnother process holds port 80 or 443Stop it, or publish a different host port
The site works over HTTP but not HTTPSThe UDP mapping for HTTP/3 is missing, or 443 is blockedPublish 443:443/udp
reverse_proxy cannot reach the appThe service is on a different network, or the name is wrongPut both on a shared network
ACME challenge failsThe domain does not point at the hostPoint the record at the public IP of the Docker host
docker deploymentdocker composepersistent volumescontainer networking

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:

  1. Create a Compose file with three services and two networks. Put the database and the application on the backend network, and give the backend network no route to the host, so the database is not reachable from outside the project.
  2. Attach Caddy to both networks. The edge network is what the published ports belong to, and the backend network is how Caddy reaches the application.
  3. Declare a named volume for /data and a named volume for /config. The /data volume is the one that matters: without it every container replacement means a new ACME account and a new certificate.
  4. 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.
  5. Give the application and the database health checks, and use depends_on with condition: service_healthy so that Caddy starts only after the application is genuinely able to serve, rather than merely started.
  6. 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.
  7. Keep the database password in the Compose .env file 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.

Found an issue with this content?

Tell us what could be improved.