coolify

Coolify

概要

Coolify は、アプリケーション、データベース、サービスを独自のインフラストラクチャにデプロイするセルフホスト可能な PaaS（Vercel／Netlify の代替サービス）です。プログラムから制御できる REST API を提供し、複数のビルドパックをサポートしています。また、リバースプロキシと SSL には Traefik を使用します。

使用する場合： アプリケーションをセルフホスト可能なインフラストラクチャにデプロイする場合、API を通じてデータベースやサービスを管理する場合、CI/CD でデプロイを自動化する場合、ベンダーロックインなしでセルフホストする場合。

使用しない場合： Coolify サーバーの初期インストール（ブラウザーから公式インストールスクリプトを使用してください）、Coolify 自体のインフラストラクチャ（Postgres、Redis など、内部で管理されるもの）を管理する場合、またはセルフホストの要件がなく、マネージドプラットフォーム（Vercel、Railway）でニーズを満たせる場合。

クイックリファレンス

パターン	方法	主なポイント
API 認証	Authorization: Bearer <token> ヘッダー	トークンはダッシュボードで作成し、権限を設定できます
アプリケーションの一覧表示	GET /api/v1/applications	ステータスと設定を含むすべてのアプリを返します
デプロイの実行	GET /api/v1/deploy?uuid=<app>&force=true	またはアプリごとの Webhook URL を使用します
アプリケーションの作成	POST /api/v1/applications/public	project_uuid、server_uuid、env_name が必要です
アプリケーションの更新	PATCH /api/v1/applications/<uuid>	ビルド、ヘルスチェック、ドメイン、制限フィールドを受け付けます
自動デプロイ	Advanced > General で有効にします	設定されたブランチへのプッシュごとにデプロイします
Webhook によるデプロイ	curl GET <webhook_url> -H "Authorization: Bearer ..."	CI パイプラインからデプロイを制御します
GitHub Actions によるデプロイ	イメージをビルドしてレジストリにプッシュし、Webhook を実行します	デプロイ前のビルドとテストを完全に制御できます
Nixpacks によるビルド	ソースコードから自動検出	対応言語では設定不要です
Dockerfile によるビルド	ビルドパックを dockerfile に設定	ビルドプロセスを完全に制御できます
Compose によるビルド	docker-compose.yaml を信頼できる唯一の情報源として使用	Coolify ラベルを使用する複数サービスのスタック
環境変数	API または環境ごとのダッシュボード	Compose 内では ${VAR} 構文で展開されます
ドメインルーティング	fqdn フィールドまたは Compose 内の Traefik ラベル	Let's Encrypt による SSL の自動設定
ヘルスチェック	API からパス、間隔、再試行回数を設定できます	running:healthy ステータスに必要です

よくある間違い

間違い	正しいパターン
API が「Unauthenticated」を返す	Bearer トークンと合わせて Accept: application/json ヘッダーを追加します
機密フィールド（自動デプロイなど）を読み取れない	トークンに view:sensitive または * の権限スコープが必要です
自動デプロイが実行されない	GitHub App が接続され、Advanced で自動デプロイが有効になっていることを確認します
デプロイ権限のない API トークンを使用している	デプロイを実行するには、トークンに明示的な deploy 権限が必要です
Compose サービスのヘルスチェックに失敗する	HTTP サービス以外には exclude_from_hc: true ラベルを追加します
認証ヘッダーなしで Webhook デプロイを行う	Webhook 呼び出しには必ず Authorization: Bearer <token> を含めます
ビルド時に環境変数を使用できない	ランタイム環境変数ではなく、Advanced メニューのビルド引数を使用します
Compose サービス間で通信できない	同じスタックネットワーク内では、ホスト名としてサービス名を使用します

委任

• API の調査：Explore エージェントを使用して、既存の Coolify リソースを確認します
• Dockerfile の最適化：Task エージェントを使用して、Coolify デプロイ向けに Dockerfile をレビューします
• CI/CD パイプラインの設計：Plan エージェントを使用して、デプロイワークフローの戦略を策定します

docker スキルが利用可能な場合は、Dockerfile の作成、マルチステージビルド、イメージの最適化を委任します。 github-actions スキルが利用可能な場合は、ワークフローの構文や CI パイプラインのパターンを委任します。 ci-cd-architecture スキルが利用可能な場合は、デプロイ戦略や環境の昇格を委任します。

参考資料

• API：認証、エンドポイント、一般的な操作、権限スコープ
• デプロイ：自動デプロイ、Webhook、GitHub Actions、CI/CD パイプライン
• ビルドパック：Nixpacks、Dockerfile、Compose の規約、設定