Déployer sur Mastra Platform

mastra deploy est la commande unique qui permet de publier une application Mastra sur Mastra Platform.

Une seule commande compile et valide votre projet avant tout envoi. Lors de la première exécution, elle crée également le projet et l’environnement sur la plateforme, lance le déploiement, diffuse les journaux de compilation et affiche votre URL publique dès que le déploiement reçoit du trafic.

mastra deploy

remarque

Cette page décrit le flux de déploiement unifié. Les anciennes commandes distinctes, mastra server deploy et mastra studio deploy, fonctionnent toujours, mais mastra deploy constitue la méthode recommandée.

Avant de commencer

Vous avez besoin d’une application Mastra et d’un compte Mastra Platform. Si vous n’êtes pas authentifié, la CLI vous invite à vous connecter lors de la première utilisation.

Un fichier .env local est facultatif. Les variables d’environnement stockées sur la plateforme sont utilisées telles quelles lors du déploiement, et les ressources gérées comme les bases de données hébergées injectent leurs propres variables. Transmettez --env-file uniquement lorsque vous souhaitez ajouter des valeurs locales par-dessus.

Votre premier déploiement

1. Depuis le répertoire de votre projet, exécutez :

   mastra deploy

   Lors de la première exécution, la CLI vous invite à créer le projet sur la plateforme, nommé d’après votre package.json, ainsi que l’environnement production. Acceptez les invites ou transmettez --yes pour accepter les valeurs par défaut sans confirmation.

2. La CLI effectue une vérification préalable avant tout envoi. Un stockage qui se rabattrait sur un chemin de fichier local, lequel ne survit pas dans le système de fichiers éphémère de la plateforme, bloquerait normalement le déploiement :

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

   Au lieu de renvoyer une erreur, la CLI vous propose de corriger le problème directement :

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

   Acceptez l’invite : le provisionnement ne prend que quelques secondes et les variables de connexion de la base de données sont automatiquement injectées dans vos déploiements, sans rien avoir à copier dans un fichier .env. Si vous refusez ou exécutez la commande dans un shell non interactif (CI, --yes), la CLI reprend son comportement précédent et affiche la commande exacte à exécuter vous-même.

   mastra env db create production --kind turso

   Le slug de l’environnement (production ci-dessus) correspond à l’environnement dans lequel la CLI aurait effectué le déploiement. Ce point est important, car mastra env db create nécessite un argument d’environnement dans les shells non interactifs lorsque le projet comporte plusieurs environnements.

   remarque

   Si la vérification préalable signale plutôt un chemin local codé en dur (Build contains a host-local storage URL), elle ne peut pas proposer de correction directe. Commencez par protéger ce chemin avec une variable d’environnement afin que le fichier ne soit utilisé que pendant le développement local :

   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. Exécutez de nouveau mastra deploy. La vérification préalable réussit, la compilation est envoyée et la CLI diffuse les journaux de compilation jusqu’à la mise en ligne du déploiement. La compilation et le déploiement complets prennent entre 30 secondes et quelques minutes. Le message de réussite ne s’affiche que lorsque la nouvelle version reçoit du trafic.

4. Vérifiez votre déploiement à l’URL affichée par la CLI. Ajoutez /api/agents pour confirmer qu’elle renvoie une liste JSON de vos agents.

   attention

   Configurez l’authentification avant d’exposer publiquement vos endpoints.

Le premier déploiement écrit un fichier .mastra-project.json qui relie votre répertoire au projet de la plateforme. Validez ce fichier dans votre dépôt afin que les déploiements ultérieurs, les exécutions de CI et les commandes mastra env ciblent le même projet sans option supplémentaire.

Déployer dans un autre environnement

mastra deploy cible par défaut l’environnement production. Transmettez --env pour en cibler un autre. Si l’environnement n’existe pas encore, la CLI vous propose de le créer :

mastra deploy --env staging

Chaque environnement dispose de sa propre URL et de ses propres variables d’environnement. Il peut également posséder sa propre base de données hébergée.

Consultez la page Environnements pour découvrir le modèle complet.

Choisir une région

Transmettez --region lorsqu’un déploiement crée un nouvel environnement afin de choisir où il s’exécute. Utilisez les formes abrégées us ou eu :

mastra deploy --env production --region eu

La région est fixée lors de la création de l’environnement. Les bases de données rattachées à un environnement sont automatiquement placées à proximité de sa région, et les données d’observabilité sont routées vers la région d’ingestion correspondant à la zone de résidence de l’environnement. Consultez la page Régions pour obtenir la liste complète des régions prises en charge ainsi que des informations sur le placement des bases de données et la colocalisation des données d’observabilité.

Vérifications préalables

La vérification préalable valide le résultat de la compilation avant tout envoi et signale uniquement les problèmes présents dans votre propre code :

• Chemins de stockage locaux : il s’agit d’une erreur bloquante. Le stockage reposant sur des fichiers, par exemple file:./mastra.db, est perdu à chaque déploiement. La vérification préalable réussit lorsque le chemin est protégé par une variable d’environnement définie localement, stockée sur la plateforme ou fournie par une base de données gérée :

  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,
  })

• Variables d’environnement manquantes : un avertissement est émis pour les variables que votre code lit, mais qu’aucune source ne fournit. Les variables référencées uniquement par du code de bibliothèque sont exclues.

La réponse recommandée à un blocage de la vérification préalable consiste à en corriger la cause, généralement en rattachant une base de données hébergée ou en stockant la variable sur la plateforme. --skip-preflight offre une solution de secours, mais ignore les vérifications qui empêchent les déploiements défectueux.

Exécutez les vérifications sans effectuer de déploiement :

mastra lint --preflight

mastra lint voit uniquement vos fichiers d’environnement locaux. Les variables stockées sur la plateforme ou injectées par des bases de données gérées ne lui sont pas visibles ; un déploiement peut donc réussir la vérification préalable alors que lint signale toujours une erreur.

Variables d’environnement

Les déploiements résolvent les variables d’environnement à partir de trois sources :

• Variables gérées : injectées par des ressources de la plateforme telles que les bases de données hébergées, par exemple TURSO_DATABASE_URL. La plateforme les définit et vous ne pouvez pas les modifier.
• Variables stockées : enregistrées sur le projet ou l’environnement depuis le tableau de bord. Elles sont utilisées telles quelles à chaque déploiement, sans nécessiter de fichier local.
• Fichiers d’environnement locaux : les déploiements superposent un fichier --env-file explicite ou les fichiers .env et .env.local présents dans l’environnement local.

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

Pour modifier les variables d’un service en cours d’exécution sans le redéployer, mettez-les à jour dans le tableau de bord, puis exécutez mastra env restart.

Résolution du projet

Chaque déploiement résout son projet cible dans l’ordre suivant :

1. La variable d’environnement MASTRA_PROJECT_ID
2. L’option --project <name|slug|id>
3. Le fichier .mastra-project.json dans le répertoire actuel

Dans la CI, définissez MASTRA_PROJECT_ID et MASTRA_API_TOKEN, puis transmettez --yes :

mastra deploy --env production --yes

Ressources associées

• Environnements
• Régions
• Bases de données hébergées
• Référence CLI de mastra deploy
• Configuration