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 Docker Registry:

registry:
  ...

Servers

The servers to deploy to, optionally with custom roles, see Servers:

servers:
  ...

Environment variables

See Environment variables:

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 Hooks for more information:

hooks_path: /user_home/kamal/hooks

Secrets path

Path to secrets, defaults to .kamal/secrets. Kamal will look for <secrets_path>-common and <secrets_path> (or <secrets_path>.<destination> when using destinations):

secrets_path: /user_home/kamal/secrets

Error pages

A directory relative to the app root to find error pages for the proxy to serve. Any files in the format 4xx.html or 5xx.html will be copied to the hosts.

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

Run directory

Directory to store kamal runtime files in on the host, default .kamal:

run_directory: /etc/kamal

SSH options

See SSH:

ssh:
  ...

Builder options

See Builders:

builder:
  ...

Accessories

Additional services to run in Docker, see Accessories:

accessories:
  ...

Proxy

Configuration for kamal-proxy, see Proxy:

proxy:
  ...

SSHKit

See SSHKit:

sshkit:
  ...

Boot options

See Booting:

boot:
  ...

Logging

Docker logging configuration, see Logging:

logging:
  ...

Aliases

Alias configuration, see Aliases:

aliases:
  ...