Kamal Overview

Kamal (formerly MRSK) is a deployment tool for Rails 8 that uses Docker and SSH to deploy applications to any server. No Kubernetes, no complex orchestration - just simple, reliable deployments.

Key Features:

Zero-downtime deployments with health checks
Automatic SSL with Let's Encrypt
Multi-server deployments
Rolling restarts
Easy rollbacks
Built-in load balancing with Traefik

Quick Start

1. Install Kamal

# Kamal comes with Rails 8
gem install kamal

# Verify installation
kamal version

2. Initialize Kamal

# Generate Kamal configuration files
kamal init

# Creates:
# - config/deploy.yml        # Main configuration
# - .env.erb                  # Environment template
# - .kamal/                   # Kamal directory

3. Configure Server

# config/deploy.yml
service: my-blog-app
image: your-username/my-blog-app

servers:
  web:
    hosts:
      - 192.168.1.100  # Your server IP
    labels:
      traefik.http.routers.my-blog-app.rule: Host(`example.com`)
      traefik.http.routers.my-blog-app-secure.entrypoints: websecure
      traefik.http.routers.my-blog-app-secure.rule: Host(`example.com`)
      traefik.http.routers.my-blog-app-secure.tls: true
      traefik.http.routers.my-blog-app-secure.tls.certresolver: letsencrypt

registry:
  username: your-username
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    RAILS_ENV: production
    RAILS_LOG_TO_STDOUT: true

builder:
  multiarch: false

4. Setup Server

# Install Docker on remote server
kamal server bootstrap

# Verify setup
kamal setup

5. Deploy

# First deployment
kamal deploy

# Subsequent deployments
kamal deploy

Code Examples & Patterns

For detailed deployment patterns and examples, see examples.md.

Pattern Categories

examples.md contains:

Kamal Configuration - Complete deploy.yml examples for various setups
Docker Configuration - Multi-stage Dockerfile optimization
Environment Management - Secrets, credentials, environment variables
Database Migrations - Safe migration strategies in production
SSL/TLS Setup - Let's Encrypt and custom certificates
Multi-Server Deployment - Load balancing across servers
Background Jobs - Deploying Solid Queue workers
Health Checks - Endpoint configuration for zero-downtime
Rollback Procedures - Recovering from failed deployments
Monitoring & Logging - Production observability setup
CI/CD Integration - GitHub Actions deployment workflows

Refer to examples.md for complete code examples.

Kamal Commands

Deployment Commands

# Initial setup (first time only)
kamal setup

# Deploy application
kamal deploy

# Deploy without building new image
kamal deploy --skip-push

# Run migrations before deployment
kamal deploy --skip-push
kamal app exec "bin/rails db:migrate"

Application Management

# Restart application
kamal app restart

# Stop application
kamal app stop

# Start application
kamal app start

# View application logs
kamal app logs -f

# Execute command in container
kamal app exec "bin/rails console"
kamal app exec "bin/rails db:migrate:status"

Rollback

# List versions
kamal app version

# Rollback to previous version
kamal rollback [VERSION]

Server Management

# SSH into server
kamal app exec --interactive bash

# View Docker containers
kamal app containers

# View server details
kamal server details

Dockerfile for Rails

Multi-Stage Dockerfile

Rails 8 includes an optimized Dockerfile by default:

# Dockerfile (Rails 8 default, optimized)
ARG RUBY_VERSION=3.4.7
FROM ruby:$RUBY_VERSION-slim AS base

WORKDIR /rails

RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y \
    curl libjemalloc2 libvips sqlite3 && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

ENV RAILS_ENV="production" \
    BUNDLE_DEPLOYMENT="1" \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT="development:test"

FROM base AS build

RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y \
    build-essential git pkg-config && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

COPY Gemfile Gemfile.lock ./
RUN bundle install && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git

COPY . .

RUN bundle exec bootsnap precompile --gemfile app/ lib/
RUN ./bin/rails assets:precompile

FROM base

COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --from=build /rails /rails

RUN groupadd --system --gid 1000 rails && \
    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
    chown -R 1000:1000 db log storage tmp
USER 1000:1000

ENTRYPOINT ["/rails/bin/docker-entrypoint"]

EXPOSE 3000
CMD ["./bin/thrust", "./bin/rails", "server"]

Environment Management

Rails Credentials

# Edit production credentials
EDITOR=nano rails credentials:edit --environment production

# Generates config/credentials/production.yml.enc
# and config/credentials/production.key

# config/credentials/production.yml.enc (encrypted)
secret_key_base: <generated>
database:
  password: <db_password>
smtp:
  username: <smtp_user>
  password: <smtp_pass>

Environment Variables

# .env (not committed to git, for local deployment)
KAMAL_REGISTRY_PASSWORD=<docker_hub_password>
RAILS_MASTER_KEY=<from config/credentials/production.key>
DATABASE_URL=postgresql://user:pass@host:5432/dbname

Database Migrations

Safe Migration Strategy

# 1. Deploy without running migrations
kamal deploy --skip-push

# 2. Run migrations separately
kamal app exec "bin/rails db:migrate"

# 3. Restart application
kamal app restart

Pre-Deployment Checks

# Check migration status before deploying
kamal app exec "bin/rails db:migrate:status"

# Run migrations in a transaction
kamal app exec "bin/rails db:migrate"

# Verify migration success
kamal app exec "bin/rails db:version"

Testing Deployment

Local Docker Testing

# Build Docker image locally
docker build -t my-app .

# Run container locally
docker run -p 3000:3000 \
  -e RAILS_MASTER_KEY=<key> \
  -e DATABASE_URL=<url> \
  my-app

# Test in browser
open http://localhost:3000

Staging Environment

# config/deploy.staging.yml
service: my-blog-app-staging
image: your-username/my-blog-app

servers:
  web:
    hosts:
      - staging.example.com

env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    RAILS_ENV: staging

# Deploy to staging
kamal deploy -c config/deploy.staging.yml

Official Documentation:

Kamal Documentation - Official Kamal guide
Docker Documentation - Docker reference
Rails Deployment Guide - Rails production config

Deployment Platforms:

DigitalOcean - Simple VPS hosting
Hetzner - Cost-effective VPS
AWS EC2 - Scalable cloud hosting

Monitoring & Logging:

AppSignal - Rails monitoring
Sentry - Error tracking
Lograge - Structured logging

CI/CD:

GitHub Actions - CI/CD automation
Kamal GitHub Action - Official action

rails-deployment

Rails Deployment with Kamal