Kamal Configuration

Configuration is read from the config/deploy.yml

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.

The available configuration options are explained below.

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

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 Bridging

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:

asset_path: /path/to/assets

Path to hooks, defaults to .kamal/hooks

See Hooks for more information

hooks_path: /user_home/kamal/hooks

Require destinations

Whether deployments require a destination to be specified, defaults to false

require_destination: true

The 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

Stop wait time

How long we wait for a container to stop before killing it, defaults to 30 seconds

stop_wait_time: 60

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 is running, default 7 This only applies to containers that do not specify a healthcheck

readiness_delay: 4

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

Additionals services to run in Docker, see Accessories

accessories:
  ...

Traefik

The Traefik proxy is used for zero-downtime deployments, see Traefik

traefik:
  ...

SSHKit

See SSHKit

sshkit:
  ...

Boot options

See Booting

boot:
  ...

Healthcheck

Configuring healthcheck commands, intervals and timeouts, see Healthchecks

healthcheck:
  ...

Logging

Docker logging configuration, see Logging

logging:
  ...