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
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:
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
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:
...