Amb el fitxer ja escrit, toca dominar l'eina que l'interpreta. La CLI de Compose té uns vint-i-cinc subcomandes, però el repartiment és molt desigual: en faràs servir cinc cada dia, unes altres cinc sovint i la resta en situacions concretes.

Aquesta lliçó les recorre per famílies, sempre sobre el compose.yaml d'Aurora Libros de la lliçó anterior. Para especial atenció a dues parelles que es confonen sense parar: up enfront de start, i exec enfront de run.

1. Taula mestra de subcomandes
2. up: la comanda que reconcilia
3. down i el perill de -v
4. start, stop, restart, pause, create
5. Observació: ps, logs, top, stats, events
6. Execució puntual: exec enfront de run
7. Construcció i publicació: build, pull, push
8. Escalat local amb --scale i els seus límits
9. Diagnòstic: config i validació a CI
10. Selecció de fitxers i projecte: -f, -p, COMPOSE_FILE
11. Autocompletat i àlies útils

Una comanda que s'oblida i és utilíssima: docker compose ls funciona des de qualsevol directori i et diu quins projectes hi ha aixecats a la màquina i amb quin fitxer.

docker compose up és el 80 % de l'ús diari. No és "arrencar": és portar l'estat real a l'estat declarat. A cada execució, per a cada servei, Compose calcula un resum de la seva configuració (el config-hash que vas veure a la lliçó 04-01) i decideix:

Aquesta selectivitat és el que fa que editar la memòria de la memòria cau i executar up -d recreï només la memòria cau i no tiri a terra la base de dades.

--wait és l'opció que converteix Compose en una eina d'automatització: sense ella, la comanda retorna el control tan bon punt els contenidors estan arrencats, i un script de CI que llança proves immediatament després s'estavella contra una base de dades que encara no accepta connexions. Amb --wait, Compose no retorna el control fins que totes les sondes de salut passen, i surt amb codi diferent de zero si alguna no ho aconsegueix.

Sense -d, up deixa el terminal enganxat als logs agregats de tots els serveis i Ctrl+C atura la pila sencera. És còmode per depurar una arrencada; perillós si te'n descuides en una sessió SSH.

Un cas molt útil de --no-deps: recrear només l'API sense reiniciar la base de dades.

down és la inversa d'up: atura i elimina contenidors i xarxes del projecte.

Grava't la segona fila. docker compose down -v esborra els volums amb nom del projecte sense preguntar: a Aurora Libros, això és el catàleg sencer de la llibreria. És exactament el que vols en reiniciar un entorn de desenvolupament i exactament el que arruïna un servidor si el teclejes per inèrcia. Dues defenses: declarar els volums crítics com a external: true (lliçó 04-02) i no crear mai un àlies de shell que inclogui -v.

El parany de restart mereix un avís explícit: no rellegeix el fitxer. Si canvies una variable d'entorn i executes docker compose restart aurora-api, el contenidor es reinicia amb la configuració antiga i et tornes boig buscant per què no s'aplica el canvi. Per aplicar canvis del fitxer, sempre up -d.

--services és or per als scripts: for s in $(docker compose ps --services); do ...; done.

Els logs són l'eina que més faràs servir:

Compose acoloreix i prefixa cada línia amb el nom del servei, així que docker compose logs -f amb la pila sencera et deixa veure el flux d'una petició travessant web → api → db. Recorda de la lliçó 03-04 que només veuràs allò que els processos escriguin a stdout/stderr.

port respon a "en quin port del host està publicat el 80 de la web?", i és imprescindible quan deixes que Docker assigni ports aleatoris.

És la distinció que més confusió genera, i la resposta és simple: exec entra en un contenidor que ja està corrent; run en crea un de nou.

-T desactiva l'assignació de pseudo-TTY: obligatori quan redirigeixes la sortida a un fitxer o encadenes canonades, o el bolcat sortirà amb caràcters de control.

--rm gairebé sempre. Sense ell, cada run deixa un contenidor aturat a la màquina; al cap d'una setmana tens quaranta contenidors aurora-libros-aurora-api-run-a3f9c2 ocupant espai. I --no-deps quan la tasca no necessita la pila: sense ell, un run innocent t'aixeca PostgreSQL i Redis.

El flux típic de CI, que veuràs complet a la lliçó 06-02, cap en tres línies: docker compose build, docker compose push i, al servidor, docker compose pull && docker compose up -d.

Aquí hi ha el primer xoc: un port fix del host no es pot repartir entre tres rèpliques. Només hi ha un 3000 a la màquina. I si el servei tingués container_name, fallaria encara abans, perquè dos contenidors no es poden dir igual.

Traient la publicació fixa, funciona:

El DNS intern de Docker retorna les tres adreces per al mateix nom, i el client en tria una. És un repartiment rudimentari —sense comprovació de salut, sense pesos, sense reintents— que serveix per a proves locals, no per a producció. El balanceig real, amb les seves estratègies i la seva gestió de rèpliques caigudes, és la lliçó 06-06.

docker compose config llegeix tots els fitxers implicats, interpola variables, fusiona overrides i mostra la configuració final tal com l'entén Compose. És la teva única manera de veure la veritat.

En una canonada de CI, --quiet és la primera comprovació que ha de córrer, abans fins i tot de construir res:

Dos avisos sobre config: resol les variables, així que la seva sortida pot contenir contrasenyes en clar (no la bolquis mai en un log públic), i mostra el resultat normalitzat, amb les formes curtes convertides en formes llargues. Aquesta normalització és justament el que necessites per entendre què va fer una fusió d'àncores o de fitxers.

Les opcions globals van abans de la subcomanda:

Amb diversos -f, Compose fusiona els fitxers en l'ordre donat i l'últim guanya en cas de conflicte. El mecanisme de fusió complet, amb les seves regles per tipus de clau, és la lliçó 04-06.

Un detall que sorprèn: quan fas servir -f, el directori base per a les rutes relatives passa a ser el del primer fitxer. Si els teus fitxers estan repartits, --project-directory et deixa fixar-lo explícitament.

I la variable d'entorn equivalent, útil per no repetir -f cent vegades al dia:

Amb l'autocompletat actiu, docker compose logs -f aur<TAB> t'ofereix els serveis reals del projecte: s'ha acabat teclejar malament els noms.

Aquest últim comentari no és cap broma: la major part de les pèrdues de dades amb Compose vénen d'un àlies curt que algú va escriure amb -v "per netejar ràpid".

Fer servir restart esperant que apliqui canvis del fitxer. No ho fa. Canvi al compose.yaml → up -d, sempre.

Confondre stop amb down. stop conserva els contenidors, down els elimina juntament amb la xarxa. Si després d'un down esperaves trobar el contenidor aturat, no hi és.

Teclejar down -v per costum. Esborra els volums amb nom i amb ells les dades. Pensa-t'ho cada vegada.

Oblidar --rm a run. Cada execució deixa un contenidor aturat. Neteja els acumulats amb docker compose rm -f.

Executar exec amb redirecció sense -T. El pseudo-TTY insereix caràcters de control i corromp bolcats i fitxers binaris.

Posar -f després de la subcomanda. Les opcions globals van abans; l'error que retorna la CLI no sempre ho deixa clar.

Consell: quan alguna cosa no es comporta com esperes, l'ordre de diagnòstic és docker compose config (què entén Compose?), docker compose ps (què està corrent?) i docker compose logs (què diu el servei?). En aquest ordre resols gairebé tot.

Exercici 1. Amb la pila aixecada, canvia el límit de memòria d'aurora-cache de 256M a 320M i aplica'l sense que es reiniciïn els altres tres serveis. Demostra amb comandes que només es va recrear la memòria cau i que el límit nou està actiu.

Exercici 2. Escriu un script verificar.sh apte per a CI que: validi el fitxer, aixequi la pila esperant que estigui sana, executi les proves de l'API en un contenidor efímer, imprimeixi l'estat dels quatre serveis i netegi tot, volums inclosos, retornant el codi de sortida de les proves.

Exercici 3. Sense apagar la pila, obtén: (a) el nombre de claus a Redis, (b) els tres primers títols del catàleg ordenats alfabèticament, i (c) un bolcat de la taula llibres al fitxer ~/llibres.sql del host. Explica quina opció és imprescindible en el tercer cas i per què.

Solució 1.

Edita el límit al compose.yaml (limits: { memory: 320M, cpus: "0.5", pids: 100 }) i aplica:

Aquí hi ha la reconciliació: Recreated només a la memòria cau, Running als altres tres perquè el seu config-hash no va canviar. Verificació:

La memòria cau porta quatre segons i els altres continuen amb els seus vint-i-dos minuts. I 335544320 bytes són exactament 320 MiB. Compte: recrear un contenidor no és reiniciar-lo, és destruir-lo i crear-ne un altre; les dades que no siguin en un volum es perden. A Redis, això significa una memòria cau buida, que aquí és inofensiu perquè /llibres la repobla des de la base de dades.

Solució 2.

Quatre decisions importants: --quiet valida abans de gastar temps construint; --wait amb --wait-timeout garanteix que les proves no arrenquin contra una base de dades que encara no respon i falla amb codi diferent de zero si no ho aconsegueix; --rm --no-deps a les proves evita deixar brossa i no torna a aixecar dependències que ja estan sanes; i down -v aquí és correcte i desitjable, perquè és un entorn d'un sol ús. Fixa't que es desa $? abans de les comandes de neteja: si no, el codi de sortida que retornaria l'script seria el de down, i el pipeline passaria sempre en verd.

Solució 3.

En el tercer cas -T és imprescindible. Sense ell, Compose assigna un pseudo-TTY a la comanda i el flux de sortida deixa de ser binari net: es tradueixen els salts de línia i s'hi colen seqüències de control, amb la qual cosa el .sql resultant pot no tornar-se a importar. La regla és senzilla: si la sortida no la llegiràs tu amb els ulls, -T.

Ja manegues la CLI completa. Saps que up no és "arrencar" sinó "reconciliar": compara el resum de configuració de cada servei amb el declarat i recrea només allò que va canviar, la qual cosa et permet ajustar un límit i tocar un únic contenidor. En coneixes les opcions decisives —-d, --build, --pull, --force-recreate, --no-deps, --remove-orphans i sobretot --wait, que espera que les sondes de salut passin i falla si no ho fan—. I tens clar què esborra cada variant de down, amb -v marcat en vermell.

Distingeixes start/stop/restart/pause d'up/down, amb el parany que restart no rellegeix el fitxer. Observes amb ps (inclosos --services i --format json), logs, top, stats, events i port. I tens interioritzada la diferència clau: exec entra en allò que ja corre, run crea un contenidor nou, amb --rm per no acumular brossa, --no-deps per no aixecar mitja pila i -T quan redirigeixes la sortida. Construeixes i publiques amb build/pull/push, escales localment amb --scale sabent que xoca amb els ports fixos i amb container_name, valides amb config --quiet a CI i controles quin fitxer i quin projecte fas servir amb -f, -p i COMPOSE_FILE.

A la lliçó següent, Aplicacions Multi-Contenidor, tot això es posa al servei del muntatge definitiu: l'arquitectura d'Aurora Libros amb dues xarxes segmentades —una de frontal i una de posterior marcada com a internal—, el DNS de Compose i la taula de qui parla amb qui i per quin port, l'ordre d'arrencada resolt amb depends_on i condition: service_healthy fent servir pg_isready i redis-cli ping, un servei de migració amb service_completed_successfully, i el patró de reintent amb backoff que cal encara que tinguis tot l'anterior. Al final, els quinze passos d'onboarding es quedaran en dos.