deploying-to-cloud

Laravel Cloud を使用したデプロイ

機能の詳細や最新の動作については、Laravel Cloud のドキュメントを参照してください。Cloud の操作では、ダッシュボードや API の手順を推測せず、Cloud CLI を使用してください。プロジェクトにインストールし、デフォルトでは ./vendor/bin/cloud として実行してください。グローバルにインストールした cloud コマンドは、フォールバックとしてのみ使用してください。以下のコマンドでは簡潔さのため cloud と記載していますが、グローバルインストールにフォールバックする場合を除き、./vendor/bin/cloud として実行してください。

アプリケーションのセットアップ

• Laravel Cloud は GitHub、GitLab、または Bitbucket からデプロイします。新しい Laravel アプリケーションには、PHP 8.2 以降、Laravel 9 以降、接続済みの Git プロバイダー、およびデプロイ先のリージョンが必要です。
• Cloud はアプリケーション用の環境を作成します。production、staging、preview の各環境を分けて使用してください。各環境には、それぞれ専用のコンピューティングリソース、リソース、デプロイ設定があります。
• 可能な限り、アプリケーションのコンピューティングリソースと接続済みリソースは同じリージョンに配置してください。
• Cloud は選択した PHP バージョンを使用して Docker イメージをビルドし、設定されたビルドコマンドとデプロイコマンドを実行した後、デプロイが成功するとダウンタイムなしでトラフィックを切り替えます。デフォルトでプッシュによるデプロイが有効になっており、手動デプロイやデプロイフックも利用できます。

ビルドとデプロイ

• 一般的な Laravel のビルドコマンドは composer install --no-dev && npm run build です。
• 最適化とキャッシュの構築コマンドは、デプロイ中ではなくビルド中に実行してください。一般的なデプロイコマンドは php artisan migrate --force です。
• ビルドコマンドとデプロイコマンドのタイムアウトは 15 分です。デプロイコマンドはリリースが有効になる直前に実行され、デプロイコマンドによるファイルシステムの変更は保持されません。
• php artisan queue:restart、php artisan horizon:terminate、php artisan optimize:clear、または php artisan storage:link をデプロイコマンドに追加しないでください。Cloud がワーカーの再起動とプロセス管理を行います。また、デプロイ中のファイルシステムの変更は保持されません。
• 環境設定、接続済みリソース、またはリンクされたシークレットを変更した後は、変更を反映するために環境を再デプロイしてください。

設定とリソース

• 接続済みのデータベース、キャッシュ、オブジェクトストレージは、接続用の環境変数を自動的に設定します。カスタム環境変数は、設定された環境変数より優先されます。
• 環境間で共有する組織レベルの値は、暗号化して Secrets Manager に保存してください。シークレットの値は作成後に読み取れません。シークレットの作成、更新、リンク、リンク解除、または削除の後は、影響を受ける環境を再デプロイしてください。
• 環境のファイルシステムは一時的なもので、レプリカ間で共有されません。永続的なキャッシュとセッションにはデータベースまたは Laravel Valkey を、永続ファイルには Laravel Cloud Object Storage を使用してください。デプロイ後もローカルファイルが残ることを前提にしないでください。

オブジェクトストレージとファイルの可視性

• Laravel Cloud Object Storage は Cloudflare R2 を基盤としています。R2 ではバケット単位で可視性が適用されるため、1 つのバケット内にプライベートなオブジェクトとパブリックなオブジェクトを混在させることはできません。
• プライベートファイルには、Storage::disk()->put(...) のように、引数なしで Storage::disk() を常に使用してください。これにより、Laravel は環境のデフォルトディスクを使用します。プライベート／デフォルトのストレージには、ディスク名を渡さないでください。プライベートな Cloud バケットを環境のデフォルトディスクとしてアタッチしてください。
• パブリックファイルには、名前付きのパブリックディスク Storage::disk('public')->put(...) を使用してください。パブリックとして設定した 2 つ目の Cloud バケットをアタッチし、public というディスク名を付けてください。
• プライベートファイルとパブリックファイルの両方を使用するアプリケーションでは、環境に 2 つの Cloud Object Storage バケットをアタッチする必要があります。プライベートなデフォルトバケットと、public という名前のパブリックバケットです。
• Cloud Object Storage では、ファイル単位または Flysystem の visibility: 'public' 設定を行わないでください。R2 はオブジェクト単位の ACL ヘッダーをサポートしておらず、そのようなリクエストを拒否します。バケットの作成時に可視性を選択してください。
• プライベートバケットにはインターネットからアクセスできませんが、Laravel の Storage::temporaryUrl(...) を使って一時的なパブリック URL を生成できます。パブリックバケットでは、すべてのオブジェクトが Cloud が提供するパブリック URL を通じて公開されます。
• Cloud Object Storage を使用する前に、S3 Flysystem アダプターをインストールしてください：composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies。

キューとスケジューリング

• 推奨されるキューの選択肢はマネージドキューです。専用ワーカーがプロビジョニングされ、キューに入った作業量に応じて自動スケーリングされます。
• マネージドキューには、サポート対象の最近の Laravel バージョンと aws/aws-sdk-php が必要です。依存関係を変更する前に、最新の Cloud ドキュメントを確認してください。
• App または Worker クラスターでスケジューラーを有効にすると、毎分 php artisan schedule:run が実行されます。環境に複数のレプリカがある場合、1 回だけ実行する必要があるタスクには Laravel の onOneServer を使用してください。
• ゼロまでスケーリングできるのは Flex のコンピュートサイズのみです。ゼロまでスケーリングする環境では、Laravel のスケジュールタスクやキューに入ったジョブの実行時に起動しますが、スリープタイムアウトに達すると、長時間実行されているジョブが中断される場合があります。中断してはならないワークロードにはマネージドキューを使用してください。

ドメインとストレージ

• 各環境には、初回のデプロイが正常に完了した後、laravel.cloud ドメインが割り当てられます。必要な DNS レコードが設定されると、Cloud がカスタムドメインを自動的に検証し、SSL をプロビジョニングします。
• 永続的なアップロード、生成ファイル、キャッシュ、セッションデータには、一時ファイルシステムを使用しないでください。代わりに、適切な Cloud リソースを使用してください。

Cloud CLI

セットアップ

composer require --dev laravel/cloud-cli
./vendor/bin/cloud auth -n

プロジェクトローカルにインストールされていない場合は、composer global require laravel/cloud-cli で CLI をグローバルにインストールし、cloud として実行してください。

cloud auth を実行するとブラウザーが開きます。ブラウザーを利用できない場合は、環境で LARAVEL_CLOUD_TOKEN を設定してください。この値は保存済みのトークンを上書きし、ディスクには何も書き込みません。代わりにトークンを保存するには、cloud auth:token --add --token=<token> -n を実行するか、echo "$TOKEN" | cloud auth:token --add -n でパイプしてください。

コマンド

コマンドは CRUD パターンに従います：resource:list、resource:get、resource:create、resource:update、resource:delete。

利用可能なリソース：application、environment、instance、database-cluster、database、cache、bucket、domain、websocket-cluster、background-process、secret、command、deployment。

一部のリソースには追加のコマンドがあります（例：domain:verify、database:open、instance:sizes、cache:types、database:types、<resource>:metrics）。これらは cloud -h で確認できます。

コマンドのシグネチャをハードコードしないでください。実行時にオプションを確認するには、必ず cloud <command> -h を実行してください。

CLI フラグ

• CLI がハングしないよう、すべてのコマンドに必ず -n を追加してください。
• すべての出力を抑制するため、-q または --silent は使用しないでください。

操作ごとのフラグの組み合わせ：

• 読み取り（:list、:get）→ --json -n
• 作成（:create）→ --json -n
• 更新（:update）→ --json -n --force
• 削除（:delete）→ -n --force（--json は付けません）
• 環境変数 → -n --force
• デプロイまたは出荷 → すべてのオプションを明示的に指定して -n（--json は付けません）

デプロイのワークフロー

タスクを判断し、該当する手順に従ってください。

• 初回デプロイ：cloud ship -h を確認してから、必要な値をすべて指定して cloud ship -n を実行します。

• 既存のアプリケーション：

  cloud deploy {app_name} {environment} -n --open
  cloud deploy:monitor -n
  

• 環境変数：cloud environment:variables -n --force

• シークレット：echo "$VALUE" | cloud secret:create --name=NAME --json -n を実行してから、cloud environment-secret:attach を実行します。

• インフラストラクチャのプロビジョニング：cloud <resource>:create --json -n

• モノレポ（サブディレクトリ内のアプリケーション）：cloud ship または cloud application:create に --root-directory=<subdir> を追加します。

• カスタムドメイン：cloud domain:create --json -n を実行してから、cloud domain:verify -n を実行します。

• エッジキャッシュ：cloud environment:purge-edge-cache {environment} -n はすべてのキャッシュをパージします。パージ範囲を絞るには、--path=/blog/post、--prefix=/blog/、--tag=<cache-tag> のいずれかを指定します。タグを使うには専用のエッジネットワークが必要です。

• Laravel Cloud ドメイン：cloud environment:vanity-domain {environment} --name=<subdomain> --deploy -n --force。ドメインの最初の部分のみを指定します。新しいドメインは次回のデプロイから有効になります。--deploy はそのデプロイを開始し、監視します。変更できるのは30分に1回のみなので、必ず事前にユーザーへ確認してください。

• リポジトリのデフォルト設定：cloud repo:config {application} -n は、リポジトリ内のアプリケーションと組織のデフォルトを設定します。ユーザーに複数の組織がある場合は、--organization=<id|name|slug> を指定します。

複数の手順を要する操作については、reference/checklists.md を参照してください。

• ユーザーの要望が不明確な場合は、何も実行する前に質問してください。

コマンドが失敗した場合

1. エラー出力を確認します。
2. :list --json -n または :get --json -n でリソースのステータスを確認します。
3. 認証エラーの場合は、cloud auth -n を実行します。
4. 問題を修正して、コマンドを再実行します。
5. 1回修正した後も同じエラーが発生する場合は、操作を繰り返さずに停止して、ユーザーに確認してください。

デプロイのたびに、必ず cloud deploy:monitor -n を実行してください。失敗した場合は、cloud deployment:logs {deploymentId} --json -n を実行して、"status": "failed" となっているビルドまたはデプロイのステップを探し、その output を確認してください。修正を試みる前に、何が問題だったかをユーザーに伝えてください。

サブエージェントへの委任

メインのコンテキストウィンドウを小さく保つため、出力の多い操作は Task ツールを使ってサブエージェントに委任してください。返されるのは要約のみで、詳細な出力はサブエージェントのコンテキストに残ります。

次の操作はサブエージェントに委任してください。

• cloud deploy:monitor -n — デプロイログが非常に長くなることがあります
• cloud deployment:get --json -n — デプロイの詳細情報全体
• cloud deployment:logs --json -n — 各ステップのビルドまたはデプロイ出力全体
• cloud <resource>:list --json -n — 多数のリソースを一覧表示すると、大量の JSON が生成されます
• cloud <resource>:metrics --json -n — すべてのデータポイントが含まれます。--fields（例：--fields=period,cpuUsage.average）で絞り込んでください
• cloud command:run — 出力が長くなる可能性がある場合
• cloud usage --detailed --json -n — ペイロードには、すべてのデータベース、キャッシュ、バケット、WebSocket、アプリケーションの詳細が含まれます
• WebFetch を使って https://cloud.laravel.com/docs/llms.txt からドキュメントを取得する操作

メインのコンテキストに残す操作：

• :create、:delete、:update などの短いコマンド — 出力が少ないため
• cloud deploy -n — デプロイ ID がすぐに必要なため
• 次の手順ですぐに結果を必要とするコマンド

ルール

以下のルールに従ってください。

• フラグの選択 — 上記で説明した組み合わせを必ず使用してください
• デプロイの順序 — デプロイしてから監視してください。監視を省略してはいけません
• 破壊的なコマンド — 必ず事前にユーザーに確認し、コマンドを表示して承認を待ってください。これには、アプリケーション、環境、データベース、キャッシュ、バケット、ドメイン、シークレットの削除と、Resend の切り離しが含まれます。
• エラーループ — 診断して一度修正し、再度失敗した場合はユーザーに確認してください

以下については状況に応じて判断してください。

• インスタンスサイズ、リージョン、クラスタータイプ — 指定されていない場合はユーザーに確認してください
• プロビジョニングするリソース — ユーザーの説明に基づいて決定してください
• プロビジョニングの順序 — 厳密な順序はありません
• 出力の提示方法 — 状況に応じて、要約、未加工データの表示、またはフィールドの抽出を行ってください

シークレット

シークレットは暗号化された値で、組織内で共有され、環境にアタッチされます。CLI は値をローカルで暗号化するため、平文が API に送信されることはありません。

cloud secret:list --json -n
echo "$VALUE" | cloud secret:create --name=STRIPE_KEY --json -n
cloud environment-secret:attach {environment} {secretId} -n
cloud environment-secret:detach {environment} {secretId} --force -n
cloud environment-secret:list {environment} --json -n

値をパイプで渡してください。--value= も使えますが、平文がシェルの履歴とプロセスリストに残ります。

secret:update、secret:delete、environment-secret:attach、environment-secret:detach では、名前ではなくシークレット ID を指定します。名前は一意ではありません。cloud secret:list --json -n で ID を確認してください。

secret:get はありません。environment-secret:detach はシークレットを 1 つの環境から切り離して保持します。secret:delete はシークレットを削除し、すべての環境から切り離します。

シークレットには PHP 拡張機能 sodium が必要です。他のコマンドでは必要ありません。

シークレットの作成、更新、アタッチ、切り離し、削除の後は、影響を受ける環境を再デプロイしてください。

メール（Resend）

Resend は環境のメール送信に使用されます。Resend アカウントの接続と送信ドメインの検証はダッシュボードで行います。CLI ではどちらも実行できません。resend:attach で検証済みの送信ドメインがないと表示された場合は、エラーに記載されているインテグレーション設定のリンクをユーザーに案内してください。

cloud resend:domains --status=verified --json -n
cloud resend:attach {environment} --from-address=hello@{verifiedDomain} --from-name="My App" --json -n
cloud resend:update {environment} --from-address=team@{verifiedDomain} --json -n
cloud resend:keys {environment} --json -n
cloud resend:detach {environment} --force -n

• 送信元アドレスには、検証済みの送信ドメインを使用する必要があります。--from-name のデフォルト値はアプリケーション名です。
• resend:attach は新しい送信キーを作成します。別の環境と共有するには、resend:keys で取得した ID を --reuse-key-id に渡してください。
• アタッチすると、Cloud は RESEND_API_KEY、MAIL_MAILER、MAIL_FROM_ADDRESS、MAIL_FROM_NAME を設定し、環境にすでに設定されていた値を置き換えます。
• アプリケーションには resend/resend-php が必要です。-n の場合、resend:attach は依存関係がないときに警告するだけです。プロジェクトで composer require resend/resend-php を実行してください。
• 切り離すと、別の環境で使用されていない限り、送信キーは削除されます。
• Resend のアタッチ、更新、切り離しの後は、環境を再デプロイしてください。

リモートアクセス

Tinker（v0.2.0 以降）

Cloud 環境で PHP コードを直接実行します。

cloud tinker {environment} --code='Your PHP code here' --timeout=60 -n

• --code — 実行する PHP コード（非対話モードでは必須）
• --timeout — 出力を待つ最大秒数（デフォルト：60）

コードでは、echo、dump などを使って結果を明示的に出力する必要があります。式だけでは出力されません。

対話型プロンプトを避けるため、必ず --code と -n を渡してください。

リモートコマンド

Cloud 環境でシェルコマンドを実行します。

cloud command:run {environment} --cmd='your command here' -n

• --cmd — 実行するコマンド（非対話モードでは必須）
• --no-monitor — リアルタイムの出力ストリーミングをスキップ
• --copy-output — 出力をクリップボードにコピー

過去のコマンドを確認します。

• cloud command:list {environment} --json -n — コマンド履歴を一覧表示
• cloud command:get {commandId} --json -n — 特定のコマンドの詳細と出力を取得

請求と使用状況

現在の組織の請求と使用状況を表示します。

cloud usage --json -n

• --period=current|previous|1|2|3 — 請求期間（デフォルト：current。1、2、3は、それぞれ1期間前、2期間前、3期間前です）。それ以外の値を指定するとエラーになります。
• --environment=<id> — 使用状況を単一の環境に絞り込みます
• --detailed — アプリケーション、リソース、アドオンごとの内訳を含めます
• --json — 機械可読形式で出力します（必ず -n と併用してください）

よく使うクエリ：

• 現在の支出：cloud usage --json -n | jq '.currentSpendCents'
• 先月の請求額：cloud usage --period=previous --json -n
• 1つの環境の詳細な内訳：cloud usage --environment=<id> --detailed --json -n

金額はすべてセント単位です。すべての階層のキーはキャメルケースです（例：currentSpendCents、bandwidth.allowanceBytes、databases[].totalCents、applications[].totalCostCents）。

設定

1. 環境変数：LARAVEL_CLOUD_TOKEN — API トークンです。保存済みのトークンより優先されます（空の場合は未設定として扱われます）
2. グローバル：~/.config/cloud/config.json — 認証トークンと設定
3. リポジトリローカル：.cloud/config.json — アプリケーションと環境のデフォルト設定（cloud repo:config {application} -nで設定）
4. CLI 引数は両方の設定ファイルより優先されます

repo:configにはアプリケーションを渡してください。省略すると、コマンドは入力を求めます。また、組織に複数のアプリケーションがある場合、-nを指定すると失敗します。デプロイコマンドにはこれらのデフォルト設定は不要です。アプリケーションと環境を直接渡してください。

複数の組織を利用するには、複数の API トークンを保存する必要があります。コマンドは.cloud/config.jsonからorganization_idを読み取り、組織を選択します。設定されていない場合、コマンドは失敗します。cloud repo:config {application} --organization=<id|name|slug> -nで設定してください。

LARAVEL_CLOUD_TOKENには1つのトークンしか設定できないため、それだけで組織が選択されます。トークンが属する組織とは別の組織を--organizationで指定すると、トークンが属する組織へのフォールバックは行われず、失敗します。

ドキュメント

Laravel Cloud のドキュメント：https://cloud.laravel.com/docs/llms.txt

Laravel Cloud の機能の仕組みについて質問された場合や、説明が必要な場合は、上記の URL からWebFetchでドキュメントを取得し、正確な回答に使用してください。

行き詰まった場合

• 公式ドキュメントは https://cloud.laravel.com/docs/llms.txt から取得してください
• コマンドのオプションは cloud <command> -h を実行して確認してください
• コマンドを確認するには cloud -h を実行してください

検証

1. 変更やデプロイを行う前に、対象のアプリケーションと環境を確認してください。
2. デプロイ前に、ステージングされた環境の変更と必要なリソースを確認してください。
3. cloud deploy:monitor -nで、すべてのデプロイが完了するまで監視してください。
4. 本番環境の変更後は、アプリケーションの URL、ログ、キュー、スケジュールされたタスク、および関連するリソースの健全性を確認してください。