Introduction to Kamal
Relevant source files
The following files were used as context for generating this wiki page:
Kamal is a tool designed to deploy web applications anywhere—from bare metal to cloud VMs—with zero downtime. It leverages Docker for containerization and utilizes kamal-proxy to seamlessly switch requests between containers during deployments. While originally built for Ruby on Rails applications, it is compatible with any web application that can be containerized. Sources: README.md:3-8
The system works across multiple servers using SSHKit to execute remote commands. It manages the entire lifecycle of an application, including bootstrapping servers, managing accessories (like databases or Redis), handling zero-downtime deployments, and performing rollbacks. Sources: README.md:3-8, lib/kamal/cli/main.rb:3-130
System Architecture
Kamal is organized into a layered architecture that moves from high-level CLI commands down to low-level remote execution via SSH.
Architectural Layers
| Layer | Component | Responsibility |
|---|---|---|
| Layer 5 | bin/kamal | Entry point for the user, invoking the Thor-based CLI. |
| Layer 4 | Kamal::Cli::* | Thor command definitions, handling user input and hooks. |
| Layer 3 | Kamal::Commander | Singleton manager (KAMAL) for target resolution and state. |
| Layer 2 | Kamal::Commands::* | Logic for building specific Docker commands. |
| Layer 1 | Kamal::Configuration | Parsing deploy.yml into validated objects. |
| Layer 0 | SSHKit | Infrastructure for remote command execution over SSH. |
Sources: CLAUDE.md:33-40
Component Relationship Diagram
The following diagram illustrates the internal flow of a Kamal command from the CLI down to the execution on remote hosts.
Sources: CLAUDE.md:33-40, lib/kamal/commander.rb:10-90
Core Deployment Workflow
The primary function of Kamal is the deployment of containerized applications. This involves several stages, from building the image to switching traffic on remote servers.
Deployment Sequence
When a user executes kamal deploy, the system follows a structured sequence to ensure the application is safely updated.
Key Deployment Commands
- setup: Initialized the environment, bootstraps servers with Docker, and deploys the app. Sources: lib/kamal/cli/main.rb:3-14
- deploy: The standard update workflow, including building/pushing images and booting new containers. Sources: lib/kamal/cli/main.rb:18-60
- redeploy: A faster version of deploy that skips server bootstrapping and image pruning. Sources: lib/kamal/cli/main.rb:64-97
- rollback [VERSION]: Quickly switches the running application to a previous container version already present on the host. Sources: lib/kamal/cli/main.rb:100-120
Configuration Management
Kamal is configured primarily through a config/deploy.yml file. This file defines the service name, image, registry credentials, and the servers (hosts) partitioned by roles.
Configuration Structure
The Kamal::Configuration class parses the YAML file and validates required keys such as service, image, and registry. Sources: lib/kamal/configuration.rb:133-157
# Example of configuration delegation in lib/kamal/configuration.rb
delegate :service, :labels, :hooks_path, to: :raw_config, allow_nil: true
Sources: lib/kamal/configuration.rb:11
Roles and Servers
Servers are organized into roles (e.g., web, workers, cron). The web role is typically the primary role that receives traffic via kamal-proxy. Sources: lib/kamal/configuration.rb:216-226, lib/kamal/configuration/role.rb:1-15
| Feature | Role Configuration |
|---|---|
| Primary Role | Defaults to web or explicitly set via primary_role. |
| Hosts | A list of IP addresses or hostnames assigned to the role. |
| Health Checks | Configurable per role to gate successful deployment. |
| Proxying | Roles can be configured to run kamal-proxy for traffic routing. |
Sources: lib/kamal/configuration.rb:216-226, lib/kamal/configuration/role.rb:137-160
Infrastructure & Connectivity
Kamal manages connectivity to remote servers and ensures the necessary software (Docker) is present.
Server Bootstrapping
The kamal server bootstrap command ensures that the remote servers have curl and Docker installed. Sources: lib/kamal/cli/main.rb:11, lib/kamal/cli/main.rb:269
Deploy Locking
To prevent concurrent deployments that might conflict, Kamal uses a locking mechanism. Before starting a deployment, it attempts to acquire a lock on the remote servers. Sources: lib/kamal/cli/main.rb:33, lib/kamal/commander.rb:15
Conclusion
Kamal provides a robust, container-centric deployment strategy that emphasizes simplicity and zero-downtime operations. By orchestrating Docker and SSHKit, it abstracts the complexities of managing remote fleets while maintaining a high degree of control through its YAML-based configuration and Thor-powered CLI. Sources: README.md:3-10, CLAUDE.md:42-45