La teva imatge auroralibros/aurora-api:1.1.0 està publicada i és impecable: usuari sense privilegis, metadades OCI, healthcheck i aturada neta en 0,3 segons. I continua retornant ECONNREFUSED a /llibres, exactament com t'anunciava la lliçó anterior. Aquest mòdul sencer existeix per arreglar això, i comença per on cal començar: entendre de debò la comanda que fas servir des de la lliçó 01-06 sense haver-la mirat mai de prop. docker run no és una comanda, són dues: crea un contenidor i l'arrenca. I admet més d'un centenar d'opcions, de les quals a la feina diària se'n fan servir unes quinze. En aquesta lliçó veuràs què fa run per dins, aprendràs aquestes quinze opcions agrupades per famílies, sobreescriuràs el CMD i l'ENTRYPOINT d'una imatge des de la línia de comandes, i aixecaràs per fi aurora-db i aurora-cache com a contenidors reals. En acabar tindràs tres contenidors vius... i l'API continuarà sense funcionar. Aquesta fallada, amb el missatge d'error canviat, és la pista amb què arrenca la resta del mòdul.

1. Què fa docker run realment: create + start
2. Anatomia de la comanda i l'ordre dels arguments
3. Família identitat: --name i --hostname
4. Família execució: -d, -it, --rm, -w, -u, --entrypoint
5. Família xarxa i ports: el mínim per treballar
6. Família configuració: -e i --env-file
7. Família dades: -v en la seva versió mínima
8. Sobreescriure el CMD i l'ENTRYPOINT des de la línia de comandes
9. Primer pla, segon pla i com desacoblar-se
10. docker attach enfront de docker exec
11. Pràctica: la base de dades i la memòria cau d'Aurora Libros

docker run és una drecera. Per sota executa dues operacions diferents que pots invocar per separat:

Docker imprimeix l'ID complet del contenidor (64 caràcters hexadecimals) i retorna el control. Fixa't en el que ha passat i en el que no:

El contenidor existeix, té la seva capa d'escriptura reservada i tota la configuració desada (ports, variables, comanda), però l'estat és Created i la columna PORTS està buida: no hi ha cap procés en marxa i el port 8080 no escolta a la teva màquina. Comprova-ho:

Ara arrenca'l:

docker start imprimeix el nom del contenidor arrencat. I ara sí:

Aquesta separació no és un detall acadèmic: explica el repartiment de responsabilitats que faràs servir durant tot el mòdul.

La conseqüència pràctica, que convé gravar-se ja: no pots afegir un port ni una variable d'entorn a un contenidor que ja existeix. Si t'has equivocat, s'esborra i es crea de nou. És exactament per això que al mòdul 4 acabaràs escrivint aquesta configuració en un fitxer en comptes de a la línia de comandes.

Neteja la demostració:

El flux complet, ara que coneixes les peces de la lliçó 01-03:

Hi ha una sola regla d'or i provoca la meitat dels errors dels principiants:

Tot el que va abans de la imatge són opcions de Docker. Tot el que va després de la imatge és la comanda que s'executa dins del contenidor.

Mira-la fallar:

Docker no ha interpretat -e com una opció seva: com que venia després d'alpine:3.20, ha intentat executar dins del contenidor un programa anomenat -e. La versió correcta:

Aquí --rm i -e MISSATGE=hola són opcions de Docker (van abans de la imatge) i sh -c 'echo $MISSATGE' és la comanda dins del contenidor (va després). Necessitem sh -c perquè l'expansió de $MISSATGE la fa un shell, i sense ell Docker passaria la cadena literal.

Una ullada general a les famílies que veuràs a les seccions següents:

Sense --name, Docker inventa un nom de dues paraules (nostalgic_hopper, elegant_bardeen) i t'obliga a copiar IDs. Amb nom, totes les comandes següents es tornen llegibles i automatitzables amb scripts:

Regles dels noms:

Aquest darrer punt és la clau de tot el mòdul, i per això els noms d'Aurora Libros (aurora-db, aurora-cache, aurora-api, aurora-web) no són decoratius: d'aquí a poc seran noms de host reals.

L'error més habitual amb --name:

Compte: el conflicte es produeix encara que el contenidor anterior estigui aturat. Un contenidor Exited continua ocupant el seu nom. Ho resols amb docker rm aurora-cache (o docker rm -f si està corrent).

Canvia el nom que el contenidor veu de si mateix dins del seu propi namespace UTS:

Sense --hostname, el hostname és l'ID curt del contenidor:

--name i --hostname són coses diferents: --name és com l'anomenes tu des de fora (i com l'anomenen altres contenidors per DNS); --hostname és com s'anomena el contenidor a si mateix. Es fa servir poc, però apareix en registres d'aplicacions i en clústers de bases de dades.

Retorna l'ID i et deixa el terminal lliure. Sense -d, el terminal queda ocupat mostrant la sortida del procés i Ctrl+C l'atura.

Prova de treure una de les dues lletres per entendre què aporta cadascuna:

Regla pràctica: -it per a persones, -d per a serveis, res per a comandes d'un sol tret. I mai -it en un script automatitzat ni a CI: sense terminal real, -t provoca the input device is not a TTY.

El contenidor s'executa, imprimeix i desapareix: no queda a docker ps -a ni ocupa capa d'escriptura. És l'opció que evita acumular desenes de contenidors morts.

Dos avisos importants:

• --rm és incompatible amb la depuració: si el contenidor falla, s'esborra juntament amb els seus registres i el seu inspect. Quan alguna cosa va malament, treu el --rm per poder investigar (lliçó 03-04).
• --rm esborra també els volums anònims associats. Amb volums amb nom no passa res, però és un detall que es reprèn a la lliçó 03-06.

• -w /tmp sobreescriu el WORKDIR /app que vas fixar al Dockerfile.
• -u 1000:1000 força un UID:GID concret encara que aquest usuari no existeixi dins de la imatge (per això id mostra els números sense nom).
• -u root anul·la el USER node de la teva imatge. És utilíssim per depurar (instal·lar una eina dins d'un contenidor sense privilegis), i alhora és un recordatori que USER és una defensa en profunditat, no una barrera infranquejable: qui pot llançar contenidors pot triar l'usuari.

Ja el vas fer servir a la lliçó 02-04 i aquí formalitza el seu lloc:

Sense --entrypoint, la teva imatge té ENTRYPOINT ["node"] fix i qualsevol cosa que escrivissis després de la imatge seria un argument de node. Amb --entrypoint sh hi entres a mirar. És la porta de servei de tota imatge ben construïda.

Aquí només l'imprescindible; el perquè complet arriba a la lliçó 03-05.

-p HOST:CONTENIDOR significa "tot el que arribi al port 8080 de la meva màquina, redirigeix-ho al port 80 d'aquest contenidor". L'ordre mai s'inverteix: primer el host, després el contenidor.

Comprova -P amb la teva pròpia imatge, que declara EXPOSE 3000:

Docker ha triat el 32768 del rang efímer. docker port és la comanda que respon a "en quin port del host ha quedat això?".

Dues idees que convé fixar des d'ara, encara que es desenvolupin a 03-05:

• EXPOSE al Dockerfile i --expose a run no obren res: són documentació que consumeixen -P i altres eines.
• Publicar un port serveix perquè tu, des del host, arribis al contenidor. Perquè dos contenidors es parlin entre ells no cal publicar res. Aquesta distinció és la que està a punt de resoldre el misteri de l'API.

Neteja:

El teu server.js no té ni un valor fix escrit: llegeix PORT, DB_HOST, DB_USER, DB_PASSWORD, DB_NAME i REDIS_HOST de l'entorn. Aquesta decisió de la lliçó 01-07 és la que permet que la mateixa imatge serveixi per al teu portàtil, per a proves i per a producció.

La segona forma és molt pràctica per no escriure secrets a la línia de comandes, on quedarien a l'historial del shell.

Les variables definides amb -e sobreescriuen les de l'ENV del Dockerfile. Comprova-ho amb la teva imatge, que porta ENV PORT=3000:

I torna a veure tota l'escala de prioritat:

Quan passes de tres variables, la línia de comandes es torna il·legible. Crea ~/aurora-libros/aurora.env:

I fes-lo servir:

Les regles del format són estrictes i diferents de les d'un script de shell. Aquest és un punt on es perd molt de temps:

I una regla de seguretat que ja coneixes del mòdul 2, ara amb la seva conseqüència concreta:

El fitxer d'entorn conté una contrasenya: no va al repositori de Git ni al context de construcció. La imatge es queda sense secrets —com ha de ser— i la configuració viatja per fora, injectada a l'arrencada. Pots combinar les dues opcions: --env-file per al gruix i -e per al que vulguis sobreescriure puntualment, perquè -e guanya sobre --env-file independentment de l'ordre en què els escriguis.

El vas fer servir a la lliçó 01-06 per servir el teu index.html amb Nginx:

La sintaxi mínima és -v ORIGEN:DESTINACIÓ[:opcions], amb la ruta del host sempre absoluta i :ro per muntar en només lectura. Amb això en tens prou fins a la lliçó 03-06, on veuràs els tres tipus de muntatge, els volums gestionats i per què el catàleg de llibres que estàs a punt de crear desapareixerà si no hi fas res. De moment, queda't amb la idea de la lliçó 01-05: tot el que un contenidor escriu fora d'un muntatge viu a la seva capa d'escriptura i mor amb ell.

Reprenem la taula de la lliçó 02-04, ara des del costat de l'execució. La teva imatge declara:

La comanda efectiva és la concatenació ENTRYPOINT + CMD → node server.js. I des de docker run pots tocar cada meitat per separat:

Comprova-ho:

Dos matisos que causen sorpreses:

• Sobreescriure l'ENTRYPOINT descarta el CMD de la imatge. A la fila 4 de la taula, el CMD ["server.js"] desapareix: si no vols que sh rebi server.js com a argument no has de fer res, ja no hi és.
• --entrypoint "" (cadena buida) és la manera de deixar la imatge sense executable fix, de manera que el que escriguis darrere de la imatge sigui la comanda completa. És el truc que salva el dia amb imatges l'entrypoint de les quals és un script complicat.

Quan arrenques sense -d, el teu terminal queda enganxat a l'entrada i la sortida del PID 1:

Aquí es queda. Si prems Ctrl+C, envies SIGINT al procés i el contenidor s'atura. Això rarament és el que vols amb un servei.

L'alternativa, si vas arrencar amb -it, és desacoblar-te sense matar-lo amb la seqüència Ctrl+P seguida de Ctrl+Q:

Continua viu. Tres condicions perquè la seqüència funcioni, i la seva absència explica el 90 % dels "a mi no em va":

1. El contenidor ha d'haver-se arrencat amb -t (necessita el pseudo-terminal).
2. Ha d'estar enganxat a stdin, és a dir, amb -i.
3. La seqüència es prem dins de la sessió, no en un altre terminal.

Si necessites Ctrl+P per a una altra cosa (a bash recupera la comanda anterior), canvia-la:

Ara la combinació és Ctrl+E seguida de e. Ho pots fer permanent a ~/.docker/config.json:

Resum de les tres maneres d'arrencar:

Neteja:

Un contenidor en segon pla es pot "tornar a mirar" de dues maneres radicalment diferents:

docker attach et connecta a l'entrada i sortida del procés PID 1 que ja existeix. No llança res de nou. I aquí hi ha el seu perill:

Has aturat Redis. Ctrl+C durant un attach va directe al PID 1. Per sortir sense matar-lo cal fer servir Ctrl+P Ctrl+Q, o directament connectar-se en mode segur:

Amb --sig-proxy=false, Ctrl+C et retorna l'indicador sense enviar el senyal al contenidor.

docker exec, en canvi, llança un procés nou dins del contenidor:

Aquest redis-cli no té res a veure amb el PID 1: és un segon procés que comparteix els namespaces del contenidor i que pot acabar sense afectar el servei.

La regla pràctica: per mirar la sortida fes servir docker logs i per entrar fes servir docker exec. Tots dos s'estudien a fons a la lliçó 03-04. docker attach es reserva per a processos que de debò esperen la teva entrada per teclat.

És el moment. Fins ara, l'API arrencava sola i fallava perquè no hi havia ni PostgreSQL ni Redis. Els posarem.

Repassem cada línia, perquè cadascuna té el seu motiu:

Comprova que és viu:

pg_isready és l'eina oficial de PostgreSQL per preguntar "acceptes connexions?". L'executem dins del contenidor amb docker exec, sense necessitat de tenir PostgreSQL instal·lat al host. Aquest detall —fer servir les eines que ja venen a la imatge— és una de les comoditats més infravalorades de Docker.

I comprova que la base de dades existeix, encara que de moment estigui buida:

Correcte: la base de dades aurora_llibres està creada, però no hi ha taules. Falta executar db/init.sql, i això es farà de manera automàtica i elegant a la lliçó 03-06, quan muntis aquest fitxer dins del contenidor.

Redis no necessita cap variable: arrenca amb la seva configuració per defecte.

Redis funciona. Dos contenidors vius.

Docker ha acceptat la comanda sense protestar. Però:

El contenidor ni tan sols s'ha quedat en marxa. Ha arrencat i ha mort amb codi de sortida 1. Vegem per què:

Fixa't bé en el missatge, perquè ha canviat respecte al mòdul 2 i aquest canvi és una pista de primer ordre:

I aquí hi ha la paradoxa que dona sentit a la resta del mòdul: aurora-db i aurora-cache estan corrent ara mateix, a la mateixa màquina, publicant els seus ports. Ho pots comprovar des del host:

Són vius, estan publicats, i tot i així aurora-api no els troba. Per què?

La resposta curta: perquè no comparteixen xarxa. Cada contenidor té la seva pròpia pila de xarxa, i a la xarxa per defecte de Docker no hi ha resolució de noms entre contenidors. La resposta llarga, amb la solució completa i el curl que retorna els vuit llibres, és la lliçó 03-05. De moment, deixa la incògnita plantejada i no esborris res: aquests dos contenidors t'acompanyen durant tot el mòdul.

Esborrem només l'API (està aturada i no serveix de res). aurora-db i aurora-cache es queden.

• Posar opcions després de la imatge. docker run alpine -e VAR=1 sh intenta executar un programa anomenat -e. Les opcions van abans de la imatge, sempre.
• Esperar poder afegir un port o una variable a un contenidor existent. No es pot: es fixen a la fase create. La solució és docker rm i tornar a crear. Quan això et cansi, ja estaràs a punt per al mòdul 4.
• Fer servir --rm mentre depures. Si el contenidor falla i s'esborra, et quedes sense registres i sense inspect. Durant la investigació, treu el --rm.
• -p 5432:5432 en una base de dades. Publica PostgreSQL a totes les interfícies, inclosa la wifi del bar. Fes servir -p 127.0.0.1:5432:5432, o directament no el publiquis: els contenidors no necessiten ports publicats per parlar entre ells.
• Invertir l'ordre a -p. -p 80:8080 amb Nginx no funciona i l'error és confús, perquè Docker publica alegrement el 80 del host cap a un 8080 on no escolta ningú. Primer el host, després el contenidor.
• -t en scripts i CI. the input device is not a TTY. En automatització fes servir -i o res, mai -t.
• Cometes en un --env-file. DB_PASSWORD="aurora_secreta" desa la contrasenya amb les cometes incloses i provoca un password authentication failed desconcertant. Sense cometes.
• Consell: fes servir --name sempre. Un contenidor sense nom és un contenidor que d'aquí a deu minuts buscaràs per ID en un docker ps -a amb vint línies.
• Consell: escriu els docker run llargs en diverses línies amb \ al final, i desa'ls en un fitxer de notes. Els repetiràs moltes vegades, i a la lliçó 03-07 veuràs quant han crescut.

Sense fer servir docker run en cap moment, crea un contenidor de nginx:alpine anomenat exercici-cicle publicat al port 8090 i amb la variable ENTORN=proves. Abans d'arrencar-lo, respon amb comandes: en quin estat està?, respon el port 8090?, apareix a docker ps? Després arrenca'l, comprova les tres coses de nou, i intenta afegir-li un segon port (8091) sense esborrar-lo. Explica què passa i per què.

Fent servir exclusivament la imatge auroralibros/aurora-api:1.1.0 i sense reconstruir-la, aconsegueix aquestes cinc sortides, escrivint la comanda exacta en cada cas:

1. La versió de Node instal·lada.
2. El contingut de /app/package.json.
3. Un shell interactiu dins del contenidor.
4. El resultat de console.log(process.env.DB_HOST) amb DB_HOST valent aurora-db.
5. La llista de fitxers de /app executant ls directament, sense que hi intervingui node ni sh.

Crea dos fitxers d'entorn, aurora-dev.env i aurora-proves.env, que difereixin en PORT (3000 i 3100), DB_NAME (aurora_llibres i aurora_llibres_test) i REDIS_HOST. Arrenca dos contenidors de l'API amb la mateixa comanda llevat de l'--env-file i el --name, verifica amb printenv que cadascun té la seva configuració, i després arrenca un tercer que faci servir aurora-dev.env però amb PORT=3200 sobreescrit des de la línia de comandes. Respon: quantes imatges diferents has necessitat?, i quina línia del teu .gitignore impedeix que això acabi al repositori?

Solució a l'exercici 1

Estat abans d'arrencar:

Les tres respostes: estat created, el port no respon (codi 000, connexió rebutjada) i no apareix a docker ps (la sortida de la tercera comanda és buida), perquè docker ps sense -a només llista contenidors en execució. La configuració està desada, però no hi ha procés ni regla de xarxa.

Ara sí: apareix a docker ps, el port retorna 200 i la variable que vas definir a la fase create hi és present.

L'intent d'afegir un port:

No hi ha cap manera de fer-ho. docker update només modifica recursos (memòria, CPU, política de reinici — lliçó 03-07), mai ports, variables ni muntatges: aquests es fixen en crear el contenidor perquè impliquen namespaces de xarxa i regles de reenviament que es construeixen a l'arrencada. L'única sortida és recrear:

Aquesta rigidesa és precisament l'argument a favor de declarar la configuració en un fitxer versionat en comptes de a la línia de comandes, que és el que fa Docker Compose al mòdul 4.

Solució a l'exercici 2

El cas 4 és el més instructiu de l'exercici: hi ha dos -e a la mateixa comanda i signifiquen coses diferents. El primer va abans de la imatge, així que és l'opció --env de Docker; el segon va després, així que és un argument que Docker lliura tal qual a l'ENTRYPOINT ["node"], i allà -e és l'opció de Node per avaluar codi. La regla de l'apartat 2 ho explica sense ambigüitat.

El cas 5 mostra la diferència entre --entrypoint ls i --entrypoint "". Amb --entrypoint ls hauries d'escriure els arguments després de la imatge igualment, però amb --entrypoint "" la línia es llegeix de manera natural: la imatge deixa d'imposar executable i tot el que segueix és la comanda completa.

Solució a l'exercici 3

Verificació amb printenv, sense arrencar l'API (que fallaria pel que ja saps):

El tercer, amb sobreescriptura puntual:

PORT val 3200 (ha guanyat el -e) i DB_NAME conserva el valor del fitxer. -e sempre té prioritat sobre --env-file, amb independència de l'ordre en què els escriguis a la línia de comandes: prova de posar-los a l'inrevés i obtindràs el mateix resultat.

Les dues respostes finals:

• Una sola imatge. auroralibros/aurora-api:1.1.0 ha servit per a tres configuracions diferents sense reconstruir-se ni una sola vegada. Aquest és el principi de construir una vegada, desplegar a tot arreu que vas veure a la lliçó 02-06: el que canvia entre entorns és la configuració injectada, mai la imatge.
• La línia del .gitignore és *.env (o aurora-*.env). Aquests fitxers contenen DB_PASSWORD=aurora_secreta; al repositori no hi entren, i al .dockerignore tampoc, perquè no acabin al context de construcció ni, per accident, dins d'una capa de la imatge.

docker run ha deixat de ser una fórmula màgica. Saps que són dues operacions, create i start, i ho has demostrat executant-les per separat: la fase create reserva la capa d'escriptura i congela la configuració —per això no pots afegir un port ni una variable a un contenidor existent—, i la fase start munta namespaces, cgroups i regles de xarxa i llança el PID 1. Coneixes la regla d'or de l'ordre dels arguments, que separa les opcions de Docker de la comanda de dins, i tens les cinc famílies d'opcions ordenades: identitat, execució, xarxa, configuració i dades.

Manegues -d per a serveis, -it per a persones i --rm per a comandes d'un sol ús, sabent que aquest --rm és el teu enemic tan bon punt alguna cosa falla. Saps sobreescriure la meitat CMD i la meitat ENTRYPOINT d'una imatge per separat, inclosa l'anul·lació total amb --entrypoint "". Saps desacoblar-te d'una sessió amb Ctrl+P Ctrl+Q sense matar el procés, i per què docker attach és una eina esmolada que et pot tombar un servei amb un Ctrl+C distret, enfront de docker exec, que llança un procés independent. I saps portar la configuració fora de la imatge amb --env-file, amb les seves regles de format estrictes i la seva contrasenya que mai no entra ni a Git ni al context de construcció.

Sobretot, la plataforma ha començat a moure's: aurora-db i aurora-cache estan corrent ara mateix a la teva màquina, amb PostgreSQL 16 acceptant connexions i Redis responent PONG. I aurora-api ja no dona ECONNREFUSED: dona getaddrinfo ENOTFOUND aurora-db, un error diferent que diu una cosa molt concreta —el nom ni tan sols es resol— i que apunta directament a la solució. A més, el contenidor no es va quedar unhealthy: va morir en dos segons amb codi de sortida 1.

I això planteja la pregunta amb què continua el curs: per què uns contenidors es queden corrent indefinidament i altres moren a l'instant? A la lliçó següent, Cicle de Vida del Contenidor, veuràs els set estats pels quals passa un contenidor i les transicions entre ells, la regla que un contenidor viu exactament el que visqui el seu procés PID 1, la diferència entre una aturada ordenada amb SIGTERM i un SIGKILL als deu segons, i la taula de codis de sortida —aquest 1, i també el 125, el 137 i el 143— que converteix un número críptic en un diagnòstic. I ensenyaràs a server.js a apagar-se netament, tancant el pool de PostgreSQL i el client de Redis abans de marxar.