Solução de Problemas do Docker

Esta página fornece orientações para solução de problemas que você pode encontrar com os builds do Docker produzidos pelos geradores. Consulte o guia de Empacotamento Docker para entender o padrão que eles seguem.

Builds Multi-Plataforma

Geradores como ts#agent, py#agent, ts#mcp-server e py#mcp-server produzem imagens para linux/arm64 (Graviton), independentemente da arquitetura do host. Construir uma imagem arm64 em um host x86_64 — ou uma imagem amd64 no Apple Silicon — requer suporte a build multi-plataforma na sua instalação local do Docker.

Se os builds multi-plataforma não estiverem configurados, o sintoma depende do Dockerfile:

Dockerfile tem uma etapa RUN (geradores TypeScript executam RUN npm install para dependências não empacotáveis): o build falha no meio com
Terminal window
```
exec /bin/sh: exec format error
```
Dockerfile usa apenas COPY (geradores Python): o build é bem-sucedido, mas docker run falha posteriormente com
Terminal window
```
exec /usr/local/bin/python: exec format error
```
Imagem base não está disponível para a plataforma de destino: o build falha na etapa FROM com no match for platform in manifest.

Habilitar Builds Multi-Plataforma

Docker Desktop (Mac / Windows / Linux) vem com emulação QEMU habilitada por padrão — nenhuma configuração extra é geralmente necessária.

Hosts Linux (incluindo runners de CI) precisam de manipuladores binfmt QEMU registrados no kernel. Instale-os uma vez por máquina:

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

Verifique se as plataformas suportadas correspondem ao que seu projeto visa:

docker buildx inspect --bootstrap

A linha Platforms: deve incluir linux/arm64.

Builds Lentos em Arquiteturas Emuladas

Construir uma imagem arm64 em um host x86_64 (ou vice-versa) usa QEMU para emular cada instrução, o que pode ser muitas vezes mais lento que um build nativo. Os geradores mitigam isso fazendo a resolução de dependências fora do Dockerfile — consulte Empacotamento Docker. Se você ainda estiver vendo builds do Docker lentos:

Certifique-se de estar executando os targets bundle / docker através do Nx (nx docker my-project) para que o pacote seja armazenado em cache entre as execuções.
No CI, considere um runner ARM nativo (por exemplo, ubuntu-24.04-arm do GitHub Actions) para evitar o QEMU completamente.

Contexto de Build Ausente em `cdk deploy` / `nx apply`

O target docker gerado escreve seu contexto de build em dist/packages/<project>/docker/... (Python) ou dist/packages/<project>/bundle/... (TypeScript), e a infraestrutura como código gerada aponta para esse diretório. Se esse diretório não existir quando você fizer synth ou apply, você verá erros como ENOENT ou “directory does not exist”.

Os geradores declaram o target docker como uma dependência de build, então nx build (ou os targets nx deploy / nx apply gerados) produzirão o contexto de build antes que o CDK ou Terraform seja executado. Se você invocar cdk ou terraform diretamente, execute a etapa docker primeiro:

nx run my-project:docker

Leitura Adicional

Docker — Multi-platform builds
guia de Empacotamento Docker — o padrão que os geradores seguem.