Solução de Problemas do Docker

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

Builds Multi-Plataforma

Geradores como ts#strands-agent, py#strands-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 do caminho 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 QEMU binfmt 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 tem como alvo:

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 do que um build nativo. Os geradores mitigam isso fazendo a resolução de dependências fora do Dockerfile — consulte Docker Bundling. Se você ainda estiver vendo builds Docker lentos:

Certifique-se de estar executando os targets bundle / docker através do Nx (nx docker my-project) para que o bundle 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 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ê executar 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 do CDK ou Terraform executar. Se você invocar cdk ou terraform diretamente, execute a etapa docker primeiro:

nx run my-project:docker

Leitura Adicional

Docker — Multi-platform builds
Docker Bundling guide — o padrão que os geradores seguem.