mcpField
K
kamal

kamal

github.com/el-feoCloud & DevOps1235 installsUpdated 14w ago
Repository

About kamal

Kamal is a deployment CLI from 37signals for containerized web applications on bare Linux servers. It uses SSH, Docker, and Kamal Proxy for deployments designed to avoid downtime, and supports operations such as rollbacks and log inspection.

Key features

  1. 01Deploy containerized apps over SSH
  2. 02Build and push container images
  3. 03Route deployments with Kamal Proxy
  4. 04Roll back to a specified version
  5. 05Inspect logs and run app commands
  6. 06Configure multiple deployment environments

Use cases

  1. 01Deploying a web app to Linux servers
  2. 02Releasing an app to staging or another environment
  3. 03Rolling back a problematic release
  4. 04Inspecting logs while troubleshooting a deployment

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/el-feo/ai-context --skill kamal

After installing, type/kamalin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
commands.md
configuration.md
workflows.md

Details

From the project README

Kamal Deployment

Kamal is a zero-downtime deployment tool for containerized applications, built by 37signals. It combines SSH, Docker, and Kamal Proxy to deploy any containerized web app to bare Linux servers.

Key components: SSH/SSHKit (remote execution), Docker (containers), Kamal Proxy (zero-downtime routing), Accessories (supporting services).

Quick Start

gem install kamal
cd your-app && kamal init          # Generate config/deploy.yml and .kamal/secrets
# Edit config/deploy.yml and .kamal/secrets
kamal setup                         # Bootstrap servers, install Docker, deploy

Minimal deploy.yml

service: myapp
image: username/myapp

servers:
  web:
    - 192.168.1.10

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

env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    RAILS_ENV: production

proxy:
  ssl: true
  host: example.com

For complete configuration options (registry variants, builder, proxy, accessories, SSH, volumes, aliases, healthchecks, rollout strategies), see references/configuration.md.

Essential Commands

kamal deploy                    # Build, push, deploy with zero downtime
kamal deploy -d staging         # Deploy to specific environment
kamal rollback VERSION          # Rollback to previous version
kamal app logs -f               # Follow application logs
kamal app exec -i --reuse "bin/rails console"  # Interactive console
kamal app maintenance           # Enable maintenance mode
kamal app live                  # Disable maintenance mode
kamal config                    # Show parsed configuration
kamal lock release              # Release stuck deployment lock

For complete command reference with all options, see references/commands.md.

Common Workflows

Deploy with Database Migration

Create .kamal/hooks/pre-deploy:

#!/bin/bash
kamal app exec -p -q "bin/rails db:migrate"

Then chmod +x .kamal/hooks/pre-deploy && kamal deploy.

Rollback
kamal app containers            # List available versions
kamal rollback abc123def        # Rollback to specific version
Debugging Failed Deployments
  1. kamal app logs -n 500 — check application logs
  2. kamal server exec "docker ps -a" — check container status
  3. kamal app exec "curl localhost:3000/up" — test health endpoint
  4. kamal config — verify configuration
  5. kamal lock release — clear stuck locks
Multiple Environments

Create config/deploy.staging.yml, then:

kamal setup -d staging && kamal deploy -d staging

For detailed workflows (CI/CD, scaling, backups, security, canary deploys, monitoring), see references/workflows.md.

Limitations

  • No state reconciliation — removing servers from config does not decommission containers
  • No dynamic provisioning — cannot auto-scale or provision servers
  • Single-server load balancing — Kamal Proxy balances containers per server; use an external LB across servers

Comments

Markdown supported