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: truein the Container Map is reachable at<proxy_host_rule>.<domain>(and-4kfor 4K instances) - the internal IP allowlist, and
expose_to_publicto 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_proxiesfor 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.
Switching to Caddy
Section titled “Switching to Caddy”-
In
inventory/group_vars/all/container_map.yml, disabletraefikand enablecaddy:inventory/group_vars/all/container_map.yml caddy:directory: trueenabled: truehomepage: truehomepage_stats: false...traefik:...enabled: falseIf your container map has no
caddyentry, runmake updateto add it (or add it as above). -
If you use SSL, set up the DNS provider
-
Run the playbook. The
traefikcontainer is removed andcaddytakes over ports80and443
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.
SSL Certificates
Section titled “SSL Certificates”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.
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:
hmsdocker_ssl_dns_provider_environment_vars: { "AWS_ACCESS_KEY_ID": "<key id>", "AWS_SECRET_ACCESS_KEY": "<secret>", }hmsdocker_caddy_dns_provider: route53hmsdocker_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.
Security
Section titled “Security”The same rules as Traefik apply:
- Containers only accept requests from
127.0.0.1and the networks inhmsdocker_proxy_allow_list(private RFC1918 ranges by default), other clients get a403.expose_to_public: trueon a container (orexpose_publicly: yeson an external host) removes this restriction n8nis never restricted (like its Traefik router), and handles its own security headers- With
hmsdocker_proxy_security_hardening, responses get theX-Frame-Options: DENYandX-Content-Type-Options: nosniffheaders. 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 a404 - 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.
Single sign-on
Section titled “Single sign-on”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.
Access logs
Section titled “Access logs”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.
External Services
Section titled “External Services”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.
Adding other Containers to Caddy
Section titled “Adding other Containers to Caddy”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:
docker exec caddy caddy reload --config /etc/caddy/CaddyfileThe 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.caddymyapp.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).
CrowdSec
Section titled “CrowdSec”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.
Homepage
Section titled “Homepage”With homepage: true on caddy in the container map, Homepage shows Caddy with its widget (upstreams and requests).
Plex Certificate
Section titled “Plex Certificate”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.
Settings
Section titled “Settings”hmsdocker_caddy_version: "2.11.9" # Caddy release, 2.11.6 or newerhmsdocker_caddy_log_level: "INFO" # DEBUG, INFO, WARN or ERRORhmsdocker_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-dnshmsdocker_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"Troubleshooting
Section titled “Troubleshooting”docker logs -f caddyshows certificate requests and errors. Sethmsdocker_caddy_log_level: DEBUGfor more detail. Look forcould not get certificate from issuerlines, theirerrorfield says why Let’s Encrypt refused or the DNS challenge failedcreating new account because no account for configured email is known to uswith ano such file or directoryerror 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, or2.11.9-<hash>for an image built with modules). Check it withdocker 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
502means Caddy cannot reach the container: check that it is running and healthy