dash 2.12.0 → 3.0.1

data/lib/kamal/configuration/docs/proxy.yml

@@ -12,6 +12,36 @@
 #
 proxy:
 
+
+  # Where each option lives when a loadbalancer fronts the fleet
+  #
+  # Every deploy option has exactly one home (see
+  # Kamal::Configuration::Proxy::DEPLOY_OPTION_DISPOSITIONS - the layering
+  # contract that enforces this):
+  #
+  #   edge     - applied only by the loadbalancer, stripped from the per-host
+  #              proxies: host/hosts, ssl (certificates, on-demand, mTLS),
+  #              ssl_redirect, ssl_staging, ssl_domains, basic_auth,
+  #              allow_ips, client_ip, rate_limit, session_affinity,
+  #              canonical_host, redirects, cache, read_routing
+  #
+  #   per-app  - applied only by the per-host proxies, next to the app:
+  #              headers, rewrites, intercept_errors, sleep, compress
+  #
+  #   both     - each layer runs its own copy, deliberately: healthcheck,
+  #              response/request timeouts, path timeouts, target pool
+  #              tuning, buffering, path_prefix, strip_path_prefix,
+  #              forward_headers, logging, exclude_metrics_paths
+  #
+  # Without a loadbalancer the single proxy is every layer at once and the
+  # whole surface applies to it. `loadbalancer`, `reboot_on_deploy` and `run`
+  # configure the containers themselves rather than a deployment, so they
+  # have no layer.
+
+  # ==========================================================================
+  # 1. Essentials — enough for most apps
+  # ==========================================================================
+
   # Hosts
   #
   # The hosts that will be used to serve the app. The proxy will only route requests
@@ -22,17 +52,71 @@ proxy:
   #
   # Specify one of `host` or `hosts`.
   host: foo.example.com
+
   hosts:
     - foo.example.com
     - bar.example.com
-    
+
   # Loadbalancer
   #
   # Specify a host to run the loadbalancer on. The loadbalancer will distribute requests
   # to all web hosts. If not specified but multiple web hosts are configured, the first
   # web host will be used as the loadbalancer host.
+  #
+  # The host may be a dedicated machine outside of `servers:`, or one of the web hosts —
+  # in which case the loadbalancer takes over that host's proxy container.
+  #
+  # Set `true` to always run the loadbalancer on the first host of the primary role, even
+  # when that role has a single host, or `false` to opt out of the automatic activation
+  # for multi-host primary roles.
   loadbalancer: lb.example.com
 
+  # Sharing one loadbalancer between several kamal apps
+  #
+  # More than one kamal app may point `loadbalancer:` at the same host. Each app
+  # registers its own service on the shared kamal-proxy and keeps its own
+  # deploy.yml; the load balancer multiplexes them by hostname.
+  #
+  # The rules kamal enforces for that topology:
+  #
+  # * Service state survives a reboot. kamal-proxy persists its services in the
+  #   `kamal-loadbalancer-config` volume (or `kamal-proxy-config` when the
+  #   loadbalancer shares a proxy host), and `kamal proxy reboot` only replaces
+  #   the container. Rebooting from app A does not drop app B's routes — the
+  #   surviving service list is printed after the restart.
+  #
+  # * Service names must be unique across apps. The loadbalancer registers a
+  #   service under the bare `service:` name, so two apps — or two destinations
+  #   of one app — sharing a name would take over each other's routes. The first
+  #   app to deploy claims the name in `.kamal/loadbalancer/services/<service>`
+  #   on the loadbalancer host; a second app deploying the same name fails at
+  #   deploy time instead of silently winning.
+  #
+  # * Apps sharing a loadbalancer must agree on `proxy/run`. All of them boot the
+  #   same container, so the first app to boot records its run configuration in
+  #   `.kamal/loadbalancer/run_config`. Another app booting with a different
+  #   `proxy/run` fails; the same app changing its own gets the usual drift
+  #   warning and applies it on `kamal proxy reboot`.
+  #
+  # * `kamal proxy remove` refuses while other apps are installed on the
+  #   loadbalancer host, exactly as it does for a proxy host. Use `--force` to
+  #   override, which removes the shared loadbalancer for every app on it.
+
+  # Automatic proxy reboot on deploy
+  #
+  # When `kamal deploy` detects that the running kamal-proxy container was
+  # started with a different image, version or run options than the current
+  # configuration, it reboots the proxy automatically — one host at a time —
+  # before booting the app.
+  #
+  # Set to false to opt out. Kamal will then print a warning when drift is
+  # detected and leave the proxy untouched until you run `kamal proxy reboot`.
+  #
+  # Root-level `proxy` setting only; ignored inside role-specific proxy blocks.
+  #
+  # Defaults to true:
+  reboot_on_deploy: false
+
   # App port
   #
   # The port the application container is exposed on.
@@ -63,9 +147,29 @@ proxy:
   #
   # Kamal supports loading custom SSL certificates directly from secrets. You should
   # pass a hash mapping the `certificate_pem` and `private_key_pem` to the secret names.
+  #
+  # The hash is also home to the rest of the TLS surface:
+  #
+  # `on_demand_url` turns on on-demand TLS: instead of a fixed `host` list, the
+  # proxy asks this endpoint whether it may issue a certificate for the hostname
+  # in an incoming handshake. A path is resolved against a healthy app target; an
+  # absolute http(s) URL is called directly. Answer 2xx to approve. On-demand TLS
+  # replaces the static hostname list, so it cannot be combined with
+  # `host`/`hosts`, with `certificate_pem`, or with `ssl_domains` — kamal rejects
+  # those at config time, because kamal-proxy would reject the deploy and there
+  # is no sensible winner to pick.
+  #
+  # `client_ca_pem` requires mutual TLS: clients must present a certificate
+  # signed by this CA bundle. Like `certificate_pem` it names a secret in
+  # `.kamal/secrets`; the content is uploaded next to the app's TLS material
+  # under `.kamal/proxy/apps-config`, and the proxy is given the path it sees
+  # inside its own container. An empty secret fails the deploy rather than
+  # silently turning mTLS off.
   ssl:
     certificate_pem: CERTIFICATE_PEM
     private_key_pem: PRIVATE_KEY_PEM
+    on_demand_url: https://app.example.com/api/v1/tls/ask
+    client_ca_pem: CLIENT_CA_PEM
   # ### Notes
   # - If the certificate or key is missing or invalid, deployments will fail.
   # - Always handle SSL certificates and private keys securely. Avoid hard-coding them in source control.
@@ -77,20 +181,37 @@ proxy:
   # HTTPS traffic), you can disable this redirect by setting `ssl_redirect: false`:
   ssl_redirect: false
 
-  # Forward headers
-  #
-  # Whether to forward the `X-Forwarded-For` and `X-Forwarded-Proto` headers.
+  # SSL staging
   #
-  # If you are behind a trusted proxy, you can set this to `true` to forward the headers.
+  # When automatic SSL is enabled, use the Let's Encrypt staging environment
+  # for certificate provisioning, so you can test your SSL configuration
+  # without running into Let's Encrypt's production rate limits. Certificates
+  # issued by the staging environment are not trusted by browsers.
   #
-  # By default, kamal-proxy will not forward the headers if the `ssl` option is set to `true`, and
-  # will forward them if it is set to `false`.
-  forward_headers: true
+  # Defaults to `false`:
+  ssl_staging: true
 
-  # Response timeout
+  # Healthcheck
   #
-  # How long to wait for requests to complete before timing out, defaults to 30 seconds:
-  response_timeout: 10
+  # When deploying, the proxy will by default hit `/up` once every second until we hit
+  # the deploy timeout, with a 5-second timeout for each request.
+  #
+  # Once the app is up, the proxy will stop hitting the healthcheck endpoint.
+  #
+  # By default, the healthcheck is sent to the app port. Set `port` to check a
+  # different port on the container, and `host` to set the Host header sent with
+  # healthcheck requests.
+  healthcheck:
+    interval: 3
+    path: /health
+    timeout: 3
+    port: 3001
+    host: health.example.com
+
+
+  # ==========================================================================
+  # 2. Traffic & routing
+  # ==========================================================================
 
   # Path-based routing
   #
@@ -102,11 +223,13 @@ proxy:
   #
   # When using path_prefix you can supply multiple routes separated by commas.
   path_prefix: "/api,/oauth_callback"
+
   # You can also specify paths as a list of paths, the configuration will be
   # rolled together into a comma separated string.
   path_prefixes:
     - "/api"
     - "/oauth_callback"
+
   # By default, the path prefix will be stripped from the request before it is forwarded upstream.
   #
   # So in the example above, a request to /api/users/123 will be forwarded to web-1 as /users/123.
@@ -115,16 +238,317 @@ proxy:
   # specify --strip-path-prefix=false
   strip_path_prefix: false
 
-  # Healthcheck
+  # Forward headers
   #
-  # When deploying, the proxy will by default hit `/up` once every second until we hit
-  # the deploy timeout, with a 5-second timeout for each request.
+  # Whether to forward the `X-Forwarded-For` and `X-Forwarded-Proto` headers.
   #
-  # Once the app is up, the proxy will stop hitting the healthcheck endpoint.
-  healthcheck:
-    interval: 3
-    path: /health
-    timeout: 3
+  # If you are behind a trusted proxy, you can set this to `true` to forward the headers.
+  #
+  # By default, kamal-proxy will not forward the headers if the `ssl` option is set to `true`, and
+  # will forward them if it is set to `false`.
+  forward_headers: true
+
+  # Header rules
+  #
+  # Rewrite headers on their way to the app and on their way back out, without
+  # the app knowing. `set` replaces whatever was there, `add` appends and keeps
+  # it, `remove` strips it.
+  #
+  # Names are canonicalised, and values have their leading and trailing
+  # whitespace trimmed. A value may contain colons — a CSP naming a scheme or a
+  # port survives intact.
+  #
+  # Two things kamal rejects rather than letting them fail late: a value with a
+  # newline or carriage return in it (that is response splitting, and shell
+  # escaping would silently turn it into a literal backslash-n), and a *request*
+  # rule naming `Host` — Go carries the host outside the header map, so the rule
+  # would do nothing at all.
+  #
+  # Response rules apply to what the app returned. Error pages, redirects, and
+  # auth or rate-limit rejections come from the proxy itself and are unaffected.
+  headers:
+    request:
+      set:
+        X-Forwarded-Host: app.example.com
+      add:
+        X-Request-Source: kamal
+      remove:
+        - X-Internal-Token
+    response:
+      set:
+        Strict-Transport-Security: max-age=31536000
+      add:
+        X-Served-By: kamal-proxy
+      remove:
+        - Server
+
+  # Redirects and rewrites
+  #
+  # A redirect answers the client with a `Location`; a rewrite changes the path
+  # the app receives while the client's URL stays as it was — which is what an
+  # SPA serving its own routes out of `/index.html` needs.
+  #
+  # `from` is a regular expression **anchored to the whole path**, so `/old` does
+  # not fire on `/not-old-either`. `to` is a path on this host, and for a
+  # redirect may also be a full http(s) URL. Captures are available as `$1`,
+  # `$2`, … Rules are tried in order and the first match wins.
+  #
+  # ### Watch the path prefix
+  #
+  # Both match the path **the client asked for, before `path_prefix` stripping**.
+  # An app mounted at `path_prefix: /api` with `strip_path_prefix` on sees
+  # `/users`, but a rule here still has to be written against `/api/users`. This
+  # is the part that is easy to get wrong.
+  #
+  # `status` applies to redirects only and must be 301, 302, 303, 307 or 308.
+  # It defaults to 301, so say 302 explicitly for anything you may want back.
+  redirects:
+    - from: /old
+      to: /new
+    - from: /gone/(.*)
+      to: https://elsewhere.example.com/$1
+      status: 302
+
+  rewrites:
+    - from: /api/(.*)
+      to: /v2/$1
+
+  # Canonical host
+  #
+  # Redirect every request to this host, to force apex or www one way.
+  canonical_host: www.example.com
+
+  # Intercept error statuses
+  #
+  # Replace these statuses coming from the app with the proxy's own error pages,
+  # discarding whatever body the app sent. 4xx and 5xx codes only.
+  #
+  # This pairs with the root-level `error_pages_path`. It works without it, but
+  # not usefully: with no pages to render, the proxy falls back to a bare
+  # plaintext status line, so the app's own error page is thrown away and
+  # replaced by the words "Bad Gateway". Kamal warns when you do that.
+  intercept_errors:
+    - 502
+    - 503
+  #
+  # ### Note
+  # Everything in this section applies on the per-host proxy, including when a
+  # loadbalancer is configured — unlike TLS and access control, which move to the
+  # loadbalancer. Applying them at both layers would append an `add` header twice
+  # and run a rewrite over its own output.
+
+
+  # ==========================================================================
+  # 3. Security & access
+  # ==========================================================================
+
+  # Basic auth
+  #
+  # Require HTTP Basic credentials on every request to this service. Requests
+  # without valid credentials get a 401 with a `WWW-Authenticate` challenge.
+  # The health check path stays open, so deploys are unaffected.
+  #
+  # Set exactly one of `password_secret` or `password` — never both.
+  #
+  # Prefer `password_secret`: it names an entry in `.kamal/secrets`, so the
+  # password never lives in this file.
+  #
+  #     basic_auth:
+  #       username: admin
+  #       password_secret: WEB_BASIC_AUTH_PASSWORD
+  #
+  # `password` sets the value directly. If you use it, interpolate rather than
+  # committing a literal:
+  #
+  #     basic_auth:
+  #       username: admin
+  #       password: <%= ENV["WEB_BASIC_AUTH_PASSWORD"] %>
+  #
+  basic_auth:
+    username: admin
+    password: <%= ENV["WEB_BASIC_AUTH_PASSWORD"] %>
+    password_secret: WEB_BASIC_AUTH_PASSWORD
+  #
+  # ### Notes
+  # - Requires a kamal-proxy that supports `--basic-auth`. This is newer than
+  #   the current `MINIMUM_VERSION`, so make sure your proxy is up to date
+  #   before enabling it — an older proxy fails the deploy on an unknown flag.
+  # - Basic credentials are replayable and are sent on every request. Use this
+  #   with `ssl: true`, or terminate TLS in front of the proxy.
+  # - kamal-proxy removes the `Authorization` header before forwarding, so a
+  #   service behind basic auth cannot also pass credentials through to its
+  #   target. When load balancing, the credentials are enforced by the load
+  #   balancer only.
+
+  # Dynamic TLS domains
+  #
+  # kamal-proxy can learn TLS hostnames from your application at runtime
+  # instead of fixing them at deploy time. It polls `source` — a path
+  # (resolved against a healthy app target) or an absolute http(s) URL —
+  # for the domain list and manages Let's Encrypt certificates for it
+  # automatically. When `source` is set, `ssl: true` is allowed without
+  # `host`/`hosts`.
+  #
+  # `interval` is the poll interval in seconds (proxy default: 300).
+  #
+  # `batch_size` controls how many domains share a certificate: 1 (the
+  # proxy default) issues per-domain certs; 2-25 enables stable SAN batching.
+  #
+  # Authentication tokens for the poll endpoint and the refresh nudge are
+  # read by the proxy from the `KAMAL_PROXY_DOMAINS_TOKEN` and
+  # `KAMAL_PROXY_REFRESH_TOKEN` environment variables. Set them on the proxy
+  # container via `proxy.run.options.env` — never as deploy flags, which
+  # leak into process listings and audit logs.
+  ssl_domains:
+    source: /api/v1/kamal/domains
+    interval: 300
+    batch_size: 1
+
+  # Who the client is
+  #
+  # Rate limiting and IP allow lists are both only as correct as the address they
+  # key on, so configure this first if anything sits in front of kamal-proxy.
+  #
+  # With no `trusted_proxies`, the client is always the address that opened the
+  # connection — nothing a client sends can influence it, which is what makes the
+  # allow list meaningful.
+  #
+  # Once you declare `trusted_proxies`, and only when the connecting address is
+  # one of them, kamal-proxy reads the forwarded chain instead: it walks the
+  # chain from the nearest hop backwards past every proxy you declared, and the
+  # first address none of your proxies wrote is the client. **List every hop**,
+  # not only the one that connects to kamal-proxy — a chain it cannot resolve
+  # denies the request rather than falling back to the connecting address.
+  #
+  # `header` names the header carrying the original client IP (`CF-Connecting-IP`
+  # behind Cloudflare, `True-Client-IP` behind some others); kamal-proxy reads it
+  # instead of `X-Forwarded-For`. It is only honoured when `trusted_proxies` is
+  # set, because otherwise it is just something the client wrote — kamal rejects
+  # that combination rather than appearing to honour it.
+  #
+  # Addresses and ranges are plain IPv4/IPv6 or CIDR. Write IPv4 as IPv4, not as
+  # an IPv4-mapped IPv6 range, and leave IPv6 zones off — neither matches
+  # anything. If clients reach you over IPv6, list IPv6 ranges too, or they are
+  # denied.
+  client_ip:
+    header: CF-Connecting-IP
+    trusted_proxies:
+      - 173.245.48.0/20
+      - 2400:cb00::/32
+
+  # Rate limiting
+  #
+  # A per-client token bucket. Requests over the limit get a 429. IPv6 clients
+  # are counted per /64, since one client can pick any address inside its own.
+  #
+  # `requests` is requests per second and may be fractional — 0.5 is one request
+  # every two seconds. `burst` is how many requests a client may make back to
+  # back before the limit applies (default: the rate, rounded up). `exempt` lists
+  # addresses and ranges the limit skips, for monitoring and health probes.
+  rate_limit:
+    requests: 100
+    burst: 20
+    exempt:
+      - 10.0.0.0/8
+
+  # IP allow list
+  #
+  # Serve this service only to these addresses and ranges; everything else gets a
+  # 403. Combine with `client_ip` above when you are behind a CDN, or the list is
+  # matched against the CDN's addresses rather than your visitors'.
+  allow_ips:
+    - 10.0.0.0/8
+    - 192.168.0.0/16
+  #
+  # ### Notes
+  # - The health check path is served without an address check and without a rate
+  #   limit, so it stays reachable during a deploy. That means it cannot be `/` —
+  #   kamal rejects `healthcheck: path: /` while either feature is on, because it
+  #   would leave the whole service open. The default `/up` is fine.
+  # - When a loadbalancer is configured, all of this moves to the loadbalancer:
+  #   the per-host proxies see the loadbalancer as their peer, so an allow list
+  #   there would refuse every request and one rate limiter would count the whole
+  #   fleet as a single client.
+
+
+  # ==========================================================================
+  # 4. Performance & observability
+  # ==========================================================================
+
+  # Two different deadlines
+  #
+  # `response_timeout` bounds how long the app may take to *start* answering —
+  # its clock stops once response headers arrive. `request_timeout` bounds the
+  # whole request, including streaming the body back to the client.
+  #
+  # They are not interchangeable, and the usual confusion is setting the first
+  # and still seeing requests hang: a slow trickle of body bytes never trips
+  # `response_timeout`, because the app answered promptly. WebSocket and
+  # event-stream responses are exempt from `request_timeout`.
+  #
+  # `response_timeout` defaults to 30 seconds; `request_timeout` defaults to 0,
+  # meaning no limit.
+  response_timeout: 10
+
+  request_timeout: 30
+
+  # Per-path timeouts
+  #
+  # Override either deadline below a path prefix. Values are Go duration strings
+  # ("90s", "5m") or plain seconds; 0 removes the limit for that prefix, which
+  # suits streaming and SSE endpoints.
+  path_response_timeouts:
+    "/api/reports": "5m"
+    "/stream": 0
+
+  path_request_timeouts:
+    "/uploads": "10m"
+    "/stream": 0
+
+  # Target connections and retries
+  #
+  # The connection pool between the proxy and this app's containers, and how
+  # hard the proxy tries to place a request on a healthy one.
+  #
+  # `max_conns` caps simultaneous connections per target, idle ones included.
+  # Requests over the cap queue rather than failing, and a streaming response
+  # holds its connection until the body closes — so pair a low cap with
+  # `request_timeout`. `max_idle_conns` caps the idle connections kept open.
+  # Both apply *per pool*, and every entry in `path_response_timeouts` adds another pool.
+  #
+  # `idle_conn_timeout` is how long an idle connection is kept; set it below the
+  # app's own keep-alive timeout, or the proxy will hand a request to a socket
+  # the app has already closed. `dial_timeout` bounds establishing a connection
+  # — `response_timeout` cannot cover that, since its clock starts only once the
+  # request has been written.
+  #
+  # `try_duration` keeps looking for a healthy target for that long before
+  # giving up, with `try_interval` between attempts. Only idempotent requests
+  # without a body are re-sent to another target.
+  #
+  # ### What 0 means here
+  #
+  # Not the same thing for every key, because the proxy resolves its own
+  # defaults from a zero:
+  #
+  # * `max_conns: 0` — unlimited
+  # * `try_duration: 0` — a single attempt, no retrying
+  # * `request_timeout: 0` — no limit
+  # * `max_idle_conns: 0` — the proxy's default of 100, **not** "keep none"
+  # * `idle_conn_timeout: 0` — the proxy's default of 90s
+  # * `dial_timeout: 0` — the proxy's default of 30s
+  # * `try_interval: 0` — the proxy's default of 250ms
+  #
+  # So there is no way to ask for zero idle connections; leave the key unset
+  # unless you mean to change it.
+  target:
+    max_conns: 100
+    max_idle_conns: 10
+    idle_conn_timeout: 90
+    dial_timeout: 5
+    disable_keep_alives: false
+    try_duration: 30
+    try_interval: 1
 
   # Buffering
   #
@@ -142,6 +566,113 @@ proxy:
     max_response_body: 0
     memory: 2_000_000
 
+  # Response compression
+  #
+  # Serve gzip, brotli or zstd without the app knowing about it. Responses the
+  # app already encoded, event streams, and media types that do not shrink are
+  # passed through untouched.
+  #
+  # `compress: true` is the common case: it offers zstd, br and gzip in that
+  # order — best ratio first, and the client's own `Accept-Encoding` preference
+  # still wins — and leaves the length and media-type defaults to the proxy.
+  #
+  #     compress: true
+  #
+  # The block form is for when you want something narrower. `encodings` names
+  # what to offer, most preferred first, from `gzip`, `br` (or `brotli`) and
+  # `zstd`; naming it is enough to switch compression on. `min_length` is the
+  # response size in bytes below which compressing costs more than it saves
+  # (proxy default 1024; set 1 to compress everything).
+  #
+  # An explicit `enabled: false` switches compression off even when `encodings`
+  # are named — it is the off switch for a block whose tuning you want to keep.
+  #
+  # `content_types` **replaces** the proxy's built-in list of compressible media
+  # types rather than adding to it, so name every type you want compressed, not
+  # just the extra ones. Entries are exact types or type wildcards. Note that
+  # `text/event-stream` is never compressed unless you name it here — holding
+  # bytes back to fill the encoder's window is exactly what an event stream's
+  # client asked you not to do.
+  compress:
+    enabled: true
+    encodings:
+      - zstd
+      - br
+      - gzip
+    content_types:
+      - text/html
+      - application/json
+    min_length: 1024
+
+  # Response cache
+  #
+  # An RFC 9111 shared cache in front of this service. Nothing is stored unless
+  # the app marks a response `public` with an `s-maxage` or `max-age`, and a
+  # response carrying `Set-Cookie` is refused unless `allow_set_cookie` says
+  # otherwise — a shared cache replaying one client's cookie to the next is the
+  # worst thing it could do.
+  #
+  # This block is the *policy*, and it is per service. Where the entries live is
+  # proxy-wide and set under `run/cache` below.
+  #
+  # Only `enabled` is required. Everything else keeps kamal-proxy's own default
+  # until you set it.
+  #
+  # `max_ttl` caps the lifetime the app asks for, in seconds, so one mistaken
+  # directive cannot pin content until the next deploy. `max_body` is the largest
+  # response body to store, in bytes — the same plain byte counts `buffering`
+  # uses. Bigger responses still reach the client, they are just not kept.
+  #
+  # `max_variants` is how many representations one URL may hold when the app
+  # negotiates with `Vary` (negative switches automatic variants off and refuses
+  # a varying response outright).
+  #
+  # `vary_headers` and `vary_cookies` add request headers and cookie names to the
+  # cache key for EVERY response this service stores. Headers the app already
+  # names in `Vary` are keyed automatically per URL and need no entry here —
+  # naming one moves it into the key for every path in the service, which is
+  # usually not what you want.
+  #
+  # ### Administering it
+  #
+  # `kamal proxy cache stats` reports what the cache is holding (add `--count`
+  # to measure entries and bytes per service, `--json` for the raw report),
+  # and `kamal proxy cache purge` drops this app's cached responses
+  # (`--path-prefix /assets` to narrow it). Both run on the layer that owns
+  # the cache - the loadbalancer when load balancing, else each proxy host.
+  #
+  # ### When it is not caching
+  #
+  # A cache that quietly stores nothing is the usual first surprise. Start with
+  # `kamal proxy cache stats`; kamal-proxy also explains every refusal — check
+  # `kamal proxy logs` for the reason, and the `cache_refusals_total` metric
+  # (by `reason`) if you run with `metrics_port`.
+  # The common reasons are a missing `Cache-Control: public, max-age=...` on the
+  # app's response, a `Set-Cookie` header, a body over `max_body`, and
+  # `variant_limit` from `max_variants`.
+  cache:
+    enabled: true
+    max_ttl: 300
+    max_body: 1_048_576
+    max_variants: 8
+    vary_headers:
+      - Accept-Encoding
+      - Accept-Language
+    vary_cookies:
+      - locale
+    allow_set_cookie: false
+
+  # Paths to leave out of the Prometheus metrics
+  #
+  # Request paths that should not be counted, typically health and readiness
+  # endpoints that would otherwise dominate the histograms.
+  #
+  # This is a per-service deploy setting even though it reads like metrics
+  # configuration — where the metrics are served and who may read them are
+  # proxy-wide and live under `run/metrics_port` and `run/metrics_allow_ips`.
+  exclude_metrics_paths:
+    - /up
+
   # Logging
   #
   # Configure request logging for the proxy.
@@ -155,6 +686,88 @@ proxy:
       - X-Request-ID
       - X-Request-Start
 
+
+  # ==========================================================================
+  # 5. Fleet — multi-host behaviour
+  # ==========================================================================
+
+  # Read-only targets
+  #
+  # kamal-proxy can split traffic between the deployed (writer) targets and a
+  # set of read-only targets, e.g. app instances backed by database replicas.
+  # Read requests are routed to the read targets; write requests always go to
+  # the writers.
+  #
+  # Targets are host:port addresses reachable from the proxy.
+  #
+  # `websockets` routes WebSocket traffic to the read targets too (default
+  # `false`). `writer_affinity_timeout` is how long, in seconds, a client's
+  # reads stick to the writer after it makes a write, so clients always read
+  # their own writes (default 1 second).
+  #
+  # When a loadbalancer fronts the fleet, read routing is decided there — at
+  # the only layer that sees the whole fleet.
+  read_routing:
+    targets:
+      - 192.168.0.2:3000
+      - 192.168.0.3:3000
+    websockets: true
+    writer_affinity_timeout: 10
+
+  # Session affinity
+  #
+  # Keep each client on the target that first served it, for apps holding session
+  # state in the instance. Off by default, and rightly so — every request is
+  # otherwise free to go to whichever target is best placed to serve it.
+  #
+  # The client carries an opaque HttpOnly cookie naming its target. When that
+  # target leaves the pool the next request falls through to another one and is
+  # re-pinned, so a deploy does not strand anybody. Reads served by a
+  # `read_targets` replica are never pinned.
+  #
+  # `cookie` renames the pin cookie; kamal-proxy picks a sensible default.
+  session_affinity:
+    enabled: true
+    cookie: _kamal_affinity
+
+  # Scale to zero
+  #
+  # Stop this service's containers after `after` seconds with no traffic, and
+  # start them again on the next request, which is held until they are healthy.
+  # Health checks and the proxy's own TLS probes are not traffic and never wake a
+  # sleeping service.
+  #
+  # `wake_timeout` is how long a request waits for the containers to come back
+  # before giving up with a 503. `containers` names the containers to stop and
+  # start, replacing what the proxy infers from the target address — needed when
+  # a target names a network alias rather than a container.
+  #
+  # ### This needs the container runtime socket
+  #
+  # Stopping and starting containers means talking to the runtime, so the proxy
+  # must have been booted with `run/docker_socket` set. That is a boot-time
+  # prerequisite for a deploy-time setting, so kamal checks it while reading this
+  # file rather than letting the first request hang.
+  #
+  # Setting `run/docker_socket` also mounts that socket into the proxy container
+  # — the flag alone only says where to look. **Reaching the container runtime
+  # socket is root-equivalent on the host**, which is why it is a separate,
+  # explicit setting and not something enabling sleep does for you.
+  #
+  # Not compatible with `tls/on_demand_url`: a sleeping target cannot answer the
+  # ask endpoint, and waking one would let any hostname on the internet start a
+  # container.
+  sleep:
+    after: 300
+    wake_timeout: 30
+    containers:
+      - app-web
+
+
+  # ==========================================================================
+  # 6. Proxy container (run)
+  # ==========================================================================
+
   # Run configuration
   #
   # These options are used when booting the proxy container.
@@ -168,11 +781,218 @@ proxy:
     publish: false                 # Publish ports to the host (default: true)
     bind_ips:                      # List of IPs to bind to when publishing ports
       - 0.0.0.0
-    registry: registry:4443        # Container registry for the kamal-proxy image
-                                   # (defaults to Docker Hub)
-    repository: myrepo/kamal-proxy # Container repository for the kamal-proxy image
-                                   # (defaults to `ghcr.io/mhenrixon/kamal-proxy`)
-    version: v0.8.0                # Version tag of the kamal-proxy image to use
+    registry: registry:4443        # Extra registry prefix for the kamal-proxy image
+                                   # (default: none). If you set this, also override
+                                   # `repository` to a host-less path (e.g.
+                                   # myfork/kamal-proxy) - the default repository
+                                   # below already embeds its ghcr.io host
+    repository: ghcr.io/mhenrixon/kamal-proxy # Container repository for the
+                                   # kamal-proxy image (this is the default)
+    version: v1.0.0.1              # Version tag of the kamal-proxy image to use.
+                                   # Defaults to the minimum version this gem
+                                   # requires - only pin it to roll forward early,
+                                   # never below the default
+    port_holder: true              # Zero-downtime proxy reboots (default: false).
+                                   # Runs a minimal long-lived kamal-proxy-net container that
+                                   # owns the published ports; proxy generations join its
+                                   # network namespace and overlap during a reboot, so config
+                                   # and version changes apply without dropping requests.
+                                   # Adopting (or leaving) this mode takes one final
+                                   # reboot with a brief gap.
+    # ACME / Let's Encrypt
+    #
+    # Certificate issuance for the whole proxy, including DNS-01 challenges.
+    # These are proxy-wide, not per-app: every service on this proxy shares the
+    # ACME account and the DNS provider.
+    #
+    # `dns_provider` names the provider that answers DNS-01 challenges. Leave it
+    # at `auto` to let the proxy pick from the credentials it can see. An
+    # unsupported name is rejected here, at config time - kamal-proxy would only
+    # log a warning and then never issue a certificate.
+    #
+    # kamal-proxy also accepts short aliases for the canonical names - `cf`
+    # (cloudflare), `do` (digitalocean), `gcp`/`google`/`googledns` (gcloud),
+    # `gd` (godaddy), `hz` (hetzner), `nc` (namecheap), `aws`/`r53` (route53)
+    # and `vr` (vultr). Prefer the canonical name; the aliases exist so a
+    # config written for the proxy's own CLI is not rejected here.
+    #
+    # `prefer_wildcard` asks for a wildcard certificate when the DNS provider
+    # supports one, and `http_fallback` falls back to an HTTP-01 challenge when
+    # DNS-01 fails. Both default to true in the proxy.
+    #
+    # `directory` overrides the ACME directory URL - point it at Let's Encrypt's
+    # staging environment while you are working out a DNS setup, so you do not
+    # burn production rate limits on failed attempts.
+    #
+    # `credentials` names entries in `.kamal/secrets` to pass to the proxy
+    # container as environment variables - the API credentials your DNS provider
+    # needs (`CF_API_TOKEN`, `LOOPIA_API_USER`, ...). Name them exactly as the
+    # provider expects them, since the name is what reaches the container.
+    #
+    # They are written to a 0600 env file on the proxy host and passed with
+    # `--env-file`, never on the command line: a DNS API token can rewrite your
+    # zone, and `docker run --env` would leave it in process listings and audit
+    # logs. Adding or renaming one changes the proxy's config digest, so the next
+    # deploy reboots the proxy to pick it up; rotating a value does not, so run
+    # `kamal proxy reboot` yourself after a rotation.
+    acme:
+      email: admin@example.com
+      dns_provider: cloudflare
+      prefer_wildcard: true
+      http_fallback: false
+      directory: https://acme-staging-v02.api.letsencrypt.org/directory
+      credentials:
+        - CF_API_TOKEN
+    # Logging and tracing
+    #
+    # `log_format` is the shape of every line the proxy writes, the access log
+    # included: `json` (the default) or `text`. `logfmt` is accepted as a name
+    # for `text`.
+    #
+    # `trace_context` decides what happens to the W3C `traceparent` header:
+    # `off` ignores it, `propagate` (the default) logs the trace an incoming
+    # request carries and forwards the header untouched, and `generate` also
+    # starts a trace when a request arrives without one.
+    log_format: json
+    trace_context: propagate
+
+    # TLS floor
+    #
+    # The lowest TLS version the HTTPS listener will negotiate: `1.2` (the
+    # default) or `1.3`. Quote it — unquoted YAML reads it as a number.
+    #
+    # This narrows what the listener accepts and cannot widen it. TLS 1.0 and
+    # 1.1 are refused outright, and HTTP/3 is always 1.3 regardless.
+    min_tls: "1.2"
+
+    # HTTP/3
+    #
+    # Offer HTTP/3 (QUIC) alongside HTTP/1.1 and HTTP/2. Needs UDP on the HTTPS
+    # port reachable as well as TCP.
+    #
+    # Defaults to false:
+    http3: true
+
+    # PROXY protocol
+    #
+    # Accept PROXY protocol v1/v2 headers on the HTTP and HTTPS listeners, so
+    # client addresses survive an L4 load balancer that cannot set
+    # `X-Forwarded-For`.
+    #
+    # **Set `proxy_protocol_allow_ips` with it.** Left empty, the proxy honours a
+    # PROXY header from any peer that can reach the port — and that header
+    # rewrites the connecting address every other feature keys on, including
+    # `allow_ips` and `rate_limit`. Kamal warns when you enable one without the
+    # other.
+    proxy_protocol: true
+    proxy_protocol_allow_ips:
+      - 10.0.0.0/8
+
+    # Metrics access
+    #
+    # Serve the metrics endpoint (see `metrics_port` above) only to these
+    # addresses or CIDR ranges. Empty means everyone who can reach the port.
+    #
+    # The metrics listener has no service behind it and matches the connecting
+    # address only — there is no forwarded chain to trust here, so
+    # `proxy/client_ip` does not apply.
+    #
+    # To leave paths out of the metrics themselves, see
+    # `proxy/exclude_metrics_paths`, which is a per-service deploy setting.
+    metrics_allow_ips:
+      - 10.0.0.0/8
+
+    # Server timeouts
+    #
+    # Connection-level deadlines for the proxy's own listeners, in seconds.
+    # These are proxy-wide; the per-service deadlines are `response_timeout` and
+    # `request_timeout` above.
+    #
+    # `read_header_timeout` bounds how long a client may take to send request
+    # headers. `read_timeout` bounds reading a whole request including its body,
+    # so a non-zero value truncates slow uploads. `write_timeout` bounds writing
+    # a whole response, so a non-zero value truncates SSE and streaming.
+    # `idle_timeout` is how long an idle keep-alive connection is kept.
+    #
+    # Zero disables each of them, and is a real value rather than "unset".
+    #
+    # `shutdown_timeout` is how long in-flight requests get to drain when the
+    # proxy stops.
+    read_header_timeout: 10
+    read_timeout: 30
+    write_timeout: 30
+    idle_timeout: 60
+    shutdown_timeout: 30
+
+    # Boot with an empty routing state when restoring the saved state fails,
+    # rather than refusing to start.
+    #
+    # Defaults to false:
+    ignore_restore_errors: true
+
+    # Bind listeners with SO_REUSEPORT, so an overlapping proxy generation can
+    # share the ports during a handoff.
+    #
+    # Defaults to false:
+    reuse_port: true
+
+    # Escape hatch for `kamal-proxy run`
+    #
+    # Anything kamal-proxy accepts that has no key above. Note the difference
+    # from `options` below, which many people expect to do this: `flags` goes to
+    # `kamal-proxy run`, `options` goes to `docker run`.
+    #
+    # `true` renders a bare flag; anything else renders `--flag value`. No
+    # translation is applied, so write Go durations and lists the way
+    # kamal-proxy wants them.
+    #
+    # A key here that a named setting already emits is rejected rather than
+    # passed twice — set one or the other.
+    flags:
+      some-new-flag: value
+
+    # Container runtime socket
+    #
+    # Path to the container runtime socket, which is what `proxy/sleep` needs in
+    # order to stop and start containers. Setting it does two things: it passes
+    # the path to kamal-proxy, and it mounts that path into the proxy container,
+    # since the flag alone only says where to look.
+    #
+    # **Reaching this socket is root-equivalent on the host.** It is a separate,
+    # explicit setting for exactly that reason — nothing else in deploy.yml turns
+    # it on for you.
+    #
+    # Defaults to none, with scale-to-zero disabled:
+    docker_socket: /var/run/docker.sock
+
+    # Response cache storage
+    #
+    # Where the entries cached by `proxy/cache` are kept. Proxy-wide: one store
+    # serves every service on this proxy, so unlike the policy above it belongs
+    # here, in the run configuration. Adding or removing it reboots the proxy
+    # on the next deploy.
+    #
+    # `store` is `memory` (the default — a per-node cache) or a `redis://` /
+    # `rediss://` URL that every proxy pointed at it shares, so one fetch warms
+    # the whole fleet.
+    #
+    # The URL never appears on the proxy's command line: kamal delivers it as
+    # `CACHE_STORE` in a 0600 env file on the host (alongside any ACME
+    # credentials), so a password in the URL stays out of process listings and
+    # kamal's audit log. The trade-off, same as the ACME credentials: changing
+    # only the URL's *value* does not move the drift digest — run
+    # `kamal proxy reboot` after rotating it.
+    #
+    # `store_timeout` only matters with a shared store, in seconds: how long
+    # the store may take to answer before the request goes to the app instead —
+    # a store that is slow or down then costs a cache, never a failed request.
+    cache:
+      store: redis://cache.example.com:6379/0
+      store_timeout: 2
+      memory_size: 134_217_728
+    # `options` are `docker run` options for the proxy container - resource
+    # limits, labels, extra mounts - NOT kamal-proxy flags. A kamal-proxy flag
+    # the gem has no key for goes in `flags` above instead.
     options:                       # Additional options to pass to `docker run`
       label:
         - custom.label=kamal-proxy