Tu imagen auroralibros/aurora-api:1.1.0 está publicada y es impecable: usuario sin privilegios, metadatos OCI, healthcheck y parada limpia en 0,3 segundos. Y sigue devolviendo ECONNREFUSED en /libros, exactamente como te anunció la lección anterior. Este módulo entero existe para arreglar eso, y empieza por donde hay que empezar: entender de verdad el comando que llevas usando desde la lección 01-06 sin haberlo mirado nunca de cerca. docker run no es un comando, es dos: crea un contenedor y lo arranca. Y admite más de un centenar de opciones, de las que en el trabajo diario se usan unas quince. En esta lección vas a ver qué hace run por dentro, vas a aprender esas quince opciones agrupadas por familias, vas a sobrescribir el CMD y el ENTRYPOINT de una imagen desde la línea de comandos, y vas a levantar por fin aurora-db y aurora-cache como contenedores reales. Al terminar tendrás tres contenedores vivos... y la API seguirá sin funcionar. Ese fallo, con su mensaje de error cambiado, es la pista con la que arranca el resto del módulo.

1. Qué hace docker run realmente: create + start
2. Anatomía del comando y el orden de los argumentos
3. Familia identidad: --name y --hostname
4. Familia ejecución: -d, -it, --rm, -w, -u, --entrypoint
5. Familia red y puertos: lo mínimo para trabajar
6. Familia configuración: -e y --env-file
7. Familia datos: -v en su versión mínima
8. Sobrescribir el CMD y el ENTRYPOINT desde la línea de comandos
9. Primer plano, segundo plano y cómo desacoplarse
10. docker attach frente a docker exec
11. Práctica: la base de datos y la caché de Aurora Libros

docker run es un atajo. Por debajo ejecuta dos operaciones distintas que puedes invocar por separado:

Docker imprime el ID completo del contenedor (64 caracteres hexadecimales) y devuelve el control. Fíjate en lo que ha ocurrido y en lo que no:

El contenedor existe, tiene su capa de escritura reservada y toda su configuración guardada (puertos, variables, comando), pero el estado es Created y la columna PORTS está vacía: no hay ningún proceso en marcha y el puerto 8080 no está escuchando en tu máquina. Compruébalo:

Ahora arráncalo:

docker start imprime el nombre del contenedor arrancado. Y ahora sí:

Esta separación no es un detalle académico: explica el reparto de responsabilidades que vas a usar durante todo el módulo.

La consecuencia práctica, que conviene grabarse ya: no puedes añadir un puerto ni una variable de entorno a un contenedor que ya existe. Si te has equivocado, se borra y se crea de nuevo. Es exactamente por eso que en el módulo 4 acabarás escribiendo esa configuración en un fichero en vez de en la línea de comandos.

Limpia la demostración:

El flujo completo, ahora que conoces las piezas de la lección 01-03:

Hay una sola regla de oro y provoca la mitad de los errores de los principiantes:

Todo lo que va antes de la imagen son opciones de Docker. Todo lo que va después de la imagen es el comando que se ejecuta dentro del contenedor.

Míralo fallar:

Docker no ha interpretado -e como una opción suya: como venía después de alpine:3.20, ha intentado ejecutar dentro del contenedor un programa llamado -e. La versión correcta:

Aquí --rm y -e MENSAJE=hola son opciones de Docker (van antes de la imagen) y sh -c 'echo $MENSAJE' es el comando dentro del contenedor (va después). Necesitamos sh -c porque la expansión de $MENSAJE la hace un shell, y sin él Docker pasaría la cadena literal.

Un vistazo general a las familias que vas a ver en las secciones siguientes:

Sin --name, Docker inventa un nombre de dos palabras (nostalgic_hopper, elegant_bardeen) y te obliga a copiar IDs. Con nombre, todos los comandos siguientes se vuelven legibles y guionizables:

Reglas de los nombres:

Ese último punto es la clave de todo el módulo, y por eso los nombres de Aurora Libros (aurora-db, aurora-cache, aurora-api, aurora-web) no son decorativos: dentro de poco serán nombres de host reales.

El error más habitual con --name:

Ojo: el conflicto ocurre aunque el contenedor anterior esté parado. Un contenedor Exited sigue ocupando su nombre. Lo resuelves con docker rm aurora-cache (o docker rm -f si está corriendo).

Cambia el nombre que el contenedor ve de sí mismo dentro de su propio namespace UTS:

Sin --hostname, el hostname es el ID corto del contenedor:

--name y --hostname son cosas distintas: --name es cómo lo llamas tú desde fuera (y cómo lo llaman otros contenedores por DNS); --hostname es cómo se llama el contenedor a sí mismo. Se usa poco, pero aparece en logs de aplicaciones y en clústeres de bases de datos.

Devuelve el ID y te deja la terminal libre. Sin -d, la terminal queda ocupada mostrando la salida del proceso y Ctrl+C lo detiene.

Prueba a quitar una de las dos letras para entender qué aporta cada una:

Regla práctica: -it para personas, -d para servicios, nada para comandos de un solo disparo. Y nunca -it en un script automatizado o en CI: sin terminal real, -t provoca the input device is not a TTY.

El contenedor se ejecuta, imprime y desaparece: no queda en docker ps -a ni ocupa capa de escritura. Es la opción que evita acumular decenas de contenedores muertos.

Dos avisos importantes:

• --rm es incompatible con la depuración: si el contenedor falla, se borra junto con sus logs y su inspect. Cuando algo va mal, quita el --rm para poder investigar (lección 03-04).
• --rm borra también los volúmenes anónimos asociados. Con volúmenes con nombre no pasa nada, pero es un detalle que se retoma en la lección 03-06.

• -w /tmp sobrescribe el WORKDIR /app que fijaste en el Dockerfile.
• -u 1000:1000 fuerza un UID:GID concreto aunque ese usuario no exista dentro de la imagen (por eso id muestra los números sin nombre).
• -u root anula el USER node de tu imagen. Es útilísimo para depurar (instalar una herramienta dentro de un contenedor sin privilegios), y a la vez es un recordatorio de que USER es una defensa en profundidad, no una barrera infranqueable: quien puede lanzar contenedores puede elegir el usuario.

Ya lo usaste en la lección 02-04 y aquí formaliza su sitio:

Sin --entrypoint, tu imagen tiene ENTRYPOINT ["node"] fijo y cualquier cosa que escribieras después de la imagen sería un argumento de node. Con --entrypoint sh entras a mirar. Es la puerta de servicio de toda imagen bien construida.

Aquí solo lo imprescindible; el porqué completo llega en la lección 03-05.

-p HOST:CONTENEDOR significa "todo lo que llegue al puerto 8080 de mi máquina, redirígelo al puerto 80 de este contenedor". El orden nunca se invierte: primero el host, después el contenedor.

Comprueba -P con tu propia imagen, que declara EXPOSE 3000:

Docker ha elegido el 32768 del rango efímero. docker port es el comando que responde a "¿en qué puerto del host quedó esto?".

Dos ideas que conviene fijar desde ya, aunque se desarrollen en 03-05:

• EXPOSE en el Dockerfile y --expose en run no abren nada: son documentación que consumen -P y otras herramientas.
• Publicar un puerto sirve para que tú, desde el host, alcances el contenedor. Para que dos contenedores se hablen entre sí no hace falta publicar nada. Esta distinción es la que está a punto de resolver el misterio de la API.

Limpia:

Tu server.js no tiene ni un valor fijo escrito: lee PORT, DB_HOST, DB_USER, DB_PASSWORD, DB_NAME y REDIS_HOST del entorno. Esa decisión de la lección 01-07 es la que permite que la misma imagen sirva para tu portátil, para pruebas y para producción.

La segunda forma es muy práctica para no escribir secretos en la línea de comandos, donde quedarían en el historial del shell.

Las variables definidas con -e sobrescriben las del ENV del Dockerfile. Compruébalo con tu imagen, que trae ENV PORT=3000:

Y vuelve a ver toda la escalera de prioridad:

Cuando pasas de tres variables, la línea de comandos se vuelve ilegible. Crea ~/aurora-libros/aurora.env:

Y úsalo:

Las reglas del formato son estrictas y distintas de las de un script de shell. Este es un punto donde se pierde mucho tiempo:

Y una regla de seguridad que ya conoces del módulo 2, ahora con su consecuencia concreta:

El fichero de entorno contiene una contraseña: no va al repositorio de Git ni al contexto de construcción. La imagen se queda sin secretos —como debe ser— y la configuración viaja por fuera, inyectada en el arranque. Puedes combinar ambas opciones: --env-file para el grueso y -e para lo que quieras sobrescribir puntualmente, porque -e gana sobre --env-file independientemente del orden en que los escribas.

Lo usaste en la lección 01-06 para servir tu index.html con Nginx:

La sintaxis mínima es -v ORIGEN:DESTINO[:opciones], con la ruta del host siempre absoluta y :ro para montar en solo lectura. Con eso te basta hasta la lección 03-06, donde verás los tres tipos de montaje, los volúmenes gestionados y por qué el catálogo de libros que estás a punto de crear desaparecerá si no haces nada al respecto. De momento, quédate con la idea de la lección 01-05: todo lo que un contenedor escribe fuera de un montaje vive en su capa de escritura y muere con él.

Retomamos la tabla de la lección 02-04, ahora desde el lado de la ejecución. Tu imagen declara:

El comando efectivo es la concatenación ENTRYPOINT + CMD → node server.js. Y desde docker run puedes tocar cada mitad por separado:

Compruébalo:

Dos matices que causan sorpresas:

• Sobrescribir el ENTRYPOINT descarta el CMD de la imagen. En la fila 4 de la tabla, el CMD ["server.js"] desaparece: si no quieres que sh reciba server.js como argumento no tienes que hacer nada, ya no está.
• --entrypoint "" (cadena vacía) es la forma de dejar la imagen sin ejecutable fijo, de modo que lo que escribas tras la imagen sea el comando completo. Es el truco que salva el día con imágenes cuyo entrypoint es un script complicado.

Cuando arrancas sin -d, tu terminal queda enganchada a la entrada y la salida del PID 1:

Ahí se queda. Si pulsas Ctrl+C, envías SIGINT al proceso y el contenedor se para. Eso rara vez es lo que quieres con un servicio.

La alternativa, si arrancaste con -it, es desacoplarte sin matarlo con la secuencia Ctrl+P seguida de Ctrl+Q:

Sigue vivo. Tres condiciones para que la secuencia funcione, y su ausencia explica el 90 % de los "a mí no me va":

1. El contenedor debe haberse arrancado con -t (necesita el pseudo-terminal).
2. Debe estar enganchado a stdin, es decir, con -i.
3. La secuencia se pulsa dentro de la sesión, no en otra terminal.

Si Ctrl+P te hace falta para otra cosa (en bash recupera el comando anterior), cámbiala:

Ahora la combinación es Ctrl+E seguida de e. Puedes hacerlo permanente en ~/.docker/config.json:

Resumen de las tres formas de arrancar:

Limpia:

Un contenedor en segundo plano se puede "volver a mirar" de dos formas radicalmente distintas:

docker attach te conecta a la entrada y salida del proceso PID 1 que ya existe. No lanza nada nuevo. Y ahí está su peligro:

Has parado Redis. Ctrl+C durante un attach va directo al PID 1. Para salir sin matarlo hay que usar Ctrl+P Ctrl+Q, o directamente conectarse en modo seguro:

Con --sig-proxy=false, Ctrl+C te devuelve el prompt sin enviar la señal al contenedor.

docker exec, en cambio, lanza un proceso nuevo dentro del contenedor:

Ese redis-cli no tiene nada que ver con el PID 1: es un segundo proceso que comparte los namespaces del contenedor y que puede terminar sin afectar al servicio.

La regla práctica: para mirar la salida usa docker logs y para entrar usa docker exec. Ambos se estudian a fondo en la lección 03-04. docker attach se reserva para procesos que de verdad esperan tu entrada por teclado.

Es el momento. Hasta ahora, la API arrancaba sola y fallaba porque no había ni PostgreSQL ni Redis. Vamos a ponerlos.

Repasemos cada línea, porque cada una tiene su motivo:

Comprueba que está vivo:

pg_isready es la herramienta oficial de PostgreSQL para preguntar "¿aceptas conexiones?". La ejecutamos dentro del contenedor con docker exec, sin necesidad de tener PostgreSQL instalado en el host. Ese detalle —usar las herramientas que ya vienen en la imagen— es una de las comodidades más infravaloradas de Docker.

Y comprueba que la base de datos existe, aunque todavía esté vacía:

Correcto: la base de datos aurora_libros está creada, pero no hay tablas. Falta ejecutar db/init.sql, y eso se hará de forma automática y elegante en la lección 03-06, cuando montes ese fichero dentro del contenedor.

Redis no necesita ninguna variable: arranca con su configuración por defecto.

Redis funciona. Dos contenedores vivos.

Docker ha aceptado el comando sin protestar. Pero:

El contenedor ni siquiera se ha quedado en marcha. Ha arrancado y ha muerto con código de salida 1. Veamos por qué:

Fíjate bien en el mensaje, porque ha cambiado respecto al módulo 2 y ese cambio es una pista de primer orden:

Y aquí está la paradoja que da sentido al resto del módulo: aurora-db y aurora-cache están corriendo ahora mismo, en la misma máquina, publicando sus puertos. Puedes comprobarlo desde el host:

Están vivos, están publicados, y aun así aurora-api no los encuentra. ¿Por qué?

La respuesta corta: porque no comparten red. Cada contenedor tiene su propia pila de red, y en la red por defecto de Docker no hay resolución de nombres entre contenedores. La respuesta larga, con la solución completa y el curl que devuelve los ocho libros, es la lección 03-05. De momento, deja la incógnita planteada y no borres nada: estos dos contenedores te acompañan durante todo el módulo.

Borramos solo la API (está parada y no sirve de nada). aurora-db y aurora-cache se quedan.

• Poner opciones después de la imagen. docker run alpine -e VAR=1 sh intenta ejecutar un programa llamado -e. Las opciones van antes de la imagen, siempre.
• Esperar poder añadir un puerto o una variable a un contenedor existente. No se puede: se fijan en la fase create. La solución es docker rm y volver a crear. Cuando esto te canse, ya estarás listo para el módulo 4.
• Usar --rm mientras depuras. Si el contenedor falla y se borra, te quedas sin logs y sin inspect. Durante la investigación, quita el --rm.
• -p 5432:5432 en una base de datos. Publica PostgreSQL en todas las interfaces, incluida la wifi del bar. Usa -p 127.0.0.1:5432:5432, o directamente no lo publiques: los contenedores no necesitan puertos publicados para hablar entre sí.
• Invertir el orden en -p. -p 80:8080 con Nginx no funciona y el error es confuso, porque Docker publica alegremente el 80 del host hacia un 8080 en el que no escucha nadie. Primero el host, después el contenedor.
• -t en scripts y CI. the input device is not a TTY. En automatización usa -i o nada, nunca -t.
• Comillas en un --env-file. DB_PASSWORD="aurora_secreta" guarda la contraseña con las comillas incluidas y provoca un password authentication failed desconcertante. Sin comillas.
• Consejo: usa --name siempre. Un contenedor sin nombre es un contenedor que dentro de diez minutos buscarás por ID en un docker ps -a con veinte líneas.
• Consejo: escribe los docker run largos en varias líneas con \ al final, y guárdalos en un fichero de notas. Vas a repetirlos muchas veces, y en la lección 03-07 verás cuánto han crecido.

Sin usar docker run en ningún momento, crea un contenedor de nginx:alpine llamado ejercicio-ciclo publicado en el puerto 8090 y con la variable ENTORNO=pruebas. Antes de arrancarlo, responde con comandos: ¿en qué estado está?, ¿responde el puerto 8090?, ¿aparece en docker ps? Después arráncalo, comprueba las tres cosas de nuevo, e intenta añadirle un segundo puerto (8091) sin borrarlo. Explica qué ocurre y por qué.

Usando exclusivamente la imagen auroralibros/aurora-api:1.1.0 y sin reconstruirla, consigue estas cinco salidas, escribiendo el comando exacto en cada caso:

1. La versión de Node instalada.
2. El contenido de /app/package.json.
3. Una shell interactiva dentro del contenedor.
4. El resultado de console.log(process.env.DB_HOST) con DB_HOST valiendo aurora-db.
5. La lista de ficheros de /app ejecutando ls directamente, sin que intervenga node ni sh.

Crea dos ficheros de entorno, aurora-dev.env y aurora-pruebas.env, que difieran en PORT (3000 y 3100), DB_NAME (aurora_libros y aurora_libros_test) y REDIS_HOST. Arranca dos contenedores de la API con el mismo comando salvo el --env-file y el --name, verifica con printenv que cada uno tiene su configuración, y después arranca un tercero que use aurora-dev.env pero con PORT=3200 sobrescrito desde la línea de comandos. Responde: ¿cuántas imágenes distintas has necesitado?, y ¿qué línea de tu .gitignore impide que esto acabe en el repositorio?

Solución al ejercicio 1

Estado antes de arrancar:

Las tres respuestas: estado created, el puerto no responde (código 000, conexión rechazada) y no aparece en docker ps (la salida del tercer comando está vacía), porque docker ps sin -a solo lista contenedores en ejecución. La configuración está guardada, pero no hay proceso ni regla de red.

Ahora sí: aparece en docker ps, el puerto devuelve 200 y la variable que definiste en la fase create está presente.

El intento de añadir un puerto:

No existe forma de hacerlo. docker update solo modifica recursos (memoria, CPU, política de reinicio — lección 03-07), nunca puertos, variables ni montajes: esos se fijan al crear el contenedor porque implican namespaces de red y reglas de reenvío que se construyen en el arranque. La única salida es recrear:

Esta rigidez es precisamente el argumento a favor de declarar la configuración en un fichero versionado en vez de en la línea de comandos, que es lo que hace Docker Compose en el módulo 4.

Solución al ejercicio 2

El caso 4 es el más instructivo del ejercicio: hay dos -e en el mismo comando y significan cosas distintas. El primero está antes de la imagen, así que es la opción --env de Docker; el segundo está después, así que es un argumento que Docker entrega tal cual al ENTRYPOINT ["node"], y ahí -e es la opción de Node para evaluar código. La regla del apartado 2 lo explica sin ambigüedad.

El caso 5 muestra la diferencia entre --entrypoint ls y --entrypoint "". Con --entrypoint ls tendrías que escribir los argumentos después de la imagen igualmente, pero con --entrypoint "" la línea se lee de forma natural: la imagen deja de imponer ejecutable y todo lo que sigue es el comando completo.

Solución al ejercicio 3

Verificación con printenv, sin arrancar la API (que fallaría por lo que ya sabes):

El tercero, con sobrescritura puntual:

PORT vale 3200 (ganó el -e) y DB_NAME conserva el valor del fichero. -e siempre tiene prioridad sobre --env-file, con independencia del orden en que los escribas en la línea de comandos: prueba a ponerlos al revés y obtendrás el mismo resultado.

Las dos respuestas finales:

• Una sola imagen. auroralibros/aurora-api:1.1.0 ha servido para tres configuraciones distintas sin reconstruirse ni una vez. Este es el principio de construir una vez, desplegar en todas partes que viste en la lección 02-06: lo que cambia entre entornos es la configuración inyectada, jamás la imagen.
• La línea del .gitignore es *.env (o aurora-*.env). Estos ficheros contienen DB_PASSWORD=aurora_secreta; en el repositorio no entran, y en el .dockerignore tampoco, para que no acaben en el contexto de construcción ni, por accidente, dentro de una capa de la imagen.

docker run ha dejado de ser una fórmula mágica. Sabes que son dos operaciones, create y start, y lo has demostrado ejecutándolas por separado: la fase create reserva la capa de escritura y congela la configuración —por eso no puedes añadir un puerto ni una variable a un contenedor existente—, y la fase start monta namespaces, cgroups y reglas de red y lanza el PID 1. Conoces la regla de oro del orden de los argumentos, que separa las opciones de Docker del comando de dentro, y tienes las cinco familias de opciones ordenadas: identidad, ejecución, red, configuración y datos.

Manejas -d para servicios, -it para personas y --rm para comandos de usar y tirar, sabiendo que ese --rm es tu enemigo en cuanto algo falla. Sabes sobrescribir la mitad CMD y la mitad ENTRYPOINT de una imagen por separado, incluida la anulación total con --entrypoint "". Sabes desacoplarte de una sesión con Ctrl+P Ctrl+Q sin matar el proceso, y por qué docker attach es una herramienta afilada que puede tumbarte un servicio con un Ctrl+C distraído, frente a docker exec, que lanza un proceso independiente. Y sabes llevar la configuración fuera de la imagen con --env-file, con sus reglas de formato estrictas y su contraseña que nunca entra ni en Git ni en el contexto de construcción.

Sobre todo, la plataforma ha empezado a moverse: aurora-db y aurora-cache están corriendo ahora mismo en tu máquina, con PostgreSQL 16 aceptando conexiones y Redis respondiendo PONG. Y aurora-api ya no da ECONNREFUSED: da getaddrinfo ENOTFOUND aurora-db, un error distinto que dice algo muy concreto —el nombre ni siquiera se resuelve— y que apunta directamente a la solución. Además, el contenedor no se quedó unhealthy: murió en dos segundos con código de salida 1.

Y eso plantea la pregunta con la que sigue el curso: ¿por qué unos contenedores se quedan corriendo indefinidamente y otros mueren al instante? En la siguiente lección, Ciclo de Vida del Contenedor, vas a ver los siete estados por los que pasa un contenedor y las transiciones entre ellos, la regla de que un contenedor vive exactamente lo que viva su proceso PID 1, la diferencia entre una parada ordenada con SIGTERM y un SIGKILL a los diez segundos, y la tabla de códigos de salida —ese 1, y también el 125, el 137 y el 143— que convierte un número críptico en un diagnóstico. Y le enseñarás a server.js a apagarse limpiamente, cerrando el pool de PostgreSQL y el cliente de Redis antes de irse.