CicloUrbana és observable, sap en quin entorn viu i treballa pel seu compte. I continua sent un JAR que algú ha d'arrencar a mà en una màquina amb Java 21 instal·lat, la zona horària correcta i les variables d'entorn ben posades. Aquest «algú» i aquestes condicions són l'última baula artesanal del projecte: la causa que funcioni en un servidor i no en un altre, i que el desplegament depengui d'una llista de passos al cap d'una persona.

Aquesta lliçó ho elimina empaquetant l'aplicació, el seu JRE i la seva configuració en una imatge de contenidor reproduïble. Veurem per què el Dockerfile que tothom escriu primer està malament, com aprofitar les capes del JAR d'Spring Boot perquè reconstruir després de canviar una línia trigui segons, quina imatge base triar, l'alternativa dels buildpacks, com es comporta la JVM dins d'un contenidor, el docker-compose.yml complet de la xarxa de Ribalta amb PostgreSQL i les seves comprovacions de salut enganxades a les sondes de 07-01, i les pràctiques de seguretat que eviten publicar una imatge amb secrets a dins.

1. Per què conteniritzar
2. Els conceptes mínims de Docker
3. El Dockerfile ingenu i per què està malament
4. El JAR d'Spring Boot per capes
5. El Dockerfile multietapa de CicloUrbana
6. Triar la imatge base
7. Buildpacks: spring-boot:build-image
8. La JVM dins d'un contenidor
9. El docker-compose.yml de la xarxa de Ribalta
10. Configurar l'aplicació al contenidor
11. spring-boot-docker-compose per a desenvolupament
12. Imatges natives amb GraalVM
13. Seguretat de la imatge
14. Publicar en un registre i etiquetar
15. Errors Comuns i Consells
16. Exercicis

Un contenidor empaqueta l'aplicació i tot allò que necessita per executar-se —el JRE, les biblioteques del sistema, la configuració per defecte, la zona horària— en un artefacte únic i immutable. El que resol, en concret:

I una conseqüència estratègica: la imatge és la unitat que entenen Kubernetes (08-04), els serveis gestionats d'AWS (08-03) i les canalitzacions de lliurament continu (08-05). Conteniritzar no és un fi en si mateix; és el requisit per a tot el que ve després.

Convé ser honest amb allò que no resol. Un contenidor no aïlla com una màquina virtual —comparteix el nucli de l'amfitrió—, no arregla una aplicació amb estat a disc local, i no fa que una configuració dolenta sigui bona: si el perfil prod no s'activa, s'activarà malament dins del contenidor exactament igual que fora (07-02).

La idea clau de tot el capítol són les capes. Una imatge és una pila de capes de només lectura; en reconstruir, Docker reutilitza de la memòria cau totes les capes anteriors al primer canvi i refà només les posteriors. I en publicar, només es transfereixen les capes que el registre no té. Tota l'optimització de l'apartat 4 consisteix a posar allò que canvia poc a baix i allò que canvia molt a dalt.

Aquest és el fitxer que gairebé tothom escriu primer:

Funciona. I té cinc problemes seriosos:

El primer és el que més fa mal en el dia a dia. En un cicle de desenvolupament normal les dependències canvien una vegada al mes i el codi canvia vint vegades al dia; amb un JAR monolític, cadascun d'aquests vint canvis reconstrueix i transfereix Spring Framework, Hibernate, Jackson i el driver de PostgreSQL sencers.

Spring Boot resol el problema publicant el JAR ja dividit en capes ordenades de menys a més volàtil:

S'inspecciona i s'extreu amb el jarmode del mateix JAR. A Spring Boot 3.3 i posteriors:

En versions anteriors el mode s'anomenava layertools (java -Djarmode=layertools -jar app.jar extract); el concepte és idèntic i val la pena conèixer tots dos noms, perquè la documentació i els exemples que circulen barregen els dos.

El resultat és un arbre de directoris, un per capa, que es copien a la imatge en ordre. Com que la capa application pesa uns pocs centenars de kilobytes i va l'última, un canvi al codi reconstrueix només aquesta: el cicle de construcció i publicació passa de minuts a segons.

Les decisions, una a una:

• Dues etapes. La primera porta Maven i el JDK complet; la segona parteix d'una imatge amb només el JRE. La imatge final no conté Maven, ni el JDK, ni el codi font, ni el repositori .m2: passa d'uns 800 MB a uns 200.
• COPY pom.xml abans que COPY src. És el truc central: mentre el POM no canviï, la capa de dependency:go-offline surt de la memòria cau i la descàrrega de dependències se salta del tot. Copiar-ho tot junt faria que qualsevol canvi de codi tornés a descarregar Internet sencer.
• -DskipTests aquí és correcte, encara que soni a heretgia després del mòdul 6: les proves ja s'han executat a la canalització (08-05) abans de construir la imatge. Executar-les una altra vegada dins del contenidor duplica el temps i, amb Testcontainers, exigiria Docker dins de Docker.
• extract --layers produeix els quatre directoris de l'apartat anterior.
• Usuari sense privilegis. addgroup/adduser és la sintaxi d'Alpine; en imatges basades en Debian seria groupadd/useradd. El --chown a cada COPY evita una capa extra només per canviar permisos.
• Les quatre COPY en aquest ordre exacte. És on es materialitza tota l'optimització: un canvi a LloguerService només invalida l'última.
• EXPOSE 8080 8081 documenta el port de l'API i el de gestió de 07-01. És informatiu, no obre res per si sol.
• TZ=Europe/Madrid evita el problema de zones horàries de 07-03: sense això, un contenidor s'executa en UTC i el cron nocturn es desplaça.
• ENTRYPOINT en forma de llista, no com a cadena. La forma de cadena arrenca el procés sota un sh -c, que es queda com a PID 1 i no reenvia els senyals: el SIGTERM de l'aturada ordenada (01-05, 07-03) no arriba mai a la JVM i el contenidor mor de cop passats deu segons.

Construir i executar:

L'avís sobre Alpine. Alpine fa servir musl com a biblioteca de C en lloc de glibc. La majoria d'aplicacions Java funcionen sense problema, però hi ha dues àrees conflictives: les biblioteques amb codi natiu (alguns clients criptogràfics, compressors, netty-tcnative) poden fallar o rendir pitjor, i certs escenaris de DNS i de resolució de noms es comporten de manera diferent. Si la imatge alpine funciona amb la suite de proves de CicloUrbana executada dins del contenidor, endavant; si apareix un error natiu estrany, la primera hipòtesi ha de ser aquesta.

Sobre distroless: no té shell, així que docker exec -it ... sh no funciona. Això és exactament el que la fa segura —un atacant que aconsegueixi execució tampoc no té shell— i el que la fa incòmoda de depurar. És l'elecció correcta quan el diagnòstic es fa per Actuator i per logs centralitzats (09-05), que és justament cap on va aquest curs.

Spring Boot pot construir la imatge sense cap Dockerfile, fent servir Cloud Native Buildpacks:

El plugin inspecciona el projecte, detecta que és una aplicació Java, tria un JRE adequat, aplica capes pel seu compte, crea un usuari sense privilegis i afegeix ajustos de memòria calculats. El resultat és una imatge OCI llesta per executar.

La recomanació honesta: si l'equip no té experiència amb Docker i vol bones pràctiques per defecte, buildpacks. Si necessita control fi —una biblioteca nativa, una imatge base corporativa aprovada, una anàlisi de vulnerabilitats concreta— el Dockerfile de l'apartat 5. Tots dos camins són legítims i tots dos produeixen imatges correctes; el que no és legítim és el Dockerfile ingenu de l'apartat 3.

Hi va haver una època en què la JVM no veia els límits del contenidor: llegia la memòria de la màquina amfitriona, dimensionava el heap amb la quarta part d'aquests 64 GB i l'orquestrador matava el procés per excedir el seu límit de 512 MB. Això està resolt des de Java 10: UseContainerSupport està actiu per defecte i la JVM llegeix els cgroups. No cal activar-ho.

El que sí que cal entendre és el repartiment de la memòria. -Xmx fixa un número absolut que cal revisar cada vegada que canvia el límit del contenidor; MaxRAMPercentage fixa una proporció del límit i s'adapta sola:

Per què 75 i no 100. Una JVM no consumeix només heap: hi ha metaespai, piles de fils, memòries intermèdies directes, codi compilat i el mateix sistema operatiu. Deixar un 25 % de marge evita que l'orquestrador mati el contenidor per OOMKilled —una fallada que, a més, és difícil de diagnosticar perquè no deixa rastre al log de l'aplicació—.

JAVA_TOOL_OPTIONS és la variable a fer servir, i no posar les opcions a l'ENTRYPOINT, per dues raons: la JVM la llegeix automàticament, i es pot sobreescriure en arrencar el contenidor sense reconstruir la imatge. La mateixa arrencada en deixa constància al log (Picked up JAVA_TOOL_OPTIONS: ...), cosa que serveix de confirmació.

A 04-02 vam crear un docker-compose.yml amb només PostgreSQL. Ara es completa amb l'aplicació:

Els punts que cal entendre:

• depends_on amb condition: service_healthy fa que l'aplicació no arrenqui fins que PostgreSQL respongui a pg_isready. Sense aquesta condició, depends_on només garanteix l'ordre d'inici, no que el servei estigui llest, i CicloUrbana fallaria en connectar i entraria en un bucle de reinicis.
• ${POSTGRES_PASSWORD:?falta POSTGRES_PASSWORD} fa que docker compose up falli immediatament si la variable no està definida, en lloc d'arrencar amb una cadena buida. És la mateixa filosofia de fallada primerenca de 07-02.
• La URL apunta a postgres, no a localhost. Dins de la xarxa del Compose, cada servei és accessible pel seu nom gràcies al DNS intern. localhost dins del contenidor de l'aplicació és el mateix contenidor.
• 127.0.0.1:8081:8081 publica el port de gestió només a l'amfitrió, no a totes les interfícies. És la traducció a Docker de la pràctica de 07-01: Actuator mai accessible des de fora.
• El healthcheck de l'aplicació consulta /actuator/health/readiness, la sonda que vam escriure a 07-01. Aquí es veu per què s'anomenava «la peça que necessita l'orquestrador»: és exactament el mateix mecanisme que farà servir Kubernetes a 08-04.
• start_period: 45s dona marge a l'arrencada d'Spring —context, Flyway, pool— sense que les fallades d'aquest període comptin com a reintents.
• limits.memory: 1g és el que dona sentit a MaxRAMPercentage=75: sense un límit declarat, el percentatge es calcula sobre la memòria de l'amfitrió.

Els secrets van en un fitxer .env al costat del docker-compose.yml i fora de Git:

Un .env versionat és el mateix error que un application-prod.yml amb credencials (07-02), amb l'agreujant que sembla un fitxer d'infraestructura inofensiu. I convé saber que les variables d'entorn d'un contenidor són visibles amb docker inspect per a qualsevol que pugui parlar amb el dimoni de Docker: per a secrets de debò, en producció es fan servir els secrets de l'orquestrador muntats com a fitxers i llegits amb spring.config.import: optional:configtree:/run/secrets/ (07-02).

La regla és la del factor III de 12-Factor App, ja aplicada a 07-02: la configuració ve de l'entorn. Dins d'un contenidor això significa que la imatge és idèntica a tots els entorns i l'única cosa que canvia són les variables:

Mai no es cou el perfil a la imatge. Escriure ENV SPRING_PROFILES_ACTIVE=prod al Dockerfile produeix una imatge que només serveix per a producció i trenca el principi de 07-02: la imatge que es prova a preproducció deixaria de ser la que es desplega. El perfil es decideix en executar.

Quan la configuració és massa extensa per a variables, es munta un fitxer:

Spring el troba sol, perquè ./config/ al costat del JAR és una de les ubicacions de la cadena de 07-02, i el :ro el munta de només lectura.

I sobre l'aturada: Docker envia SIGTERM i espera deu segons abans del SIGKILL. Com que l'aplicació té aturada ordenada amb fins a quaranta segons d'espera (07-03), cal ampliar aquest termini o el contenidor morirà a mitja petició:

A 06-05 va aparèixer el mòdul que arrenca els serveis del docker-compose.yml juntament amb l'aplicació en desenvolupament:

En executar ./mvnw spring-boot:run, Spring aixeca els serveis declarats, detecta PostgreSQL i configura sol spring.datasource.* amb el port assignat —igual que feia @ServiceConnection a les proves— i els atura en parar l'aplicació. Qui cloni CicloUrbana no necessita instal·lar res ni recordar cap ordre prèvia.

Dues precaucions. El fitxer apuntat ha de ser de desenvolupament (compose-dev.yml, només amb PostgreSQL), no el docker-compose.yml de producció que a més construeix i inicia la mateixa aplicació: això produiria dues CicloUrbana barallant-se pel port 8080. I lifecycle-management: start-only és preferible si molesta que els contenidors s'aturin cada vegada, a canvi d'haver-los de parar a mà.

GraalVM compila l'aplicació a un executable natiu per endavant, sense JVM en temps d'execució:

On brilla: funcions sense servidor, escalat a zero, arrencades molt freqüents, entorns amb memòria cara. On no compensa: una aplicació com CicloUrbana, que arrenca una vegada i s'executa durant setmanes, guanya poc i paga una compilació de deu minuts a cada construcció.

L'obstacle tècnic és la reflexió: la compilació anticipada necessita conèixer en temps de construcció totes les classes que s'instanciaran dinàmicament. Spring Boot 3 genera automàticament gran part d'aquestes metadades, però el codi propi que faci servir reflexió l'ha de declarar amb RuntimeHints:

Convé conèixer-ho i saber que existeix; per a CicloUrbana, la imatge amb JRE de l'apartat 5 és l'elecció correcta avui.

Una imatge és un artefacte que es publica i es distribueix. Tot el que hi entra, hi entra per sempre: esborrar un fitxer en una capa posterior no l'elimina de l'anterior, hi continua i es pot extreure.

El .dockerignore és més important del que sembla. Sense ell, COPY . . fica el directori .git complet dins de la imatge —amb tot l'historial, inclosos els secrets que algú va pujar i va esborrar després— i també el .env que tanta cura vam posar a no versionar. A més, el context de construcció sencer es transfereix al dimoni de Docker, cosa que alenteix cada construcció.

I un avís sobre els secrets a la construcció: ARG TOKEN seguit d'un RUN que el faci servir deixa el valor a les metadades de la imatge, visible amb docker history. Per a credencials durant la construcció existeix RUN --mount=type=secret, que no persisteix res a les capes.

La política d'etiquetatge decideix si un desplegament és reproduïble:

La regla: desplegar sempre per versió o per commit, mai per latest. Amb l'etiqueta sha-9f3a2b1 i l'/actuator/info de 07-01 retornant aquest mateix hash, la pregunta «què hi ha executant-se a Ribalta?» té resposta exacta i verificable. A 08-05 aquest etiquetatge el genera la canalització automàticament.

COPY . . abans de resoldre les dependències. Cada canvi de codi torna a descarregar el repositori Maven sencer. Primer el pom.xml, després el src.

El JAR com una sola capa. Canviar una línia invalida 60 MB. Extreu les capes amb el jarmode.

Executar com a root. És el valor per defecte i cal canviar-lo explícitament.

ENTRYPOINT en forma de cadena. El sh -c intermedi es menja el SIGTERM i l'aturada ordenada no passa mai.

depends_on sense condition: service_healthy. Garanteix l'ordre d'arrencada, no que la base de dades estigui llesta.

Fer servir localhost a la URL de la base de dades dins del contenidor. Cada contenidor té el seu propi localhost; cal fer servir el nom del servei.

No declarar un límit de memòria. MaxRAMPercentage es calcula sobre la memòria de l'amfitrió i el contenidor acaba OOMKilled.

Coure SPRING_PROFILES_ACTIVE=prod a la imatge. La imatge deixa de ser la mateixa a tots els entorns i es trenca el principi de 07-02.

Versionar el .env o no tenir .dockerignore. Tots dos fiquen secrets on no han d'estar: a Git o dins de les capes de la imatge.

Consell: fixa les versions de totes les imatges base, i programa reconstruccions periòdiques per incorporar els pedaços de seguretat de la base.

Consell: prova la imatge, no només el JAR. Arrencar el contenidor i consultar /actuator/health/readiness a la canalització detecta problemes de zona horària, permisos i variables que cap prova de JVM veu.

Consell: mesura el temps de reconstrucció. Si canviar una línia triga més de trenta segons a produir una imatge nova, l'ordre de les capes està malament.

Troba tots els problemes d'aquest fitxer, explica la conseqüència de cadascun i escriu la versió corregida.

Escriu un compose-pre.yml per a l'entorn de preproducció de l'ajuntament amb: PostgreSQL 16 amb volum i comprovació de salut; CicloUrbana amb el perfil pre, límit d'1 GB, esperant que la base de dades estigui sana, amb el port de gestió accessible només des de l'amfitrió i la seva pròpia comprovació de salut contra readiness; secrets des de .env; i un temps de gràcia d'aturada coherent amb els 40 segons de l'apartat 13 de 07-03. Explica en quin ordre arrenca tot i què passa si PostgreSQL triga un minut a estar llest.

L'equip es queixa que canviar una línia a EstacioService i veure el resultat en un contenidor triga quatre minuts. El Dockerfile és multietapa i correcte tret de l'etapa de construcció:

Diagnostica el problema, proposa'n la correcció i calcula aproximadament quant hauria de trigar després. Indica a més què més caldria revisar si després de la correcció continués trigant més d'un minut.

Solució 1

Nou problemes:

La correcció és el Dockerfile de l'apartat 5, amb dos matisos sobre l'enunciat. La contrasenya no es passa en la construcció de cap manera: és configuració d'execució i s'injecta com a variable en arrencar el contenidor; si de debò calgués una credencial durant la construcció —per exemple, per a un repositori Maven privat— la forma correcta és RUN --mount=type=secret,id=maven, que no deixa rastre a les capes. I el perfil desapareix del Dockerfile del tot, passant a docker run -e SPRING_PROFILES_ACTIVE=... o al Compose.

Solució 2

Ordre d'arrencada. Compose crea la xarxa i el volum; arrenca postgres; durant els primers 20 segons (start_period) les fallades de pg_isready no compten; quan respon, el servei passa a healthy; només llavors arrenca app, que resol postgres per DNS intern, aplica les migracions de Flyway i aixeca el context; durant 45 segons el seu propi healthcheck no penalitza, i en respondre /actuator/health/readiness amb 200 el servei queda healthy i pot rebre trànsit.

Si PostgreSQL triga un minut, el comportament continua sent correcte: amb interval: 10s, retries: 6 i start_period: 20s, hi ha marge suficient i app simplement espera. Si superés aquest marge, PostgreSQL es marcaria com a unhealthy, app no arrencaria en absolut —que és el comportament desitjat: millor no arrencar que arrencar sense base de dades— i docker compose ps mostraria clarament quin és el servei que falla.

stop_grace_period: 50s és la peça que fa coherent la cadena d'aturada: l'aplicació necessita fins a 40 segons per acabar peticions i buidar els executors (07-03), així que donar-li només els 10 segons per defecte de Docker tallaria l'aturada ordenada just a la meitat. La regla general és stop_grace_period > timeout-per-shutdown-phase > await-termination-period.

Solució 3

El diagnòstic. COPY . . copia el codi abans de resoldre les dependències, així que la capa que executa mvn package s'invalida amb qualsevol canvi de fitxer. Docker no pot reutilitzar res: cada construcció torna a descarregar tot l'arbre de dependències de Maven —Spring Boot, Hibernate, Jackson, Spring Security, JJWT, MapStruct, els drivers— des de zero. Els quatre minuts són, gairebé sencers, descàrregues repetides d'artefactes que ja es van descarregar ahir.

La correcció és separar la còpia en dos passos, amb la resolució de dependències entre tots dos:

Ara un canvi a EstacioService invalida la capa de COPY src i les posteriors, però la de les dependències surt de la memòria cau. El temps baixa al que trigui la compilació més l'empaquetatge: entre vint i quaranta segons en un projecte de la mida de CicloUrbana. I com que les capes dependencies i spring-boot-loader de la imatge final tampoc no canvien, la publicació al registre transfereix només uns centenars de kilobytes en lloc de seixanta megabytes.

Si després de la correcció continués trigant més d'un minut, hi ha quatre coses a revisar, en aquest ordre:

1. S'estan executant les proves? Sense -DskipTests, mvn package executa tota la suite del mòdul 6, inclosos els Testcontainers, que necessitarien Docker dins de Docker. Les proves van a la canalització, abans de construir la imatge.
2. Hi ha .dockerignore? Sense ell, el context de construcció inclou .git i target/, i transferir-los al dimoni abans de començar pot portar desenes de segons.
3. La memòria cau s'està invalidant per una altra via? Un COPY d'un fitxer que canvia sempre —una marca de temps, un fitxer generat— per damunt de l'etapa de dependències té el mateix efecte que el problema original.
4. La memòria cau existeix? En integració contínua, cada execució sol començar en una màquina neta sense memòria cau de capes; allà la solució és una memòria cau de capes del mateix sistema (--cache-from, cache-to) o un volum persistent per al repositori .m2 mitjançant RUN --mount=type=cache,target=/root/.m2, que és la forma moderna i la que millor funciona en canalitzacions (08-05).

CicloUrbana ja no és un JAR que algú arrenca a mà: és una imatge reproduïble que s'executa igual al portàtil d'un desenvolupador, al servidor de preproducció i a la infraestructura de l'ajuntament de Ribalta. Saps què resol un contenidor i què no, i manegues els conceptes que el sostenen —imatge, capa, contenidor, registre, etiqueta, volum, xarxa—, amb la idea central que les capes es cauegen i que per això allò que canvia poc va a baix i allò que canvia molt va a dalt.

Saps per què el Dockerfile de tres línies està malament —capa monolítica, dependència del Maven local, root, imatge grassa, senyals que no arriben— i has escrit el que sí que està bé: multietapa, amb el pom.xml copiat abans que el src perquè les dependències surtin de la memòria cau, amb el JAR descompost en les seves quatre capes pel jarmode tools, amb usuari sense privilegis, zona horària fixada, ajustos de memòria per JAVA_TOOL_OPTIONS i un ENTRYPOINT en forma de llista que sí que deixa arribar el SIGTERM a l'aturada ordenada. Coneixes les imatges base i els seus compromisos, inclòs l'advertiment sobre musl a Alpine i el preu de distroless, i saps que existeix un camí sense Dockerfile —els buildpacks d'spring-boot:build-image, amb pack rebase per apedaçar la base sense recompilar—, amb criteris clars per triar entre tots dos.

Entens com es comporta la JVM dins d'un contenidor: UseContainerSupport ja no cal activar-lo, però MaxRAMPercentage=75 sí, i el 25 % de marge és el que evita l'OOMKilled silenciós. Tens el docker-compose.yml complet de la xarxa de Ribalta, amb PostgreSQL 16, volum amb nom, xarxa pròpia, depends_on: condition: service_healthy, el port de gestió publicat només a 127.0.0.1, secrets en un .env fora de Git i —la peça que enllaça aquesta lliçó amb la primera del mòdul— un HEALTHCHECK que consulta /actuator/health/readiness. Saps configurar l'aplicació des de l'entorn sense coure mai el perfil a la imatge, muntar un YAML extern de només lectura i ampliar stop_grace_period perquè l'aturada ordenada hi càpiga. I tens spring-boot-docker-compose aixecant la base de dades en desenvolupament, la visió general de GraalVM amb els seus temps reals i els seus RuntimeHints, la llista de pràctiques de seguretat de la imatge —usuari no root, base mínima, zero secrets a les capes, .dockerignore, escaneig amb docker scout o Trivy— i una política d'etiquetatge que fa verificable quina versió s'executa a Ribalta.

Fins aquí, tot el que hem construït és una sola aplicació: un monòlit ben fet, provat, observable, configurable i ara conteniritzat. És una arquitectura perfectament respectable i, per a una xarxa municipal de bicicletes, probablement la correcta. Però tard o d'hora algú planteja la pregunta: i si el mòdul de facturació tingués el seu propi cicle de vida? I si l'equip d'estacions desplegués sense coordinar-se amb el de lloguers? I si calgués escalar només la part que consulta la disponibilitat, que rep cent vegades més trànsit que la resta? La lliçó següent, Spring Boot i Microserveis, respon a aquestes preguntes amb honestedat: quin problema resolen realment els microserveis, què es paga per ells, com es decideix on tallar, què es trenca quan cada servei té la seva pròpia base de dades, i per què la primera resposta correcta gairebé sempre és modularitzar el monòlit.