Al cerrar el módulo 4 teníamos servicio-catalogo y servicio-pedidos funcionando con npm run dev en un portátil, con MongoDB, PostgreSQL y RabbitMQ levantados a mano con docker run. Eso sirve para desarrollar, pero no para desplegar: en producción cada servicio se ejecutará en varias réplicas, en máquinas que nadie ha preparado a mano, y tendrá que arrancar, morir y volver a arrancar cientos de veces sin que un humano intervenga. El contenedor es la unidad que hace posible todo eso: empaqueta el servicio con su Node.js exacto y sus dependencias en una imagen inmutable que se ejecuta igual en el portátil de Luis, en el runner de CI y en el clúster de Kubernetes. Esta lección construye la imagen de producción de servicio-catalogo, explica cómo se etiqueta, se ejecuta y se apaga, y levanta por primera vez el sistema completo de TechCorp con Docker Compose, incluida la única prueba E2E que 04-05 dejó pendiente. Kubernetes (05-02) y el pipeline que construirá estas imágenes en cada commit (05-03) se apoyan en lo que aquí queda fijado.

1. Por qué contenedores para microservicios
2. Conceptos: imagen, capa, contenedor, registro, volumen y red
3. El Dockerfile de producción de servicio-catalogo, línea a línea
4. .dockerignore, caché de capas y orden de las instrucciones
5. Etiquetado de imágenes y registro
6. Comandos básicos de Docker
7. Señales, PID 1 y apagado ordenado dentro del contenedor
8. Docker Compose: el entorno local completo de TechCorp
9. Operar el entorno: up, down, logs, ps, migraciones y la prueba E2E
10. Tamaño de imagen y seguridad básica

Un contenedor es un proceso aislado que el núcleo de Linux ejecuta con su propio sistema de ficheros, su propia vista de la red y límites de CPU y memoria, a partir de una imagen que contiene todo lo que ese proceso necesita (binario de Node, node_modules, código). No hay un sistema operativo invitado ni un hipervisor: el contenedor comparte el núcleo del anfitrión, por eso arranca en milisegundos y ocupa megabytes.

Para TechCorp el encaje es directo:

• Una imagen = una unidad de despliegue. servicio-catalogo es una imagen; desplegar la versión 1.4.2 es ejecutar esa imagen. No hay "instalar Node 20 en el servidor" ni "copiar la carpeta y hacer npm install": todo eso ocurrió una vez, al construir la imagen.
• Reproducibilidad. La misma imagen que pasó las pruebas de integración en CI es la que se ejecuta en producción, byte a byte. Se acaba el "en mi máquina funciona" y el "en producción hay otra versión de pg".
• Aislamiento. Seis servicios Node en la misma máquina no comparten node_modules, ni puertos, ni variables de entorno. Cada uno cree tener la máquina para él.
• Arranque rápido y desechable. El apagado ordenado de 04-02 y la configuración por entorno de 04-03 se escribieron pensando en esto: un contenedor nace, sirve, recibe SIGTERM y muere; otro ocupa su lugar.

Que los servicios no tengan estado en disco no es casualidad: es lo que permite matarlos y replicarlos sin pensar. Todo lo que debe sobrevivir vive en la base de datos o en el broker.

El Dockerfile vive en la raíz del repositorio techcorp/servicio-catalogo y viene de la plantilla techcorp/plantilla-servicio-node (04-01, ejercicio 2: el Dockerfile se copia y se adapta). Usa multi-stage build: una etapa instala dependencias y otra, limpia, se queda solo con lo necesario para ejecutar.

Instrucción por instrucción:

• # syntax=docker/dockerfile:1: activa la sintaxis moderna de BuildKit (necesaria para --mount=type=secret).
• FROM node:20-alpine AS dependencias: imagen base oficial de Node 20 sobre Alpine Linux (unos 50 MB frente a los 350 MB de node:20). AS dependencias le da nombre a la etapa para poder copiar de ella después.
• WORKDIR /app: crea /app y lo hace directorio de trabajo para las instrucciones siguientes.
• COPY package.json package-lock.json ./ antes de copiar el código: es la clave de la caché (apartado 4).
• RUN --mount=type=secret,id=npmrc ... npm ci --omit=dev: npm ci instala exactamente lo que dice el package-lock.json (reproducible; falla si el lock no cuadra con package.json); --omit=dev deja fuera nodemon, jest, supertest, @pact-foundation/pact, testcontainers. El token de GitHub Packages se monta como fichero solo durante este comando; se pasa al construir con --secret id=npmrc,src=$HOME/.npmrc.
• FROM node:20-alpine (segunda vez): la imagen final empieza de cero; nada de la etapa anterior pasa a ella salvo lo que se copie explícitamente.
• ENV NODE_ENV=production: Express desactiva mensajes de depuración y algunas librerías optimizan; el config.js de 04-03 lo lee como una variable más.
• COPY --from=dependencias --chown=node:node /app/node_modules ./node_modules: trae solo node_modules ya instalado. --chown=node:node asigna la propiedad al usuario node (uid 1000) que la imagen base ya define; sin ello los ficheros serían de root y el proceso no root podría no leerlos si los permisos fuesen restrictivos.
• Tres COPY separados para package.json, src y scripts: scripts/ entra porque semilla.js se ejecuta desde la misma imagen (apartado 8). No se copian pruebas, contratos ni ficheros de configuración de desarrollo.
• USER node: todo lo que se ejecute a partir de aquí (incluido CMD) corre sin privilegios. Es la medida de seguridad más barata y más eficaz de esta lección.
• EXPOSE 3001: documenta el puerto (no lo publica; eso se hace con -p o en Compose/Kubernetes). Coincide con PUERTO=3001 de 04-02.
• HEALTHCHECK: Docker ejecuta wget contra /health/live cada 30 s, con 10 s de gracia al arrancar; tres fallos seguidos marcan el contenedor unhealthy. Alpine trae wget en BusyBox, así que no hace falta instalar curl. Kubernetes ignora HEALTHCHECK y usa sus propias probes (05-02); en Compose sí es útil para depends_on (apartado 8).
• CMD ["node", "src/servidor.js"]: el comando de arranque, igual que el script start de 04-02, pero sin pasar por npm (apartado 7).

¿Por qué multi-stage si un servicio JavaScript no compila nada? Porque separa dos preocupaciones: en la primera etapa puede haber tokens, caché de npm, herramientas de compilación de módulos nativos; en la segunda solo lo que se ejecuta. Si un día un servicio se escribe en TypeScript, la etapa 1 pasa a ser "instalar y compilar" y la etapa 2 no cambia.

COPY src ./src copia lo que hay en el contexto de build (el directorio que se pasa a docker build). Sin filtro, un COPY . . arrastraría node_modules local (con dependencias de desarrollo y binarios de otro sistema operativo), .env con secretos, .git, pactos/, cobertura de pruebas... El .dockerignore los excluye del contexto:

Sobre la caché: Docker construye las capas en orden y, para cada instrucción, reutiliza la capa cacheada si la instrucción y sus entradas no han cambiado; en cuanto una capa cambia, todas las siguientes se reconstruyen. De ahí el orden del Dockerfile:

Un cambio en src/rutas/productos.js invalida solo la capa roja: el npm ci (la operación lenta, 30-60 s con descarga) se reutiliza de la caché. Si copiásemos primero todo el código y luego instalásemos, cada commit repetiría la instalación. Regla: lo que cambia menos, arriba; lo que cambia más, abajo.

Una imagen se identifica por registro/organización/nombre:etiqueta. TechCorp usa dos etiquetas por build:

Ambas apuntan al mismo digest (sha256:...), que es el identificador real e inmutable de la imagen. Lo que no se usa en producción es latest:

• latest no significa "la más reciente", significa "la última a la que alguien puso esa etiqueta". Es una etiqueta mutable: hoy apunta a 1.4.2 y mañana a 1.5.0 sin que ningún manifiesto cambie.
• Con latest, dos réplicas del mismo Deployment pueden ejecutar versiones distintas según cuándo hicieron pull, y un rollback es imposible porque nadie sabe qué había antes.
• Los manifiestos de 05-02 llevan siempre una etiqueta concreta; cambiar de versión es cambiar esa línea, y eso queda en git.

Construcción y publicación manual (el pipeline de 05-03 automatiza exactamente esto):

Los que se usan a diario, con la imagen recién construida:

host.docker.internal es el nombre con el que un contenedor llega al anfitrión (Docker Desktop; en Linux, --add-host=host.docker.internal:host-gateway). Solo tiene sentido en este experimento suelto: en Compose y en Kubernetes los servicios se encuentran por nombre dentro de la misma red.

En 04-02 escribimos el apagado ordenado: al recibir SIGTERM, /health/ready pasa a 503, servidor.close() termina las peticiones en curso, se cierra Mongo y el proceso sale, con un límite de 10 s. Dentro de un contenedor hay tres detalles que pueden anular ese trabajo:

1. Quién es PID 1. El proceso arrancado por CMD es el PID 1 del contenedor y es el único que recibe la señal de docker stop o del kubelet. Con la forma exec CMD ["node", "src/servidor.js"], PID 1 es Node y nuestro manejador se ejecuta. Con la forma shell CMD node src/servidor.js, PID 1 es /bin/sh, que recibe SIGTERM y no lo reenvía a Node: el servicio muere 10 s después por SIGKILL, con las peticiones a medias. Y con CMD ["npm", "start"], PID 1 es npm, que tampoco reenvía señales de forma fiable. Por eso el Dockerfile llama a node directamente.
2. PID 1 no tiene manejadores por defecto. El núcleo trata al PID 1 de forma especial: si no instala manejador para una señal, la ignora. Node sí instala el nuestro (process.on('SIGTERM')), así que estamos cubiertos; un servicio que se olvidase de ello no moriría nunca con docker stop, solo con SIGKILL.
3. Procesos zombi. PID 1 debe "recoger" procesos hijos terminados. Node no lanza hijos en nuestros servicios, pero si algún día uno ejecuta child_process, conviene un init mínimo: docker run --init (Docker inyecta tini) o, en Kubernetes, shareProcessNamespace o tini en la imagen. Es una línea barata que evita un problema raro de diagnosticar.

Tiempos: docker stop espera 10 s por defecto (-t lo cambia); Compose usa stop_grace_period; Kubernetes, terminationGracePeriodSeconds (30 s por defecto, 05-02). El límite interno de 10 s de 04-02 está pensado para caber dentro de cualquiera de ellos.

Docker Compose describe en un YAML un conjunto de contenedores, redes y volúmenes y los levanta con un comando. Es la herramienta del entorno local y de la E2E (04-01, 04-05); no es un orquestador de producción. El fichero vive en el repositorio techcorp/plataforma, en local/compose.yaml, y asume que los repositorios de servicios están clonados como directorios hermanos (../../servicio-catalogo, etc.).

Puntos que conviene entender bien:

• Red por defecto. Compose crea una red techcorp_default y conecta todos los servicios; cada uno resuelve a los demás por el nombre del servicio. Por eso CATALOGO_URL=http://servicio-catalogo:3001 y RABBITMQ_URL=amqp://rabbitmq:5672 son idénticos a los que usaremos en Kubernetes: la configuración de 04-03 no cambia entre local y clúster.
• ports solo donde hace falta. El gateway publica 8080; las bases de datos y RabbitMQ se publican por comodidad de desarrollo. Los servicios servicio-* no publican puertos: solo se llega a ellos por el gateway o desde otros contenedores, como en producción.
• healthcheck + depends_on: condition. Sin condición, depends_on solo ordena el arranque, no espera a que PostgreSQL acepte conexiones; servicio-pedidos arrancaría, config.js validaría, el pool fallaría y el /health/ready estaría en 503 hasta que se conectase. Con service_healthy Compose espera al healthcheck; con service_completed_successfully espera a que la tarea de un solo uso termine con código 0. Así las migraciones siempre están aplicadas antes de que arranque Pedidos, sin scripts de espera.
• Tareas de un solo uso con la misma imagen. catalogo-semilla y pedidos-migraciones no necesitan otra imagen: usan la del servicio y cambian command. Es la razón por la que el Dockerfile copia scripts/. En Kubernetes serán Job (05-02).
• image + build. Con ambos, docker compose build construye y etiqueta la imagen como :local; docker compose up la usa. Si mañana se quiere probar la imagen que publicó CI, basta con cambiar :local por :sha-9f3c2ab y omitir el build.
• servicio-clientes como stub. Reutiliza scripts/stubClientes.js de 04-04 desde la imagen de Pedidos. Cuando el servicio real exista (orden de extracción de 02-02), se sustituye por su propio build, con CLIENTES_DB_URL y el resto sin tocar.

Comprobación manual del flujo de pedido de todo el curso, esta vez a través del gateway y con todos los servicios en contenedores:

Como Inventario, Pagos y Notificaciones aún no están extraídos, en local se simulan sus respuestas publicando los eventos con scripts/publicarEvento.js de 04-04, o añadiendo al Compose stubs consumidores (ejercicio 2). La prueba E2E de 04-05 se ejecuta sobre este mismo entorno desde el repositorio plataforma:

Ese trío de comandos es literalmente lo que ejecutará el pipeline de 05-03 antes de promocionar a staging: si una cola está mal enlazada o falta una variable, falla aquí y no en producción.

La regla resumida: la imagen contiene código y dependencias; nada más. Configuración y secretos llegan del entorno (04-03), datos viven en volúmenes o servicios externos, y el proceso no es root.

• COPY . . al principio del Dockerfile. Cada cambio de código repite npm ci. Primero package*.json, luego instalar, luego el código.
• Olvidar .dockerignore. El node_modules del portátil (con binarios de macOS) y el .env con la contraseña de PostgreSQL acaban dentro de la imagen publicada en ghcr.io.
• CMD npm start o forma shell. SIGTERM no llega a Node; cada despliegue corta peticiones. Forma exec y node directamente.
• latest en cualquier sitio que no sea el portátil. Sin trazabilidad ni rollback.
• depends_on sin condition. "Funciona" en el portátil rápido y falla en el runner de CI, donde PostgreSQL tarda 8 s en aceptar conexiones. healthcheck en cada dependencia y service_healthy.
• Publicar puertos de los servicios internos "para probar". Se prueban a través del gateway (o con docker compose exec); publicar 3002 acostumbra a saltarse la única puerta que existirá en producción.
• Consejo: ejecuta docker compose config para ver el YAML final con variables sustituidas; y docker compose up --build --wait como comando único al empezar el día.

Ejercicio 1. Escribe el Dockerfile de producción de servicio-pedidos (04-04) partiendo del de Catálogo. Indica qué líneas cambian y por qué, teniendo en cuenta que Pedidos necesita migraciones/ y scripts/migrar.js dentro de la imagen, escucha en 3002 y su HEALTHCHECK no debe usarse en Kubernetes.

Ejercicio 2. El equipo de Pedidos quiere que la E2E pase en local sin Inventario ni Pagos reales. Añade al compose.yaml un servicio saga-simulada que ejecute un script Node (scripts/sagaSimulada.js, ya escrito: consume pedido.creado de una cola propia y publica stock.reservado y pago.confirmado) usando la imagen de Pedidos. ¿Qué variables necesita, de qué depende y por qué no debe publicar puertos?

Ejercicio 3. Un compañero ejecuta docker stop servicio-catalogo y observa que tarda exactamente 10 s y que en los logs no aparece "apagando". Su Dockerfile termina con CMD npm start. Explica la causa, la corrección, y qué otro síntoma tendría en Kubernetes con terminationGracePeriodSeconds: 30.

Solución 1. Cambian: COPY --chown=node:node migraciones ./migraciones añadido junto a src y scripts (el Job de 05-02 y pedidos-migraciones de Compose ejecutan node scripts/migrar.js desde esta imagen y leen migraciones/*.sql); EXPOSE 3002; el HEALTHCHECK apunta a http://localhost:3002/health/live. Como Kubernetes ignora HEALTHCHECK (usa livenessProbe), se puede dejar para Compose o eliminarlo; lo importante es no confundirlo con la probe. Todo lo demás (dos etapas, npm ci --omit=dev con el secreto npmrc, --chown=node:node, USER node, CMD ["node","src/servidor.js"]) es idéntico: es lo que la plantilla de 04-01 da hecho.

Solución 2.

Solo necesita RABBITMQ_URL (habla únicamente por eventos, como Inventario y Pagos en 03-04: "no expuestos"). No publica puertos porque no expone HTTP y porque nada de fuera de la red de Compose debe hablar con él; si un día lo hiciera, sería por el gateway. Depende de RabbitMQ sano y de que Pedidos haya arrancado (declara la topología al conectar; alternativamente el script puede declararla él mismo con mensajeria/topologia de la librería, y entonces la segunda dependencia sobra).

Solución 3. Con CMD npm start, PID 1 es npm, que arranca node src/servidor.js como hijo. docker stop envía SIGTERM a PID 1 (npm), que no lo reenvía a Node; el manejador process.on('SIGTERM') de 04-02 nunca se ejecuta, así que no hay línea "apagando" ni servidor.close(). Pasados 10 s Docker envía SIGKILL y todo muere en seco: las peticiones en curso reciben connection reset. Corrección: CMD ["node", "src/servidor.js"] (forma exec, Node como PID 1). En Kubernetes el síntoma sería que cada rolling update (05-04) tarda 30 s por pod en lugar de 1-2 s y que, durante esos 30 s, el pod sigue recibiendo tráfico hasta que el readinessProbe falla, porque /health/ready nunca pasó a 503; con la forma exec, el propio servicio se marca no listo en el instante del SIGTERM.

Hemos convertido los procesos Node de los módulos anteriores en unidades desplegables: una imagen por servicio, construida con un Dockerfile multi-stage sobre node:20-alpine (npm ci --omit=dev con el token de npm como secreto de build, COPY --chown=node:node, USER node, EXPOSE, HEALTHCHECK opcional a /health/live, CMD ["node","src/servidor.js"] en forma exec para que SIGTERM llegue al apagado ordenado de 04-02), con .dockerignore y un orden de instrucciones que aprovecha la caché de capas, etiquetada con versión semántica y sha-<commit> en ghcr.io/techcorp/ y nunca con latest. Y hemos levantado por primera vez el sistema completo con Docker Compose (plataforma/local/compose.yaml): PostgreSQL 16, MongoDB 7 y RabbitMQ con healthchecks, tareas de un solo uso para la semilla y las migraciones, servicio-catalogo, servicio-pedidos, el stub de Clientes y el gateway en 8080, con las mismas variables de entorno de 04-03 y los mismos nombres DNS de 03-05, y sobre él la única prueba E2E del curso. Compose es perfecto para un portátil, pero no reinicia un contenedor caído en otra máquina, no reparte réplicas ni gestiona despliegues sin cortes: para eso está Kubernetes, que en la siguiente lección ejecutará estas mismas imágenes con los ConfigMap y Secret que 04-03 dejó nombrados.