Llevas cuatro lecciones con la misma avería y ya sabes exactamente qué la causa: nslookup aurora-db devuelve NXDOMAIN porque la red bridge por defecto no tiene DNS interno entre contenedores. La conectividad está ahí —nc -zv 172.17.0.2 5432 responde succeeded—, pero la API no sabe cómo se llama su base de datos.

Esta lección es la que lo arregla, y con dos comandos. Pero antes de escribirlos vas a entender de verdad el modelo de red de Docker: por qué cada contenedor tiene su propio localhost, qué hace cada uno de los drivers integrados, en qué se diferencia la bridge por defecto de una red creada por ti, y cuál es la diferencia —que se confunde constantemente— entre publicar un puerto y que dos contenedores se hablen. Después crearás aurora-net, moverás los tres servicios dentro, y ejecutarás el curl que llevas todo el curso esperando. Y para rematar, pondrás delante aurora-web con Nginx como proxy inverso, y abrirás la librería completa en el navegador.

1. Por qué los contenedores no se ven entre sí
2. Los drivers de red integrados
3. La bridge por defecto frente a las redes definidas por el usuario
4. Los comandos de docker network
5. Publicación de puertos, revisitada
6. Práctica: aurora-net y la resolución de nombres
7. El momento de la verdad: /libros devuelve los ocho libros
8. aurora-web: Nginx como proxy inverso
9. Conectar y desconectar redes en caliente
10. Buenas prácticas de red

Un contenedor no es solo un proceso aislado: tiene su propio namespace de red. Eso significa que posee, en exclusiva, su lista de interfaces, su tabla de rutas, sus reglas de cortafuegos, sus puertos y —esto es lo que confunde a todo el mundo— su propio localhost.

Tres localhost distintos en la misma máquina. Cuando server.js intentaba conectarse a localhost:5432 en el módulo 2, estaba preguntando por PostgreSQL dentro de su propio contenedor, donde solo vive node. De ahí el ECONNREFUSED: alguien contestó (el propio contenedor) diciendo que ahí no hay nadie escuchando.

Compruébalo tú mismo:

Cada uno con su IP, y en el localhost de la API no hay ninguna base de datos. La regla, en una línea:

Dentro de un contenedor, localhost siempre significa "yo mismo". Para hablar con otro contenedor hay que usar su dirección: su IP o, mucho mejor, su nombre.

Docker implementa las redes mediante drivers intercambiables:

Las tres primeras vienen preconfiguradas y las ves con:

Un vistazo rápido a host y none, que se usan poco pero conviene reconocer:

Con --network host, el contenedor tiene la misma IP que tu máquina: no hay -p que valga porque los puertos son directamente los del host, y no hay ningún aislamiento de red. Con --network none, solo existe lo: ni siquiera puede hacer ping a nada.

Aquí está el corazón de la lección. Existen dos tipos de red bridge y se comportan de forma muy distinta:

Solo la primera fila importa hoy, pero es determinante: en una red propia, Docker levanta un servidor DNS interno en 127.0.0.11 que resuelve los nombres de los contenedores conectados a esa red. En la bridge por defecto, ese DNS existe pero solo reenvía consultas a los servidores del host: no conoce ningún nombre de contenedor. Ese es, literalmente, todo el misterio que llevas arrastrando desde la lección 02-06.

Antes de arreglarlo, deja constancia del punto de partida:

Con opciones, cuando necesites control:

--internal merece atención: una red interna permite que los contenedores se hablen entre sí pero les corta la salida al exterior. Es una defensa excelente para una base de datos que no tiene por qué salir a Internet, y se retoma en la lección 05-03.

Y la consulta más útil de todas: quién está conectado.

De momento no imprime nada: la red está vacía.

Una red con contenedores conectados no se puede borrar (network ... has active endpoints). Y las tres redes predefinidas —bridge, host, none— no se pueden eliminar nunca.

Ahora que entiendes el modelo, la tabla de la lección 03-01 cobra sentido pleno:

Y esta es la distinción que hay que tener absolutamente clara:

De ahí salen dos errores clásicos que ahora puedes evitar:

• Publicar puertos "para que los contenedores se vean". No hace falta y encima expone servicios internos. aurora-db no necesita ningún -p para que la API la use; solo lo necesitas tú, si quieres conectarte con un cliente desde el host.
• Usar el puerto del host en la cadena de conexión de otro contenedor. Si publicas -p 5433:5432, otro contenedor debe seguir conectándose a aurora-db:5432, el puerto interno. El 5433 solo existe para el host.

Manos a la obra. Primero, la red:

Ahora recrea los tres servicios dentro de ella. Como la red es un ajuste de namespace, se fija al crear el contenedor (lección 03-01), así que hay que borrar y volver a crear:

Fíjate en un cambio importante en aurora-cache: ya no lleva -p. Nadie desde el host necesita hablar con Redis; solo la API, y para eso basta con estar en la misma red. Es el principio de exponer lo mínimo imprescindible.

Antes de arrancar la API, vuelve a cargar el catálogo, porque el contenedor de la base de datos es nuevo:

Anota esta molestia, porque es la segunda vez que la sufres: cada vez que recreas aurora-db pierdes los datos y tienes que volver a cargarlos a mano. Esa es la carencia que resuelve la lección 03-06.

Y ahora la API:

Ahí está. El mismo comando que hace diez minutos devolvía código 2 y ninguna línea, ahora resuelve los tres nombres. No has cambiado ni una línea de server.js, ni el Dockerfile, ni el fichero de entorno: solo has puesto los contenedores en una red propia.

Comprueba también la conectividad real, puerto a puerto:

Los tres, por nombre. Y observa el detalle: aurora-cache responde en el 6379 aunque no publicaste ningún puerto. La publicación es para el host; dentro de la red, todos los puertos del contenedor están disponibles para sus vecinos.

Y el estado de la flota:

(healthy). Ese paréntesis lleva cuatro lecciones diciendo unhealthy. El HEALTHCHECK que escribiste en la lección 02-04 hace su comprobación contra /salud, /salud consulta PostgreSQL y Redis, ambos responden, y por primera vez devuelve 200. Y fíjate en la línea de aurora-cache: 6379/tcp a secas, sin flecha. Expuesto pero no publicado.

db: ok. cache: ok. Y ahora, el comando que llevas todo el curso esperando:

Los ocho libros. El jardín de senderos que se bifurcan, Rayuela, Cien años de soledad, La sombra del viento, Nada, La casa de los espíritus, Los detectives salvajes y El tiempo entre costuras, ordenados por título, servidos por una API en un contenedor, leídos de una base de datos PostgreSQL en otro contenedor, a través de una red virtual que has creado tú. Párate un segundo en esto: la plataforma de Aurora Libros está viva. Es la primera vez desde la lección 01-07, donde la ejecutabas a mano en quince pasos y fallaba, que el sistema completo funciona de extremo a extremo.

Y hay una segunda comprobación, más sutil, que demuestra que la caché también está haciendo su trabajo:

La primera llamada fue a PostgreSQL y guardó el resultado en Redis con un TTL de 60 segundos; la segunda ya lo sirvió desde la caché. Los tres contenedores están cooperando: la API habla con la base de datos por su nombre y con la caché por el suyo. Compruébalo también por el otro extremo:

Esa última fila es la lección que hay que llevarse: el problema nunca estuvo en la aplicación ni en la imagen. Estaba en cómo se conectaban los contenedores entre sí.

Falta el cuarto servicio. Tu web/index.html de la lección 01-07 llama a /api/libros, una ruta relativa, no a http://localhost:3000/libros. Ese diseño era deliberado: el navegador debe hablar con un único origen, y quien reparte por dentro es Nginx.

Crea ~/aurora-libros/web/nginx.conf:

Línea a línea, lo que importa:

Arranca el contenedor:

Dos detalles del comando:

• Los dos -v montan ficheros del host en solo lectura (:ro). Es la sintaxis mínima de la lección 03-01; la lección 03-06 explica qué son exactamente estos montajes y por qué :ro es importante en ficheros de configuración.
• --stop-signal SIGQUIT aplica lo que aprendiste en la lección 02-04: Nginx hace un apagado ordenado con SIGQUIT y uno abrupto con SIGTERM. Con esta opción, docker stop aurora-web no corta peticiones a medio servir.

Comprueba la cadena completa:

Abre http://localhost:8080 en el navegador. La página de Aurora Libros carga, llama a /api/libros, Nginx la reenvía a aurora-api, la API consulta PostgreSQL o Redis, y la tabla se rellena con los ocho títulos y sus precios en euros. La arquitectura completa, funcionando:

Ni una sola IP escrita a mano en ninguna parte: aurora-web busca aurora-api, y aurora-api busca aurora-db y aurora-cache, todos por nombre.

Con redes definidas por el usuario, y solo con ellas, puedes cambiar la topología sin recrear nada:

aurora-db tiene ahora dos interfaces y dos IPs, una en cada red. Es el patrón habitual para dar acceso a una herramienta de administración sin abrir la red de la aplicación:

Adminer ve la base de datos, pero no ve aurora-api ni aurora-cache, porque no está en aurora-net. Aislamiento por diseño.

Y un apunte sobre alias de red, que serán importantes en el módulo 4:

Un contenedor puede responder a varios nombres en la misma red. Es lo que permite, por ejemplo, cambiar de implementación sin tocar la configuración de quien la consume.

Cómo queda la superficie expuesta de Aurora Libros:

En un despliegue real, incluso el -p 3000:3000 de la API sobraría: si el navegador solo habla con Nginx, la API no necesita estar publicada. Puedes probarlo recreándola sin -p y verás que http://localhost:8080/api/libros sigue funcionando perfectamente, porque el proxy la alcanza por la red interna.

Lo que esta lección no cubre, y dónde se ve: cómo funciona el bridge por dentro (parejas veth, iptables, nat), las redes overlay entre varios hosts, macvlan y las políticas de red se estudian en la lección 05-01 y en la 06-03.

• Usar localhost para referirse a otro contenedor. Dentro de un contenedor, localhost es él mismo. Usa el nombre del otro contenedor.
• Dejar los contenedores en la bridge por defecto y esperar que se resuelvan por nombre. No ocurrirá jamás. Crea una red con docker network create.
• Escribir IPs a mano. Funciona hasta el siguiente reinicio. Docker asigna las IPs por orden de arranque.
• Usar el puerto publicado del host en la conexión entre contenedores. Con -p 5433:5432, otro contenedor debe seguir usando el 5432.
• Publicar puertos "para que se vean entre ellos". No hace falta, y expone servicios internos a toda la red.
• Intentar cambiar de red con docker start. La red se fija al crear. Se cambia con network connect/disconnect, o recreando.
• 502 en Nginx tras recrear la API. Nginx cacheó la IP antigua. Se resuelve con resolver 127.0.0.11 valid=10s y proxy_pass sobre una variable, como en la configuración de esta lección.
• Olvidar la / final de proxy_pass. Sin ella, /api/libros se reenvía como /api/libros y la API responde 404. Con ella, llega como /libros.
• Consejo: docker network inspect es la forma más rápida de responder a "¿quién está en esta red y con qué IP?".
• Consejo: para diagnosticar, lanza netshoot conectado a la red (--network aurora-net) y prueba nc, dig y curl desde dentro de ella.

Crea dos redes, red-a y red-b. Levanta un contenedor servidor-a con nginx:alpine en red-a, y dos clientes de nicolaka/netshoot: cliente-a en red-a y cliente-b en red-b. Demuestra con comandos que:

1. cliente-a resuelve servidor-a por nombre y obtiene un HTTP 200.
2. cliente-b no lo resuelve ni lo alcanza, ni por nombre ni por IP.
3. Después, sin recrear nada, haz que cliente-b pueda alcanzarlo, y verifica cuántas IPs tiene entonces.

Levanta una pila mínima en una red red-tienda: un mini-db con redis:7-alpine sin ningún -p, y un mini-api con nicolaka/netshoot que ejecute sleep 3600, publicando -p 9999:80. Responde con comandos y explicaciones:

1. ¿Puede mini-api hablar con mini-db? Demuéstralo.
2. ¿Puedes tú, desde el host, hablar con mini-db con redis-cli o nc? ¿Por qué?
3. ¿Qué responde curl localhost:9999 y por qué, si mini-api no tiene ningún servidor web?
4. Recrea mini-db con -p 127.0.0.1:6380:6379 y repite el punto 2. ¿Ha cambiado algo para mini-api?

Con la plataforma de Aurora Libros funcionando, provoca y diagnostica dos averías reales del proxy:

1. Cambia en nginx.conf el destino a http://aurora-api-inexistente:3000, recarga Nginx con docker kill -s SIGHUP aurora-web y observa qué devuelve curl localhost:8080/api/libros. Diagnostica con docker logs aurora-web.
2. Restaura el destino correcto pero quita la barra final de proxy_pass. Recarga y observa el nuevo error. Explica exactamente qué ruta le está llegando a aurora-api (compruébalo con docker logs aurora-api).
3. Deja todo correcto y demuestra, recreando aurora-api sin -p, que la web sigue funcionando en localhost:8080.

Solución al ejercicio 1

1. Desde cliente-a:

2. Desde cliente-b:

Aquí hay dos fallos distintos y ambos importan: el nombre no se resuelve (no comparten red, así que el DNS de red-b no conoce a servidor-a) y tampoco funciona la IP, porque son dos bridges separadas y el tráfico entre ellas no está permitido. Compáralo con el diagnóstico de la lección 03-04: allí el nombre fallaba pero la IP funcionaba, lo que demostraba que sí compartían red. La combinación de las dos pruebas es lo que distingue "misma red sin DNS" de "redes distintas".

3. Conectar en caliente:

Dos IPs, una por red, sin haber parado ni recreado el contenedor. Eso solo es posible con redes definidas por el usuario.

Solución al ejercicio 2

1.

Sí, perfectamente, y mini-db no publica ningún puerto. Dentro de una red compartida, todos los puertos del contenedor están disponibles para sus vecinos: -p no tiene nada que ver con esto.

2.

No. Como mini-db no publicó ningún puerto, no existe ninguna regla que reenvíe tráfico del host hacia él. El host y la red de Docker son dos ámbitos distintos: el host solo alcanza lo que se ha publicado explícitamente.

3.

La publicación existe —docker ps muestra 0.0.0.0:9999->80/tcp—, pero dentro del contenedor no hay nada escuchando en el 80: mini-api solo ejecuta sleep. Es la demostración de que -p no comprueba nada: crea el reenvío aunque el destino esté vacío. Es el mismo error que se comete al invertir el orden en -p 80:8080.

4.

Ahora tú puedes conectarte desde el host por el puerto 6380, y para mini-api no ha cambiado absolutamente nada: sigue usando mini-db:6379, el puerto interno. Los dos caminos son independientes.

Solución al ejercicio 3

1. Destino inexistente:

502 Bad Gateway es el error de "el proxy no pudo hablar con el destino", y el log da el motivo exacto: could not be resolved. Es el mismo NXDOMAIN de la lección 03-04, visto desde Nginx. Y merece la pena notar que la web estática sigue sirviéndose sin problema en http://localhost:8080/: solo falla la ruta /api/.

2. Sin la barra final:

Ahora sí llega a la API, pero con la ruta equivocada. Con la barra final, proxy_pass http://aurora-api:3000/ sustituye el prefijo /api/ por /, así que /api/libros llega como /libros. Sin ella, Nginx concatena la ruta completa y la API recibe /api/libros, una ruta que server.js no define, de ahí el 404 de Express. Un solo carácter, y la mitad de los proxies mal configurados del mundo se explican por él.

3. Restaurar y quitar la publicación de la API:

Justo lo que se buscaba: desde el host, el puerto 3000 ya no existe; desde la web, los ocho libros siguen llegando. La API ha dejado de estar expuesta y el servicio no se ha resentido, porque Nginx la alcanza por la red interna. Es exactamente la arquitectura que querrías en producción: una sola puerta de entrada.

Como en las siguientes lecciones conviene poder llamar a la API directamente para hacer pruebas, vuelve a dejarla publicada:

El misterio está resuelto y la plataforma está viva. Sabes que cada contenedor tiene su propia pila de red y su propio localhost, y que por eso localhost:5432 dentro de la API preguntaba por una base de datos que nunca estuvo ahí. Conoces los drivers integrados —bridge para casi todo, host cuando no quieres aislamiento ni NAT, none para aislamiento total— y sabes que overlay, macvlan e ipvlan existen para escenarios de varios hosts y de integración con la red física que verás en las lecciones 05-01 y 06-03.

Y tienes clavada la diferencia que lo explicaba todo: la bridge por defecto no tiene DNS interno; una red definida por el usuario sí. Un docker network create aurora-net y un --network aurora-net en cada contenedor, y getent hosts aurora-db pasó de devolver código 2 a devolver 172.18.0.2 aurora-db. Sin tocar una línea de server.js, ni el Dockerfile, ni el fichero de entorno. También sabes conectar y desconectar redes en caliente para dar acceso puntual a una herramienta de administración, y poner alias de red a un contenedor.

Distingues publicar un puerto de comunicar dos contenedores: -p es para que el host y el exterior entren; dentro de la red, todos los puertos están disponibles por nombre sin publicar nada. Por eso aurora-cache ya no lleva -p, aurora-db está atada a 127.0.0.1, y has demostrado que hasta la API puede vivir sin publicación si Nginx es la única puerta de entrada.

El resultado, en una línea: curl http://localhost:3000/libros devuelve los ocho libros de Aurora Libros, servidos por Node desde PostgreSQL, cacheados en Redis con su TTL de 60 segundos, y http://localhost:8080 muestra la librería completa en el navegador a través de un proxy inverso que reenvía /api/ sin exponer la API. El healthcheck marca healthy por primera vez en todo el curso. Cuatro contenedores, una red, cero IPs escritas a mano.

Queda un problema, y ya lo has sufrido dos veces en esta misma lección: cada vez que recreas aurora-db, los ocho libros desaparecen y tienes que volver a cargar init.sql con docker cp. Los datos viven en un volumen anónimo que nadie controla, o directamente en la capa de escritura que muere con el contenedor. En la siguiente lección, Persistencia de Datos con Volúmenes, atacarás ese problema de raíz: verás los tres tipos de montaje —volúmenes gestionados, bind mounts y tmpfs—, la diferencia entre -v y --mount, dónde viven realmente los volúmenes y por qué no debes tocarlos a mano. Le darás a PostgreSQL el volumen aurora-datos, montarás init.sql para que se ejecute solo, y repetirás la prueba definitiva: insertar un libro nuevo, destruir el contenedor de la base de datos, recrearlo, y comprobar que el libro sigue ahí.