Reverse proxy
How the bundled Caddy proxy puts a service on HTTPS from one field, and why yoink owns the routing change.
When a service sets domain: api.example.com, yoink starts a managed Caddy in front of it. The proxy routes the hostname, gets a Let’s Encrypt cert, and renews the cert. It has the same drift detection, logs, and TUI surface as any yoink service. You do not write the Caddy config.
The smallest config
# yoink.yaml
hosts:
- { address: 1.2.3.4, user: root }
proxy:
email: [email protected] # for Let's Encrypt registration
services:
- name: api
image: ghcr.io/me/api
tag: v1
domain: api.example.com # ← the whole proxy opt-in
run:
port: 8080
healthcheck_path: /health
When the DNS record of api.example.com points at 1.2.3.4, yoink up puts the service on https://api.example.com with a valid cert.
All fields are in the proxy config reference.
How it works
When any service sets domain:, yoink adds a yoink-proxy service that runs caddy:2. yoink generates the Caddy config from your yoink.yaml. yoink pushes the config through the admin API of Caddy at fixed points in the rolling deploy. Thus yoink owns the routing change, and no separate reconciler competes with it for Docker labels.
yoink manages two Docker networks for you:
yoink-ingress: the proxy and every service withdomain:join this network. The proxy reaches your containers by name through it.yoink-proxy-admin: the admin API of the proxy listens here. yoink publishes the admin port only on the loopback of the host, never on a public interface. yoink reaches it through an SSH tunnel for the duration of one/loadcall.
Upstream entries name containers, not IPs. As a result, a container restart with a new IP does not break routing, because Docker DNS resolves the name. The active health checks of Caddy take dead backends out of rotation.
Rolling deploys with zero traffic loss
For each service, a deploy has these stages:
- The new replicas start.
- yoink waits for the healthcheck of each new replica.
- yoink pushes the updated Caddy config (
/load). The upstream pool of the service now contains only the new replicas. - Caddy reloads in-process. Open connections to the old replicas continue until they close, and new requests go to the new replicas.
- The old replicas stop.
yoink drives every stage, and there is no second reconciler. The config push occurs only when the set of containers changes, and yoink is in the loop at that time.
If a healthcheck or the config push fails, yoink removes the new replicas. The old replicas stay in the pool and keep running.
A service with publish: is the exception. Its old container stops before the new one starts, because only one container can bind a host port.
What yoink does not model
The typed proxy fields cover routing, TLS, compression, and HSTS. yoink models deploy primitives, and Caddy models traffic handling.
Auth, rate limiting, headers, CORS, redirects, mTLS, geo-blocking, WAF, and L4/TCP routing are not in the schema of yoink. They live in caddy_extra_json:, in the JSON config syntax of the Caddy docs. This escape hatch is the advertised path for these features. The other paths are caddy_extra_caddyfile: and a custom proxy image.
Snippets cookbook
The ready-to-paste snippets for caddy_extra_json: and caddy_extra_caddyfile: are on their own page: Caddy snippets cookbook. Each snippet has the Caddyfile form and the JSON form. The page covers forward auth, basic auth, IP allowlist, custom headers, body-size limit, redirects, maintenance page, and plugins.
Three layers of handlers
A request passes through three layers in a fixed order:
- The
proxy.global_handlers:chain runs for every request, before any service route matches. - The handlers of your
caddy_extra_json:snippet run on the matched route. - The handlers that yoink manages run: compression, the HSTS header, and
reverse_proxyto the upstream.
Thus your auth gates, rate limits, and redirects see the request before yoink compresses or forwards it. The exact order is in Per-route handler order.
proxy.global_handlers: fits fleet-wide concerns, and caddy_extra_json: fits per-app concerns. Examples of fleet-wide concerns:
- CrowdSec bouncer: IP-based denial that applies everywhere, not only to the services that opt in. A service that you add tomorrow has protection with no change to its config.
- Coraza / OWASP CRS: signature-based payload inspection on every request.
- Global rate limiting:
caddy-ratelimitzones that apply across hostnames, for example oneper_ipbudget for the whole proxy.
The entries run as a pipeline, so their order matters. Cheap filters (the CrowdSec hashmap lookup) work best before expensive ones (the Coraza regex evaluation). Then the proxy spends no CPU on traffic that it rejects anyway.
Global Caddy config
yoink does not model the global config values of Caddy as typed fields. Examples are the server-level trusted_proxies and client_ip_headers, and the top-level storage for shared ACME state across hosts. Top-level app blocks for plugins such as cache-handler and coraza are also in this group.
proxy.config_extra: takes raw JSON for these values, and yoink deep-merges it into the generated config. Your value wins on every leaf conflict. Two paths are the exception: yoink rejects a write to the routes or to the TLS connection policies. A write there removes routes or disables mTLS.
config_extra: injects raw config. global_handlers: is the typed slot for handlers. The merge rules are in the config_extra: block of the reference.
Plugins without a registry
For rate limiting, redis-storage, the L4 module, or a non-bundled DNS provider, proxy.xcaddy: takes a list of plugins. yoink then builds Caddy on each host that the proxy runs on, and tags the image locally. The proxy service runs from that tag, so no registry is necessary.
The tag is a content hash of the build inputs. Thus later yoink up runs skip the build until the build inputs change. The costs are a slow first up on each fresh host and a need for egress to proxy.golang.org. The xcaddy: block of the reference lists the full build behavior.
One cert for every route
When proxy.tls: is set, all routed services use the same TLS config by default. This is the Cloudflare pattern: every route is an origin behind the edge of Cloudflare. mTLS proves that the request came from Cloudflare.
No cert state lives on the host filesystem. All of it lives in secrets.age or comes through provider: command, encrypted at rest.
The cert volume
The yoink_caddy_data named volume holds your ACME state, issued certs, and OCSP staples. Let’s Encrypt has strict rate limits (5 duplicate-cert issuances per week). With a fresh volume, Caddy must get every cert again, so a casual removal of the volume is expensive.
yoink prune does not touch the volume. A manual purge is your decision and your responsibility.
See also
- Proxy config reference: every per-service field and every
proxy:field, with the merge rules. - Caddy snippets cookbook: ready-to-paste
caddy_extra_json:andcaddy_extra_caddyfile:snippets. - Caddy plugins (xcaddy, no registry): the task page for a custom Caddy build on each host.
- Cloudflare Origin Certificates: a 15-year cert from Cloudflare in place of Let’s Encrypt, sealed in the repo. Origin-pull mTLS locks your origin to the edge of Cloudflare.
- gRPC hosting:
upstream_h2c: truefor native gRPC backends (Tonic, grpc-go, grpc-java). - Multi-host Let’s Encrypt with Redis storage: shared ACME state across hosts, so that they do not all hit the Let’s Encrypt rate limits.
- Networking: the Docker networks that yoink manages.
- Caddy JSON config reference: the syntax for
caddy_extra_json:snippets. - Caddyfile docs: the syntax for
caddy_extra_caddyfile:.