Docker para Node.js: La configuración para producción de la que nadie habla | Akousa

dockerfile

# Etapa única: ~600MB
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]
 
# Multi-stage: ~150MB
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
CMD ["node", "dist/server.js"]

Enfoque	Tamaño de imagen
`node:20` + `npm install`	1.1 GB
`node:20-slim` + `npm install`	420 MB
`node:20-alpine` + `npm ci`	280 MB
Multi-stage + alpine + solo deps de producción	150 MB
Multi-stage + alpine + deps podadas	95 MB

dockerfile

# ============================================
# Etapa 1: Instalar dependencias
# ============================================
FROM node:20-alpine AS deps
 
# Seguridad: crear un directorio de trabajo antes que nada
WORKDIR /app
 
# Instalar dependencias basadas en el lockfile
# Copiar SOLO los archivos de package primero — esto es crítico para el caché de capas
COPY package.json package-lock.json ./
 
# ci es mejor que install: es más rápido, estricto y reproducible
# --omit=dev excluye las devDependencies de esta etapa
RUN npm ci --omit=dev
 
# ============================================
# Etapa 2: Construir la aplicación
# ============================================
FROM node:20-alpine AS builder
 
WORKDIR /app
 
# Copiar archivos de package e instalar TODAS las dependencias (incluyendo dev)
COPY package.json package-lock.json ./
RUN npm ci
 
# AHORA copiar el código fuente — los cambios aquí no invalidan la caché de npm ci
COPY . .
 
# Construir la aplicación (compilación TypeScript, build de Next.js, etc.)
RUN npm run build
 
# ============================================
# Etapa 3: Runner de producción
# ============================================
FROM node:20-alpine AS runner
 
# Añadir labels para metadatos de la imagen
LABEL maintainer="your-email@example.com"
LABEL org.opencontainers.image.source="https://github.com/yourorg/yourrepo"
 
# Seguridad: instalar dumb-init para manejo adecuado de señales PID 1
RUN apk add --no-cache dumb-init
 
# Seguridad: establecer NODE_ENV antes que nada
ENV NODE_ENV=production
 
# Seguridad: usar usuario no-root
# La imagen de node ya incluye un usuario 'node' (uid 1000)
USER node
 
# Crear directorio de la app propiedad del usuario node
WORKDIR /app
 
# Copiar dependencias de producción de la etapa deps
COPY --from=deps --chown=node:node /app/node_modules ./node_modules
 
# Copiar aplicación construida de la etapa builder
COPY --from=deps --chown=node:node /app/package.json ./
COPY --from=builder --chown=node:node /app/dist ./dist
 
# Exponer el puerto (solo documentación — no lo publica)
EXPOSE 3000
 
# Health check: curl no está disponible en alpine, usar node
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
# Usar dumb-init como PID 1 para manejar señales correctamente
ENTRYPOINT ["dumb-init", "--"]
 
# Iniciar la aplicación
CMD ["node", "dist/server.js"]

javascript

// Manejador de shutdown limpio — esto funciona con dumb-init
process.on("SIGTERM", async () => {
  console.log("SIGTERM recibido, cerrando limpiamente...");
 
  // Dejar de aceptar nuevas conexiones
  server.close();
 
  // Esperar que las solicitudes existentes terminen
  await drainConnections();
 
  // Cerrar conexiones de base de datos
  await db.end();
 
  process.exit(0);
});

# Dependencias
node_modules
npm-debug.log*

# Control de versiones
.git
.gitignore

# Configuración del IDE
.vscode
.idea
*.swp
*.swo

# Variables de entorno (NUNCA deben estar en una imagen)
.env
.env.*
!.env.example

# Archivos de test
__tests__
*.test.js
*.test.ts
*.spec.js
*.spec.ts
coverage
.nyc_output

# Documentación y metadatos
README.md
CHANGELOG.md
LICENSE
docs

# CI/CD
.github
.gitlab-ci.yml
.circleci
Jenkinsfile

# Docker
Dockerfile*
docker-compose*
.dockerignore

# OS
.DS_Store
Thumbs.db

bash

# Cualquiera con acceso al daemon puede ver los env vars
docker inspect container_name
 
# También visibles en el historial del proceso
cat /proc/1/environ
 
# Y en los logs de Docker si los imprimes accidentalmente
docker logs container_name

javascript

import { readFileSync } from "node:fs";
 
function getSecret(name) {
  try {
    return readFileSync(`/run/secrets/${name}`, "utf8").trim();
  } catch {
    // Fallback a env var para desarrollo local
    return process.env[name.toUpperCase()];
  }
}
 
const apiKey = getSecret("api_key");
const dbUrl = getSecret("database_url");

dockerfile

# syntax=docker/dockerfile:1
 
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
 
# El secret se monta temporalmente — nunca se almacena en la imagen
RUN --mount=type=secret,id=npmrc,target=/app/.npmrc \
    npm ci
 
COPY . .
RUN npm run build

dockerfile

FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
# Eliminar archivos innecesarios de node_modules
RUN find node_modules -name "*.md" -delete && \
    find node_modules -name "*.d.ts" -delete && \
    find node_modules -name "CHANGELOG*" -delete && \
    find node_modules -name "LICENSE*" -delete && \
    find node_modules -name "*.map" -delete && \
    find node_modules -name "*.ts" ! -name "*.d.ts" -delete && \
    find node_modules -name "test" -type d -exec rm -rf {} + 2>/dev/null; \
    find node_modules -name "__tests__" -type d -exec rm -rf {} + 2>/dev/null; \
    find node_modules -name "docs" -type d -exec rm -rf {} + 2>/dev/null; true

dockerfile

FROM gcr.io/distroless/nodejs20-debian12 AS runner
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=deps /app/package.json ./
CMD ["dist/server.js"]

dockerfile

# Malo: 3 capas, archivos intermedios persistidos
RUN apk add --no-cache dumb-init
RUN addgroup -g 1001 nodejs
RUN adduser -S -u 1001 -G nodejs nextjs
 
# Bueno: 1 capa, sin archivos intermedios
RUN apk add --no-cache dumb-init && \
    addgroup -g 1001 nodejs && \
    adduser -S -u 1001 -G nodejs nextjs

yaml

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: runner
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000" # Vincular solo a localhost
    environment:
      - NODE_ENV=production
    env_file:
      - .env
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp

yaml

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
 
- name: Build and push
  uses: docker/build-push-action@v5
  with:
    context: .
    push: true
    tags: ghcr.io/myorg/myapp:latest
    cache-from: type=gha
    cache-to: type=gha,mode=max

bash

# Primer build — sin caché, velocidad completa
DOCKER_BUILDKIT=1 docker build -t myapp .
 
# Builds posteriores — las capas sin cambios vienen de la caché
DOCKER_BUILDKIT=1 docker build -t myapp .

bash

# Verificar que el contenedor se ejecuta como no-root
docker run --rm myapp:latest whoami
# Debería imprimir: node
 
# Verificar que las dependencias de dev no están presentes
docker run --rm myapp:latest ls node_modules/.package-lock.json
# Debería mostrar solo dependencias de producción
 
# Verificar que no hay secretos en las variables de entorno
docker inspect myapp_container | jq '.[0].Config.Env'
# No debería contener secretos
 
# Verificar las capas de la imagen en busca de secretos filtrados
docker history myapp:latest

yaml

# docker-compose.dev.yml
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: builder # Usar la etapa builder, no runner
    volumes:
      - .:/app # Montar código fuente para recarga en caliente
      - /app/node_modules # No montar sobre node_modules
    command: npm run dev
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development

Docker para Node.js: La configuración para producción de la que nadie habla

Por qué tu Dockerfile actual probablemente está mal

Ejecutarse como Root

Instalar devDependencies en producción

COPY de todo

Sin health checks

Sin estrategia de caché de capas

Builds Multi-Stage: La mayor mejora individual

Comparaciones reales de tamaño

¿Por qué Alpine?

El Dockerfile completo para producción

¿Por qué tres etapas en lugar de dos?

`npm ci` vs `npm install`

El problema del PID 1

El patrón del health check

El .dockerignore que realmente necesitas

Medir el impacto del contexto de build

Gestión de secretos: Deja de usar variables de entorno

El problema con las variables de entorno

Docker Secrets (Modo Swarm)

BuildKit Secrets para tiempo de build

Docker Compose con env_file

Optimización del tamaño de imagen: Más allá de lo básico

Podar node_modules

Distroless como imagen base

Compresión de capas

Configuración de Docker Compose para producción

Caché de Docker en CI

GitHub Actions con Docker Layer Caching

Docker Build local con caché

Seguridad en contenedores más allá de lo básico

Escaneo de imágenes

Verificación en runtime

Configuración del Security Context (Kubernetes)

Workflow de desarrollo local

La lista de verificación

Artículos relacionados

Monorepos in 2026: Nx, Turborepo, and the Lessons Nobody Shares

YAML Validator Guide: Catch Config Errors Before Deploy

Por qué tu Dockerfile actual probablemente está mal

Ejecutarse como Root

Instalar devDependencies en producción

COPY de todo

Sin health checks

Sin estrategia de caché de capas

Builds Multi-Stage: La mayor mejora individual

Comparaciones reales de tamaño

¿Por qué Alpine?

El Dockerfile completo para producción

¿Por qué tres etapas en lugar de dos?

npm ci vs npm install

El problema del PID 1

El patrón del health check

El .dockerignore que realmente necesitas

Medir el impacto del contexto de build

Gestión de secretos: Deja de usar variables de entorno

El problema con las variables de entorno

Docker Secrets (Modo Swarm)

BuildKit Secrets para tiempo de build

Docker Compose con env_file

Optimización del tamaño de imagen: Más allá de lo básico

Podar node_modules

Distroless como imagen base

Compresión de capas

Configuración de Docker Compose para producción

Caché de Docker en CI

GitHub Actions con Docker Layer Caching

Docker Build local con caché

Seguridad en contenedores más allá de lo básico

Escaneo de imágenes

Verificación en runtime

Configuración del Security Context (Kubernetes)

Workflow de desarrollo local

La lista de verificación

Artículos relacionados

Monorepos in 2026: Nx, Turborepo, and the Lessons Nobody Shares

YAML Validator Guide: Catch Config Errors Before Deploy

`npm ci` vs `npm install`