kamal-2-deployment

name	Kamal 2 Deployment
description	This skill should be used when the user asks about "Kamal", "Kamal 2", "deployment", "deploying Rails", "Docker deployment", "VPS deployment", or zero-downtime deployments. Load this skill when setting up or troubleshooting Kamal deployments.
version	0.1.0

Kamal 2 Deployment

Kamal 2 is Rails' official deployment tool for zero-downtime deployments to any server. This skill covers Kamal setup, configuration, and deployment workflows.

Why Kamal

• Simple: One command to deploy
• Portable: Deploy to any server
• No lock-in: Own your infrastructure
• Zero-downtime: Rolling deployments
• Docker-based: Consistent environments

Setup

Install:

gem install kamal

Initialize:

kamal init

Generates: config/deploy.yml and .kamal/secrets

Basic Configuration

# config/deploy.yml
service: myapp
image: myapp

servers:
  web:
    hosts:
      - 192.168.1.1
    labels:
      traefik.http.routers.myapp.rule: Host(`myapp.com`)

registry:
  server: ghcr.io
  username: myusername
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY

Deployment Commands

# Initial deploy
kamal setup

# Regular deploy
kamal deploy

# Rollback
kamal rollback

# View logs
kamal app logs

# SSH into container
kamal app exec -i bash

# Run console
kamal app exec rails console

Deployment Process

1. Build Docker image
2. Push to registry
3. Pull on servers
4. Run migrations
5. Start new containers
6. Health check
7. Stop old containers

SSL/HTTPS

Kamal handles SSL automatically via Let's Encrypt:

# In config/deploy.yml
traefik:
  options:
    publish:
      - "443:443"
    volume:
      - "/letsencrypt/acme.json:/letsencrypt/acme.json"
  args:
    entryPoints.web.address: ":80"
    entryPoints.websecure.address: ":443"
    certificatesResolvers.letsencrypt.acme.email: "[e-mail]"

Best Practices

1. Test locally: docker build .
2. Staged rollout: Deploy to staging first
3. Monitor: Check logs after deploy
4. Health checks: Ensure working
5. Backup database: Before deploys

Kamal makes deployment simple while keeping you in control.

Additional Resources

Example Files

Working examples in examples/:

• examples/deploy.yml - Complete Kamal 2 configuration with multi-server setup, SSL/HTTPS, health checks, workers, and accessories

External Resources

• Kamal Documentation
• Kamal GitHub