El teu compose.yaml de la lliçó anterior fa servir set claus. L'especificació de Compose en defineix més de seixanta, però no cal que les memoritzis: la majoria són la traducció directa d'una opció de docker run que ja domines del mòdul 3.

Aquesta lliçó és la referència pràctica d'un servei, organitzada per blocs i aplicada a Aurora Libros. Al final tindràs els quatre serveis declarats en un sol fitxer. L'explicació de com interactuen entre ells és la lliçó 04-04, i les variables d'entorn tenen lliçó pròpia, la 04-05.

1. Taula mestra: claus de servei i el seu equivalent a docker run
2. Imatge i construcció: image i build
3. Identitat: container_name i hostname
4. Execució: command, entrypoint, user, init i l'aturada
5. Xarxa i ports: ports, expose, networks, àlies
6. Dades: volumes, tmpfs, read_only
7. Salut i dependències: healthcheck i depends_on
8. Recursos i reinici: restart i deploy.resources
9. Etiquetes: labels
10. Blocs de nivell superior: volumes: i networks:
11. Àncores i referències YAML per no repetir-te
12. Aurora Libros: els quatre serveis declarats

L'única fila sense equivalent és depends_on, i no és casualitat: la relació entre serveis és exactament allò que docker run no sap expressar.

image pren una referència igual que docker run: repositori i etiqueta (postgres:16-alpine) o, millor per a producció, un digest immutable (postgres@sha256:9f3d0e...).

build diu a Compose que construeixi la imatge en comptes de descarregar-la. En forma curta és només el context (build: ./api); en forma llarga, tot el que vas aprendre al mòdul 2:

Quan apareixen les dues claus juntes, build mana a l'hora de construir i image dóna el nom del resultat. És la combinació més útil: docker compose build etiqueta la imatge amb aquest nom i docker compose push la publica.

Només amb build, si no poses image, Compose etiqueta la imatge com a <projecte>-<servei>.

container_name fixa el nom exacte i desactiva el prefixat de projecte. Sona còmode, i per això molta gent el posa; té tres inconvenients seriosos: impedeix docker compose up --scale (dos contenidors no es poden dir igual), impedeix aixecar dos projectes del mateix fitxer a la mateixa màquina, i no el necessites, perquè per parlar entre serveis es fa servir el nom del servei. Posa'l només quan alguna cosa externa —un script heretat, un agent de monitoratge— exigeixi un nom concret.

command i entrypoint admeten forma de cadena (command: node server.js, que passa pel shell) i forma de llista (["node", "server.js"], execució directa). Prefereix la llista: és la forma exec i garanteix que el teu procés sigui PID 1 i rebi SIGTERM, tal com vas veure a la lliçó 03-02. init: true insereix un init mínim com a PID 1 que reenvia senyals i enterra zombis, útil quan el teu procés llança fills i no els neteja. I stop_grace_period accepta unitats (10s, 1m30s): per a PostgreSQL, que necessita tancar un checkpoint abans de morir, puja'l a 30 segons.

ports publica un port del contenidor al host. Forma curta, "[IP:]portHost:portContenidor[/protocol]":

La forma llarga és més verbosa però explícita: - {target: 80, published: "8080", protocol: tcp, mode: host}, on target és el port intern, published el del host i mode: ingress només té sentit a Swarm.

expose no publica res: documenta quins ports escolta el contenidor. És informatiu, perquè dins d'una xarxa d'usuari tots els ports entre contenidors ja són accessibles.

networks connecta el servei a les xarxes declarades al bloc de nivell superior. Sense aquesta clau, el servei va a la xarxa default del projecte.

Un servei pot estar en diverses xarxes alhora —és exactament el que farà aurora-api a la lliçó 04-04— i els aliases li donen noms DNS extra, útils per migrar sense tocar el codi dels clients.

La forma curta és la sintaxi origen:destí[:opcions] de docker run -v, i l'origen decideix el tipus de muntatge:

La regla és la del mòdul 3: si l'origen comença per . o / és un bind mount; si no, és un volum amb nom que s'ha de declarar al bloc volumes: de nivell superior. La forma llarga equival a --mount:

Una diferència important: amb la forma curta, si l'origen d'un bind no existeix, Docker crea un directori buit; amb la forma llarga, falla amb un error clar i t'estalvia el clàssic "vaig muntar un directori on esperava un fitxer".

read_only: true amb un parell de tmpfs és una de les mesures d'enduriment més barates que existeixen; el tema complet és la lliçó 05-03.

El healthcheck de Compose substitueix o complementa el HEALTHCHECK del Dockerfile:

Tres maneres d'escriure test:

start_period és la clau que gairebé ningú fa servir i gairebé tothom necessita: PostgreSQL triga uns segons a acceptar connexions la primera vegada, i sense aquest marge el contenidor es marca unhealthy abans d'haver tingut oportunitat d'arrencar.

depends_on en forma curta —depends_on: [aurora-db, aurora-cache]— només garanteix l'ordre d'arrencada: Compose llança el contenidor de PostgreSQL, espera que el procés estigui en marxa i tot seguit llança l'API. Però PostgreSQL triga cinc segons més a acceptar connexions, així que l'API arrenca contra una base de dades que encara no respon. La forma llarga resol exactament això:

La distinció entre "arrencat" i "preparat" és la que separa un compose.yaml que funciona a la teva màquina d'un que funciona sempre. Es desenvolupa a la lliçó 04-04.

restart accepta els quatre valors de docker run amb el mateix significat: no (per defecte), always, on-failure[:n] i unless-stopped. Els límits, en canvi, viuen sota deploy, un bloc que originalment era exclusiu de Swarm:

Aquí hi ha una confusió clàssica que convé aclarir: fora de Swarm, docker compose sí que aplica deploy.resources.limits. El que s'ignora són replicas, placement, update_config i rollback_config, perquè no tenen sentit en un sol host. I recorda de la lliçó 03-07 que limits és un sostre dur —superar el de memòria significa OOM i codi 137— mentre que reservations és una garantia tova que influeix en qui cedeix memòria sota pressió.

Admet també forma de llista (- "clau=valor"). Fes servir la notació de DNS invers a les claus per no xocar amb les d'altres eines. Serveixen per filtrar (docker ps --filter "label=..."), i moltes eines de l'ecosistema —proxies inversos automàtics, agents de mètriques— es configuren exclusivament amb etiquetes.

Tot volum amb nom que facis servir en un servei s'ha de declarar a dalt:

external: true és la protecció definitiva per a dades crítiques: Compose assumeix que el volum existeix i ni tan sols down -v el toca. Si no existeix, l'up falla en comptes de crear-ne un de buit en silenci.

Les xarxes segueixen el mateix patró:

internal: true és la clau que sosté la segmentació de la lliçó 04-04: els contenidors d'aquesta xarxa no tenen ruta cap a l'exterior, ni l'exterior cap a ells. Una base de dades allà dins no pot descarregar res d'Internet encara que algú aconsegueixi executar-hi codi.

Quan quatre serveis comparteixen política de reinici, logging i etiquetes, copiar-ho quatre vegades és demanar que es desincronitzin. YAML ofereix àncores (&), referències (*) i fusió de mapes (<<:), i Compose hi afegeix les claus d'extensió x-, que ignora en processar el fitxer:

Dos límits que convé conèixer: les àncores només funcionen dins del mateix fitxer (no travessen diversos -f), i <<: fusiona al primer nivell, no en profunditat: si l'àncora porta labels i el servei també defineix labels, el del servei substitueix el de l'àncora per complet, no els barreja. Comprova sempre el resultat amb docker compose config.

Amb tot l'anterior, aquest és el fitxer complet. Les credencials continuen escrites a mà —això s'arregla a la lliçó 04-05— i hi ha una sola xarxa; la segmentació arriba a la 04-04.

Cinquanta línies de bash imperatiu s'han convertit en un fitxer declaratiu, versionable i llegible, i de passada ha guanyat coses que l'script no tenia: sondes de salut als quatre serveis, rotació de logs i etiquetes coherents. Valida'l i aixeca'l:

Els quatre serveis healthy. Que hagin arrencat en l'ordre correcte és sort, perquè encara no hi ha ni un depends_on; això s'arregla a la lliçó 04-04.

Posar container_name per costum. Trenca l'escalat i la coexistència de projectes, i no aporta res: per parlar entre serveis es fa servir el nom del servei.

Fer servir un volum amb nom sense declarar-lo a dalt. Compose falla amb service refers to undefined volume. Els bind mounts no necessiten declaració; els volums amb nom, sí.

Esperar que depends_on a seques esperi que el servei estigui preparat. Només espera que arrenqui. Sense condition: service_healthy continuaràs tenint curses d'arrencada.

Definir un healthcheck sense start_period. El servei es marca unhealthy durant la seva arrencada normal i arrossega tot el que en depengui.

Escriure test: curl -f http://localhost/salut en una imatge Alpine. curl no ve instal·lat a les imatges Alpine oficials; wget sí. Un healthcheck que invoca un binari inexistent falla sempre, i el símptoma —unhealthy sense més pistes— despista molt.

Consell: comença cada servei nou amb image, restart i healthcheck, i afegeix la resta només quan ho necessitis. Un compose.yaml amb claus que ningú sap per què hi són és tan dolent com un script de bash.

Exercici 1. Tradueix a un servei de Compose aquesta comanda, sense ometre cap opció, i explica on va cadascuna:

Exercici 2. El bloc x-comu del fitxer d'Aurora Libros inclou labels. Afegeix a aurora-db una etiqueta pròpia com.auroralibros.component: "base-de-dades" i comprova amb docker compose config què passa amb l'etiqueta heretada. Explica el resultat i proposa una solució.

Exercici 3. Declara un volum aurora-copies que apunti a un volum extern ja existent anomenat copies-aurora, munta'l de només lectura a aurora-db a /copies, i demostra que docker compose down -v no l'esborra.

Solució 1.

--name s'omet deliberadament (el nom del servei ja identifica el contenidor), --network passa a networks, els límits baixen a deploy.resources.limits, --stop-timeout es converteix en stop_grace_period amb unitats, i els arguments posteriors a la imatge es converteixen en command en forma de llista.

Solució 2. Afegint labels: { com.auroralibros.component: "base-de-dades" } al servei aurora-db:

L'etiqueta com.auroralibros.projecte ha desaparegut: <<: fusiona només al primer nivell, i com que el servei defineix la seva pròpia clau labels, aquesta substitueix per complet el mapa heretat. La solució és una segona àncora per al contingut de les etiquetes:

Ara config en mostra les dues. Regla general: quan fusionis àncores, verifica-ho sempre amb docker compose config; el que creus que hereta i el que hereta de veritat no sempre coincideixen.

Solució 3. Després de docker volume create copies-aurora, afegeix el muntatge a aurora-db i la declaració externa:

down -v ha esborrat aurora-libros_aurora-dades, que era del projecte, però copies-aurora continua allà: en ser external, Compose el considera prestat i no el gestiona. És el mecanisme que has de fer servir per a qualsevol volum la pèrdua del qual sigui inacceptable.

Ja tens la referència completa d'un servei de Compose, i sobretot el mapa mental que la sosté: gairebé cada clau és una opció de docker run amb un altre nom, i només depends_on expressa alguna cosa que la CLI imperativa no sabia dir. Saps quan fer servir image i quan build —i per què sovint totes dues juntes—, per què container_name sobra gairebé sempre, com es tradueixen command, entrypoint, user, init, stop_signal i stop_grace_period, i les dues formes —curta i llarga— de ports i volumes, amb el matís que la llarga falla en comptes de crear un directori buit quan el bind no existeix.

Domines el bloc healthcheck complet, inclòs el start_period que evita marcar com a malalt un servei que només està arrencant, i coneixes la diferència entre les tres condicions de depends_on: service_started, service_healthy i service_completed_successfully. Saps que restart té els mateixos quatre valors de sempre i que deploy.resources.limits sí que s'aplica fora de Swarm. Declares volums i xarxes als blocs de nivell superior, blindes les dades crítiques amb external: true, aïlles amb internal: true, i evites la repetició amb àncores x-/&/*/<<: sabent que la fusió és superficial. I tens el compose.yaml amb els quatre serveis d'Aurora Libros declarats.

A la lliçó següent, Comandes de Docker Compose, passaràs del fitxer a la CLI: el cicle de vida complet (up i la seva reconciliació, down i el perill de -v, start, stop, restart, pause), l'observació (ps, logs, top, stats, events), la diferència essencial entre exec i run, la construcció i publicació, l'escalat local amb --scale i per què xoca amb els ports fixos, i la selecció de fitxers i projecte amb -f, -p i COMPOSE_FILE.