Empaquetado Docker

Varios generadores (como ts#agent y py#agent) producen una imagen Docker que se envía a Amazon ECR y es consumida por la infraestructura de AWS. Esta guía describe el patrón que siguen para que puedas aplicarlo a otros casos de uso — por ejemplo, ejecutar un proyecto FastAPI en Amazon ECS, o desplegar un servidor Express en contenedor.

Docker o Finch

El motor de contenedores utilizado para construir imágenes se elige en el momento de creación del espacio de trabajo mediante la bandera --containers (docker, finch, o infer — el valor predeterminado — que detecta automáticamente lo que está instalado). Finch es una alternativa de código abierto y compatible con Docker. La selección se registra en aws-nx-plugin.config.mts y se aplica a cada generador que emite comandos de construcción de contenedores. Las construcciones de activos de imagen de CDK respetan la elección a través de la variable de entorno CDK_DOCKER.

El Patrón

El patrón recomendado tiene tres piezas:

1. Un target bundle en tu proyecto que produce un directorio autocontenido de artefactos de tiempo de ejecución. Para TypeScript esto es un bundle JavaScript de un solo archivo con tree-shaking producido por Rolldown; para Python esto es un requirements.txt y las dependencias instaladas producidas por uv.
2. Un Dockerfile mínimo que simplemente hace COPY de la salida del bundle en una imagen base. Debido a que el bundling ya manejó el tree-shaking y la instalación de dependencias, el Dockerfile no necesita ejecutar npm install o uv sync.
3. Un target docker que copia el Dockerfile junto con la salida del bundle (para que el contexto de construcción de Docker solo contenga archivos necesarios en tiempo de ejecución), y luego ejecuta docker build.

El contexto de construcción de Docker se escribe en la carpeta dist de tu proyecto. Tu infraestructura como código (CDK o Terraform) luego apunta a ese directorio para enviar la imagen a ECR.

¿Por qué hacer el bundle fuera del Dockerfile?

Mantener el paso de bundle en Nx (en lugar de dentro del Dockerfile) significa:

• Nx puede cachear el target bundle, por lo que las construcciones repetidas son rápidas.
• El Dockerfile no necesita acceso a tu monorepo, registros privados o secretos de tiempo de construcción.
• La capa de imagen es diminuta — un solo COPY de artefactos ya construidos, sin node_modules transitivos ni cadena de herramientas de construcción.

TypeScript

Bundle Target

Configura un target bundle que invoque Rolldown. Si estás comenzando desde un ts#project, agrega lo siguiente a tu 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"]
    }
  }
}

Y un rolldown.config.ts en la raíz de tu proyecto:

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',
  },
]);

Ejecuta el target bundle para producir 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

Dependencias no empaquetables

Algunos paquetes npm no pueden ser empaquetados porque dependen de require dinámico, bindings nativos o resolución de rutas de archivos en tiempo de ejecución. Agrégalos al array external en rolldown.config.ts para que se dejen como llamadas require() en tiempo de ejecución, e instálalos dentro del Dockerfile en su lugar (ver abajo):

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

Dockerfile

Crea un Dockerfile en el directorio fuente de tu proyecto. El archivo no hace nada más que hacer COPY del bundle en una imagen base de Node, además de npm install de cualquier paquete external que no pudo ser empaquetado. Coloca el paso RUN npm install antes del COPY, para que Docker pueda cachear la capa de node_modules instalados y solo volver a ejecutarla cuando la lista de dependencias realmente cambie:

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

Fija tus dependencias

Fija cada dependencia instalada dentro del Dockerfile a una versión exacta (como arriba) — de lo contrario npm install tomará silenciosamente una versión más nueva la próxima vez que construyas, produciendo imágenes que se comportan de manera diferente dependiendo de cuándo fueron construidas.

Docker Target

Agrega un target docker que:

1. Copie el Dockerfile en el directorio de salida del bundle (para que el contexto de construcción contenga solo el bundle + Dockerfile), y
2. Ejecute docker build (opcional para CDK — ver abajo).

{
  "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 de archivos multiplataforma

El paquete ncp proporciona un comando de copia de archivos/directorios multiplataforma, evitando cp (no disponible en Windows). Instálalo en la raíz de tu workspace con pnpm add -D -w ncp.

Ejecutar este target produce una imagen local etiquetada como my-scope-my-project:latest, construida desde el contexto mínimo en 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 construye la imagen por sí mismo

Si solo estás desplegando con CDK, el comando docker build anterior es opcional — el DockerImageAsset de CDK (mostrado bajo Infraestructura) construirá la imagen por ti en el momento del synth. Aún necesitas copiar el Dockerfile en el directorio de contexto de construcción para que CDK pueda encontrarlo. Los generadores mantienen el paso local de docker build para darte una forma rápida de hacer smoke-test de la imagen con docker run.

Para Terraform, el paso docker build es requerido — el patrón null_resource de abajo envía una imagen etiquetada localmente.

Python

Bundle Target

Configura un target bundle que use uv para exportar e instalar dependencias para tu plataforma objetivo. El generador py#project y el generador py#lambda-function configuran esto por ti. La configuración del target se ve así:

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

Arquitectura objetivo

Cambia --python-platform a x86_64-manylinux_2_28 si tu imagen Docker se ejecutará en x86_64.

Ejecutar nx bundle my-project produce dist/packages/my-project/bundle-arm/ conteniendo el código fuente de tu proyecto, sus dependencias y un requirements.txt — todo lo que la imagen necesita en tiempo de ejecución.

Dockerfile

El Dockerfile simplemente copia el bundle en una imagen base de Python. Debido a que uv ya instaló todas las dependencias en el directorio del bundle, no necesitas ejecutar pip install dentro de la imagen:

FROM public.ecr.aws/docker/library/python:3.14-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

Agrega un target docker que copie el Dockerfile en el directorio de salida del bundle, y luego ejecute 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"]
    }
  }
}

Esto limpia el directorio de salida, luego copia tanto el contenido del bundle como el Dockerfile en dist/.../docker, que se convierte en el contexto de construcción de 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

Escaneo de Imágenes con Trivy

Es una buena práctica escanear tus imágenes en busca de vulnerabilidades conocidas. Los generadores que siguen este patrón agregan un target trivy que escanea la imagen construida con Trivy, ejecutándose desde la imagen Trivy alojada en ECR, y sale con código distinto de cero en hallazgos HIGH o CRITICAL.

Agrega un target trivy que tenga dependsOn en tu target docker. Guarda la imagen construida en un tarball y la escanea a través de un montaje de enlace relativo al workspace, por lo que el mismo comando funciona tanto con docker como con finch:

{
  "targets": {
    "trivy": {
      "cache": true,
      "inputs": ["default", "^production"],
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/trivy"],
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "rimraf dist/packages/my-project/trivy",
          "make-dir dist/packages/my-project/trivy",
          "ncp 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"]
    }
  }
}

Los targets de escaneo por imagen de cada proyecto se agregan bajo un target trivy a nivel de workspace, que el script raíz trivy proporcionado ejecuta (nx run-many --target trivy).

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

Ejecuta Trivy en CI

El escaneo intencionalmente no está conectado a build ya que esto puede introducir fricción innecesaria al iterar durante el desarrollo, dado que la base de datos de vulnerabilidades de Trivy se actualiza continuamente con nuevos CVEs.

En su lugar, recomendamos ejecutar el comando anterior como un paso dedicado en tu pipeline de CI antes del despliegue a entornos de producción.

El caché omite imágenes sin cambios

Debido a que la imagen está completamente determinada por el código fuente de tu proyecto, declarar inputs (aquí default y ^production, coincidiendo con el target bundle) permite a Nx cachear el escaneo y omitir el re-escaneo de una imagen que no ha cambiado. Fija la versión de la imagen Trivy (por ejemplo, trivy:0.72.0) para que los escaneos sean reproducibles.

Supresión de hallazgos

Trivy lee un archivo .trivyignore (una lista de IDs de vulnerabilidad, uno por línea) desde la raíz de tu proyecto. --ignore-unfixed omite vulnerabilidades sin solución disponible, por lo que el escaneo solo falla en problemas que puedes solucionar actualizando herramientas en tu Dockerfile. Consulta la documentación de filtrado de Trivy para más detalles.

Infraestructura

Conectar el directorio de contexto de construcción resultante a la infraestructura como código es lo mismo tanto para TypeScript como para Python — solo difiere la ruta al directorio de contexto de construcción (dist/packages/my-project/bundle para TypeScript, dist/packages/my-project/docker para Python).

CDK

Usa DockerImageAsset de CDK apuntando al directorio de contexto de construcción. CDK construirá la imagen y la publicará en el repositorio ECR de activos de CDK en el momento del despliegue:

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,
});

El helper findWorkspaceRoot es generado por el generador ts#infra y exportado desde @my-scope/common-constructs. Si no estás usando constructos compartidos, puedes codificar la ruta al directorio dist relativa a donde se invoca cdk — típicamente la raíz del workspace — y omitir la llamada a findWorkspaceRoot por completo.

Ejecutar bundle antes del synth

CDK no ejecuta los targets bundle/docker automáticamente — debes ejecutar nx build my-project (o conectar el target deploy para que dependa de build) antes de cdk deploy. Los generadores que usan este patrón declaran docker y bundle como dependencias de build para que esto suceda de forma transparente.

Usa el DockerImageAsset con cualquier constructo de AWS que acepte una imagen de contenedor, por ejemplo aws_ecs.ContainerImage.fromDockerImageAsset(image).

Terraform

El proveedor de AWS de Terraform no tiene un recurso de primera clase para “construir y enviar una imagen Docker”. El patrón usado por los generadores es:

1. El target build del proyecto ejecuta docker build, produciendo una imagen local etiquetada como my-scope-my-project:latest.
2. Un aws_ecr_repository para almacenar la imagen.
3. Un null_resource con un provisionador local-exec que autentica en ECR, re-etiqueta la imagen construida localmente con su digest de contenido, y la envía.
4. El recurso downstream (por ejemplo, aws_ecs_task_definition) referencia la imagen por su etiqueta inmutable basada en digest.

resource "aws_ecr_repository" "repo" {
  name                 = "my-project-repository"
  image_tag_mutability = "IMMUTABLE"
  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}}')'\"}'"]
}

locals {
  # Content-based, immutable image tag derived from the local image digest
  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
}

resource "null_resource" "docker_publish" {
  triggers = {
    docker_digest  = data.external.docker_digest.result.digest
    repository_url = aws_ecr_repository.repo.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
  }
}

El bloque data.external.docker_digest asegura que el null_resource se vuelva a ejecutar cada vez que cambie el hash de la imagen local, desencadenando un nuevo push en cada cambio de código significativo. La imagen se envía bajo una etiqueta inmutable basada en contenido derivada de su digest, por lo que el repositorio ECR puede usar mutabilidad de etiqueta IMMUTABLE y rechazar cualquier intento de sobrescribir una etiqueta existente.

Ejecutar bundle antes del apply

nx apply <project> requiere que la etiqueta de imagen my-scope-my-project:latest ya exista localmente. Ejecuta nx build my-project (o nx docker my-project) antes de nx apply <project>.

Lectura Adicional

• Generador ts#agent — un ejemplo completo de este patrón para un agente TypeScript desplegado en Bedrock AgentCore Runtime.
• Generador py#agent — el equivalente para Python.
• Documentación de Rolldown — referencia de configuración para el bundler de TypeScript.
• Documentación de uv — referencia para exportación e instalación de dependencias de Python.