Caddy Docker Compose Reverse Proxy: Automatic HTTPS Without Fragile State

TL;DR

Caddy is a practical Docker Compose reverse proxy when you want automatic HTTPS without maintaining a large label-based control plane. Run the official Caddy image, mount a persistent /data volume for certificates and other runtime state, persist /config, and keep routing rules in a short Caddyfile.

For a public hostname, point DNS to the server, expose ports 80 and 443, and use a hostname in the Caddyfile. Caddy can then obtain and renew certificates automatically when the hostname resolves correctly and the server is publicly reachable. Private names do not qualify for automatic public certificates.

The complete pattern is:

1. Create a shared Docker network.
2. Start Caddy with persistent caddy_data and caddy_config volumes.
3. Attach the application to the same network.
4. Proxy to the application by its Compose service name.
5. Validate and reload the Caddyfile.
6. Back up the Caddy state before upgrades.

TOC

• Choose a public or private hostname
• Create the Compose stack
• Write a minimal Caddyfile
• Name the network and upstream correctly
• Validate and reload configuration
• Verify HTTPS and the upstream
• Back up state and plan updates
• Troubleshooting table
• FAQ

Choose a public or private hostname

Use a public DNS name when you want a publicly trusted certificate. For example, app.example.com must resolve to the server running Caddy, and inbound TCP ports 80 and 443 must reach the Caddy container. The official automatic HTTPS documentation explains the hostname and reachability requirements.

Do not promise automatic public certificates for names such as app.local, internal-only DNS records, or hostnames reachable only through a private network. Those names can still be served through HTTP, internal certificates, or certificates issued by your own private authority, but that is a different trust model.

Before starting, decide whether another service already owns ports 80 or 443. Only one process can bind each host port. If Caddy is the public entry point, expose those ports from Caddy and keep application ports private.

Create the Compose stack

The official Caddy installation guide links to the official Docker image and its recommended Compose usage. This example keeps Caddy and a sample application in one project:

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - caddy_data:/data
      - caddy_config:/config
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
    networks:
      - proxy

  app:
    image: nginx:alpine
    restart: unless-stopped
    expose:
      - "80"
    networks:
      - proxy

volumes:
  caddy_data:
  caddy_config:

networks:
  proxy:

The two named volumes are essential. The official Docker image documentation requires persistent /data and recommends persisting /config. The /data directory contains certificates, private keys, and other operational state. Losing it can cause unnecessary certificate reissuance and can make a previously stable deployment difficult to recover. Persisting /config keeps Caddy’s configuration-related state durable as well.

The application uses expose, not ports, because it does not need to publish a host port. Caddy reaches it over the Docker network. This reduces the number of externally reachable services and makes Caddy the single HTTPS boundary.

Write a minimal Caddyfile

Create Caddyfile beside compose.yaml:

app.example.com {
    reverse_proxy app:80
}

This is enough for a basic reverse proxy. Caddy matches requests for app.example.com, obtains HTTPS when requirements are satisfied, and forwards traffic to the container named app on port 80. The official reverse proxy directive documentation covers upstream selection, load balancing, health checks, headers, and transport options.

Keep the first configuration small. Add headers, authentication, caching, or health checks only when the application needs them. A short Caddyfile is easier to audit, review, and restore than a large collection of labels spread across multiple services.

Name the network and upstream correctly

Inside a Compose network, containers reach one another through service names. In this example, app is the upstream hostname and 80 is the port exposed by the application container. Do not use localhost:80: from inside the Caddy container, localhost means Caddy itself.

If Caddy and the application live in separate Compose projects, create one external network and attach both projects to it:

networks:
  proxy:
    external: true

Create the network once with your normal Docker workflow, then use the same network name in both projects. The target service must be attached to that network, and the hostname in reverse_proxy must resolve to the other container. If the projects use different service names, use the actual reachable container or network alias.