Configuration

deploy.yml

Everything config/deploy.yml can contain — destinations, roles, hooks, and every root-level setting.

Configuration is read from the config/deploy.yml.

Destinations#

When running commands, you can specify a destination with the -d flag, e.g., dash 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 dash docs registry:

registry:
  ...

Servers#

The servers to deploy to, optionally with custom roles, see dash docs servers:

servers:
  ...

Environment variables#

See dash 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 .dash/hooks (.kamal/hooks is still read when only that exists). See https://dash.zoolutions.llc/docs/hooks for every hook, when it fires, and its environment:

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 .dash/secrets (.kamal/secrets is still read when only that exists). dash 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 we retain per role, and how many 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#

Where dash keeps its runtime files on each host — per-app env and assets, the proxy's boot files and apps-config mount, loadbalancer service claims, deploy locks, and the audit log. Resolved against the SSH user's home, default .dash. A host still holding the pre-3.4 .kamal directory is renamed to .dash in place the next time dash takes a lock on it; nothing is rebooted.

The key is accepted but not yet honoured — the path is currently always .dash. Tracked separately from the stage-3 rename.

run_directory: .dash

SSH options#

See dash docs ssh:

ssh:
  ...

Builder options#

See dash docs builder:

builder:
  ...

Accessories#

Additional services to run in Docker, see dash docs accessory:

accessories:
  ...

Proxy#

Configuration for dash-proxy, see dash docs proxy:

proxy:
  ...

SSHKit#

See dash docs sshkit:

sshkit:
  ...

Boot options#

See dash docs boot:

boot:
  ...

Logging#

Docker logging configuration, see dash docs logging:

logging:
  ...

Output#

Configure output loggers (OTel, file), see dash docs output:

output:
  ...

Deploy report#

Advice printed under the deploy timing table, see dash docs report:

report:
  ...

Aliases#

Alias configuration, see dash docs alias:

aliases:
  ...

Generated from the gem's lib/dash/configuration/docs/configuration.yml — the same reference dash docs prints in your terminal, so this page always matches your installed version.