Kamal in Ruby on Rails

What is Kamal in Ruby on Rails?

Kamal is a command-line deployment tool that packages applications into Docker images and deploys them directly to any Linux server over SSH, whether a VPS, bare metal, or cloud instance, without needing a PaaS.

It handles zero-downtime deployments using Kamal Proxy, which manages traffic switching between old and new containers during an update.

Why Is Kamal Useful?

Traditional server deployment involves complex configuration, while PaaS platforms add cost and lock-in. Kamal helps by:

• Deploying to any Linux server without needing a PaaS
• Using Docker to ensure consistent environments across development and production
• Enabling zero-downtime deployments out of the box
• Managing environment secrets securely
• Supporting multiple servers and roles (web, workers, cron) in one configuration
• Keeping deployment infrastructure under the developer's full control
• Reducing hosting costs compared to managed platforms

It is especially useful for teams that want the simplicity of a PaaS workflow while retaining the cost and control benefits of self-managed infrastructure.

How Does Kamal Work?

Kamal reads its deployment configuration, builds a Docker image, and deploys it to one or more servers.

Key components:

• deploy.yml – The central configuration file that defines servers, image registry, environment variables, and roles
• Docker Image – The application is packaged into a Docker image and pushed to a container registry
• SSH Access – Kamal connects to the target servers over SSH to execute deployment commands.
• Kamal Proxy – A lightweight proxy that handles traffic switching for zero-downtime deployments
• Accessories – Supporting services like databases, Redis, or cron jobs defined and managed alongside the main application

Examples

Scenario 1: Basic Configuration

Kamal is configured in config/deploy.yml.

yaml

service: myapp 
image: your-dockerhub-username/myapp 
 
servers: 
  web: 
    - 192.168.1.1 
 
registry: 
  username: your-dockerhub-username 
  password: 
    - KAMAL_REGISTRY_PASSWORD 
 
env: 
  secret: 
    - RAILS_MASTER_KEY 
    - DATABASE_URL 

This defines the application name, Docker image, target server, registry credentials, and secrets pulled from environment variables.

Scenario 2: Deploying the Application

Once configured, the deployment lifecycle comes down to two commands.

bin/kamal setup   # First-time setup: installs Docker, pulls image, starts app 
bin/kamal deploy  # Subsequent deploys: builds, pushes, and switches containers 

bin/kamal setup is run once to prepare the server. Every subsequent deployment uses bin/kamal deploy, which builds the new image, pushes it to the registry, and performs a zero-downtime swap via Kamal Proxy.

Scenario 3: Managing Accessories

Kamal can manage supporting services alongside the application.

yaml

accessories: 
  db: 
    image: mysql:8.0 
    host: 192.168.1.1 
    env: 
      secret: 
        - MYSQL_ROOT_PASSWORD 
    volumes: 
      - /var/lib/mysql:/var/lib/mysql 
 
  redis: 
    image: redis:7.0 
    host: 192.168.1.1 

Kamal can also manage long-lived supporting services, called accessories, such as MySQL and Redis. These services can run on the same server as the application or on separate hosts, depending on the configuration. Accessories are managed separately from the main application deployment.

Where to Use Kamal?

• Rails 8 applications deploying to a VPS or bare metal server
• Teams moving away from expensive PaaS platforms
• Applications that need zero-downtime deployments without complex infrastructure
• Multi-server setups with separate web and worker roles
• Projects where Docker-based consistency between environments is a priority

In Summary

Kamal is Rails 8's built-in deployment tool that makes shipping Docker-based applications to any Linux server straightforward, without depending on a PaaS. It brings zero-downtime deployments, secret management, and accessory orchestration into a single configuration file and a handful of commands.