kamal-deployment

Kamal 2 のデプロイ

Kamal は 37signals が提供するデプロイツールです。Docker、SSH、Kamal Proxy を使用して、コンテナ化されたアプリケーションをあらゆる Linux サーバーにデプロイします。ダウンタイムのないデプロイ、ローリング再起動、自動 SSL/TLS 証明書、補助サービスの管理に対応しています。

クイックスタート

# Install
gem install kamal

# Initialize in your project
kamal init
# Creates: config/deploy.yml, .kamal/secrets, .kamal/hooks/

# First deploy (bootstraps servers + deploys)
kamal setup

# Subsequent deploys
kamal deploy

主な概念

• サービス：コンテナを一意に設定するために使用する、アプリケーションの名前です
• サーバー：アプリケーションのイメージを実行する仮想または物理ホストです
• ロール：同じコマンドを実行するサーバーのグループです（例：web、job）
• アクセサリー：独立したライフサイクルを持つ、長時間稼働する補助サービスです（データベース、Redis など）
• Kamal Proxy：ダウンタイムのないデプロイと、各サーバーでの SSL 終端処理を行うリバースプロキシです
• Kamal 2 は kamal という独自のプライベートネットワークを提供します。設定にカスタムのプライベートネットワークを追加しないでください

設定リファレンス

deploy.yml の完全な設定については、configuration.md を参照してください。

ワークフロー

初期設定

1. kamal init を実行して設定ファイルを生成します
2. config/deploy.yml を設定します（configuration.md を参照）
3. .kamal/secrets にレジストリの認証情報とアプリのシークレットを設定します
4. アプリの Dockerfile でポート 80 を公開し、/up のヘルスチェックを設定します
5. production.rb で config.assume_ssl = true と config.force_ssl = true を設定します
6. Rails 7 以降では、ホスト認証の対象から /up を除外します：

   config.host_authorization = { exclude: ->(request) { request.path == "/up" } }
   

7. 初回デプロイのために kamal setup を実行します

更新のデプロイ

kamal deploy                    # Full deploy (build + push + deploy)
kamal deploy --skip-push        # Deploy existing image from registry
kamal deploy --version=VERSION  # Deploy specific version

アクセサリーの管理

kamal accessory boot all        # Boot all accessories
kamal accessory boot postgres   # Boot specific accessory
kamal accessory reboot redis    # Reboot an accessory
kamal accessory remove postgres # Remove an accessory
kamal accessory details postgres
kamal accessory logs postgres

メンテナンスとデバッグ

# Logs
kamal app logs                  # Application logs
kamal app logs -f               # Follow logs
kamal app logs -r web           # Logs for specific role
kamal proxy logs                # Proxy logs

# Console access
kamal app exec -i 'bin/rails console'
kamal app exec -i --reuse bash  # Shell into running container
kamal app exec --primary "bin/rails about"

# Rollback
kamal app containers            # List available versions
kamal rollback [VERSION]         # Rollback to version

# Redeploy (skip bootstrap, proxy setup, pruning, registry login)
kamal redeploy

# Locks
kamal lock status               # Check deploy lock
kamal lock acquire -m "reason"  # Prevent deploys
kamal lock release              # Allow deploys again

# Server management
kamal server bootstrap          # Bootstrap servers with Docker
kamal details                   # Show details about all containers
kamal audit                     # Show audit log from servers
kamal prune                     # Prune old images and containers
kamal config                    # Show combined config (includes secrets!)
kamal docs [SECTION]            # Show Kamal configuration docs

# Cleanup
kamal remove                    # Remove everything from servers

グローバルフラグ

フラグ	説明
-v, --verbose	詳細なログ出力
-q, --quiet	最小限のログ出力
--version=VERSION	指定したアプリのバージョンを使用して実行
-p, --primary	プライマリホストのみ
-h, --hosts=HOSTS	カンマ区切りのホスト（ワイルドカードに対応）
-r, --roles=ROLES	カンマ区切りのロール（ワイルドカードに対応）
-d, --destination	デプロイ先
-H, --skip-hooks	フックの実行をスキップ

データベース操作

# Run migrations via entrypoint (recommended)
# bin/docker-entrypoint handles db:prepare automatically

# Or via pre-deploy hook
kamal app exec -p -q -d $KAMAL_DESTINATION --version $KAMAL_VERSION "rails db:migrate"

# Database backup (with S3 backup accessory)
kamal accessory exec s3_backup "sh backup.sh"
kamal accessory exec s3_backup "sh restore.sh"

アーキテクチャのパターン

単一サーバーおよび複数サーバー構成の完全な例については、examples.md を参照してください。

単一サーバー（Rails + PostgreSQL + Redis + Sidekiq）

Let's Encrypt の SSL を使用し、すべてのサービスを 1 台の VPS で実行します。小規模から中規模のアプリに最適です。

複数サーバー（スケール構成）

プライベートネットワーク上のロードバランサーの背後に、Web、ジョブ、データベース、キャッシュ用のサーバーを分けて配置します。トラフィックの多いアプリに最適です。

フック

デプロイの各段階で実行する、.kamal/hooks/ 内のカスタムスクリプトです。フックがゼロ以外の値を返すと、コマンドは中断されます。

利用可能なフック：docker-setup、pre-connect、pre-build、pre-deploy、post-deploy、pre-app-boot、post-app-boot、pre-proxy-reboot、post-proxy-reboot。

詳細は、configuration.md を参照してください。

Kamal 1 からのアップグレード

kamal upgrade              # In-place upgrade from Kamal 1 to 2
kamal upgrade --rolling    # Zero-downtime upgrade
kamal downgrade            # Reverse if needed

よくある注意点

• Kamal 2 は独自の kamal ネットワークを作成します。設定からカスタムのプライベートネットワークを削除してください
• SSL を使用する場合は、production.rb で必ず config.assume_ssl = true を設定してください
• VM のホスト名にドメイン名を使用しないでください。/etc/resolv.conf が上書きされます
• Docker によるポート公開は UFW を迂回します。UFW でポートを閉じるだけでは不十分です。Docker のルールは iptables でより優先されます
• deploy_timeout が短いと、性能の低いサーバーで失敗します。デプロイが失敗する場合は、値を大きくしてください
• アセットのブリッジは asset_path で明示的に設定する必要があります。自動では設定されません
• 新しいデプロイ先に移行する前に、アクセサリーを削除する必要があります
• Kamal 2 は config/deploy.yml で ERB をサポートしていません（Kamal 1 とは異なります）
• ActionController::RoutingError を解決するには、Devise イニシャライザーで config.reload_routes = false を設定してください
• Cloudflare の背後で実行する場合は、プロキシ設定で forward_headers: true を有効にして、実際のクライアント IP を保持してください

CI/CD

GitHub Actions によるデプロイワークフローについては、cicd.md を参照してください。

バックアップ

S3 を使用したデータベースのバックアップ方法については、backups.md を参照してください。

サーバーのセキュリティ強化

本番環境のサーバーのセキュリティ設定については、server-hardening.mdをご覧ください。

ログ記録と監視

Vector によるログの集約と構造化ログについては、logging.mdをご覧ください。