Bundling Docker

Diversi generatori (come ts#strands-agent e py#strands-agent) producono un’immagine Docker che viene caricata su Amazon ECR e utilizzata dall’infrastruttura AWS. Questa guida descrive il pattern che seguono in modo da poterlo applicare ad altri casi d’uso — ad esempio, eseguire un progetto py#fast-api su Amazon ECS o distribuire un server Express containerizzato.

Il Pattern

Il pattern raccomandato è composto da tre parti:

1. Un target bundle sul tuo progetto che produce una directory autonoma di artefatti di runtime. Per TypeScript si tratta di un bundle JavaScript a file singolo ottimizzato tramite tree-shaking prodotto da Rolldown; per Python si tratta di un requirements.txt e delle dipendenze installate prodotte da uv.
2. Un Dockerfile minimale che semplicemente esegue COPY dell’output del bundle in un’immagine base. Poiché il bundling ha già gestito il tree-shaking e l’installazione delle dipendenze, il Dockerfile non necessita di eseguire npm install o uv sync.
3. Un target docker che copia il Dockerfile accanto all’output del bundle (in modo che il contesto di build Docker contenga solo i file necessari al runtime), quindi esegue docker build.

Il contesto di build Docker viene scritto nella cartella dist del tuo progetto. Il tuo codice di infrastruttura (CDK o Terraform) punta quindi a quella directory per caricare l’immagine su ECR.

Perché eseguire il bundle fuori dal Dockerfile?

Mantenere lo step di bundle in Nx (anziché all’interno del Dockerfile) significa:

• Nx può cachare il target bundle, quindi le build ripetute sono veloci.
• Il Dockerfile non necessita di accesso al tuo monorepo, ai registri privati o ai segreti di build-time.
• Il layer dell’immagine è minuscolo — un singolo COPY di artefatti già compilati, senza node_modules transitivi o toolchain di build.

TypeScript

Bundle Target

Configura un target bundle che invoca Rolldown. Se stai partendo da un ts#project, aggiungi quanto segue al tuo project.json:

{
  "targets": {
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle"],
      "options": {
        "command": "rolldown -c rolldown.config.ts",
        "cwd": "{projectRoot}"
      },
      "dependsOn": ["compile"]
    }
  }
}

E un rolldown.config.ts alla radice del tuo progetto:

rolldown.config.ts

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    tsconfig: 'tsconfig.lib.json',
    input: 'src/index.ts',
    output: {
      file: '../../dist/packages/my-project/bundle/index.js',
      format: 'cjs',
      inlineDynamicImports: true,
    },
    platform: 'node',
  },
]);

Esegui il target bundle per produrre dist/packages/my-project/bundle/index.js:

pnpm

pnpm nx bundle my-project

yarn

yarn nx bundle my-project

npm

npx nx bundle my-project

bun

bunx nx bundle my-project

Dipendenze non bundlabili

Alcuni pacchetti npm non possono essere inclusi nel bundle perché si basano su require dinamici, binding nativi o risoluzione di percorsi file a runtime. Aggiungili all’array external in rolldown.config.ts in modo che vengano lasciati come chiamate require() a runtime, e installali all’interno del Dockerfile invece (vedi sotto):

{
  // ...
  external: ['@aws/aws-distro-opentelemetry-node-autoinstrumentation'],
}

Dockerfile

Crea un Dockerfile nella directory sorgente del tuo progetto. Il file non fa altro che eseguire COPY del bundle in un’immagine base Node, più npm install di eventuali pacchetti external che non possono essere inclusi nel bundle. Posiziona lo step RUN npm install prima del COPY, in modo che Docker possa cachare il layer node_modules installato e rieseguirlo solo quando l’elenco delle dipendenze cambia effettivamente:

FROM public.ecr.aws/docker/library/node:lts

WORKDIR /app

# Install packages that cannot be bundled (declared as "external" in rolldown.config.ts).
# Kept above the COPY so this layer is cached and only invalidated when the install list changes.
RUN npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation@0.10.0

# Copy bundled application
COPY index.js /app

EXPOSE 8080

CMD ["node", "index.js"]

Fissa le tue dipendenze

Fissa ogni dipendenza installata all’interno del Dockerfile a una versione esatta (come sopra) — altrimenti npm install scaricherà silenziosamente una release più recente la prossima volta che esegui la build, producendo immagini che si comportano diversamente a seconda di quando sono state costruite.

Docker Target

Aggiungi un target docker che:

1. Copia il Dockerfile nella directory di output del bundle (in modo che il contesto di build contenga solo il bundle + Dockerfile), e
2. Esegue docker build (opzionale per CDK — vedi sotto).

{
  "targets": {
    "docker": {
      "cache": true,
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "ncp packages/my-project/src/Dockerfile dist/packages/my-project/bundle/Dockerfile",
          "docker build --platform linux/arm64 -t my-scope-my-project:latest dist/packages/my-project/bundle"
        ],
        "parallel": false
      },
      "dependsOn": ["bundle"]
    }
  }
}

Copia file cross-platform

Il pacchetto ncp fornisce un comando di copia file/directory cross-platform, evitando cp (non disponibile su Windows). Installalo alla radice del tuo workspace con pnpm add -D -w ncp.

L’esecuzione di questo target produce un’immagine locale taggata my-scope-my-project:latest, costruita dal contesto minimale in dist/packages/my-project/bundle/:

pnpm

pnpm nx docker my-project

yarn

yarn nx docker my-project

npm

npx nx docker my-project

bun

bunx nx docker my-project

CDK costruisce l’immagine da solo

Se stai distribuendo solo con CDK, il comando docker build sopra è opzionale — DockerImageAsset di CDK (mostrato sotto Infrastructure) costruirà l’immagine per te al momento del synth. Devi comunque copiare il Dockerfile nella directory del contesto di build in modo che CDK possa trovarlo. I generatori mantengono lo step locale docker build per darti un modo rapido per fare uno smoke-test dell’immagine con docker run.

Per Terraform, lo step docker build è richiesto — il pattern null_resource sotto carica un’immagine taggata localmente.

Python

Bundle Target

Configura un target bundle che usa uv per esportare e installare le dipendenze per la tua piattaforma target. Il generatore py#project e il generatore py#lambda-function configurano entrambi questo per te. La configurazione del target appare così:

{
  "targets": {
    "bundle-arm": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle-arm"],
      "options": {
        "commands": [
          "uv export --frozen --no-dev --no-editable --project {projectRoot} --package my_project -o dist/{projectRoot}/bundle-arm/requirements.txt",
          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform aarch64-manylinux_2_28 --target dist/{projectRoot}/bundle-arm -r dist/{projectRoot}/bundle-arm/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    }
  }
}

Architettura target

Cambia --python-platform in x86_64-manylinux_2_28 se la tua immagine Docker verrà eseguita su x86_64.

L’esecuzione di nx bundle my-project produce dist/packages/my-project/bundle-arm/ contenente il sorgente del tuo progetto, le sue dipendenze e un requirements.txt — tutto ciò di cui l’immagine ha bisogno al runtime.

Dockerfile

Il Dockerfile copia semplicemente il bundle in un’immagine base Python. Poiché uv ha già installato tutte le dipendenze nella directory del bundle, non è necessario eseguire pip install all’interno dell’immagine:

FROM public.ecr.aws/docker/library/python:3.12-slim

WORKDIR /app

# Copy bundled package (source + installed dependencies)
COPY . /app

EXPOSE 8080

ENV PYTHONPATH=/app
ENV PATH="/app/bin:${PATH}"

CMD ["python", "-m", "my_project.main"]

Docker Target

Aggiungi un target docker che copia il Dockerfile nella directory di output del bundle, quindi esegue docker build:

{
  "targets": {
    "docker": {
      "cache": true,
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "rimraf dist/packages/my-project/docker",
          "make-dir dist/packages/my-project/docker",
          "ncp dist/packages/my-project/bundle-arm dist/packages/my-project/docker",
          "ncp packages/my-project/src/Dockerfile dist/packages/my-project/docker/Dockerfile",
          "docker build --platform linux/arm64 -t my-scope-my-project:latest dist/packages/my-project/docker"
        ],
        "parallel": false
      },
      "dependsOn": ["bundle-arm"]
    }
  }
}

Questo cancella la directory di output, quindi copia sia i contenuti del bundle che il Dockerfile in dist/.../docker, che diventa il contesto di build Docker.

pnpm

pnpm nx docker my-project

yarn

yarn nx docker my-project

npm

npx nx docker my-project

bun

bunx nx docker my-project

Infrastructure

Collegare la directory del contesto di build risultante all’infrastruttura come codice è lo stesso sia per TypeScript che per Python — cambia solo il percorso alla directory del contesto di build (dist/packages/my-project/bundle per TypeScript, dist/packages/my-project/docker per Python).

CDK

Usa DockerImageAsset di CDK puntando alla directory del contesto di build. CDK costruirà l’immagine e la pubblicherà nel repository ECR degli asset CDK al momento del deploy:

import { DockerImageAsset, Platform } from 'aws-cdk-lib/aws-ecr-assets';
import { findWorkspaceRoot } from ':my-scope/common-constructs';
import * as path from 'path';
import * as url from 'url';

const image = new DockerImageAsset(this, 'MyImage', {
  directory: path.join(
    // Resolve from the compiled construct location to the workspace root
    findWorkspaceRoot(url.fileURLToPath(new URL(import.meta.url))),
    'dist/packages/my-project/bundle',
  ),
  platform: Platform.LINUX_ARM64,
});

L’helper findWorkspaceRoot è generato dal generatore ts#infra ed esportato da :my-scope/common-constructs. Se non stai usando costrutti condivisi, puoi codificare il percorso alla directory dist relativo a dove viene invocato cdk — tipicamente la radice del workspace — e omettere completamente la chiamata a findWorkspaceRoot.

Eseguire bundle prima di synth

CDK non esegue automaticamente i target bundle/docker — devi eseguire nx build my-project (o collegare il target deploy a dipendere da build) prima di cdk deploy. I generatori che usano questo pattern dichiarano docker e bundle come dipendenze di build in modo che ciò avvenga in modo trasparente.

Usa DockerImageAsset con qualsiasi costrutto AWS che accetti un’immagine container, ad esempio aws_ecs.ContainerImage.fromDockerImageAsset(image).

Terraform

Il provider AWS di Terraform non ha una risorsa di prima classe “build and push a Docker image”. Il pattern usato dai generatori è:

1. Un aws_ecr_repository per contenere l’immagine.
2. Una null_resource con un provisioner local-exec che si autentica su ECR, ri-tagga l’immagine costruita localmente e la carica.
3. La risorsa downstream (ad es. aws_ecs_task_definition) fa riferimento a "${aws_ecr_repository.repo.repository_url}:latest".

resource "aws_ecr_repository" "repo" {
  name                 = "my-project-repository"
  image_tag_mutability = "MUTABLE"
  force_delete         = true
}

# Invalidate the push whenever the locally-built image digest changes
data "external" "docker_digest" {
  program = ["sh", "-c", "echo '{\"digest\":\"'$(docker inspect my-scope-my-project:latest --format '{{.Id}}')'\"}'"]
}

resource "null_resource" "docker_publish" {
  triggers = {
    docker_digest  = data.external.docker_digest.result.digest
    repository_url = aws_ecr_repository.repo.repository_url
  }

  provisioner "local-exec" {
    command = <<-EOT
      aws ecr get-login-password --region ${data.aws_region.current.id} \
        | docker login --username AWS --password-stdin ${self.triggers.repository_url}
      docker tag my-scope-my-project:latest ${self.triggers.repository_url}:latest
      docker push ${self.triggers.repository_url}:latest
    EOT
  }
}

Il blocco data.external.docker_digest garantisce che la null_resource venga rieseguita ogni volta che l’hash dell’immagine locale cambia, attivando un nuovo push ad ogni modifica significativa del codice.

Eseguire bundle prima di apply

nx apply <project> richiede che il tag dell’immagine my-scope-my-project:latest esista già localmente. Esegui nx build my-project (o nx docker my-project) prima di nx apply <project>.

Ulteriori Letture

• generatore ts#strands-agent — un esempio completo di questo pattern per un agente TypeScript distribuito su Bedrock AgentCore Runtime.
• generatore py#strands-agent — l’equivalente per Python.
• Documentazione Rolldown — riferimento di configurazione per il bundler TypeScript.
• Documentazione uv — riferimento per l’esportazione e l’installazione delle dipendenze Python.