Caddy reverse proxy quadlet

The quadlet files

Every quadlet file below passes podman's quadlet generator and systemd-analyze verify on podman 5.0 and the current release. Personal values are placeholders: replace example.com, /srv/... paths and the time zone with your own.

[Unit]
Description=Caddy reverse proxy

[Container]
Image=docker.io/library/caddy:2
ContainerName=caddy
AutoUpdate=registry
PublishPort=80:80
PublishPort=443:443
# HTTP/3
PublishPort=443:443/udp
# Mount the folder, not the single Caddyfile, so edits are seen after a reload.
Volume=/etc/caddy:/etc/caddy:ro,Z
# Certificates and ACME account: losing this means requesting every certificate again.
Volume=caddy-data.volume:/data
Volume=caddy-config.volume:/config

[Service]
Restart=always
ExecReload=/usr/bin/podman exec caddy caddy reload --config /etc/caddy/Caddyfile
TimeoutStartSec=900

[Install]
WantedBy=multi-user.target

[Volume]
VolumeName=caddy-data

[Volume]
VolumeName=caddy-config

{
	email admin@example.com
}

# One block per site. Caddy gets and renews the certificate for each name.
whoami.example.com {
	# localhost inside this container is the container itself:
	# reach services on the host through host.containers.internal.
	reverse_proxy host.containers.internal:8080
}

changes.example.com {
	reverse_proxy host.containers.internal:5000
}

Why is it built this way?

Why rootful. Caddy must receive traffic on ports 80 and 443, which are privileged, and it should start at boot on its own. Only the proxy runs as root; the apps behind it stay rootless and publish high ports such as 8080.

Three kinds of storage. The Caddyfile comes from /etc/caddy on the host, mounted read-only, so you edit it with any editor. caddy-data.volume holds certificates and the ACME account: this is the volume you must never lose. caddy-config.volume holds Caddy's autosaved config and can be rebuilt.

Reload instead of restart. The ExecReload= line runs caddy reload inside the running container, so sudo systemctl reload caddy.service applies a new Caddyfile without dropping connections. Quadlet passes [Service] lines straight into the generated unit.

Reaching the apps. host.containers.internal resolves to the host inside every podman container, so reverse_proxy host.containers.internal:8080 reaches a rootless app published on port 8080, such as the whoami quadlet. PublishPort=443:443/udp enables HTTP/3.

Updates. caddy:2 follows Caddy 2 releases, and AutoUpdate=registry keeps it current with rollback on failure. The Caddyfile syntax is in the Caddy documentation.

How do I start it?

Run these with sudo. Quadlet reads /etc/containers/systemd/ for system services.

sudo mkdir -p /etc/containers/systemd /etc/caddy
# save the Caddyfile in /etc/caddy/, the three quadlet files in /etc/containers/systemd/
sudo systemctl daemon-reload
sudo systemctl start caddy.service
# after every Caddyfile change:
sudo systemctl reload caddy.service

Check the result with sudo systemctl status and the logs with sudo journalctl -u followed by the service name. To turn a docker-compose file of your own into files like these, use the compose to quadlet converter.

Common mistakes

Frequently asked questions