convex-deploy

Convex バックエンドとフルスタックアプリのデプロイライフサイクル、環境、安全な段階的ロールアウト戦略について説明します。 - モデル：プロジェクトごとに本番デプロイメントが 1 つ、チームメンバーごとに開発デプロイメントが 1 つ、ブランチごとにプレビューデプロイメントが 1 つあります。 - プレビューデプロイメントはベータ版で、自動的にクリーンアップされます。データのシードには `--preview-run` が必要です。 - ローカルデプロイメント：`npx convex dev --local --once` を実行します。公開 URL はなく、Node アクションには Node 18 が必要です。 - エージェントモード：AI コーディングエージェントの開発時の権限を制限するには、`CONVEX_AGENT_MODE=anonymous` を使用します。 - 環境変数はデプロイメントごとに設定されます。システム変数は `CONVEX_CLOUD_URL` と `CONVEX_SITE_URL` です。 - 安全な変更のルール：スキーマはデータと一致していなければなりません。任意フィールド、バックフィル、ユニオンを使って移行してください。関数には後方互換性を持たせ、スケジュール済みジョブの引数は常に有効な状態にしてください。 - プロジェクト設定：`convex.json` で関数のパスや Node ランタイムを変更できます。静的コード生成はベータ版です。 - デプロイメントを一時停止すると、新しい呼び出しはエラーになり、スケジュール済みジョブはキューに入り、cron はスキップされます。まず開発環境でテストすることを推奨します。

デプロイ操作

• 主なコマンド：npx convex dev、npx convex deploy、npx convex codegen、npx convex run（本番環境には --prod を使用します）。
• エージェントモード：AI エージェントとして反復作業を行い、安全にコード生成アーティファクトを生成する場合は、CONVEX_AGENT_MODE=anonymous npx convex dev --once を使用することを推奨します。
• デプロイ先の解決：CONVEX_DEPLOY_KEY が設定されていればそれが優先され、そうでなければ CONVEX_DEPLOYMENT のプロジェクトの本番デプロイメントが使われます。
• ビルド手順：npx convex deploy --cmd "npm run build" を使用します。必要に応じて --cmd-url-env-var-name も使用します。
• デプロイキー：本番、プレビュー、開発、管理者（コミットまたはログへの記録は禁止です）。
• ホスティングの流れ：
  • Vercel／Netlify のビルドコマンドには npx convex deploy --cmd 'npm run build' を使用することを推奨します。
  • 環境ごと（プレビューと本番）に CONVEX_DEPLOY_KEY を設定する必要があります。
  • プレビューのデータシードには --preview-run 'functionName' を使用します。
  • カスタムホスティング：バックエンドをデプロイし、フロントエンドは別の場所でホストします。カスタムドメインを使用するには、CONVEX_CLOUD_URL を上書きして再デプロイします。CONVEX_SITE_URL は任意です。

必須の出力

• ドキュメントに記載されている正確な CLI コマンドとフラグを使用する必要があります。
• デプロイ先の解決方法（デプロイキーと CONVEX_DEPLOYMENT のどちらが使われるか）を明記する必要があります。
• デプロイによる影響（スキーマの検証、インデックスのバックフィル、コード生成、バンドル化）を明示する必要があります。
• 該当する場合は、.convex.site と .convex.cloud の URL の使い分けに常に触れることを推奨します。

デプロイモデル

• 各プロジェクトには、本番デプロイメントが 1 つと、チームメンバーごとにクラウド開発デプロイメントが 1 つあります。
• プレビューデプロイメントはブランチごとに作成され、一定期間の経過後に自動的にクリーンアップされます。
• ローカルデプロイメントは開発専用で、npx convex dev のサブプロセスとして実行されます。

CLI ワークフロー

開発

• npx convex dev：
  • ファイルを監視し、変更を開発デプロイメントにプッシュします。
  • convex/_generated/* を再生成します。
  • ログ出力を制御するには --tail-logs を使用することを推奨します。
• ローカル開発：
  • ローカルバックエンドには npx convex dev --local --once を使用します。
  • 注：公開 URL はありません。HTTP リクエストにはプロキシ（例：ngrok）が必要です。
  • ローカルでの Node アクションには Node 18 が必要です。

デプロイ

• npx convex deploy：
  • 関数の型チェックを行います。
  • コード生成を再実行します。
  • 関数、スキーマ、インデックスをバンドルしてプッシュします。
• デプロイ先の解決：
  • CONVEX_DEPLOY_KEY が設定されている場合、そのキーの対象にデプロイします。
  • そうでない場合は、CONVEX_DEPLOYMENT のプロジェクトの本番デプロイメントを使用します。
• 任意のビルドコマンド：
  • npx convex deploy --cmd "npm run build"
  • 環境変数名をカスタマイズするには --cmd-url-env-var-name を使用します。

デプロイキー

• 本番デプロイキー：プロジェクトの本番デプロイメントを対象にします（一般的な CI 用）。
• プレビューデプロイキー：ブランチごとにプレビューデプロイメントを作成します。
• 開発デプロイキー：単一の開発デプロイメントにスコープされます。
• 管理者キー：すべてを制御できます。匿名のローカルデプロイメントで使用されます。
• セキュリティ：デプロイキーをコードに貼り付けたり、コミット履歴に含めたりしてはなりません。

プレビュー環境へのデプロイ

• ベータ機能であり、ライフサイクルに応じて自動クリーンアップされます（デフォルトは5日間）。
• プレビュー環境のデプロイ名はブランチに紐付けられます。再デプロイすると、以前のプレビュー環境が置き換えられます。
• データのシードには、デプロイ時に関数を実行する必要があります（--preview-run）。

環境変数

• ダッシュボードまたは npx convex env を使って、デプロイごとに設定する必要があります。
• 同じキーに対して、開発環境と本番環境の両方で値が必要になる場合があります。
• システム変数：
  • CONVEX_CLOUD_URL はクライアント RPC に使用します。
  • CONVEX_SITE_URL は HTTP アクションに使用します。
• 実行時に process.env に基づいてエクスポートを分岐してはいけません。関数はデプロイ時に設定されます。

安全な段階的リリースのルール

• スキーマは既存のデータと一致する必要があります。検証に失敗すると、デプロイはブロックされます。
• 安全なスキーマ変更：
  • テーブルを追加します。
  • オプションのフィールドを追加し、バックフィルしてから必須にします。
  • v.union を使って範囲を広げ、バックフィルしてから狭めます。
• 古いクライアントが稼働している間、関数は下位互換性を維持する必要があります。
• スケジュール済み関数は、以前にスケジュールされた引数を受け付ける必要があります。

インデックスのバックフィル

• 新しいインデックスはデプロイ中にバックフィルされるため、本番環境へのプッシュが遅くなる場合があります。
• 大規模なテーブルでは、ステージング済みインデックス（検索／ベクトルインデックスを含む）を使用することをおすすめします。
• インデックスを削除すると、デプロイ時に削除されます。それらに依存するコードパスがないことを確認する必要があります。

URL

• HTTP アクション：https://<deployment>.convex.site。
• クライアント URL：https://<deployment>.convex.cloud（CONVEX_CLOUD_URL 経由）。
• .convex.site と .convex.cloud の混在について警告することをおすすめします。

回答チェックリスト

• 環境（dev/prod/preview/local）を明記します。
• 正確なコマンドと必要な環境変数を提示します。
• 安全上の考慮事項（スキーマ、関数、スケジュール済み関数）を列挙します。
• トラブルシューティング時にログの場所（CLI またはダッシュボード）を記載します。