Conceptos básicos de Docker

10 ejemplos para contenerizar una API de Node.js con TypeScript en Node 24 LTS - 7 básicos y 3 intermedios.

Requisitos previos

mkdir node-api && cd node-api
npm init -y
npm pkg set type=module
npm install express@5
npm install -D typescript@5.6 tsx @types/express @types/node

Para patrones multi-etapa y endurecimiento de imágenes, consulta Construcciones multi-etapa y Contenedores sin root.

Ejemplos básicos

1. Dockerfile mínimo

FROM node:24-bookworm-slim
 
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist ./dist
 
ENV NODE_ENV=production
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"]

• npm ci usa el archivo de bloqueo para instalaciones reproducibles
• Copia package*.json antes del código fuente para que las capas de dependencias se almacenen bien en caché
• USER node ejecuta el proceso sin privilegios de root

2. .dockerignore

node_modules
dist
.git
.env
.env.*
*.md
coverage
.vscode
Dockerfile*
docker-compose*.yml

• Un contexto de construcción más pequeño significa un docker build más rápido
• Nunca copies .env en una capa de imagen
• Ignora los artefactos de prueba y documentación que no necesitas en tiempo de ejecución

3. Construir TypeScript en CI, ejecutar JS en la imagen

FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npm run build
 
FROM node:24-bookworm-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/main.js"]

• Compila TypeScript en una etapa de construcción o en CI antes de docker build
• La imagen de tiempo de ejecución contiene solo dist/ y node_modules de producción
• Consulta Construcciones multi-etapa para patrones más profundos

4. PORT desde el entorno

import express from "express";
 
const app = express();
const port = Number(process.env.PORT ?? 3000);
 
app.get("/health", (_req, res) => {
  res.json({ status: "ok" });
});
 
app.listen(port, "0.0.0.0", () => {
  console.log(`listening on ${port}`);
});

• Enlaza a 0.0.0.0 dentro de los contenedores, no a 127.0.0.1
• Kubernetes, ECS y Cloud Run inyectan PORT
• El endpoint de salud es necesario para las comprobaciones del balanceador de carga

5. docker build y docker run

docker build -t my-api:local .
docker run --rm -p 3000:3000 -e PORT=3000 my-api:local
curl http://localhost:3000/health

• -p 3000:3000 mapea el puerto del host al puerto del contenedor
• --rm elimina el contenedor después de salir (bueno para pruebas de humo locales)
• Pasa secretos a través de -e localmente; usa un gestor de secretos en producción

6. Scripts de package.json para Docker

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/main.js",
    "docker:build": "docker build -t my-api:local .",
    "docker:run": "docker run --rm -p 3000:3000 -e PORT=3000 my-api:local"
  }
}

• Un comando para que el equipo construya y pruebe localmente
• CI puede llamar a npm run docker:build después de que pasen las pruebas
• Mantén start como node simple, no tsx, en imágenes de producción

7. HEALTHCHECK en Dockerfile

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT||3000) + '/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"

• Docker marca los contenedores no saludables para las políticas de reinicio
• Los orquestadores (K8s) prefieren sus propias sondas sobre HEALTHCHECK
• Mantén /health rápido: sin llamadas a la base de datos (usa /ready para eso)

Ejemplos intermedios

8. Multi-etapa con objetivos de desarrollo y producción

FROM node:24-bookworm-slim AS base
WORKDIR /app
COPY package*.json ./
 
FROM base AS dev
RUN npm ci
COPY . .
CMD ["npx", "tsx", "watch", "src/main.ts"]
 
FROM base AS prod
RUN npm ci --omit=dev
COPY dist ./dist
USER node
CMD ["node", "dist/main.js"]

docker build --target dev -t my-api:dev .
docker build --target prod -t my-api:prod .

• Un Dockerfile sirve para desarrollo local (tsx watch) y producción
• --target selecciona la etapa final
• El objetivo de desarrollo puede incluir devDependencies; el de producción no

9. docker compose para la pila local

# compose.yml
services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      PORT: 3000
      DATABASE_URL: postgres://postgres:postgres@db:5432/app
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

• depends_on con condition: service_healthy evita la condición de carrera al inicio
• Compose es para desarrollo local; la producción usa K8s o plataformas gestionadas
• Consulta Sondas de salud y preparación

10. Fijar la imagen base por digest

FROM node:24-bookworm-slim@sha256:abc123def456...

• Los digests evitan reconstrucciones sorpresa cuando una etiqueta se mueve
• Renovate o Dependabot pueden abrir PRs cuando las imágenes base se actualizan
• Combina con el escaneo de imágenes en CI - Mejores prácticas de Docker

Preguntas frecuentes

Relacionado

• Construcciones multi-etapa - dependencias de desarrollo fuera de producción
• Contenedores sin root - patrones de USER node
• Sondas de salud y preparación - /health vs /ready
• Reducción de tamaño de imagen - capas más pequeñas
• Mejores prácticas de Docker - lista de verificación de la sección

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.