kamal Documentation

Technical Documentation: basecamp/kamal

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Kamal: Deploy web apps anywhere

From bare metal to cloud VMs, deploy web apps anywhere with zero downtime. Kamal uses 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 for documentation on installation, configuration, and commands.

Contributing to the documentation Copy Chapter

Please help us improve Kamal's documentation on the basecamp/kamal-site repository.

License Copy Chapter

Kamal is released under the MIT License.

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

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 ` 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`) Copy Section

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`) Copy Section

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`) Copy Section

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 =`:

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`) Copy Section

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 `-common` first and then ``.

When using destinations, it instead looks for `-common` first and then

`.`. 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`) Copy Section

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.`. 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:
:
MYSQL_USER: monitoring
:
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`) Copy Section

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`) Copy Section

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`) Copy Section

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)
# (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`) Copy Section

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:
-
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: .dkr.ecr..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: -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`) Copy Section

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`) Copy Section

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`) Copy Section

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 or @:

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`) Copy Section

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