Risoluzione dei problemi Docker

Questa pagina fornisce una guida alla risoluzione dei problemi che potresti incontrare con le build Docker prodotte dai generatori. Consulta la guida al Docker Bundling per informazioni sul pattern che seguono.

Build Multi-Piattaforma

I generatori come ts#strands-agent, py#strands-agent, ts#mcp-server e py#mcp-server producono immagini per linux/arm64 (Graviton), indipendentemente dall’architettura dell’host. La creazione di un’immagine arm64 su un host x86_64 — o di un’immagine amd64 su Apple Silicon — richiede il supporto per le build multi-piattaforma nella tua installazione Docker locale.

Se le build multi-piattaforma non sono configurate, il sintomo dipende dal Dockerfile:

Il Dockerfile ha uno step RUN (i generatori TypeScript eseguono RUN npm install per le dipendenze non raggruppabili): la build fallisce a metà con
Terminal window
```
exec /bin/sh: exec format error
```
Il Dockerfile usa solo COPY (generatori Python): la build ha successo, ma docker run fallisce successivamente con
Terminal window
```
exec /usr/local/bin/python: exec format error
```
L’immagine base non è disponibile per la piattaforma di destinazione: la build fallisce allo step FROM con no match for platform in manifest.

Abilitare le Build Multi-Piattaforma

Docker Desktop (Mac / Windows / Linux) viene fornito con l’emulazione QEMU abilitata di default — di solito non è richiesta alcuna configurazione aggiuntiva.

Gli host Linux (inclusi i runner CI) necessitano dei gestori binfmt QEMU registrati con il kernel. Installali una volta per macchina:

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

Verifica che le piattaforme supportate corrispondano a quelle di destinazione del tuo progetto:

docker buildx inspect --bootstrap

La riga Platforms: dovrebbe includere linux/arm64.

Build Lente su Architetture Emulate

La creazione di un’immagine arm64 su un host x86_64 (o viceversa) usa QEMU per emulare ogni istruzione, il che può essere molte volte più lento di una build nativa. I generatori mitigano questo problema eseguendo la risoluzione delle dipendenze al di fuori del Dockerfile — vedi Docker Bundling. Se stai ancora riscontrando build Docker lente:

Assicurati di eseguire i target bundle / docker attraverso Nx (nx docker my-project) in modo che il bundle sia memorizzato nella cache tra le esecuzioni.
Su CI, considera un runner ARM nativo (ad es. ubuntu-24.04-arm di GitHub Actions) per evitare completamente QEMU.

Contesto di Build Mancante durante `cdk deploy` / `nx apply`

Il target docker generato scrive il suo contesto di build in dist/packages/<project>/docker/... (Python) o dist/packages/<project>/bundle/... (TypeScript), e l’infrastruttura come codice generata punta a quella directory. Se quella directory non esiste quando esegui synth o apply, vedrai errori come ENOENT o “directory does not exist”.

I generatori dichiarano il target docker come dipendenza di build, quindi nx build (o i target generati nx deploy / nx apply) produrrà il contesto di build prima che CDK o Terraform venga eseguito. Se invochi cdk o terraform direttamente, esegui prima lo step docker:

nx run my-project:docker

Ulteriori Letture

Docker — Multi-platform builds
Docker Bundling guide — il pattern seguito dai generatori.