Solución de problemas de Docker

Esta página proporciona orientación para solucionar problemas que pueda encontrar con las compilaciones de Docker producidas por los generadores. Consulte la guía de empaquetado de Docker para obtener información sobre el patrón que siguen.

Compilaciones multiplataforma

Los generadores como ts#strands-agent, py#strands-agent, ts#mcp-server y py#mcp-server producen imágenes para linux/arm64 (Graviton), independientemente de la arquitectura del host. Compilar una imagen arm64 en un host x86_64 — o una imagen amd64 en Apple Silicon — requiere soporte de compilación multiplataforma en su instalación local de Docker.

Si las compilaciones multiplataforma no están configuradas, el síntoma depende del Dockerfile:

• El Dockerfile tiene un paso RUN (los generadores de TypeScript ejecutan RUN npm install para dependencias no empaquetables): la compilación falla a mitad de camino con

  exec /bin/sh: exec format error

• El Dockerfile solo usa COPY (generadores de Python): la compilación tiene éxito, pero docker run falla más tarde con

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

• La imagen base no está disponible para la plataforma de destino: la compilación falla en el paso FROM con no match for platform in manifest.

Habilitar compilaciones multiplataforma

Docker Desktop (Mac / Windows / Linux) viene con emulación QEMU habilitada de forma predeterminada — normalmente no se requiere configuración adicional.

Los hosts Linux (incluidos los ejecutores de CI) necesitan controladores binfmt de QEMU registrados con el kernel. Instálelos una vez por máquina:

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

Verifique que las plataformas compatibles coincidan con las que su proyecto tiene como objetivo:

docker buildx inspect --bootstrap

La línea Platforms: debe incluir linux/arm64.

Entornos de CI

GitHub Actions, GitLab CI y proveedores similares normalmente no registran controladores QEMU de forma predeterminada. Agregue un paso como docker/setup-qemu-action antes de cualquier objetivo nx build / nx docker que produzca una imagen de arquitectura cruzada.

Compilaciones lentas en arquitecturas emuladas

Compilar una imagen arm64 en un host x86_64 (o viceversa) usa QEMU para emular cada instrucción, lo que puede ser muchas veces más lento que una compilación nativa. Los generadores mitigan esto haciendo la resolución de dependencias fuera del Dockerfile — consulte Empaquetado de Docker. Si todavía está viendo compilaciones de Docker lentas:

• Asegúrese de ejecutar los objetivos bundle / docker a través de Nx (nx docker my-project) para que el paquete se almacene en caché entre ejecuciones.
• En CI, considere un ejecutor ARM nativo (por ejemplo, ubuntu-24.04-arm de GitHub Actions) para evitar QEMU por completo.

Contexto de compilación faltante en cdk deploy / nx apply

El objetivo docker generado escribe su contexto de compilación en dist/packages/<project>/docker/... (Python) o dist/packages/<project>/bundle/... (TypeScript), y la infraestructura como código generada apunta a ese directorio. Si ese directorio no existe cuando sintetiza o aplica, verá errores como ENOENT o “directory does not exist”.

Los generadores declaran el objetivo docker como una dependencia de build, por lo que nx build (o los objetivos generados nx deploy / nx apply) producirán el contexto de compilación antes de que CDK o Terraform se ejecute. Si invoca cdk o terraform directamente, ejecute primero el paso de docker:

nx run my-project:docker

Lectura adicional

• Docker — Multi-platform builds
• Guía de empaquetado de Docker — el patrón que siguen los generadores.