Deploy containerized web applications to any Linux server using Kamal. Use when users need to deploy, configure, debug, or manage Kamal deployments including initial setup, configuration of deploy.yml, deployment workflows, rollbacks, managing accessories (databases, Redis), troubleshooting deployment issues, or understanding Kamal commands and best practices.
Deploy containerized apps to Linux servers with Kamal. Use when users need to set up deployments, configure deploy.yml, manage staging/production environments, troubleshoot failures, or handle rollbacks and accessories like databases and Redis.
/plugin marketplace add el-feo/ai-context/plugin install devops@jebs-dev-toolsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/commands.mdreferences/configuration.mdreferences/workflows.mdKamal is a zero-downtime deployment tool for containerized applications, originally built by 37signals for deploying Rails apps but works with any containerized web application.
Philosophy: Kamal uses an imperative "push" model where you explicitly tell servers what to do, unlike declarative tools like Kubernetes. It combines SSH, Docker, and Kamal Proxy to achieve zero-downtime deployments.
Components:
Use this skill when you need to:
config/deploy.yml or understand configuration options# 1. Install Kamal
gem install kamal
# 2. Initialize configuration
cd your-app
kamal init
# 3. Edit config/deploy.yml
# - Set service name and image
# - Add server IP addresses
# - Configure registry credentials
# - Set environment variables
# 4. Configure secrets in .kamal/secrets
KAMAL_REGISTRY_PASSWORD=your-token
RAILS_MASTER_KEY=your-key
# 5. Run initial setup (installs Docker, deploys everything)
kamal setup
kamal deploy # Build, push, deploy with zero downtime
kamal deploy -d staging # Deploy to staging environment
kamal app logs -f # Follow application logs
kamal app exec -i --reuse "bin/rails console" # Rails console
kamal app logs -g "error" # Search logs
kamal rollback <version> # Rollback
kamal app maintenance # Maintenance mode
kamal app live # Exit maintenance
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
servers:
web:
hosts:
- 192.168.1.10
- 192.168.1.11
worker:
hosts:
- 192.168.1.12
cmd: bundle exec sidekiq
accessories:
postgres:
image: postgres:15
host: 192.168.1.20
port: 5432
env:
secret:
- POSTGRES_PASSWORD
clear:
POSTGRES_DB: myapp_production
directories:
- data:/var/lib/postgresql/data
redis:
image: redis:7
host: 192.168.1.21
directories:
- data:/data
For comprehensive configuration options, see references/configuration.md.
kamal init - Initialize configuration fileskamal setup - First-time setup (installs Docker, deploys everything)kamal deploy - Standard deploy with zero downtimekamal redeploy - Fast redeploy (skips proxy setup)kamal rollback VERSION - Rollback to previous versionkamal app logs [-f] - View logs (follow with -f)kamal app exec "COMMAND" - Run command in containerkamal app exec -i --reuse "bash" - Interactive shellkamal app maintenance - Enable maintenance modekamal app live - Disable maintenance modekamal app containers - List all containers (for rollback)kamal app version - Show deployed versionkamal accessory boot NAME - Start accessorykamal accessory logs NAME [-f] - View accessory logskamal accessory exec NAME "CMD" - Run command in accessorykamal config - Show parsed configurationkamal lock status - Check deployment lockkamal lock release - Release stuck lockkamal server exec "CMD" - Run command on hostkamal deploy -d staging - Deploy to stagingkamal deploy -h 192.168.1.10 - Deploy to specific hostkamal deploy -r web - Deploy to specific roleFor complete command reference, see references/commands.md.
Using pre-deploy hook (recommended):
Create .kamal/hooks/pre-deploy:
#!/bin/bash
kamal app exec -p -q "bin/rails db:migrate"
chmod +x .kamal/hooks/pre-deploy
kamal deploy
# Check what went wrong
kamal app logs
# List available versions
kamal app containers
# Rollback to previous version
kamal rollback abc123def
kamal app logs -n 500kamal server exec "docker ps -a"kamal app exec "curl localhost:3000/up"kamal configkamal lock releaseCreate environment-specific configs:
config/deploy.yml (production)config/deploy.staging.ymlkamal setup -d staging
kamal deploy -d staging
kamal deploy # production
For detailed workflows, troubleshooting guides, and best practices, see references/workflows.md.
# PostgreSQL
kamal accessory exec postgres "psql -U myapp"
kamal accessory exec postgres "pg_dump -U myapp myapp_production" > backup.sql
# Redis
kamal accessory exec redis "redis-cli"
# MySQL
kamal accessory exec mysql "mysql -u root -p myapp_production"
kamal accessory exec litestream "litestream generations /data/production.sqlite3"
kamal accessory exec litestream "litestream restore /data/production.sqlite3"
ssh:
user: deploy
port: 2222
builder:
context: .
dockerfile: Dockerfile.production
args:
RUBY_VERSION: 3.2.0
healthcheck:
path: /up
port: 3000
interval: 10
max_attempts: 7
aliases:
console: app exec --interactive --reuse "bin/rails console"
shell: app exec --interactive --reuse "bash"
logs: app logs -f
Use: kamal console instead of full command.
- name: Deploy
env:
KAMAL_REGISTRY_PASSWORD: ${{ secrets.REGISTRY_TOKEN }}
RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
run: |
gem install kamal
kamal deploy
This skill includes comprehensive reference documentation:
config/deploy.yml reference with all options, registry configurations, accessory setups, and example configurationsRead these references when you need detailed information about specific configuration options, commands, or deployment patterns.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.