Kamal Deployment: From Zero to Hero

2 minute read

Kamal lets you deploy web apps anywhere, from a single VPS to a fleet of servers, without needing Kubernetes or a PaaS. This guide walks you through the entire journey, from installing Kamal to rolling back a bad deploy.

For complete config visit Kamal Config Generator

1. Install Kamal

gem install kamal

2. Initialize your project

kamal init

This creates two files:

  1. .kamal/secrets
  2. config/deploy.yml

We cover installation and initialization in more detail in How to setup Kamal?

3. Configure config/deploy.yml

<% require "dotenv"; Dotenv.load(".env") %>

service: kamal-demo
image: yourregistryusername/kamal-demo
servers:
  web:
    - 12.34.56.78

proxy:
  ssl: true
  host: example.com

registry:
  username: yourregistryusername
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    SOLID_QUEUE_IN_PUMA: true

volumes:
  - 'kamal_demo_storage:/rails/storage'

asset_path: /rails/public/assets

builder:
  arch: amd64

Note: If your database needs a container of its own (Postgres, MySQL, SQLite), check out our dedicated guides for Postgres, MySQL, and SQLite.

4. Add your secrets

# .kamal/secrets
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
RAILS_MASTER_KEY=$(cat config/master.key)

# .env
KAMAL_REGISTRY_PASSWORD=dckr_pat_*******************o

Read more on handling secrets in Managing Secrets with Kamal - A Complete Guide

5. Deploy

kamal deploy

This builds your image, pushes it to the registry, boots up Traefik on your servers, and starts your app containers with zero downtime.

6. Rollback if something goes wrong

Find the previous good version:

kamal app containers -q

Then rollback to it:

kamal rollback [VERSION]

We go deeper into this in How to rollback a deployment with Kamal?

7. Day-to-day commands

Once you’re deployed, these commands cover most of what you’ll need:

kamal app logs -f      # tail logs
kamal app exec --interactive --reuse "bin/rails console"   # rails console
kamal app details       # container status

You can also set up shortcuts for these with aliases, and add extra services like a database or Redis with accessories.

FAQs

Do I need Kubernetes to use Kamal? No. Kamal works over SSH and plain Docker, so a single VPS is enough to get started.

Can I deploy to multiple servers? Yes, just list additional hosts under servers in deploy.yml and Kamal will deploy to all of them.

What happens during a deploy? Kamal builds a new image, pushes it to your registry, pulls it on each server, boots the new containers, waits for health checks to pass, then swaps traffic over through Traefik before stopping the old containers.

How do I undo a bad deploy? Use kamal rollback [VERSION] with the previous container’s version hash, see the rollback section above.

📘 Learn Kamal with a Practical Guide

Check out Kamal Handbook by Josef Strzibny - a concise eBook covering real-world deployment tips.

This is an affiliate link. I may earn a small commission if you buy, at no extra cost to you.

You May Also Enjoy