Dépannage Docker

Cette page fournit des conseils de dépannage pour les problèmes que vous pouvez rencontrer avec les builds Docker produits par les générateurs. Consultez le guide Docker Bundling pour en savoir plus sur le modèle qu’ils suivent.

Builds multi-plateformes

Les générateurs tels que ts#strands-agent, py#strands-agent, ts#mcp-server et py#mcp-server produisent des images pour linux/arm64 (Graviton), quelle que soit l’architecture de l’hôte. Construire une image arm64 sur un hôte x86_64 — ou une image amd64 sur Apple Silicon — nécessite la prise en charge des builds multi-plateformes dans votre installation Docker locale.

Si les builds multi-plateformes ne sont pas configurés, le symptôme dépend du Dockerfile :

• Le Dockerfile contient une étape RUN (les générateurs TypeScript exécutent RUN npm install pour les dépendances non empaquetables) : le build échoue en cours de route avec

  exec /bin/sh: exec format error

• Le Dockerfile utilise uniquement COPY (générateurs Python) : le build réussit, mais docker run échoue plus tard avec

  exec /usr/local/bin/python: exec format error

• L’image de base n’est pas disponible pour la plateforme cible : le build échoue à l’étape FROM avec no match for platform in manifest.

Activer les builds multi-plateformes

Docker Desktop (Mac / Windows / Linux) est livré avec l’émulation QEMU activée par défaut — aucune configuration supplémentaire n’est généralement requise.

Les hôtes Linux (y compris les runners CI) nécessitent l’enregistrement des gestionnaires QEMU binfmt avec le noyau. Installez-les une fois par machine :

docker run --privileged --rm tonistiigi/binfmt --install all

Vérifiez que les plateformes prises en charge correspondent à ce que votre projet cible :

docker buildx inspect --bootstrap

La ligne Platforms: doit inclure linux/arm64.

Environnements CI

GitHub Actions, GitLab CI et les fournisseurs similaires n’enregistrent généralement pas les gestionnaires QEMU par défaut. Ajoutez une étape telle que docker/setup-qemu-action avant toute cible nx build / nx docker qui produit une image multi-architecture.

Builds lents sur architectures émulées

Construire une image arm64 sur un hôte x86_64 (ou vice versa) utilise QEMU pour émuler chaque instruction, ce qui peut être plusieurs fois plus lent qu’un build natif. Les générateurs atténuent ce problème en effectuant la résolution des dépendances en dehors du Dockerfile — voir Docker Bundling. Si vous constatez toujours des builds Docker lents :

• Assurez-vous d’exécuter les cibles bundle / docker via Nx (nx docker my-project) afin que le bundle soit mis en cache entre les exécutions.
• Sur CI, envisagez un runner ARM natif (par exemple ubuntu-24.04-arm de GitHub Actions) pour éviter complètement QEMU.

Contexte de build manquant lors de cdk deploy / nx apply

La cible docker générée écrit son contexte de build dans dist/packages/<project>/docker/... (Python) ou dist/packages/<project>/bundle/... (TypeScript), et l’infrastructure en tant que code générée pointe vers ce répertoire. Si ce répertoire n’existe pas lorsque vous synthétisez ou appliquez, vous verrez des erreurs comme ENOENT ou “directory does not exist”.

Les générateurs déclarent la cible docker comme dépendance de build, donc nx build (ou les cibles générées nx deploy / nx apply) produira le contexte de build avant que CDK ou Terraform ne s’exécute. Si vous invoquez cdk ou terraform directement, exécutez d’abord l’étape docker :

nx run my-project:docker

Lectures complémentaires

• Docker — Multi-platform builds
• Docker Bundling guide — le modèle que suivent les générateurs.