デプロイ ガイド — Coolify on VPS

1. プロダクション トポロジ

Coolify は VPS にインストールされ、以下の別々のコンテナを実行します。

Coolify のリバース プロキシはドメインと TLS を処理します。データベース/Redis は Docker/Coolify のプライベート ネットワークを介してのみアクセスできます。

2. Coolify の準備

1. プロジェクトと環境を別々に作成します: staging と production。
2. フロントエンドとバックエンド リポジトリの Git リソースを追加します。
3. 適切な環境に PostgreSQL と Redis マネージド リソースを追加します。
4. ドメインを追加し、HTTPS を有効化し、CORS FRONTEND_URL バックエンドをドメインのフロントエンドに設定します。
5. Coolify のシークレットとしてすべての環境変数を保存し、.env をコミットしないでください。

バックエンドは同じソース/イメージから 2 回デプロイされます: backend-api は pnpm start:prod を実行し、backend-worker は pnpm start:worker を実行します。環境ごとに 1 つの スケジューラ ライフサイクルが有効であることを確認し、または Redis の分散ロックを使用します。

3. デプロイ順序

1. データベースをバックアップし、Prisma のマイグレーションをレビューします。
2. backend-api の新しいバージョンをデプロイします。
3. pnpm prisma migrate deploy を 1 回だけ実行して、プロダクション マイグレーションを実行します。
4. 同じ環境で backend-worker をデプロイまたは再起動します。
5. NEXT_PUBLIC_API_URL が正しい場合にフロントエンドをデプロイします。
6. /health、/api/docs (ステージングのみ)、ワーカー キュー、ウェブフック サンドボックスを確認します。

API とワーカーが同時にマイグレーションを実行してはなりません。Coolify のリリース コマンド/ワンオフ タスクを使用してください。

4. 支払いウェブフックと OAuth

• https://api.hub.domain.com/webhooks/midtrans と https://api.hub.domain.com/webhooks/xendit をプロバイダーのダッシュボードに登録します。
• OAuth SaaS のリダイレクト URI を oauth_clients のように正確に登録します。ワイルドカードを受け入れないでください。
• プロバイダーの署名が必要な場合、ウェブフック エンドポイントが raw body を受け入れるようにしてください。
• デプロイ後、サンドボックス トランザクションを実行し、ウェブフックを再試行して idempotensi を確認します。

5. 監視、バックアップ、ロールバック

• コンテナの健康、HTTP 5xx、VPS のディスク、PostgreSQL/Redis の接続、失敗したジョブのキュー、ウェブフック エラーを監視します。
• PostgreSQL を定期的にバックアップし、定期的に復元テストを実行します。Redis はソース オブ トゥルースを保持していないため、パERSISTENCE の構成は復元のために役立ちます。
• ログを保管する保管期間を決定し、シークレットやトークンを保存しないでください。
• Coolify のデプロイ リビジョンを使用してアプリケーションをロールバックします。破壊的なマイグレーションでは、段階的に互換性のあるマイグレーションを使用し、バックアップがテストされた場合にのみスキーマをロールバックしてください。

6. リリース チェックリスト

• フロントエンドと API の HTTPS、ドメイン、CORS が正しいです。
• PostgreSQL と Redis はインターネットに公開されていません。
• 環境のシークレットが入力されていて、ステージング/プロダクション間で異なります。
• Prisma マイグレーションが 1 回成功しました。
• API とワーカーが正常に動作し、スケジューラが複数回実行されていないことを確認します。
• Midtrans/Xendit のウェブフック署名とサンドボックス テストが成功しました。
• メール検証/請求とジョブ ライフサイクルが正常に実行されます。
• データベースのバックアップとロールバックのプロセスがテストされました。