En tancar el mòdul 4 teníem servei-cataleg i servei-comandes funcionant amb npm run dev en un portàtil, amb MongoDB, PostgreSQL i RabbitMQ aixecats a mà amb docker run. Això serveix per desenvolupar, però no per desplegar: en producció cada servei s'executarà en diverses rèpliques, en màquines que ningú no ha preparat a mà, i haurà d'arrencar, morir i tornar a arrencar centenars de vegades sense que cap humà hi intervingui. El contenidor és la unitat que ho fa possible: empaqueta el servei amb el seu Node.js exacte i les seves dependències en una imatge immutable que s'executa igual al portàtil del Luis, al runner de CI i al clúster de Kubernetes. Aquesta lliçó construeix la imatge de producció de servei-cataleg, explica com s'etiqueta, s'executa i s'atura, i aixeca per primera vegada el sistema complet de TechCorp amb Docker Compose, inclosa l'única prova E2E que 04-05 va deixar pendent. Kubernetes (05-02) i el pipeline que construirà aquestes imatges a cada commit (05-03) es recolzen en el que aquí queda fixat.

1. Per què contenidors per a microserveis
2. Conceptes: imatge, capa, contenidor, registre, volum i xarxa
3. El Dockerfile de producció de servei-cataleg, línia a línia
4. .dockerignore, memòria cau de capes i ordre de les instruccions
5. Etiquetatge d'imatges i registre
6. Ordres bàsiques de Docker
7. Senyals, PID 1 i aturada ordenada dins del contenidor
8. Docker Compose: l'entorn local complet de TechCorp
9. Operar l'entorn: up, down, logs, ps, migracions i la prova E2E
10. Mida d'imatge i seguretat bàsica

Un contenidor és un procés aïllat que el nucli de Linux executa amb el seu propi sistema de fitxers, la seva pròpia vista de la xarxa i límits de CPU i memòria, a partir d'una imatge que conté tot el que aquell procés necessita (binari de Node, node_modules, codi). No hi ha cap sistema operatiu convidat ni cap hipervisor: el contenidor comparteix el nucli de l'amfitrió, i per això arrenca en mil·lisegons i ocupa megabytes.

Per a TechCorp l'encaix és directe:

• Una imatge = una unitat de desplegament. servei-cataleg és una imatge; desplegar la versió 1.4.2 és executar aquesta imatge. No hi ha "instal·lar Node 20 al servidor" ni "copiar la carpeta i fer npm install": tot això va passar una vegada, en construir la imatge.
• Reproduïbilitat. La mateixa imatge que va passar les proves d'integració a CI és la que s'executa en producció, byte a byte. S'acaba el "a la meva màquina funciona" i el "a producció hi ha una altra versió de pg".
• Aïllament. Sis serveis Node a la mateixa màquina no comparteixen node_modules, ni ports, ni variables d'entorn. Cadascun es pensa que té la màquina per a ell sol.
• Arrencada ràpida i d'un sol ús. L'aturada ordenada de 04-02 i la configuració per entorn de 04-03 es van escriure pensant en això: un contenidor neix, serveix, rep SIGTERM i mor; un altre n'ocupa el lloc.

Que els serveis no tinguin estat a disc no és casualitat: és el que permet matar-los i replicar-los sense pensar-hi. Tot el que ha de sobreviure viu a la base de dades o al broker.

El Dockerfile viu a l'arrel del repositori techcorp/servei-cataleg i prové de la plantilla techcorp/plantilla-servei-node (04-01, exercici 2: el Dockerfile es copia i s'adapta). Fa servir multi-stage build: una etapa instal·la dependències i una altra, neta, es queda només amb el que cal per executar.

Instrucció per instrucció:

• # syntax=docker/dockerfile:1: activa la sintaxi moderna de BuildKit (necessària per a --mount=type=secret).
• FROM node:20-alpine AS dependencies: imatge base oficial de Node 20 sobre Alpine Linux (uns 50 MB davant dels 350 MB de node:20). AS dependencies dona nom a l'etapa per poder copiar-ne coses després.
• WORKDIR /app: crea /app i el converteix en directori de treball per a les instruccions següents.
• COPY package.json package-lock.json ./ abans de copiar el codi: és la clau de la memòria cau (apartat 4).
• RUN --mount=type=secret,id=npmrc ... npm ci --omit=dev: npm ci instal·la exactament el que diu el package-lock.json (reproduïble; falla si el lock no quadra amb package.json); --omit=dev deixa fora nodemon, jest, supertest, @pact-foundation/pact, testcontainers. El token de GitHub Packages es munta com a fitxer només durant aquesta ordre; es passa en construir amb --secret id=npmrc,src=$HOME/.npmrc.
• FROM node:20-alpine (segona vegada): la imatge final comença de zero; res de l'etapa anterior no hi passa tret del que es copiï explícitament.
• ENV NODE_ENV=production: Express desactiva missatges de depuració i algunes llibreries optimitzen; el config.js de 04-03 el llegeix com una variable més.
• COPY --from=dependencies --chown=node:node /app/node_modules ./node_modules: porta només node_modules ja instal·lat. --chown=node:node assigna la propietat a l'usuari node (uid 1000) que la imatge base ja defineix; sense això els fitxers serien de root i el procés no root podria no poder-los llegir si els permisos fossin restrictius.
• Tres COPY separats per a package.json, src i scripts: scripts/ hi entra perquè llavor.js s'executa des de la mateixa imatge (apartat 8). No es copien proves, contractes ni fitxers de configuració de desenvolupament.
• USER node: tot el que s'executi a partir d'aquí (inclòs CMD) corre sense privilegis. És la mesura de seguretat més barata i més eficaç d'aquesta lliçó.
• EXPOSE 3001: documenta el port (no el publica; això es fa amb -p o a Compose/Kubernetes). Coincideix amb PORT=3001 de 04-02.
• HEALTHCHECK: Docker executa wget contra /health/live cada 30 s, amb 10 s de gràcia en arrencar; tres fallades seguides marquen el contenidor unhealthy. Alpine porta wget a BusyBox, així que no cal instal·lar curl. Kubernetes ignora HEALTHCHECK i fa servir les seves pròpies probes (05-02); a Compose sí que és útil per a depends_on (apartat 8).
• CMD ["node", "src/servidor.js"]: l'ordre d'arrencada, igual que l'script start de 04-02, però sense passar per npm (apartat 7).

Per què multi-stage si un servei JavaScript no compila res? Perquè separa dues preocupacions: a la primera etapa hi pot haver tokens, memòria cau d'npm, eines de compilació de mòduls natius; a la segona, només el que s'executa. Si un dia un servei s'escriu en TypeScript, l'etapa 1 passa a ser "instal·lar i compilar" i l'etapa 2 no canvia.

COPY src ./src copia el que hi ha al context de build (el directori que es passa a docker build). Sense filtre, un COPY . . arrossegaria el node_modules local (amb dependències de desenvolupament i binaris d'un altre sistema operatiu), .env amb secrets, .git, pactes/, cobertura de proves... El .dockerignore els exclou del context:

Sobre la memòria cau: Docker construeix les capes en ordre i, per a cada instrucció, reutilitza la capa desada si la instrucció i les seves entrades no han canviat; tan bon punt una capa canvia, totes les següents es reconstrueixen. D'aquí l'ordre del Dockerfile:

Un canvi a src/rutes/productes.js invalida només la capa vermella: l'npm ci (l'operació lenta, 30-60 s amb descàrrega) es reutilitza de la memòria cau. Si copiéssim primer tot el codi i després instal·léssim, cada commit repetiria la instal·lació. Regla: el que canvia menys, a dalt; el que canvia més, a baix.

Una imatge s'identifica per registre/organització/nom:etiqueta. TechCorp fa servir dues etiquetes per build:

Totes dues apunten al mateix digest (sha256:...), que és l'identificador real i immutable de la imatge. El que no es fa servir en producció és latest:

• latest no vol dir "la més recent", vol dir "l'última a la qual algú va posar aquesta etiqueta". És una etiqueta mutable: avui apunta a 1.4.2 i demà a 1.5.0 sense que cap manifest canviï.
• Amb latest, dues rèpliques del mateix Deployment poden executar versions diferents segons quan van fer pull, i un rollback és impossible perquè ningú no sap què hi havia abans.
• Els manifestos de 05-02 porten sempre una etiqueta concreta; canviar de versió és canviar aquella línia, i això queda a git.

Construcció i publicació manual (el pipeline de 05-03 automatitza exactament això):

Les que es fan servir cada dia, amb la imatge acabada de construir:

host.docker.internal és el nom amb què un contenidor arriba a l'amfitrió (Docker Desktop; a Linux, --add-host=host.docker.internal:host-gateway). Només té sentit en aquest experiment aïllat: a Compose i a Kubernetes els serveis es troben pel nom dins de la mateixa xarxa.

A 04-02 vam escriure l'aturada ordenada: en rebre SIGTERM, /health/ready passa a 503, servidor.close() acaba les peticions en curs, es tanca Mongo i el procés surt, amb un límit de 10 s. Dins d'un contenidor hi ha tres detalls que poden anul·lar aquesta feina:

1. Qui és PID 1. El procés arrencat per CMD és el PID 1 del contenidor i és l'únic que rep el senyal de docker stop o del kubelet. Amb la forma exec CMD ["node", "src/servidor.js"], PID 1 és Node i el nostre gestor s'executa. Amb la forma shell CMD node src/servidor.js, PID 1 és /bin/sh, que rep SIGTERM i no el reenvia a Node: el servei mor 10 s després per SIGKILL, amb les peticions a mitges. I amb CMD ["npm", "start"], PID 1 és npm, que tampoc no reenvia senyals de manera fiable. Per això el Dockerfile crida node directament.
2. PID 1 no té gestors per defecte. El nucli tracta el PID 1 de manera especial: si no instal·la un gestor per a un senyal, l'ignora. Node sí que instal·la el nostre (process.on('SIGTERM')), així que estem coberts; un servei que se n'oblidés no moriria mai amb docker stop, només amb SIGKILL.
3. Processos zombi. PID 1 ha de "recollir" els processos fills acabats. Node no llança fills als nostres serveis, però si algun dia un executa child_process, convé un init mínim: docker run --init (Docker injecta tini) o, a Kubernetes, shareProcessNamespace o tini a la imatge. És una línia barata que evita un problema difícil de diagnosticar.

Temps: docker stop espera 10 s per defecte (-t ho canvia); Compose fa servir stop_grace_period; Kubernetes, terminationGracePeriodSeconds (30 s per defecte, 05-02). El límit intern de 10 s de 04-02 està pensat per cabre dins de qualsevol d'ells.

Docker Compose descriu en un YAML un conjunt de contenidors, xarxes i volums i els aixeca amb una sola ordre. És l'eina de l'entorn local i de l'E2E (04-01, 04-05); no és un orquestrador de producció. El fitxer viu al repositori techcorp/plataforma, a local/compose.yaml, i assumeix que els repositoris de serveis estan clonats com a directoris germans (../../servei-cataleg, etc.).

Punts que convé entendre bé:

• Xarxa per defecte. Compose crea una xarxa techcorp_default i hi connecta tots els serveis; cadascun resol els altres pel nom del servei. Per això CATALEG_URL=http://servei-cataleg:3001 i RABBITMQ_URL=amqp://rabbitmq:5672 són idèntics als que farem servir a Kubernetes: la configuració de 04-03 no canvia entre local i clúster.
• ports només on cal. El gateway publica el 8080; les bases de dades i RabbitMQ es publiquen per comoditat de desenvolupament. Els serveis servei-* no publiquen ports: només s'hi arriba pel gateway o des d'altres contenidors, com en producció.
• healthcheck + depends_on: condition. Sense condició, depends_on només ordena l'arrencada, no espera que PostgreSQL accepti connexions; servei-comandes arrencaria, config.js validaria, el pool fallaria i el /health/ready estaria en 503 fins que es connectés. Amb service_healthy Compose espera el healthcheck; amb service_completed_successfully espera que la tasca d'un sol ús acabi amb codi 0. Així les migracions sempre estan aplicades abans que arrenqui Comandes, sense scripts d'espera.
• Tasques d'un sol ús amb la mateixa imatge. cataleg-llavor i comandes-migracions no necessiten cap altra imatge: fan servir la del servei i canvien command. És la raó per la qual el Dockerfile copia scripts/. A Kubernetes seran Job (05-02).
• image + build. Amb tots dos, docker compose build construeix i etiqueta la imatge com a :local; docker compose up la fa servir. Si demà es vol provar la imatge que va publicar CI, n'hi ha prou de canviar :local per :sha-9f3c2ab i ometre el build.
• servei-clients com a stub. Reutilitza scripts/stubClients.js de 04-04 des de la imatge de Comandes. Quan el servei real existeixi (ordre d'extracció de 02-02), se substitueix pel seu propi build, amb CLIENTS_DB_URL i la resta sense tocar.

Comprovació manual del flux de comanda de tot el curs, aquesta vegada a través del gateway i amb tots els serveis en contenidors:

Com que Inventari, Pagaments i Notificacions encara no estan extrets, en local se'n simulen les respostes publicant els esdeveniments amb scripts/publicarEsdeveniment.js de 04-04, o afegint al Compose stubs consumidors (exercici 2). La prova E2E de 04-05 s'executa sobre aquest mateix entorn des del repositori plataforma:

Aquest trio d'ordres és literalment el que executarà el pipeline de 05-03 abans de promocionar a staging: si una cua està mal enllaçada o falta una variable, falla aquí i no en producció.

La regla resumida: la imatge conté codi i dependències; res més. Configuració i secrets arriben de l'entorn (04-03), les dades viuen en volums o serveis externs, i el procés no és root.

• COPY . . al començament del Dockerfile. Cada canvi de codi repeteix npm ci. Primer package*.json, després instal·lar, després el codi.
• Oblidar el .dockerignore. El node_modules del portàtil (amb binaris de macOS) i el .env amb la contrasenya de PostgreSQL acaben dins de la imatge publicada a ghcr.io.
• CMD npm start o forma shell. SIGTERM no arriba a Node; cada desplegament talla peticions. Forma exec i node directament.
• latest en qualsevol lloc que no sigui el portàtil. Sense traçabilitat ni rollback.
• depends_on sense condition. "Funciona" al portàtil ràpid i falla al runner de CI, on PostgreSQL triga 8 s a acceptar connexions. healthcheck a cada dependència i service_healthy.
• Publicar ports dels serveis interns "per provar". Es proven a través del gateway (o amb docker compose exec); publicar el 3002 acostuma a saltar-se l'única porta que existirà en producció.
• Consell: executa docker compose config per veure el YAML final amb les variables substituïdes; i docker compose up --build --wait com a ordre única en començar el dia.

Exercici 1. Escriu el Dockerfile de producció de servei-comandes (04-04) partint del de Catàleg. Indica quines línies canvien i per què, tenint en compte que Comandes necessita migracions/ i scripts/migrar.js dins de la imatge, escolta al 3002 i el seu HEALTHCHECK no s'ha de fer servir a Kubernetes.

Exercici 2. L'equip de Comandes vol que l'E2E passi en local sense Inventari ni Pagaments reals. Afegeix al compose.yaml un servei saga-simulada que executi un script Node (scripts/sagaSimulada.js, ja escrit: consumeix comanda.creada d'una cua pròpia i publica estoc.reservat i pagament.confirmat) fent servir la imatge de Comandes. Quines variables necessita, de què depèn i per què no ha de publicar ports?

Exercici 3. Un company executa docker stop servei-cataleg i observa que triga exactament 10 s i que als logs no apareix "aturant". El seu Dockerfile acaba amb CMD npm start. Explica la causa, la correcció, i quin altre símptoma tindria a Kubernetes amb terminationGracePeriodSeconds: 30.

Solució 1. Canvien: COPY --chown=node:node migracions ./migracions afegit al costat de src i scripts (el Job de 05-02 i comandes-migracions de Compose executen node scripts/migrar.js des d'aquesta imatge i llegeixen migracions/*.sql); EXPOSE 3002; el HEALTHCHECK apunta a http://localhost:3002/health/live. Com que Kubernetes ignora HEALTHCHECK (fa servir livenessProbe), es pot deixar per a Compose o eliminar-lo; l'important és no confondre'l amb la probe. Tota la resta (dues etapes, npm ci --omit=dev amb el secret npmrc, --chown=node:node, USER node, CMD ["node","src/servidor.js"]) és idèntica: és el que la plantilla de 04-01 dona fet.

Solució 2.

Només necessita RABBITMQ_URL (parla únicament per esdeveniments, com Inventari i Pagaments a 03-04: "no exposats"). No publica ports perquè no exposa HTTP i perquè res de fora de la xarxa de Compose no hi ha de parlar; si un dia ho fes, seria pel gateway. Depèn que RabbitMQ estigui sa i que Comandes hagi arrencat (declara la topologia en connectar; alternativament l'script la pot declarar ell mateix amb missatgeria/topologia de la llibreria, i llavors la segona dependència sobra).

Solució 3. Amb CMD npm start, PID 1 és npm, que arrenca node src/servidor.js com a fill. docker stop envia SIGTERM al PID 1 (npm), que no el reenvia a Node; el gestor process.on('SIGTERM') de 04-02 no s'executa mai, així que no hi ha línia "aturant" ni servidor.close(). Passats 10 s Docker envia SIGKILL i tot mor de cop: les peticions en curs reben connection reset. Correcció: CMD ["node", "src/servidor.js"] (forma exec, Node com a PID 1). A Kubernetes el símptoma seria que cada rolling update (05-04) triga 30 s per pod en lloc d'1-2 s i que, durant aquests 30 s, el pod continua rebent trànsit fins que el readinessProbe falla, perquè /health/ready no va passar mai a 503; amb la forma exec, el mateix servei es marca com a no llest a l'instant del SIGTERM.

Hem convertit els processos Node dels mòduls anteriors en unitats desplegables: una imatge per servei, construïda amb un Dockerfile multi-stage sobre node:20-alpine (npm ci --omit=dev amb el token d'npm com a secret de build, COPY --chown=node:node, USER node, EXPOSE, HEALTHCHECK opcional a /health/live, CMD ["node","src/servidor.js"] en forma exec perquè SIGTERM arribi a l'aturada ordenada de 04-02), amb .dockerignore i un ordre d'instruccions que aprofita la memòria cau de capes, etiquetada amb versió semàntica i sha-<commit> a ghcr.io/techcorp/ i mai amb latest. I hem aixecat per primera vegada el sistema complet amb Docker Compose (plataforma/local/compose.yaml): PostgreSQL 16, MongoDB 7 i RabbitMQ amb healthchecks, tasques d'un sol ús per a la llavor i les migracions, servei-cataleg, servei-comandes, l'stub de Clients i el gateway al 8080, amb les mateixes variables d'entorn de 04-03 i els mateixos noms DNS de 03-05, i a sobre l'única prova E2E del curs. Compose és perfecte per a un portàtil, però no reinicia un contenidor caigut en una altra màquina, no reparteix rèpliques ni gestiona desplegaments sense talls: per a això hi ha Kubernetes, que a la lliçó següent executarà aquestes mateixes imatges amb els ConfigMap i Secret que 04-03 va deixar anomenats.