Skip to content

Caddy

Caddy can be used as the reverse proxy instead of Traefik. It routes the same containers, on the same subdomains, with the same protections:

  • every container with proxy: true in the Container Map is reachable at <proxy_host_rule>.<domain> (and -4k for 4K instances)
  • the internal IP allowlist, and expose_to_public to lift it
  • a Let’s Encrypt wildcard certificate through the DNS challenge, with HTTP/3
  • Authentik and Tinyauth sign-ins
  • external hosts from hmsdocker_proxy_ext_hosts_list
  • the CrowdSec bouncer, and hmsdocker_proxy_trusted_proxies for proxies in front of it
  • hmsdocker_proxy_security_hardening, access logs, endpoint verification, the Homepage widget and the Plex certificate script

Only one reverse proxy can run, since both use ports 80 and 443. The playbook stops if both are enabled.

  1. In inventory/group_vars/all/container_map.yml, disable traefik and enable caddy:

    inventory/group_vars/all/container_map.yml
    caddy:
    directory: true
    enabled: true
    homepage: true
    homepage_stats: false
    ...
    traefik:
    ...
    enabled: false

    If your container map has no caddy entry, run make update to add it (or add it as above).

  2. If you use SSL, set up the DNS provider

  3. Run the playbook. The traefik container is removed and caddy takes over ports 80 and 443

The Caddy settings are in roles/hmsdocker/defaults/main/caddy.yml. Copy the ones you change into inventory/group_vars/all/caddy.yml (or run make config, which copies every defaults file).

Everything else is shared with Traefik and stays in inventory/group_vars/all/reverse_proxy.yml (traefik.yml until you run make update), so switching back and forth does not change how your services are reached:

Setting Used by Caddy for
hmsdocker_ssl_enabled getting a Let’s Encrypt certificate, see SSL Certificates
hmsdocker_ssl_letsencrypt_staging the Let’s Encrypt staging server
hmsdocker_ssl_letsencrypt_email the Let’s Encrypt account
hmsdocker_ssl_sans the wildcard certificate(s), *.<domain> by default
hmsdocker_ssl_dns_provider_environment_vars the DNS provider credentials, passed to the container
hmsdocker_ssl_dns_resolver_1, hmsdocker_ssl_dns_resolver_2 the DNS servers used to check the DNS challenge
hmsdocker_proxy_allow_list the internal IP allowlist
hmsdocker_proxy_security_hardening security headers
hmsdocker_proxy_ext_hosts_enabled, hmsdocker_proxy_ext_hosts_list external services
hmsdocker_proxy_access_logs request logs in docker logs caddy
hmsdocker_proxy_verify_endpoints checking every route at the end of the run
hmsdocker_proxy_trusted_proxies proxies in front of Caddy, whose X-Forwarded-For header gives the client IP

hmsdocker_traefik_ssl_dns_provider_code, hmsdocker_traefik_log_level and the Traefik dashboard settings are not used by Caddy.

The Traefik SSL requirements apply: a domain Let’s Encrypt can issue certificates for, and a DNS provider with an API key. As with Traefik, start with the staging server (hmsdocker_ssl_letsencrypt_staging: true, the default) and switch to production once the staging certificate works.

Caddy uses a DNS provider module from caddy-dns for the DNS challenge. The official Caddy image has none, so when SSL is enabled the playbook builds a Caddy image with the module (named hmsd-caddy). The first build takes a few minutes, later runs reuse it until the Caddy version or the modules change. Images built for an earlier version or module list are removed once Caddy runs the new one. Docker keeps the build cache, which docker builder prune removes.

inventory/group_vars/all/caddy.yml
hmsdocker_caddy_dns_provider: cloudflare # the module name from https://github.com/caddy-dns (defaults to hmsdocker_traefik_ssl_dns_provider_code)
hmsdocker_caddy_dns_provider_config: "{env.CF_DNS_API_TOKEN}" # what the provider's README puts after `dns <provider>`

{env.NAME} reads a value from the container’s environment, which gets every variable in hmsdocker_ssl_dns_provider_environment_vars. Use it for keys and tokens so they are not written into the Caddyfile.

For a provider with several settings, write them as a block. Example for Route 53:

inventory/group_vars/all/reverse_proxy.yml
hmsdocker_ssl_dns_provider_environment_vars:
{
"AWS_ACCESS_KEY_ID": "<key id>",
"AWS_SECRET_ACCESS_KEY": "<secret>",
}
inventory/group_vars/all/caddy.yml
hmsdocker_caddy_dns_provider: route53
hmsdocker_caddy_dns_provider_config: |-
{
access_key_id {env.AWS_ACCESS_KEY_ID}
secret_access_key {env.AWS_SECRET_ACCESS_KEY}
region us-east-1
}

Caddy gets a certificate for each name in hmsdocker_ssl_sans (*.<domain> by default) and uses it for every subdomain it covers. A subdomain that no wildcard covers gets its own certificate. Certificates are stored in <apps path>/caddy/data.

Caddy redirects HTTP to HTTPS and serves HTTP/3 on UDP 443, see HTTP/3.

The same rules as Traefik apply:

  • Containers only accept requests from 127.0.0.1 and the networks in hmsdocker_proxy_allow_list (private RFC1918 ranges by default), other clients get a 403. expose_to_public: true on a container (or expose_publicly: yes on an external host) removes this restriction
  • n8n is never restricted (like its Traefik router), and handles its own security headers
  • With hmsdocker_proxy_security_hardening, responses get the X-Frame-Options: DENY and X-Content-Type-Options: nosniff headers. Caddy only accepts TLS 1.2 and newer in any case, and like Traefik, answers requests for any host it does not route (including requests to the server’s IP) with a 404
  • Traffic through Cloudflare Tunnel bypasses Caddy the same way it bypasses Traefik

Caddy’s admin API only listens inside the container. Port 2020 (reachable from the Docker network only) serves the container health check and the read-only upstream status used by the Homepage widget.

Authentik and Tinyauth work as with Traefik: a container with authentik: true, or listed in hmsdocker_tinyauth_protected_containers, requires a sign-in. Caddy checks the IP allowlist first, then the sign-in.

For Authentik, Caddy forwards to the same outpost containers (authentik-proxy-<project>-<container>), so the outpost setup is unchanged. The generated outpost configs in <apps path>/authentik/outposts have no Traefik labels while Caddy is enabled.

With hmsdocker_proxy_access_logs (or CrowdSec) enabled, Caddy logs every request to docker logs caddy, independent of hmsdocker_caddy_log_level. API keys and tokens that apps send in headers or the URL (X-Api-Key, X-Plex-Token, X-Emby-Token, apikey, api_key, token and similar) are removed from the log, as are cookies and Authorization headers.

hmsdocker_proxy_ext_hosts_list works the same way, see Adding External Services to Traefik. Caddy sends the external host’s own hostname to it (as written in backend_url, with the port only if it has one) and does not verify the certificate of an https:// backend. Only the scheme, host and port of backend_url are used, a path is ignored.

If an external host uses the same subdomain as a container, Caddy only routes the container and the playbook prints a warning.

Every *.caddy file in hmsdocker_caddy_custom_config_location (default <apps path>/caddy/custom) is added to the Caddyfile, so you can route containers outside of this project or other services. The playbook never changes these files. Reload Caddy after editing them:

Terminal window
docker exec caddy caddy reload --config /etc/caddy/Caddyfile

The container must be on the hms-docker_proxy_net network (use your hmsdocker_project_name if you changed it), see the Traefik example for the network settings. You can use the same protections as the built-in routes:

# <apps path>/caddy/custom/myapp.caddy
myapp.example.com {
route {
# CrowdSec bouncer (does nothing while crowdsec is disabled), keep it first
import hmsd_crowdsec
# Internal IP allowlist, leave it out to allow everyone
import hmsd_internal
# Optional: require a Tinyauth sign-in
import hmsd_tinyauth
# Optional: require an Authentik sign-in through this outpost container
# import hmsd_authentik authentik-proxy-hms-docker-myapp
reverse_proxy http://myapp:8080
}
}

Without SSL, start the site address with http:// (e.g. http://myapp.example.com).

With crowdsec enabled, every route Caddy serves blocks the IPs CrowdSec bans. See CrowdSec with Caddy.

Each Caddy image has its own Caddyfile folder, <apps path>/caddy/config/<image tag>/. When a change needs a new image (enabling or disabling CrowdSec or SSL, a new Caddy version or module), Compose switches the image and the Caddyfile together, so Caddy never loads a config its image can’t run. If the run stops before that, Caddy keeps working with its previous image and config, and the next run finishes the change. Folders of earlier images are removed once Caddy runs the new one.

With homepage: true on caddy in the container map, Homepage shows Caddy with its widget (upstreams and requests).

The Plex SSL script (hmsdocker_plex_ssl_enabled) uses Caddy’s certificate while Caddy is enabled. It picks the newest certificate that covers hmsdocker_plex_ssl_public_hostname, preferring production over staging certificates.

inventory/group_vars/all/caddy.yml
hmsdocker_caddy_version: "2.11.9" # Caddy release, 2.11.6 or newer
hmsdocker_caddy_log_level: "INFO" # DEBUG, INFO, WARN or ERROR
hmsdocker_caddy_dns_provider: "{{ hmsdocker_traefik_ssl_dns_provider_code }}"
hmsdocker_caddy_dns_provider_module: "github.com/caddy-dns/{{ hmsdocker_caddy_dns_provider }}" # only change for a provider outside github.com/caddy-dns
hmsdocker_caddy_dns_provider_config: "{env.CF_DNS_API_TOKEN}"
hmsdocker_caddy_extra_modules: [] # more Caddy modules to build in, e.g. ["github.com/mholt/caddy-ratelimit"]
hmsdocker_caddy_custom_config_location: "{{ hmsdocker_apps_path }}/caddy/custom"
  • docker logs -f caddy shows certificate requests and errors. Set hmsdocker_caddy_log_level: DEBUG for more detail. Look for could not get certificate from issuer lines, their error field says why Let’s Encrypt refused or the DNS challenge failed
  • creating new account because no account for configured email is known to us with a no such file or directory error is not a failure: Caddy registers a new ACME account the first time it uses an email address with a CA
  • Caddy only uses Let’s Encrypt, like Traefik. Certificates from an earlier Caddy setup that used another CA (such as ZeroSSL) are not renewed, Caddy gets new ones from Let’s Encrypt
  • The generated config is <apps path>/caddy/config/<image tag>/Caddyfile (e.g. 2.11.9, or 2.11.9-<hash> for an image built with modules). Check it with docker exec caddy caddy validate --config /etc/caddy/Caddyfile
  • If Caddy does not start, the playbook stops with a message. The cause is usually a DNS provider setting that does not match the provider’s README, or a token the module rejects
  • A 502 means Caddy cannot reach the container: check that it is running and healthy