xcaddy build reference

Image tags, labels, rebuild rules, and the generated Dockerfile of the proxy.xcaddy build, with a list of Caddy plugins.

Read as MarkdownEdit on GitHub

Config

The fields of proxy.xcaddy: are in the proxy reference and the config reference.

proxy.xcaddy: and proxy.image: are mutually exclusive. image: uses an image that you supply. xcaddy: uses a build that yoink manages.

Image tag and labels

Item Value
Local tag yoink-caddy:<hash>
Hash inputs (caddy_version, base_image, builder_image, sorted plugins, sorted env, sorted replace)
Label yoink.caddy.xcaddy_hash=<hash>
Label yoink.caddy.plugins=<csv>
Build location The image cache of each proxy host

Rebuild rules

Two yoink up runs give the same yoink-caddy:<hash> tag if and only if all hash inputs are the same. yoink sorts plugins, env, and replace before the hash, so their order has no effect. If the host has the tag, yoink skips the build.

Change Hash changes? Effect
Reorder plugins: entries in the YAML No No-op
Add or remove a plugin Yes Fresh build on the next up
Change a module@version pin (for example @v0.1.0 → @v0.2.0) Yes Fresh build
Remove the @version from a pinned plugin Yes Fresh build (different string ≠ same module)
Pin caddy_version: v2.8.4 Yes Fresh build
Add or change an env or replace entry Yes Fresh build
New caddy or plugin release upstream (no config change) No yoink uses the cached build. yoink up --rebuild-proxy forces a rebuild.

Generated Dockerfile

yoink proxy-dockerfile prints the Dockerfile and makes no docker calls. The Dockerfile has two stages: caddy:2-builder → caddy:2. Each env entry adds an ENV line to the builder stage. Each replace entry adds a --replace argument. yoink pulls the builder image before each build.

# syntax=docker/dockerfile:1
FROM caddy:2-builder AS builder
RUN xcaddy build \
    --with github.com/caddy-dns/cloudflare \
    --with github.com/caddyserver/caddy-l4 \
    --with github.com/mholt/[email protected]

FROM caddy:2
COPY --from=builder /usr/bin/caddy /usr/bin/caddy
LABEL yoink.caddy.xcaddy_hash=763762748729e677
LABEL yoink.caddy.plugins="github.com/caddy-dns/cloudflare,github.com/caddyserver/caddy-l4,github.com/mholt/[email protected]"

Plugins

yoink does not model these features natively. This list is not complete: the caddy module index lists every published module.

Plugin Function Notes
caddyserver/cache-handler RFC-compliant HTTP caching at the proxy. Not useful behind a CDN edge. Recipe.
mholt/caddy-ratelimit In-process rate limiting for each IP, header, or zone. A second layer behind the limiter of a CDN, or the only layer when the proxy is the public surface. Recipe.
mholt/caddy-l4 Layer-4 (TCP/UDP) routing: Postgres, SSH, custom protocols, and gRPC with mTLS passthrough. yoink does not model L4 routes. The plugin compiles with xcaddy, but you must write the Caddy admin pushes for the routes.
greenpau/caddy-security SSO/AAA at the proxy: JWT validation, OAuth2 / OIDC, SAML, LDAP, and authorization policies for each route. Auth at the proxy without an extra service. Works with forward_auth (in core caddy), or with the authenticate and authorize directives of the plugin.
corazawaf/coraza-caddy ModSecurity-compatible Web Application Firewall, with the OWASP Core Rule Set. For a proxy behind a CDN that has no WAF, or as a second layer. Heavier than the other plugins in this list: do a benchmark before you use it on hot endpoints.
hslatman/caddy-crowdsec-bouncer Enforces the community IP blocklists of CrowdSec at the proxy. Needs a CrowdSec local API instance that the proxy can reach. That instance can run as a yoink service.
caddy-dns/* DNS-01 ACME challenge providers (cloudflare, route53, digitalocean, hetzner, and more). Required for wildcard certs. Recipe.
pberkel/caddy-storage-redis Shared ACME storage backend for fleets of many hosts. Recipe.
WeidiDeng/caddy-cloudflare-ip Trust source for the Cloudflare IP ranges, with automatic refresh. Behind Cloudflare, it passes the real client IP to logs, geo-IP, and IP-aware rate limits. Works with trusted_proxies in proxy.config_extra:. Recipe.

See also

Type a flag, a config field, or a task.