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

# Proxy
#
# Kamal uses [kamal-proxy](https://github.com/basecamp/kamal-proxy) to provide
# gapless deployments. It runs on ports 80 and 443 and forwards requests to the
# application container.
#
# The proxy is configured in the root configuration under `proxy`. These are
# options that are set when deploying the application, not when booting the proxy.
#
# They are application-specific, so they are not shared when multiple applications
# run on the same proxy.
#
proxy:

  # Hosts
  #
  # The hosts that will be used to serve the app. The proxy will only route requests
  # to this host to your app.
  #
  # If no hosts are set, then all requests will be forwarded, except for matching
  # requests for other apps deployed on that server that do have a host set.
  #
  # Specify one of `host` or `hosts`.
  host: foo.example.com
  hosts:
    - foo.example.com
    - bar.example.com

  # App port
  #
  # The port the application container is exposed on.
  #
  # Defaults to 80:
  app_port: 3000

  # SSL
  #
  # kamal-proxy can provide automatic HTTPS for your application via Let's Encrypt.
  #
  # This requires that we are deploying to one server and the host option is set.
  # The host value must point to the server we are deploying to, and port 443 must be
  # open for the Let's Encrypt challenge to succeed.
  #
  # If you set `ssl` to `true`, `kamal-proxy` will stop forwarding headers to your app,
  # unless you explicitly set `forward_headers: true`
  #
  # Defaults to `false`:
  ssl: ...

  # Custom SSL certificate
  #
  # In some cases, using Let's Encrypt for automatic certificate management is not an
  # option, or you may already have SSL certificates issued by a different
  # Certificate Authority (CA). Kamal supports loading custom SSL certificates
  # directly from secrets.
  #
  # Examples:
  #   ssl: true              # Enable SSL with Let's Encrypt
  #   ssl: false             # Disable SSL
  #   ssl:                   # Enable custom SSL
  #     certificate_pem: CERTIFICATE_PEM
  #     private_key_pem: PRIVATE_KEY_PEM

  # SSL redirect
  #
  # By default, kamal-proxy will redirect all HTTP requests to HTTPS when SSL is enabled.
  # If you prefer that HTTP traffic is passed through to your application (along with
  # 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.
  #
  # 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

  # Response timeout
  #
  # How long to wait for requests to complete before timing out, defaults to 30 seconds:
  response_timeout: 10

  # Path-based routing
  #
  # For applications that split their traffic to different services based on the request path,
  # you can use path-based routing to mount services under different path prefixes.
  path_prefix: '/api'
  # 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.
  # To instead forward the request with the original path (including the prefix),
  # specify --strip-path-prefix=false
  strip_path_prefix: false

  # Healthcheck
  #
  # 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.
  healthcheck:
    interval: 3
    path: /health
    timeout: 3

  # Buffering
  #
  # Whether to buffer request and response bodies in the proxy.
  #
  # By default, buffering is enabled with a max request body size of 1GB and no limit
  # for response size.
  #
  # You can also set the memory limit for buffering, which defaults to 1MB; anything
  # larger than that is written to disk.
  buffering:
    requests: true
    responses: true
    max_request_body: 40_000_000
    max_response_body: 0
    memory: 2_000_000

  # Logging
  #
  # Configure request logging for the proxy.
  # You can specify request and response headers to log.
  # By default, `Cache-Control`, `Last-Modified`, and `User-Agent` request headers are logged:
  logging:
    request_headers:
      - Cache-Control
      - X-Forwarded-Proto
    response_headers:
      - X-Request-ID
      - X-Request-Start

# Enabling/disabling the proxy on roles
#
# The proxy is enabled by default on the primary role but can be disabled by
# setting `proxy: false` in the primary role's configuration.
#
# ```yaml
# servers:
#   web:
#     hosts:
#      - ...
#     proxy: false
# ```
#
# It is disabled by default on all other roles but can be enabled by setting
# `proxy: true` or providing a proxy configuration for that role.
#
# ```yaml
# servers:
#   web:
#     hosts:
#      - ...
#   web2:
#     hosts:
#      - ...
#     proxy: true
# ```