Deploy Configuration (deploy.yml)
Relevant source files
The following files were used as context for generating this wiki page:
The deploy.yml file serves as the central configuration authority for Kamal deployments. It defines the service identity, container images, target server infrastructure, and the operational parameters for both the primary application and its supporting accessories.
This configuration is processed by the Kamal::Configuration class, which handles YAML parsing, ERB evaluation for dynamic values, and strict validation of deployment constraints. It allows developers to define a "source of truth" for the entire deployment lifecycle, including environment variables, volume mappings, and proxy settings.
Sources: lib/kamal/configuration.rb:1-15, test/configuration_test.rb:6-25
Configuration Lifecycle and Evaluation
The configuration loading process follows a specific hierarchy to allow for environment-specific overrides and dynamic secret injection.
Loading Logic
Kamal loads the base deploy.yml and, if a destination is specified, merges it with a destination-specific file (e.g., deploy.production.yml). All files are evaluated as ERB templates before being parsed as YAML.
The loading mechanism uses YAML.unsafe_load (or load) on the ERB-rendered result to support advanced YAML features while ensuring symbols are correctly mapped for internal logic.
Sources: lib/kamal/configuration.rb:21-48, test/configuration_test.rb:195-210
Core Components
The configuration is structured into several top-level keys that define different aspects of the deployment.
1. Service and Image Identity
Identifies the application name and the Docker image repository. The service name is restricted to alphanumeric characters, hyphens, and underscores.
- service: The unique name of the application.
- image: The Docker image name (e.g.,
dhh/app). - registry: Credentials and server information for the Docker registry.
Sources: lib/kamal/configuration.rb:284, test/configuration_test.rb:11-15
2. Infrastructure: Servers and Roles
Servers can be defined as a simple list or categorized into roles (e.g., web, workers). Each role can have its own specific host list and overrides.
| Key | Description |
|---|---|
servers | List of IP addresses or a hash of roles. |
primary_role | The role used for primary tasks (defaults to web). |
allow_empty_roles | Boolean allowing roles with no hosts for specific scenarios. |
Sources: lib/kamal/configuration.rb:190-205, test/configuration_test.rb:21-30
3. Accessories
Accessories are long-running support containers (like databases or caches) that have their own lifecycle separate from the main application.
Accessories can be targeted to specific hosts using the host, hosts, or roles keys. They also support persistent data through directories and volumes.
Sources: test/configuration/accessory_test.rb:10-100, lib/kamal/configuration.rb:69-72
Validation Logic
Kamal performs extensive validation to prevent misconfigurations before reaching the server.
Essential Validations
The Kamal::Configuration initializer triggers a suite of checks:
- Presence:
service,registry, andimageare mandatory. - Service Name: Must match
/^[a-z0-9_-]+$/i. - Hosts: At least one server or accessory must be defined.
- SSL Consistency: Roles using SSL must have exactly one host unless a load balancer or custom certificates are provided.
Sources: lib/kamal/configuration.rb:261-295, lib/kamal/configuration/validator/proxy.rb:10-30
Secret Validation
The validate_secrets! method ensures that all referenced environment variables and registry passwords are present in the environment or secret files before the deployment begins.
Operational Parameters
The configuration controls the runtime behavior of Docker containers through various arguments.
Docker Arguments Mapping
Configuration keys are translated into specific Docker CLI flags during the build and boot phases.
| deploy.yml Key | Docker Flag | Derived From |
|---|---|---|
volumes | --volume | config.volume_args |
logging | --log-opt / --log-driver | config.logging_args |
env | --env / --env-file | role.env_args |
labels | --label | role.label_args |
Sources: lib/kamal/commands/app.rb:18-35, lib/kamal/configuration.rb:225-235
Timeouts and Retries
Operational safety is managed via timeout settings defined in the YAML:
- deploy_timeout: Seconds to wait for a successful boot (default: 30s).
- drain_timeout: Seconds to wait for requests to finish during a swap (default: 30s).
- readiness_delay: Seconds to wait before checking health after boot (default: 7s).
Sources: lib/kamal/configuration.rb:241-255, lib/kamal/cli/main.rb:450-455
Summary
The deploy.yml configuration is the structural backbone of Kamal. By combining ERB-powered YAML with a rigorous validation engine, it ensures that infrastructure definitions are both flexible and safe. It bridges the gap between high-level service definitions and low-level Docker execution, providing a consistent interface for managing complex multi-server and multi-role deployments.
Sources: lib/kamal/configuration.rb:1-15, test/configuration_test.rb:310-330