bfren/caddy-proxy repository overview

⁠Docker Caddy Proxy

Docker Repository⁠ - bfren ecosystem⁠

Reverse proxy built on Caddy⁠, configured using a simple JSON file. Caddy requests and renews SSL certificates from Let's Encrypt automatically, using either the HTTP challenge or the DNS challenge (via deSEC⁠), which also supports wildcard certificates.

This is the successor to bfren/nginx-proxy⁠ - see Migrating from nginx-proxy⁠.

⁠Contents

• Ports⁠
• Volumes⁠
• Environment Variables⁠
• Configuration⁠
• Custom Domain Configuration⁠
• DNS Challenge⁠
• Automatic Reload⁠
• Helper Functions⁠
• Migrating from nginx-proxy⁠
• Licence / Copyright⁠

⁠Ports

Ports 80 and 443 need mapping from the host to your proxy container, e.g. adding "0.0.0.0:80:80" to the ports section of your docker compose file. Port 80 is needed for the HTTP challenge and to redirect HTTP to HTTPS. Map 443/udp as well to enable HTTP/3.

Caddy runs as the www user (UID 1000), not root, and no extra capabilities are needed: Docker allows unprivileged users to bind to ports below 1024 inside a container by default. If you use host networking (network_mode: host) the host's setting applies instead, so you will need to set net.ipv4.ip_unprivileged_port_start=80 (or lower) on the host.

• 80
• 443
• 443/udp

⁠Volumes

Files and directories in all three volumes are owned by www (UID / GID 1000), so they can be edited by the main user account on the host.

⁠Environment Variables

⁠Configuration

Domains are defined in /ssl/conf.json - see proxy-conf-sample.json for an example and proxy-conf-schema.json for the full definition. Add the $schema property to get validation and autocomplete in your editor.

{
    "$schema": "https://raw.githubusercontent.com/bfren/docker-caddy-proxy/main/proxy-conf-schema.json",
    "domains": [
        {
            "primary": "example.com",
            "aliases": [ "www.example.com", "ex.com" ],
            "upstream": "http://example:5000",
            "redirectToPrimary": true
        }
    ]
}

Existing conf.json files from nginx-proxy (using primary, upstream, aliases and custom) work without changes.

⁠Routes

Each route can have a path matcher (e.g. /api/* - if omitted the route matches everything) and must have exactly one of:

"routes": [
    { "path": "/api/*", "upstream": [ "http://api1:8080", "http://api2:8080" ], "lb": "round_robin", "stripPrefix": "/api" },
    { "path": "/old/*", "redirect": "https://example.com/new{http.request.uri.path}" },
    { "path": "/files/*", "root": "/www/files" }
]

⁠Defaults

For every domain:

• HTTP requests are redirected to HTTPS, and certificates are requested and renewed automatically.
• Responses are compressed using zstd or gzip, depending on what the browser supports. Images and other already-compressed formats, responses under 512 bytes, and responses the upstream has already compressed are left alone.
• Secure headers are added (Strict-Transport-Security, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection), and X-Clacks-Overhead: GNU Terry Pratchett - because he was a legend⁠.
• X-Real-IP is sent to the upstream, as well as Caddy's standard X-Forwarded-* headers. WebSockets work automatically.
• If the upstream cannot be reached (after retrying for retry, so a quick restart is not noticed), or returns 502, 503 or 504, an auto-refreshing maintenance page is shown.
• Requests for unknown hosts are redirected to BF_PROXY_DOMAIN.

BF_PROXY_DOMAIN serves the files in /www/public, with static files (images, CSS, JavaScript, fonts etc.) cached for a year, and /favicon.ico returning 204 (No Content) unless you add one.

⁠AI Crawlers

When BF_PROXY_BLOCK_AI_BOTS=1 (the default), requests from crawlers that collect AI training data receive 403 Forbidden. The list comes from ai.robots.txt⁠: its robots.json is downloaded when the image is built (the release is set by the AI_ROBOTS_VERSION build argument), and only crawlers whose function is training data collection are kept - AI search crawlers, assistants and user-triggered agents (e.g. OAI-SearchBot, ChatGPT-User, PerplexityBot) are not blocked. The list is saved to /usr/share/caddy-proxy/ai-bots.txt.

⁠Custom Domain Configuration

Each domain's complete Caddy configuration is stored in /sites/<primary>.json:

• route - the domain's route (added to the HTTPS server)
• errors - the domain's error route (shows the maintenance page)
• tls - the domain's certificate automation policy, including the ACME challenge

If the file does not exist it is generated from the standard base. What happens next depends on custom:

• "custom": false (default) - the file is regenerated every time the container starts (or proxy-regenerate is run), so any changes you make to it will be lost. To add to the generated configuration, add *.json files to /sites/<primary>.d - each should contain a Caddy route⁠ object or an array of routes. They are added in file name order, after the security headers and basic auth (so they cannot bypass them) and before the routes from conf.json and the default upstream. Nginx *.conf files from nginx-proxy are ignored (a warning is logged).

  Files ending .before.json (e.g. 10-health.before.json) are added first instead - before the alias redirect, AI bot blocking, security headers, compression and basic auth - so use them only for routes that must not be protected, e.g. a public /health endpoint on a site that otherwise requires a login. A warning is logged whenever they are loaded.

  Within each group (*.before.json and other *.json files), files are loaded in natural sort order: numbers are compared by value (2-x.json before 10-x.json) and upper case sorts before lower case (Z.json before a.json). To keep the order predictable, use lower case names with a two-digit prefix, leaving gaps so files can be added later, e.g. 10-health.before.json, 10-api.json, 20-static.json.

• "custom": true - if the file already exists it is left alone, giving you complete control of the domain's configuration, starting from the standard base. Run proxy-regenerate -d <primary> -f to regenerate it.

⁠DNS Challenge

The DNS challenge allows certificates to be issued for wildcard domains, and for servers that are not reachable on port 80. Caddy is built with the deSEC⁠ DNS provider module.

1. Create a token in your deSEC account with permission to manage the relevant domains.
2. Set BF_PROXY_DESEC_TOKEN to the token, and either set BF_PROXY_ACME_CHALLENGE=dns or "challenge": "dns" for each domain.
3. If certificate requests fail because the record has not propagated, set BF_PROXY_DNS_PROPAGATION_DELAY (e.g. 60s) and / or BF_PROXY_DNS_RESOLVERS (e.g. 1.1.1.1).

The token is not written to the generated configuration files - Caddy reads it from the environment at runtime.

⁠Automatic Reload

By default, run proxy-regenerate after changing conf.json, users.json or files in /sites.

Set BF_PROXY_AUTO_RELOAD=1 to do this automatically: conf.json, users.json and the *.json files in /sites are checked every 5 seconds. When they change (and have stopped changing for 5 seconds, so saving several files only causes one reload) configuration is regenerated and Caddy is reloaded without dropping connections. The checks use about 1 MB of memory and very little CPU.

If the new configuration is not valid (e.g. a JSON syntax error or a missing upstream), the errors are written to the container log and Caddy keeps running with the current configuration.

⁠Helper Functions

⁠Migrating from nginx-proxy

1. Copy /ssl/conf.json to the new /ssl volume - it is converted automatically on startup. The original is kept as /ssl/conf.json.nginx-proxy and $schema is updated. Anything that cannot be converted (e.g. custom Nginx configuration) is reported in the container log.
2. In your docker compose file, change the image to bfren/caddy-proxy and rename environment variables from PROXY_* to BF_PROXY_* - old variable names are ignored. The following are no longer used: PROXY_ENABLE_AUTO_UPDATE (Caddy renews automatically), PROXY_ENABLE_NAXSI (NAXSI has been removed), PROXY_SSL_KEY_BITS, PROXY_SSL_DHPARAM_BITS, PROXY_GETSSL_SKIP_HTTP_TOKEN_CHECK and PROXY_UPSTREAM_DNS_RESOLVER (upstreams are resolved when requests are made).
3. Custom Nginx configuration in /sites cannot be converted automatically - the new per-domain files are Caddy JSON.
4. Existing certificates are not reused - Caddy will request new ones. Caddy requests one certificate per host name (getssl used one certificate per primary domain), so check Let's Encrypt rate limits⁠ if you have many domains, and leave BF_PROXY_LETS_ENCRYPT_LIVE=0 until everything works.
5. nginx-adduser is replaced by proxy-adduser - users are stored in /ssl/users.json and enabled per domain using auth.

⁠Licence

⁠Copyright