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 use 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

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