Configuration

Lorsque vous déployez sur la plateforme Mastra, la CLI génère un fichier de configuration .mastra-project.json et résout les variables d’environnement depuis la plateforme et, facultativement, vos fichiers .env locaux.

Cette page explique ces deux mécanismes.

Configuration du projet

Le fichier .mastra-project.json est généré automatiquement lors de votre premier mastra deploy. Il associe votre projet local à un projet de la plateforme. L’intégration GitHub écrit le même fichier dans les dépôts associés.

Validez-le dans votre gestion de versions afin que les déploiements suivants, y compris depuis la CI, ciblent le bon projet.

Votre fichier ressemblera à ceci :

.mastra-project.json

{
  "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
  "projectName": "my-project",
  "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
}

Champ	Description
projectId	UUID du projet, attribué à sa création.
projectName	Nom de projet lisible par une personne. Il sert de libellé d’affichage dans le tableau de bord et la sortie de la CLI.
organizationId	Organisation propriétaire du projet. Tous les déploiements, clés d’API et ressources sont limités à cette organisation.

Variables d’environnement

Un fichier env local est facultatif. mastra deploy résout les variables depuis trois sources :

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

Pour fixer le déploiement à un fichier env précis au lieu de vous fier à la sélection par défaut, passez --env-file :

mastra deploy --env-file .env.production --yes

Examinez et nettoyez les fichiers env locaux avant le déploiement afin d’éviter d’envoyer des secrets personnels ou réservés au développement.

Observability

Les variables d’environnement suivantes configurent le produit Observability sur la plateforme Mastra.

Variable	Description
MASTRA_PLATFORM_ACCESS_TOKEN	Token d’accès limité à l’organisation. La CLI l’écrit lors du provisionnement d’Observability et l’utilise pour s’authentifier auprès de la plateforme.
MASTRA_PROJECT_ID	UUID du projet de la plateforme. MastraPlatformExporter l’utilise pour associer les données d’observabilité au projet de plateforme. Les déploiements Studio et Server lisent l’ID de projet depuis .mastra-project.json.
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT	Remplacement facultatif de l’endpoint d’observabilité. Cette variable n’est définie automatiquement que pour le développement local de la plateforme. Sa valeur par défaut est https://observability.mastra.ai.
MASTRA_ORG_ID	Remplace l’organisation active pour les commandes de la CLI. Vous pouvez aussi la définir avec l’indicateur --org sur les commandes prises en charge.

MastraPlatformExporter lit MASTRA_PLATFORM_ACCESS_TOKEN pour authentifier l’export vers la plateforme.

Environnements multiples

Un seul projet exécute la même base de code dans plusieurs environnements, tels que production et staging. Chaque environnement possède sa propre URL, ses propres variables stockées et son propre historique de déploiement. Un seul fichier .mastra-project.json les couvre tous :

mastra deploy --env production --yes
mastra deploy --env staging --env-file .env.staging --yes

remarque

Les versions précédentes de la plateforme exigeaient un projet par environnement. Les environnements remplacent ce modèle ; conservez donc un seul projet et déployez dans ses environnements.