Déployer Mastra sur AWS Lambda

Déployez votre application Mastra sur AWS Lambda à l’aide de conteneurs Docker et de l’adaptateur web AWS Lambda. Cette approche exécute votre serveur Mastra sous la forme d’une fonction Lambda conteneurisée avec mise à l’échelle automatique.

info

Ce guide explique comment déployer le serveur Mastra. Si vous utilisez un adaptateur de serveur ou un framework web, procédez comme vous le feriez habituellement pour ce framework.

Avant de commencer

Vous aurez besoin des éléments suivants :

• Une application Mastra
• Un compte AWS disposant des autorisations nécessaires pour Lambda, ECR et IAM
• AWS CLI installé : exécutez aws configure pour vous authentifier
• Docker installé et en cours d’exécution

attention

Sur AWS Lambda, le système de fichiers est éphémère : tout fichier de base de données local sera donc perdu entre les appels. Si vous utilisez LibSQLStore avec un fichier local, configurez-le plutôt pour utiliser une base de données distante compatible avec LibSQL (par exemple, Turso).

Créer un Dockerfile

Créez un Dockerfile à la racine de votre projet :

Dockerfile

FROM node:22-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci

# Copy source and build Mastra
COPY src ./src
RUN npx mastra build

# Alpine compatibility for some native deps
RUN apk add --no-cache gcompat

# Add the Lambda Web Adapter
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapter

# Run as non-root
RUN addgroup -g 1001 -S nodejs && \
  adduser -S mastra -u 1001 && \
  chown -R mastra:nodejs /app

USER mastra

# Adapter / app configuration
ENV PORT=8080
ENV NODE_ENV=production
ENV AWS_LWA_READINESS_CHECK_PATH="/api"

# Start the Mastra server
CMD ["node", ".mastra/output/index.mjs"]

remarque

Ce Dockerfile utilise npm. Si vous utilisez pnpm, yarn ou un autre gestionnaire de paquets, adaptez les commandes en conséquence (par exemple, npm ci ne fonctionne pas avec les fichiers de verrouillage de pnpm).

Générer et publier l’image Docker

1. Configurez les variables d’environnement du déploiement. Utilisez la même région pour tous les services AWS (ECR, Lambda) afin d’éviter que certaines ressources n’apparaissent pas d’une région à l’autre :

   export PROJECT_NAME="your-mastra-app"
   export AWS_REGION="us-east-1"
   export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

2. Générez votre image Docker. Désactivez BuildKit afin de garantir la compatibilité de l’image avec l’environnement d’exécution de conteneurs de Lambda :

   export DOCKER_BUILDKIT=0
   docker build --platform linux/arm64 -t "$PROJECT_NAME" .

   remarque

   Le format d’image par défaut de BuildKit peut entraîner des problèmes de compatibilité avec Lambda. Définir DOCKER_BUILDKIT=0 permet d’utiliser le générateur classique, qui produit des images dans un format accepté de manière fiable par Lambda.

3. Créez un dépôt Amazon ECR pour stocker votre image Docker :

   aws ecr create-repository --repository-name "$PROJECT_NAME" --region "$AWS_REGION"

4. Connectez-vous à Amazon ECR :

   aws ecr get-login-password --region "$AWS_REGION" | \
     docker login --username AWS --password-stdin \
     "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com"

5. Étiquetez votre image et publiez-la dans ECR :

   docker tag "$PROJECT_NAME":latest \
     "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest
   
   docker push \
     "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest

Créer la fonction Lambda

1. Accédez à la console AWS Lambda et cliquez sur Créer une fonction. Vérifiez que la région sélectionnée est la même que celle dans laquelle vous avez créé votre dépôt ECR.

2. Sélectionnez Image de conteneur, puis configurez la fonction :

   • Nom de la fonction : saisissez un nom (par exemple, mastra-app)
   • URI de l’image de conteneur : cliquez sur Parcourir les images, sélectionnez votre dépôt ECR, puis choisissez l’étiquette latest
   • Architecture : sélectionnez arm64

   Cliquez sur Créer une fonction pour créer la fonction Lambda.

3. Configurez la mémoire et le délai d’expiration. Accédez à Configuration > Configuration générale, puis cliquez sur Modifier :

   • Mémoire : 512 Mo (à adapter aux besoins de votre application)
   • Délai d’expiration : 1 minute ou plus (la valeur par défaut de 3 secondes est trop courte pour la plupart des applications Mastra)

   Cliquez sur Enregistrer.

4. Ajoutez des variables d’environnement. Accédez à Configuration > Variables d’environnement, puis cliquez sur Modifier. Ajoutez les variables dont votre application Mastra a besoin :

   • OPENAI_API_KEY : votre clé API OpenAI (si vous utilisez OpenAI)
   • ANTHROPIC_API_KEY : votre clé API Anthropic (si vous utilisez Anthropic)
   • Les autres clés API propres aux fournisseurs selon vos besoins (par exemple, TURSO_DATABASE_URL et TURSO_AUTH_TOKEN si vous utilisez LibSQL avec Turso)

   Cliquez sur Enregistrer.

5. Activez une URL de fonction pour permettre un accès externe. Accédez à Configuration > URL de fonction, puis cliquez sur Créer une URL de fonction :

   • Type d’authentification : sélectionnez AUCUN pour un accès public
   • Sous Paramètres supplémentaires, cochez Configurer le partage des ressources entre origines (CORS), puis définissez les options suivantes :
     • Origines autorisées : *
     • En-têtes autorisés : content-type (x-amzn-request-context est également requis avec des services tels que CloudFront/API Gateway)
     • Méthodes autorisées : *

   Cliquez sur Enregistrer.

Vérifier votre déploiement

1. Copiez l’URL de la fonction depuis la console Lambda, puis ouvrez <your-function-url>/api/agents dans votre navigateur. Une liste JSON de vos agents devrait s’afficher.

2. Vous pouvez maintenant appeler vos points de terminaison Mastra via HTTP.

   attention

   Pour les déploiements en production, configurez l’authentification avant d’exposer publiquement vos points de terminaison, limitez les origines CORS à vos domaines de confiance, utilisez des rôles AWS IAM pour accéder de façon sécurisée aux autres services AWS et stockez les variables d’environnement sensibles dans AWS Secrets Manager ou Parameter Store.

Étapes suivantes

Ce guide propose une prise en main rapide du déploiement de Mastra sur AWS Lambda. Pour les charges de travail en production, envisagez d’activer la surveillance CloudWatch pour votre fonction Lambda, de configurer AWS X-Ray pour le traçage distribué et de configurer la simultanéité provisionnée afin d’obtenir des performances constantes.

Ressources associées

• Présentation du déploiement
• Serveur Mastra
• Adaptateurs de serveur
• Documentation AWS Lambda
• Adaptateur web AWS Lambda