Kamal — Zero-Downtime Docker Deploys to Any Server

What it is

Kamal is Basecamp's deploy tool that ships Docker containers to bare metal servers or cloud VMs with a single command. It provides Heroku-like deployment workflows on servers you actually own. Kamal handles Docker image building, pushing to registries, rolling deploys with zero downtime via a reverse proxy, and multi-server orchestration.

Kamal targets developers and teams who want simple deployments without Kubernetes complexity. If you have a few servers and want push-button deploys, Kamal bridges the gap between manual SSH deployment and full container orchestration.

How it saves time or tokens

Kamal replaces manual deployment scripts with a single declarative config file and one command. It installs Docker and the kamal-proxy reverse proxy on your servers automatically. Rolling deploys ensure zero downtime by starting the new version before stopping the old one. Multi-server support deploys to an entire fleet simultaneously.

How to use

1. Install Kamal:

gem install kamal

1. Initialize configuration:

cd my-app
kamal init
# Edit config/deploy.yml with your servers, registry, and image settings

1. First-time setup and deploy:

kamal setup    # Installs Docker and kamal-proxy on all servers
kamal deploy   # Build, push, and deploy your app

Example

# config/deploy.yml
service: my-app
image: myregistry/my-app

servers:
  web:
    hosts:
      - 192.168.1.10
      - 192.168.1.11
  worker:
    hosts:
      - 192.168.1.12
    cmd: bundle exec sidekiq

registry:
  server: ghcr.io
  username: my-github-user
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  clear:
    RAILS_ENV: production
  secret:
    - DATABASE_URL
    - REDIS_URL

Related on TokRepo

• DevOps Tools — Deployment and infrastructure tools
• Self-Hosted Tools — Run applications on your own servers

This tool integrates with standard development workflows and requires minimal configuration to get started. It is available as open-source software with documentation and community support through the official repository. The project follows semantic versioning for stable releases.

For teams evaluating this tool, the key advantage is reducing manual work in repetitive tasks. The automation provided by the built-in features means less custom code to maintain and fewer integration points to manage. This translates directly to lower maintenance costs and faster iteration cycles.

Common pitfalls

• Kamal requires SSH access to target servers and Docker registry credentials; ensure SSH keys and registry auth are configured before running setup.
• The deploy.yml file contains secrets references; use environment variables or .env files rather than committing credentials to version control.
• Kamal installs its own reverse proxy (kamal-proxy); if you already have Nginx or Traefik on your servers, configure port mapping to avoid conflicts.