> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://github.com/awslabs/aws-lambda-web-adapter). 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](https://mastra.zisheng.pro/fr/docs/server/mastra-server). Si vous utilisez un [adaptateur de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters) ou un [framework web](https://mastra.zisheng.pro/fr/docs/deployment/web-framework), procédez comme vous le feriez habituellement pour ce framework.

## Avant de commencer

Vous aurez besoin des éléments suivants :

- Une [application Mastra](https://mastra.zisheng.pro/fr/guides/getting-started/quickstart)
- Un [compte AWS](https://aws.amazon.com/) disposant des autorisations nécessaires pour Lambda, ECR et IAM
- **[AWS CLI](https://aws.amazon.com/cli/)** installé : exécutez `aws configure` pour vous authentifier
- **[Docker](https://www.docker.com/)** 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](https://mastra.zisheng.pro/fr/reference/storage/libsql) avec un fichier local, configurez-le plutôt pour utiliser une base de données distante compatible avec LibSQL (par exemple, [Turso](https://turso.tech/)).

## 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 :

   ```bash
   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 :

   ```bash
   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 :

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

4. Connectez-vous à Amazon ECR :

   ```bash
   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 :

   ```bash
   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](https://console.aws.amazon.com/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](https://mastra.zisheng.pro/fr/docs/server/auth) 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](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html) pour votre fonction Lambda, de configurer [AWS X-Ray](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html) pour le traçage distribué et de configurer la [simultanéité provisionnée](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html) afin d’obtenir des performances constantes.

## Ressources associées

- [Présentation du déploiement](https://mastra.zisheng.pro/fr/docs/deployment/overview)
- [Serveur Mastra](https://mastra.zisheng.pro/fr/docs/server/mastra-server)
- [Adaptateurs de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters)
- [Documentation AWS Lambda](https://docs.aws.amazon.com/lambda/)
- [Adaptateur web AWS Lambda](https://github.com/awslabs/aws-lambda-web-adapter)