# Technical Documentation: basecamp/kamal

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/basecamp/kamal)

### Overview (`README.md`)

# Kamal: Deploy web apps anywhere

From bare metal to cloud VMs, deploy web apps anywhere with zero downtime. Kamal uses [kamal-proxy](https://github.com/basecamp/kamal-proxy) to seamlessly switch requests between containers. Works seamlessly across multiple servers, using SSHKit to execute commands. Originally built for Rails apps, Kamal will work with any type of web app that can be containerized with Docker.

➡️ See [kamal-deploy.org](https://kamal-deploy.org) for documentation on [installation](https://kamal-deploy.org/docs/installation), [configuration](https://kamal-deploy.org/docs/configuration), and [commands](https://kamal-deploy.org/docs/commands).

## Contributing to the documentation

Please help us improve Kamal's documentation on [the basecamp/kamal-site repository](https://github.com/basecamp/kamal-site).

## License

Kamal is released under the [MIT License](https://opensource.org/licenses/MIT).

---

### Lib Kamal Configuration Docs Accessory.Yml (`lib/kamal/configuration/docs/accessory.yml`)

# Accessories
#
# Accessories can be booted on a single host, a list of hosts, or on specific roles.
# The hosts do not need to be defined in the Kamal servers configuration.
#
# Accessories are managed separately from the main service — they are not updated
# when you deploy, and they do not have zero-downtime deployments.
#
# Run `kamal accessory boot <accessory>` to boot an accessory.
# See `kamal accessory --help` for more information.

# Configuring accessories
#
# First, define the accessory in the `accessories`:
accessories:
  mysql:

    # Service name
    #
    # This is used in the service label and defaults to `<service>-<accessory>`,
    # where `<service>` is the main service name from the root configuration:
    service: mysql

    # Image
    #
    # The Docker image to use.
    # Prefix it with its server when using root level registry different from Docker Hub.
    # Define registry directly or via anchors when it differs from root level registry.
    image: mysql:8.0

    # Registry
    #
    # By default accessories use Docker Hub registry.
    # You can specify different registry per accessory with this option.
    # Don't prefix image with this registry server.
    # Use anchors if you need to set the same specific registry for several accessories.
    #
    # ```yml
    # registry:
    #   <<: *specific-registry
    # ```
    #
    # See kamal docs registry for more information:
    registry:
      ...

    # Accessory hosts
    #
    # Specify one of `host`, `hosts`, `role`, `roles`, `tag` or `tags`:
    host: mysql-db1
    hosts:
      - mysql-db1
      - mysql-db2
    role: mysql
    roles:
      - mysql
    tag: writer
    tags:
      - writer
      - reader

    # Custom command
    #
    # You can set a custom command to run in the container if you do not want to use the default:
    cmd: "bin/mysqld"

    # Port mappings
    #
    # A bind address is required — Kamal will not guess on a security-relevant choice.
    # Use the full `ip:host:container` form (or the bracketed `[ip]:host:container`
    # form for IPv6) and choose the bind address explicitly:
    #
    #   "127.0.0.1:3306:3306"  binds localhost only (private — the usual choice for
    #                          databases, caches, and other backing services)
    #   "0.0.0.0:3306:3306"    binds all interfaces (public — reachable from the
    #                          internet; only use this when you really mean it)
    #   "[::1]:3306:3306"      IPv6 localhost
    #
    # See [https://docs.docker.com/engine/network/port-publishing/](https://docs.docker.com/engine/network/port-publishing/),
    # and especially note the security implications of exposing ports publicly.
    port: "127.0.0.1:3306:3306"

    # Labels
    labels:
      app: myapp

    # Options
    #
    # These are passed to the Docker run command in the form `--<name> <value>`:
    options:
      restart: always
      cpus: 2

    # Environment variables
    #
    # See kamal docs env for more information:
    env:
      ...

    # Copying files
    #
    # You can specify files to mount into the container.
    #
    # They will be uploaded from the local repo to the host and then mounted.
    # ERB files will be evaluated before being copied.
    #
    # You can use the string format: `local:remote` or `local:remote:options`
    # where the options can be `ro` for read-only or `z`/`Z` for SELinux labels
    files:
      - config/my.cnf.erb:/etc/mysql/my.cnf
      - config/myoptions.cnf:/etc/mysql/myoptions.cnf:ro
      - config/certs:/etc/mysql/certs:ro,Z
    #
    # Or you can use the hash format for custom mode and ownership.
    #
    # Note: Setting `owner` requires root access:
    files:
      - local: config/secret.key
        remote: /etc/mysql/secret.key
        mode: "0600"
        owner: "mysql:mysql"
      - local: config/ca-cert.pem
        remote: /etc/mysql/certs/ca-cert.pem
        mode: "0644"
        owner: "1000:1000"
        options: "Z"

    # Directories
    #
    # You can specify directories to mount into the container. They will be created on the host
    # before being mounted.
    #
    # You can use the string format: `local:remote` or `local:remote:options`
    # where the options can be `ro` for read-only or `z`/`Z` for SELinux labels
    directories:
      - mysql-logs:/var/log/mysql
      - mysql-data:/var/lib/mysql:z
    #
    # Or you can use the hash format for custom mode and ownership.
    #
    # Note: Setting `owner` requires root access:
    directories:
      - local: mysql-data
        remote: /var/lib/mysql
        mode: "0750"
        owner: "mysql:mysql"
      - local: mysql-logs
        remote: /var/log/mysql
        mode: "0755"
        options: "z"

    # Volumes
    #
    # Any other volumes to mount, in addition to the files and directories.
    # They are not created or copied before mounting:
    volumes:
      - /path/to/mysql-logs:/var/log/mysql

    # Network
    #
    # The network the accessory will be attached to.
    #
    # Defaults to kamal:
    network: custom

    # Proxy
    #
    # You can run your accessory behind the Kamal proxy. See kamal docs proxy for more information
    proxy:
      ...

---

### Lib Kamal Configuration Docs Alias.Yml (`lib/kamal/configuration/docs/alias.yml`)

# Aliases
#
# Aliases are shortcuts for Kamal commands.
#
# For example, for a Rails app, you might open a console with:
#
# ```shell
# kamal app exec -i --reuse "bin/rails console"
# ```
#
# By defining an alias, like this:
aliases:
  console: app exec -i --reuse "bin/rails console"
# You can now open the console with:
#
# ```shell
# kamal console
# ```

# Configuring aliases
#
# Aliases are defined in the root config under the alias key.
#
# Each alias is named and can only contain lowercase letters, numbers, dashes, and underscores:
aliases:
  uname: app exec -p -q -r web "uname -a"
#
# Aliases can include a destination with the `-d` flag:
  staging_deploy: deploy -d staging

---

### Lib Kamal Configuration Docs Boot.Yml (`lib/kamal/configuration/docs/boot.yml`)

# Booting
#
# When deploying to large numbers of hosts, you might prefer not to restart your services on every host at the same time.
#
# Kamal’s default is to boot new containers on all hosts in parallel. However, you can control this with the boot configuration.

boot:

  # The number or percentage of hosts to boot at a time.
  # This can be an integer (e.g., 3) or a percentage string (e.g., 25%).
  limit: 25%

  # The number of seconds to wait between booting each group of hosts.
  wait: 10

  # Whether to boot roles in parallel on a host.
  #
  # If a host has multiple roles, control whether they are booted in parallel or sequentially on that host.
  #
  # Defaults to false.
  parallel_roles: true

---

### Lib Kamal Configuration Docs Builder.Yml (`lib/kamal/configuration/docs/builder.yml`)

# Builder
#
# The builder configuration controls how the application is built with `docker build`.
#
# See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information.

# Builder options
#
# Options go under the builder key in the root configuration.
builder:

  # Arch
  #
  # The architectures to build for — you can set an array or just a single value.
  #
  # Allowed values are `amd64` and `arm64`:
  arch:
    - amd64

  # Remote
  #
  # The connection string for a remote builder. If supplied, Kamal will use this
  # for builds that do not match the local architecture of the deployment host.
  remote: ssh://docker@docker-builder

  # Local
  #
  # If set to false, Kamal will always use the remote builder even when building
  # the local architecture.
  #
  # Defaults to true:
  local: true

  # Buildpack configuration
  #
  # The build configuration for using pack to build a Cloud Native Buildpack image.
  #
  # For additional buildpack customization options you can create a project descriptor
  # file(project.toml) that the Pack CLI will automatically use.
  # See https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/use-project-toml/ for more information.
  pack:
    builder: heroku/builder:24
    buildpacks:
      - heroku/ruby
      - heroku/procfile

  # Builder cache
  #
  # The type must be either 'gha' or 'registry'.
  #
  # The image is only used for registry cache and is not compatible with the Docker driver:
  cache:
    type: registry
    options: mode=max
    image: kamal-app-build-cache

  # Build context
  #
  # If this is not set, then a local Git clone of the repo is used.
  # This ensures a clean build with no uncommitted changes.
  #
  # To use the local checkout instead, you can set the context to `.`, or a path to another directory.
  context: .

  # Dockerfile
  #
  # The Dockerfile to use for building, defaults to `Dockerfile`:
  dockerfile: Dockerfile.production

  # Build target
  #
  # If not set, then the default target is used:
  target: production

  # Build arguments
  #
  # Any additional build arguments, passed to `docker build` with `--build-arg <key>=<value>`:
  args:
    ENVIRONMENT: production

  # Referencing build arguments
  #
  # ```shell
  # ARG RUBY_VERSION
  # FROM ruby:$RUBY_VERSION-slim as base
  # ```

  # Build secrets
  #
  # Values are read from `.kamal/secrets`:
  secrets:
    - SECRET1
    - SECRET2

  # Referencing build secrets
  #
  # ```shell
  # # Copy Gemfiles
  # COPY Gemfile Gemfile.lock ./
  #
  # # Install dependencies, including private repositories via access token
  # # Then remove bundle cache with exposed GITHUB_TOKEN
  # RUN --mount=type=secret,id=GITHUB_TOKEN \
  #   BUNDLE_GITHUB__COM=x-access-token:$(cat /run/secrets/GITHUB_TOKEN) \
  #   bundle install && \
  #   rm -rf /usr/local/bundle/cache
  # ```

  # SSH
  #
  # SSH agent socket or keys to expose to the build:
  ssh: default=$SSH_AUTH_SOCK

  # Driver
  #
  # The build driver to use, defaults to `docker-container`:
  driver: docker
  #
  # If you want to use Docker Build Cloud (https://www.docker.com/products/build-cloud/), you can set the driver to:
  driver: cloud org-name/builder-name

  # Provenance
  #
  # It is used to configure provenance attestations for the build result.
  # The value can also be a boolean to enable or disable provenance attestations.
  provenance: mode=max

  # SBOM (Software Bill of Materials)
  #
  # It is used to configure SBOM generation for the build result.
  # The value can also be a boolean to enable or disable SBOM generation.
  sbom: true

---

### Lib Kamal Configuration Docs Configuration.Yml (`lib/kamal/configuration/docs/configuration.yml`)

# Kamal Configuration
#
# Configuration is read from the `config/deploy.yml`.

# Destinations
#
# When running commands, you can specify a destination with the `-d` flag,
# e.g., `kamal deploy -d staging`.
#
# In this case, the configuration will also be read from `config/deploy.staging.yml`
# and merged with the base configuration.

# Extensions
#
# Kamal will not accept unrecognized keys in the configuration file.
#
# However, you might want to declare a configuration block using YAML anchors
# and aliases to avoid repetition.
#
# You can prefix a configuration section with `x-` to indicate that it is an
# extension. Kamal will ignore the extension and not raise an error.

# The service name
#
# This is a required value. It is used as the container name prefix.
service: myapp

# The Docker image name
#
# The image will be pushed to the configured registry.
image: my-image

# Labels
#
# Additional labels to add to the container:
labels:
  my-label: my-value

# Volumes
#
# Additional volumes to mount into the container:
volumes:
  - /path/on/host:/path/in/container:ro

# Registry
#
# The Docker registry configuration, see kamal docs registry:
registry:
  ...

# Servers
#
# The servers to deploy to, optionally with custom roles, see kamal docs servers:
servers:
  ...

# Environment variables
#
# See kamal docs env:
env:
  ...

# Asset path
#
# Used for asset bridging across deployments, default to `nil`.
#
# If there are changes to CSS or JS files, we may get requests
# for the old versions on the new container, and vice versa.
#
# To avoid 404s, we can specify an asset path.
# Kamal will replace that path in the container with a mapped
# volume containing both sets of files.
# This requires that file names change when the contents change
# (e.g., by including a hash of the contents in the name).
#
# To configure this, set the path to the assets.
#
# You can also specify mount options after a colon, such as `ro` for read-only
# or `z`/`Z` for SELinux labels
asset_path: /path/to/assets

# Hooks path
#
# Path to hooks, defaults to `.kamal/hooks`.
# See https://kamal-deploy.org/docs/hooks for more information:
hooks_path: /user_home/kamal/hooks

# Hook output
#
# Hook output visibility. Can be set globally or per-hook.
# CLI flags (`-v`, `-q`) override these settings.
#
# - `:quiet` - hook output is hidden
# - `:verbose` - hook output is shown
#
# With no setting, hook output follows CLI verbosity flags.
#
# Note: Failed hooks always show output in the error message regardless of setting.
#
# Global setting for all hooks:
hooks_output: :verbose
# Or per-hook settings:
hooks_output:
  pre-deploy: :verbose
  pre-build: :quiet

# Secrets path
#
# Path to secrets, defaults to `.kamal/secrets`.
# Kamal looks for `<secrets_path>-common` first and then `<secrets_path>`.
# When using destinations, it instead looks for `<secrets_path>-common` first and then
# `<secrets_path>.<destination>`. Later files override earlier ones.
secrets_path: /user_home/kamal/secrets

# Error pages
#
# A directory relative to the app root to find error pages for the proxy to serve.
# Name each page after the HTTP status code it serves, e.g. 404.html, 500.html,
# 502.html, 503.html, and 504.html.
error_pages_path: public

# Require destinations
#
# Whether deployments require a destination to be specified, defaults to `false`:
require_destination: true

# Primary role
#
# This defaults to `web`, but if you have no web role, you can change this:
primary_role: workers

# Allowing empty roles
#
# Whether roles with no servers are allowed. Defaults to `false`:
allow_empty_roles: false

# Retain containers
#
# How many old containers and images we retain, defaults to 5:
retain_containers: 3

# Minimum version
#
# The minimum version of Kamal required to deploy this configuration, defaults to `nil`:
minimum_version: 1.3.0

# Readiness delay
#
# Seconds to wait for a container to boot after it is running, default 7.
#
# This only applies to containers that do not run a proxy or specify a healthcheck:
readiness_delay: 4

# Deploy timeout
#
# How long to wait for a container to become ready, default 30:
deploy_timeout: 10

# Drain timeout
#
# How long to wait for a container to drain, default 30:
drain_timeout: 10

# Stop timeout
#
# How long to wait for a container to stop after SIGTERM, default is
# the drain_timeout for non-proxied roles and 10s (Docker default) for proxied roles.
# Can be overridden per role:
stop_timeout: 30

# Run directory
#
# Directory to store kamal runtime files in on the host, default `.kamal`:
run_directory: /etc/kamal

# SSH options
#
# See kamal docs ssh:
ssh:
  ...

# Builder options
#
# See kamal docs builder:
builder:
  ...

# Accessories
#
# Additional services to run in Docker, see kamal docs accessory:
accessories:
  ...

# Proxy
#
# Configuration for kamal-proxy, see kamal docs proxy:
proxy:
  ...

# SSHKit
#
# See kamal docs sshkit:
sshkit:
  ...

# Boot options
#
# See kamal docs boot:
boot:
  ...

# Logging
#
# Docker logging configuration, see kamal docs logging:
logging:
  ...

# Output
#
# Configure output loggers (OTel, file), see kamal docs output:
output:
  ...

# Aliases
#
# Alias configuration, see kamal docs alias:
aliases:
  ...

---

### Lib Kamal Configuration Docs Env.Yml (`lib/kamal/configuration/docs/env.yml`)

# Environment variables
#
# Environment variables can be set directly in the Kamal configuration or
# read from `.kamal/secrets`.

# Reading environment variables from the configuration
#
# Environment variables can be set directly in the configuration file.
#
# These are passed to the `docker run` command when deploying.
env:
  DATABASE_HOST: mysql-db1
  DATABASE_PORT: 3306

# Secrets
#
# Kamal uses dotenv to automatically load environment variables from the configured secrets files.
#
# Common secrets across all destinations can be set in `.kamal/secrets-common`. Kamal looks for
# `.kamal/secrets-common` first, then `.kamal/secrets`, with later values overriding earlier ones.
#
# If you are using destinations, Kamal looks for `.kamal/secrets-common` first, then
# `.kamal/secrets.<destination>`. The non-destination `.kamal/secrets` file is not read when a
# destination is selected.
#
# This file can be used to set variables like `KAMAL_REGISTRY_PASSWORD` or database passwords.
# You can use variable or command substitution in the secrets file.
#
# ```shell
# KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
# RAILS_MASTER_KEY=$(cat config/master.key)
# ```
#
# You can also use [secret helpers](../../commands/secrets) for some common password managers.
#
# ```shell
# SECRETS=$(kamal secrets fetch ...)
#
# REGISTRY_PASSWORD=$(kamal secrets extract REGISTRY_PASSWORD $SECRETS)
# DB_PASSWORD=$(kamal secrets extract DB_PASSWORD $SECRETS)
# ```
#
# If you store secrets directly in `.kamal/secrets`, ensure that it is not checked into version control.
#
# To pass the secrets, you should list them under the `secret` key. When you do this, the
# other variables need to be moved under the `clear` key.
#
# Unlike clear values, secrets are not passed directly to the container
# but are stored in an env file on the host:
env:
  clear:
    DB_USER: app
  secret:
    - DB_PASSWORD

# Aliased secrets
#
# You can also alias secrets to other secrets using a `:` separator.
#
# This is useful when the ENV name is different from the secret name. For example, if you have two
# places where you need to define the ENV variable `DB_PASSWORD`, but the value is different depending
# on the context.
#
# ```shell
# SECRETS=$(kamal secrets fetch ...)
#
# MAIN_DB_PASSWORD=$(kamal secrets extract MAIN_DB_PASSWORD $SECRETS)
# SECONDARY_DB_PASSWORD=$(kamal secrets extract SECONDARY_DB_PASSWORD $SECRETS)
# ```
env:
  secret:
    - DB_PASSWORD:MAIN_DB_PASSWORD
  tags:
    secondary_db:
      secret:
        - DB_PASSWORD:SECONDARY_DB_PASSWORD
accessories:
  main_db_accessory:
    env:
      secret:
        - DB_PASSWORD:MAIN_DB_PASSWORD
  secondary_db_accessory:
    env:
      secret:
        - DB_PASSWORD:SECONDARY_DB_PASSWORD

# Tags
#
# Tags are used to add extra env variables to specific hosts.
# See kamal docs servers for how to tag hosts.
#
# Tags are only allowed in the top-level env configuration (i.e., not under a role-specific env).
#
# The env variables can be specified with secret and clear values as explained above.
env:
  tags:
    <tag1>:
      MYSQL_USER: monitoring
    <tag2>:
      clear:
        MYSQL_USER: readonly
      secret:
        - MYSQL_PASSWORD

# Example configuration
env:
  clear:
    MYSQL_USER: app
  secret:
    - MYSQL_PASSWORD
  tags:
    monitoring:
      MYSQL_USER: monitoring
    replica:
      clear:
        MYSQL_USER: readonly
      secret:
        - READONLY_PASSWORD

---

### Lib Kamal Configuration Docs Logging.Yml (`lib/kamal/configuration/docs/logging.yml`)

# Custom logging configuration
#
# Set these to control the Docker logging driver and options.

# Logging settings
#
# These go under the logging key in the configuration file.
#
# This can be specified at the root level or for a specific role.
logging:

  # Driver
  #
  # The logging driver to use, passed to Docker via `--log-driver`:
  driver: json-file

  # Options
  #
  # Any logging options to pass to the driver, passed to Docker via `--log-opt`:
  options:
    max-size: 100m

---

### Lib Kamal Configuration Docs Output.Yml (`lib/kamal/configuration/docs/output.yml`)

# Output
#
# Configure where Kamal sends command output logs.

# Output options
#
# The options are specified under the output key in the configuration file.
output:

  # OTel
  #
  # Ship deploy logs to an OpenTelemetry-compatible endpoint via OTLP HTTP.
  #
  # Logs are sent as OTLP log records with resource attributes derived from
  # Kamal's deploy tags (service, version, performer, destination, etc.)
  otel:
    endpoint: http://otel-gateway:4318

  # File
  #
  # Write deploy logs to a file on the local machine.
  #
  # One log file is created per deploy, named with the timestamp and command.
  file:
    path: /var/log/kamal/

---

### Lib Kamal Configuration Docs Proxy.Yml (`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: 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.
  # Usage sample: path_prefix: '/api'
  #
  # You can also specify multiple paths in two ways.
  #
  # 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.
  #
  # 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

  # Run configuration
  #
  # These options are used when booting the proxy container.
  #
  run:
    http_port: 8080                # HTTP port to use (default 80)
    https_port: 8443               # HTTPS port to use (default 443)
    metrics_port: 9090             # Port for Prometheus metrics
    debug: true                    # Debug logging (default: false)
    log_max_size: "30m"            # Maximum log file size (default: "10m")
    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 `basecamp/kamal-proxy`)
    version: v0.8.0                # Version tag of the kamal-proxy image to use
    options:                       # Additional options to pass to `docker run`
      label:
        - custom.label=kamal-proxy
      memory: 512m
      cpus: 0.5

# 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
# ```

---

### Lib Kamal Configuration Docs Registry.Yml (`lib/kamal/configuration/docs/registry.yml`)

# Registry
#
# The default registry is Docker Hub, but you can change it using `registry/server`.

# Using a local container registry
#
# If the registry server starts with `localhost`, Kamal will start a local Docker registry
# on that port and push the app image to it.
registry:
  server: localhost:5555

# Using Docker Hub as the container registry
#
# By default, Docker Hub creates public repositories. To avoid making your images public,
# set up a private repository before deploying, or change the default repository privacy
# settings to private in your [Docker Hub settings](https://hub.docker.com/repository-settings/default-privacy).
#
# A reference to a secret (in this case, `KAMAL_REGISTRY_PASSWORD`) will look up the secret
# in the local environment:
registry:
  username:
    - <your docker hub username>
  password:
    - KAMAL_REGISTRY_PASSWORD

# Using AWS ECR as the container registry
#
# You will need to have the AWS CLI installed locally for this to work.
# AWS ECR’s access token is only valid for 12 hours. In order to avoid having to manually regenerate the token every time, you can use ERB in the `deploy.yml` file to shell out to the AWS CLI command and obtain the token:
registry:
  server: <your aws account id>.dkr.ecr.<your aws region id>.amazonaws.com
  username: AWS
  password: <%= %x(aws ecr get-login-password) %>

# Using GCP Artifact Registry as the container registry
#
# To sign into Artifact Registry, you need to
# [create a service account](https://cloud.google.com/iam/docs/service-accounts-create#creating)
# and [set up roles and permissions](https://cloud.google.com/artifact-registry/docs/access-control#permissions).
# Normally, assigning the `roles/artifactregistry.writer` role should be sufficient.
#
# Once the service account is ready, you need to generate and download a JSON key and base64 encode it:
#
# ```shell
# base64 -i /path/to/key.json | tr -d "\\n"
# ```
#
# You'll then need to set the `KAMAL_REGISTRY_PASSWORD` secret to that value.
#
# Use the environment variable as the password along with `_json_key_base64` as the username.
# Here’s the final configuration:
registry:
  server: <your registry region>-docker.pkg.dev
  username: _json_key_base64
  password:
    - KAMAL_REGISTRY_PASSWORD

# Validating the configuration
#
# You can validate the configuration by running:
#
# ```shell
# kamal registry login
# ```

---

### Lib Kamal Configuration Docs Role.Yml (`lib/kamal/configuration/docs/role.yml`)

# Roles
#
# Roles are used to configure different types of servers in the deployment.
# The most common use for this is to run web servers and job servers.
#
# Kamal expects there to be a `web` role, unless you set a different `primary_role`
# in the root configuration.

# Role configuration
#
# Roles are specified under the servers key:
servers:

  # Simple role configuration
  #
  # This can be a list of hosts if you don't need custom configuration for the role.
  #
  # You can set tags on the hosts for custom env variables (see kamal docs env):
  web:
    - 172.1.0.1
    - 172.1.0.2: experiment1
    - 172.1.0.2: [ experiment1, experiment2 ]

  # Custom role configuration
  #
  # When there are other options to set, the list of hosts goes under the `hosts` key.
  #
  # By default, only the primary role uses a proxy.
  #
  # For other roles, you can set it to `proxy: true` to enable it and inherit the root proxy
  # configuration or provide a map of options to override the root configuration.
  #
  # For the primary role, you can set `proxy: false` to disable the proxy.
  #
  # You can also set a custom `cmd` to run in the container and overwrite other settings
  # from the root configuration.
  workers:
    hosts:
      - 172.1.0.3
      - 172.1.0.4: experiment1
    cmd: "bin/jobs"
    stop_timeout: 30
    options:
      memory: 2g
      cpus: 4
    logging:
      ...
    proxy:
      ...
    labels:
      my-label: workers
    env:
      ...
    asset_path: /public

---

### Lib Kamal Configuration Docs Servers.Yml (`lib/kamal/configuration/docs/servers.yml`)

# Servers
#
# Servers are split into different roles, with each role having its own configuration.
#
# For simpler deployments, though, where all servers are identical, you can just specify a list of servers.
# They will be implicitly assigned to the `web` role.
servers:
  - 172.0.0.1
  - 172.0.0.2
  - 172.0.0.3

# Tagging servers
#
# Servers can be tagged, with the tags used to add custom env variables (see kamal docs env).
servers:
  - 172.0.0.1
  - 172.0.0.2: experiments
  - 172.0.0.3: [ experiments, three ]

# Roles
#
# For more complex deployments (e.g., if you are running job hosts), you can specify roles and configure each separately (see kamal docs role):
servers:
  web:
    ...
  workers:
    ...

---

### Lib Kamal Configuration Docs Ssh.Yml (`lib/kamal/configuration/docs/ssh.yml`)

# SSH configuration
#
# Kamal uses SSH to connect and run commands on your hosts.
# By default, it will attempt to connect to the root user on port 22.
#
# If you are using a non-root user, you may need to bootstrap your servers manually before using them with Kamal. On Ubuntu, you’d do:
#
# ```shell
# sudo apt update
# sudo apt upgrade -y
# sudo apt install -y docker.io curl git
# sudo usermod -a -G docker app
# ```

# SSH options
#
# The options are specified under the ssh key in the configuration file.
ssh:

  # The SSH user
  #
  # Defaults to `root`:
  user: app

  # The SSH port
  #
  # Defaults to 22:
  port: "2222"

  # Proxy host
  #
  # Specified in the form <host> or <user>@<host>:
  proxy: root@proxy-host

  # Proxy command
  #
  # A custom proxy command, required for older versions of SSH:
  proxy_command: "ssh -W %h:%p user@proxy"

  # Log level
  #
  # Defaults to `fatal`. Set this to `debug` if you are having SSH connection issues.
  log_level: debug

  # Keys only
  #
  # Set to `true` to use only private keys from the `keys` and `key_data` parameters,
  # even if ssh-agent offers more identities. This option is intended for
  # situations where ssh-agent offers many different identities or you
  # need to overwrite all identities and force a single one.
  keys_only: false

  # Keys
  #
  # An array of file names of private keys to use for public key
  # and host-based authentication:
  keys: [ "~/.ssh/id.pem" ]

  # Key data
  #
  # An array of strings, with each element of the array being a secret name.
  key_data:
    - SSH_PRIVATE_KEY
  # You can also provide raw private key in PEM format, but this is deprecated.
  key_data:
    - "-----BEGIN OPENSSH PRIVATE KEY----- ..."

  # Config
  #
  # Set to true to load the default OpenSSH config files (~/.ssh/config,
  # /etc/ssh_config), to false ignore config files, or to a file path
  # (or array of paths) to load specific configuration. Defaults to true.
  config: [ "~/.ssh/myconfig" ]

  # Forward agent
  #
  # Whether to forward the local SSH agent to the remote host. Defaults to
  # true (sshkit's default). Set to false when connecting through a jump
  # host or tunnel that does not support agent forwarding (for example,
  # Cloudflare Access for Infrastructure with SSH).
  forward_agent: false

---

### Lib Kamal Configuration Docs Sshkit.Yml (`lib/kamal/configuration/docs/sshkit.yml`)

# SSHKit
#
# [SSHKit](https://github.com/capistrano/sshkit) is the SSH toolkit used by Kamal.
#
# The default, settings should be sufficient for most use cases, but
# when connecting to a large number of hosts, you may need to adjust.

# SSHKit options
#
# The options are specified under the sshkit key in the configuration file.
sshkit:

  # Max concurrent starts
  #
  # Creating SSH connections concurrently can be an issue when deploying to many servers.
  # By default, Kamal will limit concurrent connection starts to 30 at a time.
  max_concurrent_starts: 10

  # Pool idle timeout
  #
  # Kamal sets a long idle timeout of 900 seconds on connections to try to avoid
  # re-connection storms after an idle period, such as building an image or waiting for CI.
  pool_idle_timeout: 300

  # DNS retry settings
  #
  # Some resolvers (mDNSResponder, systemd-resolved, Tailscale) can drop lookups during
  # bursts of concurrent SSH starts. Kamal will retry DNS failures automatically.
  #
  # Number of retries after the initial attempt. Set to 0 to disable.
  dns_retries: 3

---

--- METRICS ---
- Files Extracted: 15
- Estimated Token Budget: ~9285 tokens
- Canonical Reference: https://codewiki.google/github.com/basecamp/kamal