Mastra platformにデプロイする

mastra deployは、MastraアプリケーションをMastra platformにリリースするための単一コマンドです。

1つのコマンドで、処理を開始する前にプロジェクトをビルドして検証します。さらに、初回実行時にはplatformプロジェクトと環境を作成し、デプロイを実行してビルドログをストリーミングし、デプロイがトラフィックを処理し始めると公開URLを表示します。

mastra deploy

注記

このページでは、統合されたデプロイフローについて説明します。以前の分割コマンドであるmastra server deployとmastra studio deployも引き続き動作しますが、mastra deployが推奨される方法です。

始める前に

MastraアプリケーションとMastra platformアカウントが必要です。認証されていない場合、初回使用時にCLIがログインを求めます。

ローカルの.envファイルは任意です。platformに保存された環境変数はデプロイ時にそのまま使用され、ホステッドデータベースなどの管理対象リソースは独自の変数を注入します。ローカルの値を上位レイヤーとして適用する場合にのみ、--env-fileを渡してください。

最初のデプロイ

1. プロジェクトディレクトリから、次を実行します。

   mastra deploy

   初回実行時に、CLIはplatformプロジェクト（package.jsonに基づく名前）とproduction環境の作成を求めます。プロンプトを承認するか、確認なしでデフォルトを受け入れるには--yesを渡します。

2. CLIはリリース処理の前にpreflight checkを実行します。ローカルファイルパスにフォールバックするストレージ（platformの一時ファイルシステムでは保持されません）は通常、デプロイをブロックします。

   file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set

   CLIはエラーで終了する代わりに、その場での修正を提案します。

   Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)

   プロンプトを承認すると、プロビジョニングが数秒で行われます。データベースの接続変数はデプロイに自動的に注入されるため、.envファイルにコピーするものはありません。拒否するか、非対話型シェル（CI、--yes）で実行した場合、CLIは以前の動作にフォールバックし、自分で実行する正確なコマンドを表示します。

   mastra env db create production --kind turso

   環境slug（上記のproduction）は、CLIがデプロイしようとした環境と一致します。プロジェクトに複数の環境がある場合、非対話型シェルでmastra env db createを実行するには環境引数が必要なため、これは重要です。

   注記

   preflightで代わりにハードコードされたローカルパス（Build contains a host-local storage URL）が報告された場合、その場での修正は提供されません。まず環境変数でパスをガードし、ローカル開発時にのみファイルが使用されるようにしてください。

   src/mastra/index.ts

   new LibSQLStore({
     id: 'mastra-storage',
     // Uses the hosted database when deployed, a local file during development
     url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
     authToken: process.env.TURSO_AUTH_TOKEN,
   })

3. mastra deployをもう一度実行します。preflightを通過するとビルドがアップロードされ、デプロイがliveになるまでCLIがビルドログをストリーミングします。ビルドとデプロイ全体には、30秒から数分かかります。成功メッセージは、新しいバージョンがトラフィックを処理し始めたときにのみ表示されます。

4. CLIが表示したURLでデプロイを確認します。/api/agentsを追加し、AgentのJSONリストが返されることを確認してください。

   警告

   エンドポイントを公開する前に、認証を設定してください。

最初のデプロイでは、ディレクトリをplatformプロジェクトに関連付ける.mastra-project.jsonファイルが書き込まれます。以降のデプロイ、CI実行、mastra envコマンドが追加のフラグなしで同じプロジェクトを対象にするよう、コミットしてください。

別の環境にデプロイする

mastra deployはデフォルトでproduction環境を対象とします。別の環境を対象にするには--envを渡します。環境がまだ存在しない場合、CLIが作成を提案します。

mastra deploy --env staging

各環境には、個別のURLと環境変数が割り当てられます。独自のホステッドデータベースを持つこともできます。

全体のモデルについては、環境を参照してください。

リージョンを選択する

デプロイで新しい環境を作成するときに--regionを渡すと、実行する場所を指定できます。usまたはeuの省略形を使用します。

mastra deploy --env production --region eu

リージョンは環境の作成時に固定されます。環境に接続されたデータベースは、その環境のリージョン付近に自動配置され、Observabilityデータは環境のデータレジデンシーゾーンに対応する取り込みリージョンへルーティングされます。対応リージョン、データベースの配置、Observabilityのコロケーションについては、リージョンを参照してください。

Preflight check

preflightは処理を開始する前にビルド済みの出力を検証し、自分のコードにある問題のみを報告します。

• ローカルストレージパス: デプロイを完全にブロックします。ファイルベースのストレージ（例: file:./mastra.db）は、デプロイのたびに失われます。ローカルで設定された環境変数、platformに保存された環境変数、または管理対象データベースが提供する環境変数でパスがガードされている場合、preflightを通過します。

  src/mastra/storage.ts

  import { LibSQLStore } from '@mastra/libsql'
  
  export const storage = new LibSQLStore({
    id: 'mastra-storage',
    // Uses the hosted database when deployed, a local file during development
    url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
    authToken: process.env.TURSO_AUTH_TOKEN,
  })

• 不足している環境変数: コードが読み取るものの、どのソースからも提供されない変数に対する警告です。ライブラリコードからのみ参照される変数は除外されます。

preflightによってブロックされた場合は、通常、ホステッドデータベースを接続するか変数をplatformに保存して、原因を修正することを推奨します。--skip-preflightはエスケープハッチとして用意されていますが、壊れたデプロイを防ぐためのチェックを省略します。

デプロイせずにチェックを実行します。

mastra lint --preflight

mastra lintから見えるのはローカルのenvファイルだけです。platformに保存された変数や管理対象データベースによって注入される変数は認識されないため、lintではエラーが報告されても、デプロイ時のpreflightは通過する場合があります。

環境変数

デプロイは、次の3つのソースから環境変数を解決します。

• 管理変数: ホステッドデータベースなどのplatformリソースによって注入されます（例: TURSO_DATABASE_URL）。platformが定義するため、編集できません。
• 保存変数: ダッシュボードを通じてプロジェクトまたは環境に保存されます。ローカルファイルがなくても、デプロイのたびにそのまま使用されます。
• ローカルenvファイル: デプロイ時に、明示的に指定した--env-file、または現在の.envと.env.localファイルの値が上位レイヤーとして適用されます。

mastra deploy --env staging --env-file .env.staging

再デプロイせずに実行中のサービスの変数を変更するには、ダッシュボードで変数を更新し、mastra env restartを実行します。

プロジェクトの解決

すべてのデプロイは、次の順序で対象プロジェクトを解決します。

1. MASTRA_PROJECT_ID環境変数
2. --project <name|slug|id>フラグ
3. 現在のディレクトリにある.mastra-project.jsonファイル

CIでは、MASTRA_PROJECT_IDとMASTRA_API_TOKENを設定し、--yesを渡します。

mastra deploy --env production --yes

関連情報

• 環境
• リージョン
• ホステッドデータベース
• mastra deploy CLIリファレンス
• 設定