Docker Bundling

Vários geradores (como ts#agent e py#agent) produzem uma imagem Docker que é enviada para o Amazon ECR e consumida pela infraestrutura AWS. Este guia descreve o padrão que eles seguem para que você possa aplicá-lo a outros casos de uso — por exemplo, executar um projeto FastAPI no Amazon ECS, ou implantar um servidor Express containerizado.

Docker ou Finch

O mecanismo de contêiner usado para construir imagens é escolhido no momento da criação do workspace através da flag --containers (docker, finch, ou infer — o padrão — que detecta automaticamente o que está instalado). Finch é uma alternativa open-source e drop-in para o Docker. A seleção é registrada em aws-nx-plugin.config.mts e aplicada a todos os geradores que emitem comandos de construção de contêiner. As construções de image asset do CDK respeitam a escolha através da variável de ambiente CDK_DOCKER.

O Padrão

O padrão recomendado tem três partes:

1. Um target bundle no seu projeto que produz um diretório autocontido de artefatos de runtime. Para TypeScript, isso é um bundle JavaScript de arquivo único com tree-shaking produzido pelo Rolldown; para Python, isso é um requirements.txt e dependências instaladas produzidas pelo uv.
2. Um Dockerfile mínimo que simplesmente faz COPY da saída do bundle para uma imagem base. Como o bundling já tratou do tree-shaking e da instalação de dependências, o Dockerfile não precisa executar npm install ou uv sync.
3. Um target docker que copia o Dockerfile junto com a saída do bundle (para que o contexto de build do Docker contenha apenas os arquivos necessários em runtime), e então executa docker build.

O contexto de build do Docker é escrito na pasta dist do seu projeto. Seu código de infraestrutura (CDK ou Terraform) então aponta para esse diretório para enviar a imagem para o ECR.

Por que fazer bundle fora do Dockerfile?

Manter a etapa de bundle no Nx (em vez de dentro do Dockerfile) significa:

• O Nx pode fazer cache do target bundle — sua saída é um diretório em disco, então um cache hit genuinamente o restaura.
• O Dockerfile não precisa de acesso ao seu monorepo, registros privados ou segredos de build.
• A camada da imagem é minúscula — um único COPY de artefatos já construídos, sem node_modules transitivos ou toolchain de build.

TypeScript

Bundle Target

Configure um target bundle que invoca o Rolldown. Se você está começando de um ts#project, adicione o seguinte ao seu project.json:

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

E um rolldown.config.ts na raiz do seu projeto:

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',
      codeSplitting: false,
    },
    platform: 'node',
  },
]);

Execute o target bundle para produzir 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

Dependências não empacotáveis

Alguns pacotes npm não podem ser empacotados porque dependem de require dinâmico, bindings nativos ou resolução de caminho de arquivo em runtime. Adicione-os ao array external em rolldown.config.ts para que sejam deixados como chamadas require() de runtime, e instale-os dentro do Dockerfile (veja abaixo):

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

Dockerfile

Crie um Dockerfile no diretório de origem do seu projeto. O arquivo não faz nada além de aplicar as atualizações de segurança da imagem base, fazer COPY do bundle para uma imagem base Node, mais npm install de quaisquer pacotes external que não puderam ser empacotados. Coloque a etapa RUN npm install antes do COPY, para que o Docker possa fazer cache da camada node_modules instalada e só executá-la novamente quando a lista de dependências realmente mudar:

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

# Apply the distribution's security updates: base image tags lag behind the
# security suite, so their OS packages carry vulnerabilities that already have a
# published fix.
RUN apt-get update && \
    apt-get upgrade -y --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

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"]

Fixe suas dependências

Fixe cada dependência instalada dentro do Dockerfile em uma versão exata (como acima) — caso contrário, npm install silenciosamente pegará uma versão mais recente na próxima vez que você construir, produzindo imagens que se comportam de forma diferente dependendo de quando foram construídas.

Docker Target

Adicione um target docker que:

1. Copia o Dockerfile para o diretório de saída do bundle (para que o contexto de build contenha apenas o bundle + Dockerfile), e
2. Executa docker build (opcional para CDK — veja abaixo).

{
  "targets": {
    "docker": {
      "cache": false,
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "shx cp 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"]
    }
  }
}

Não faça cache de construções de imagem

Defina "cache": false em targets de construção de imagem. Uma imagem construída não é escrita em um caminho de outputs no sistema de arquivos, então o Nx não tem nada para restaurar em um cache hit. Mecanismos de contêiner fazem cache de camadas de imagem independentemente, então não há penalidade de desempenho.

Cópia de arquivo multiplataforma

O pacote shx fornece comandos cp, rm e mkdir multiplataforma, evitando os builtins do shell (indisponíveis no Windows). Instale-o na raiz do seu workspace:

pnpm

pnpm add -Dw shx

yarn

yarn add -D shx

npm

npm install --legacy-peer-deps -D shx

bun

bun add -D shx

Executar este target produz uma imagem local com tag my-scope-my-project:latest, construída a partir do contexto mínimo em 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 constrói a imagem por si só

Se você está apenas implantando com CDK, o comando docker build acima é opcional — o DockerImageAsset do CDK (mostrado em Infraestrutura) construirá a imagem para você no momento do synth. Você ainda precisa copiar o Dockerfile para o diretório de contexto de build para que o CDK possa encontrá-lo. Os geradores mantêm a etapa local docker build para dar a você uma maneira rápida de testar a imagem com docker run.

Para Terraform, a etapa docker build é necessária — o padrão null_resource abaixo envia uma imagem com tag local.

Python

Bundle Target

Configure um target bundle que usa uv para exportar e instalar dependências para sua plataforma alvo. O gerador py#project e o gerador py#lambda-function configuram isso para você. A configuração do target se parece com:

{
  "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"]
    }
  }
}

Arquitetura alvo

Mude --python-platform para x86_64-manylinux_2_28 se sua imagem Docker for executar em x86_64.

Executar nx bundle my-project produz dist/packages/my-project/bundle-arm/ contendo o código-fonte do seu projeto, suas dependências e um requirements.txt — tudo que a imagem precisa em runtime.

Dockerfile

O Dockerfile aplica as atualizações de segurança da imagem base, e então copia o bundle para uma imagem base Python. Como o uv já instalou todas as dependências no diretório do bundle, você não precisa executar pip install dentro da imagem:

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

# Apply the distribution's security updates: base image tags lag behind the
# security suite, so their OS packages carry vulnerabilities that already have a
# published fix.
RUN apt-get update && \
    apt-get upgrade -y --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

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

Adicione um target docker que copia o Dockerfile para o diretório de saída do bundle, e então executa docker build:

{
  "targets": {
    "docker": {
      "cache": false,
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "shx rm -rf dist/packages/my-project/docker",
          "shx mkdir -p dist/packages/my-project/docker",
          "shx cp -R dist/packages/my-project/bundle-arm/. dist/packages/my-project/docker",
          "shx cp 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"]
    }
  }
}

Isso limpa o diretório de saída, e então copia tanto o conteúdo do bundle quanto o Dockerfile para dist/.../docker, que se torna o contexto de build do 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

Escaneando Imagens com Trivy

É uma boa prática escanear suas imagens em busca de vulnerabilidades conhecidas. Os geradores que seguem este padrão adicionam um target trivy que escaneia a imagem construída com Trivy, executando a partir da imagem Trivy hospedada no ECR, e sai com código diferente de zero em descobertas HIGH ou CRITICAL.

O target copia um .trivyignore da raiz do seu projeto para o diretório de escaneamento e o passa para o Trivy com --ignorefile, então crie esse arquivo primeiro — um vazio está bom, e é onde você suprime descobertas mais tarde:

touch packages/my-project/.trivyignore

Então adicione um target trivy que depende (dependsOn) do seu target docker. Ele salva a imagem construída em um tarball e a escaneia através de um bind mount relativo ao workspace, para que o mesmo comando funcione tanto com docker quanto com finch:

{
  "targets": {
    "trivy": {
      "cache": false,
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/trivy"],
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "shx rm -rf dist/packages/my-project/trivy",
          "shx mkdir -p dist/packages/my-project/trivy",
          "shx cp packages/my-project/.trivyignore dist/packages/my-project/trivy/.trivyignore",
          "docker save -o dist/packages/my-project/trivy/image.tar my-scope-my-project:latest",
          "docker run --rm -v \"./dist/packages/my-project/trivy\":/scan public.ecr.aws/aquasecurity/trivy:0.72.0 image --input /scan/image.tar --ignorefile /scan/.trivyignore --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 --no-progress -q"
        ],
        "parallel": false
      },
      "dependsOn": ["docker"]
    }
  }
}

Os targets de escaneamento por imagem de cada projeto são agregados sob um target trivy em todo o workspace, que o script raiz trivy fornecido executa (nx run-many --target trivy).

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

Execute Trivy no CI

O escaneamento intencionalmente não está conectado ao build, pois isso pode introduzir atrito desnecessário ao iterar durante o desenvolvimento, já que o banco de dados de vulnerabilidades do Trivy é continuamente atualizado com novos CVEs.

Em vez disso, recomendamos executar o comando acima como uma etapa dedicada em seu pipeline de CI antes da implantação em estágios de produção.

Suprimindo descobertas

O Trivy lê um arquivo .trivyignore (uma lista de IDs de vulnerabilidade, um por linha) da raiz do seu projeto. --ignore-unfixed pula vulnerabilidades sem correção disponível, então o escaneamento só falha em problemas que você pode resolver atualizando ferramentas no seu Dockerfile. Veja a documentação de filtragem do Trivy para detalhes.

Aplique as atualizações de segurança da distribuição

Uma tag de imagem base fica atrás do conjunto de segurança de sua distribuição, então seus pacotes do sistema operacional carregam vulnerabilidades que já têm uma correção publicada. Atualize-os como o primeiro passo da sua construção, antes de qualquer outra instrução para que as camadas posteriores instalem contra os pacotes atualizados. Para uma imagem base derivada do Debian (como usada pelas imagens Node e Python acima):

RUN apt-get update && \
    apt-get upgrade -y --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

Os Dockerfiles gerados fazem isso para você.

Infraestrutura

Conectar o diretório de contexto de build resultante ao código de infraestrutura é o mesmo para TypeScript e Python — apenas o caminho para o diretório de contexto de build difere (dist/packages/my-project/bundle para TypeScript, dist/packages/my-project/docker para Python).

CDK

Use o DockerImageAsset do CDK apontando para o diretório de contexto de build. O CDK construirá a imagem e a publicará no repositório ECR de assets do CDK no momento do 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,
});

O helper findWorkspaceRoot é gerado pelo gerador ts#infra e exportado de @my-scope/common-constructs. Se você não está usando constructs compartilhados, você pode codificar o caminho para o diretório dist relativo a onde cdk é invocado — tipicamente a raiz do workspace — e omitir completamente a chamada findWorkspaceRoot.

Executando bundle antes do synth

O CDK não executa os targets bundle/docker automaticamente — você deve executar nx build my-project (ou conectar o target deploy para depender de build) antes de cdk deploy. Os geradores que usam este padrão declaram docker e bundle como dependências de build para que isso aconteça de forma transparente.

Use o DockerImageAsset com qualquer construct AWS que aceite uma imagem de contêiner, por exemplo aws_ecs.ContainerImage.fromDockerImageAsset(image).

Terraform

O provider AWS do Terraform não tem um recurso de primeira classe “construir e enviar uma imagem Docker”. O padrão usado pelos geradores é:

1. O target build do projeto executa docker build, produzindo uma imagem local com tag my-scope-my-project:latest.
2. Um repositório ECR compartilhado usando o módulo core/asset-ecr
3. Um null_resource com um provisioner local-exec que autentica no ECR, re-tageia a imagem construída localmente com seu digest de conteúdo, e a envia.
4. O recurso downstream (por exemplo, aws_ecs_task_definition) referencia a imagem por sua tag imutável baseada em digest.

Como um repositório armazena todas as imagens, cada tag é namespacada pelo proprietário da imagem, bem como seu digest, então imagens compartilhando o registro nunca colidem.

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

# 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}}')'\"}'"]
}

locals {
  # Content-based, immutable image tag derived from the local image digest, and
  # namespaced by owner so images sharing the registry never collide
  image_tag = "my-project-${replace(data.external.docker_digest.result.digest, "sha256:", "")}"
}

resource "null_resource" "docker_publish" {
  triggers = {
    docker_digest  = data.external.docker_digest.result.digest
    repository_url = module.asset_ecr.repository_url
    image_tag      = local.image_tag
  }

  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}:${self.triggers.image_tag}
      docker push ${self.triggers.repository_url}:${self.triggers.image_tag}
    EOT
  }
}

O bloco data.external.docker_digest garante que o null_resource seja executado novamente sempre que o hash da imagem local mudar, acionando um novo push em cada mudança significativa de código. A imagem é enviada sob uma tag imutável baseada em conteúdo derivada de seu digest, então o repositório compartilhado usa mutabilidade de tag IMMUTABLE e rejeita qualquer tentativa de sobrescrever uma tag existente.

Executando bundle antes do apply

nx apply <project> requer que a tag de imagem my-scope-my-project:latest já exista localmente. Execute nx build my-project (ou nx docker my-project) antes de nx apply <project>.

Leitura Adicional

• Gerador ts#agent — um exemplo completo deste padrão para um agente TypeScript implantado no Bedrock AgentCore Runtime.
• Gerador py#agent — o equivalente para Python.
• Documentação do Rolldown — referência de configuração para o bundler TypeScript.
• Documentação do uv — referência para exportação e instalação de dependências Python.