Proxy

Kamal uses 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: true

Custom SSL certificate

In some cases, using Let’s Encrypt for automatic certificate management is not an option, for example if you are running from more than one host.

Or you may already have SSL certificates issued by a different Certificate Authority (CA).

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.

  ssl:
    certificate_pem: CERTIFICATE_PEM
    private_key_pem: PRIVATE_KEY_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.

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.

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.

servers:
  web:
    hosts:
     - ...
  web2:
    hosts:
     - ...
    proxy: true