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. ```yaml service: myapp ``` ## The Docker image name The image will be pushed to the configured registry. ```yaml image: my-image ``` ## Labels Additional labels to add to the container: ```yaml labels: my-label: my-value ``` ## Volumes Additional volumes to mount into the container: ```yaml volumes: - /path/on/host:/path/in/container:ro ``` ## Registry The Docker registry configuration, see dash docs registry: ```yaml registry: ... ``` ## Servers The servers to deploy to, optionally with custom roles, see dash docs servers: ```yaml servers: ... ``` ## Environment variables See dash docs env: ```yaml 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 ```yaml 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](https://dash.zoolutions.llc/docs/hooks) for every hook, when it fires, and its environment: ```yaml 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: ```yaml hooks_output: :verbose ``` Or per-hook settings: ```yaml 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 `-common` first and then ``. When using destinations, it instead looks for `-common` first and then `.`. Later files override earlier ones. ```yaml 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. ```yaml error_pages_path: public ``` ## Require destinations Whether deployments require a destination to be specified, defaults to `false`: ```yaml require_destination: true ``` ## Primary role This defaults to `web`, but if you have no web role, you can change this: ```yaml primary_role: workers ``` ## Allowing empty roles Whether roles with no servers are allowed. Defaults to `false`: ```yaml allow_empty_roles: false ``` ## Retain containers How many old containers we retain per role, and how many images we retain, defaults to 5: ```yaml retain_containers: 3 ``` ## Minimum version The minimum version of Kamal required to deploy this configuration, defaults to `nil`: ```yaml 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: ```yaml readiness_delay: 4 ``` ## Deploy timeout How long to wait for a container to become ready, default 30: ```yaml deploy_timeout: 10 ``` ## Drain timeout How long to wait for a container to drain, default 30: ```yaml 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: ```yaml 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. ```yaml run_directory: .dash ``` ## SSH options See dash docs ssh: ```yaml ssh: ... ``` ## Builder options See dash docs builder: ```yaml builder: ... ``` ## Accessories Additional services to run in Docker, see dash docs accessory: ```yaml accessories: ... ``` ## Proxy Configuration for dash-proxy, see dash docs proxy: ```yaml proxy: ... ``` ## SSHKit See dash docs sshkit: ```yaml sshkit: ... ``` ## Boot options See dash docs boot: ```yaml boot: ... ``` ## Logging Docker logging configuration, see dash docs logging: ```yaml logging: ... ``` ## Output Configure output loggers (OTel, file), see dash docs output: ```yaml output: ... ``` ## Deploy report Advice printed under the deploy timing table, see dash docs report: ```yaml report: ... ``` ## Aliases Alias configuration, see dash docs alias: ```yaml aliases: ... ``` > **Note:** 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.