App Deployment Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
The App Deployment Lifecycle in Kamal manages the end-to-end process of delivering containerized web applications to servers. It encompasses initial setup, image building, delivery, orchestration of container boots, and maintenance of the running environment. Kamal leverages kamal-proxy to achieve zero-downtime deployments by seamlessly switching requests between old and new container versions.
The lifecycle is designed to work across multiple servers and roles (e.g., web, workers), utilizing SSHKit for remote command execution and Docker for process isolation.
Sources: README.md:3-8, lib/kamal/cli/main.rb:21-72
Orchestration Flow
The deployment process follows a strict sequence to ensure system stability and availability. This includes validating configuration, preparing the registry, executing hooks, and managing the state of containers on remote hosts.
Primary Deployment Sequence
The deploy command represents the standard lifecycle of an application update. It begins with local preparation and extends to remote host management.
The flow ensures that the infrastructure (proxy) is ready before application containers are manipulated.
Sources: lib/kamal/cli/main.rb:21-65
Core Components and Configurations
The lifecycle is governed by the Kamal::Configuration class, which parses the deploy.yml template and environment-specific overrides.
Configuration Parameters
The following table outlines key configuration options that influence the deployment lifecycle:
| Option | Type | Description | Default |
|---|---|---|---|
service | String | Unique name of the application | N/A |
image | String | Docker image name/repository | N/A |
servers | Hash/Array | Hosts mapped to specific roles | N/A |
retain_containers | Integer | Number of old containers to keep | 5 |
deploy_timeout | Integer | Seconds to wait for deployment | 30 |
drain_timeout | Integer | Seconds to allow requests to finish | 30 |
readiness_delay | Integer | Delay before stopping old container | 7 |
Sources: lib/kamal/configuration.rb:233-255, lib/kamal/cli/templates/deploy.yml:1-125
Application Booting and Readiness
The Kamal::Cli::App#boot method handles the actual starting of containers. It supports staggered rollouts through "boot groups" to prevent simultaneous downtime across all hosts.
Boot Sequence and Health Checks
- Asset Preparation: Before booting, error pages, assets, and SSL certificates are synchronized to the hosts.
- Grouped Execution: Hosts are divided into groups based on the
boot/limitconfiguration. - Readiness Barriers: Kamal uses a barrier pattern to ensure primary roles/hosts are ready before proceeding.
- Proxy Integration: If a role runs a proxy, the new container endpoint is registered with
kamal-proxy.
Version Management and Rollbacks
Kamal tracks versions using Docker tags and container names (formatted as service-role-destination-VERSION).
Rollback Logic
A rollback is a shortened deployment lifecycle that skips building and pulling. It attempts to find an existing container for the target version. If found, it boots that version and switches the proxy, effectively reverting the environment.
- Availability Check: Kamal verifies the container exists on the hosts via
container_id_for_version. - Execution: It invokes
kamal:cli:app:bootwith the specific version, triggering the same proxy-switching logic used in standard deploys.
Sources: lib/kamal/cli/main.rb:108-132, lib/kamal/commands/app.rb:73-82
Maintenance and Lifecycle Operations
The lifecycle includes states beyond "active," primarily managed through kamal-proxy integration.
Maintenance Mode
When maintenance is enabled, kamal-proxy is instructed to stop traffic to the app containers and optionally display a custom message or error page.
- Command:
kamal app maintenance - Internal Action: Executes
kamal-proxy stop <service-role>on the proxy hosts.
Cleanup (Pruning)
To prevent disk exhaustion, the lifecycle includes a pruning phase. Kamal removes old containers (beyond the retain_containers limit) and old images that are no longer referenced by the current or recent versions.
- Containers: Pruned by service and role labels.
- Images: Pruned by service label.
Sources: lib/kamal/cli/app.rb:259-272, lib/kamal/commands/app.rb:156-170, lib/kamal/cli/main.rb:58-61
Conclusion
The App Deployment Lifecycle in Kamal provides a robust framework for managing containerized applications with a focus on zero-downtime and automated orchestration. By integrating configuration validation, asset management, and proxy-aware booting, it ensures that application transitions are handled safely across complex, multi-role server environments.