Tienes los cuatro servicios declarados y dominas la CLI. Falta lo que de verdad convierte cuatro contenedores en una aplicación: cómo se encuentran entre sí, qué puede hablar con qué, y en qué orden deben estar listos.

En esta lección montas la pila definitiva de Aurora Libros: DNS interno, dos redes segmentadas para que la web no pueda tocar la base de datos, arranque coordinado con sondas de salud reales, un servicio de migración que corre una vez y termina, y el patrón de reintento que hace falta aunque todo lo anterior esté bien. Al final, los quince pasos de onboarding de la lección 01-07 se habrán quedado en dos.

1. La arquitectura final
2. Cómo se encuentran los servicios: el DNS de Compose
3. Quién habla con quién y por qué puerto
4. Segmentación en dos redes
5. Demostración: la web no llega a la base de datos
6. El orden de arranque: por qué depends_on a secas no basta
7. Sondas de salud reales y condition: service_healthy
8. Un servicio que corre una vez: service_completed_successfully
9. Por qué la aplicación debe reintentar igualmente
10. El compose.yaml completo y comentado
11. Puesta en marcha end-to-end
12. El recuento del onboarding

aurora-api es el único servicio que está en las dos redes: es la frontera. Todo lo que entra desde fuera pasa por aurora-web, y todo lo que toca los datos vive en una red sin salida al exterior.

En la lección 03-05 viste que una red bridge de usuario incorpora un servidor DNS interno en 127.0.0.11. Compose se apoya exactamente en eso, con una precisión que conviene grabar:

El nombre de host de un servicio es el nombre del servicio, no el del contenedor.

El contenedor se llama aurora-libros-aurora-db-1, pero desde la API te conectas a aurora-db. Compose registra en el DNS de cada red:

Los alias resultan muy útiles al migrar: si el código heredado busca postgres, añades aliases: [postgres] y funciona sin tocar una línea de la aplicación.

Una consecuencia importante: la resolución es por red. Un servicio solo resuelve los nombres de los servicios con los que comparte alguna red. Es la base de la segmentación del apartado 4.

Aquí está el error conceptual más repetido con Compose: usar el puerto publicado en lugar del interno. La publicación (ports) es una puerta desde el host hacia dentro; entre contenedores no interviene para nada.

Solo la primera fila usa un puerto publicado, porque es la única que entra desde el host. El resto viaja por la red interna de Docker.

Esto se refleja en el web/nginx.conf que ya escribiste en el módulo 3, donde proxy_pass http://aurora-api:3000/; usa nombre de servicio y puerto interno. Y en las variables de la API: DB_HOST=aurora-db, REDIS_HOST=aurora-cache. Nada de localhost, nada de direcciones IP, nada de puertos publicados.

Con una sola red, los cuatro servicios se ven entre sí. Funciona, pero significa que si alguien compromete el contenedor de nginx —el más expuesto, el único que recibe tráfico de fuera— tiene acceso directo al puerto 5432 de PostgreSQL. La buena práctica es segmentar por zonas:

internal: true hace dos cosas: los contenedores de esa red no tienen ruta hacia el exterior (ni siquiera pueden hacer ping a Internet) y nadie desde fuera del host puede alcanzarlos. Si una dependencia comprometida de PostgreSQL intentara llamar a casa, no tendría por dónde.

Efecto colateral que conviene conocer: un contenedor conectado solo a redes internas no puede publicar puertos en el host. Por eso aurora-db deja de publicar 127.0.0.1:5432; para acceder a la base de datos usarás docker compose exec, y el entorno de desarrollo (lección 04-07) volverá a exponerla añadiendo el servicio a una red no interna.

La segmentación no es teoría: se comprueba.

La primera resuelve; la segunda no devuelve nada y termina con código 2. aurora-web y aurora-db no comparten ninguna red, así que para nginx la base de datos sencillamente no existe en el DNS. Con la caja de herramientas de red de la lección 03-04, la diferencia entre las dos redes es tajante:

Desde frontal el nombre ni siquiera resuelve; desde trasera conecta; y la propia base de datos no tiene salida a Internet. Esa es la diferencia entre "funciona" y "funciona y además contiene el daño". El endurecimiento completo llega en la lección 05-03.

Prueba lo que pasa sin ninguna condición, con depends_on: [aurora-db] en la API:

Compose ha cumplido su promesa: arrancó aurora-db antes. El problema es qué significa "antes". Hay tres estados distintos y solo el tercero sirve:

PostgreSQL tarda entre 3 y 10 segundos desde que el proceso arranca hasta que acepta conexiones, y en el primer arranque, con init.sql por ejecutar, bastante más. La distinción entre "arrancado" y "listo" es la que rompe la mitad de los compose.yaml que circulan por ahí.

La solución tiene dos mitades. Primera: sondas que digan la verdad sobre cada servicio.

Segunda mitad: declarar la dependencia de la salud, no del arranque.

Ahora Compose no lanza la API hasta que ambas sondas pasan. Si una nunca llega a healthy, up --wait falla con un mensaje claro en lugar de dejarte un servicio reiniciándose en bucle.

Aurora Libros necesita aplicar el esquema y las migraciones antes de que la API atienda peticiones. Eso no es un servicio permanente: es una tarea que corre, termina y desaparece.

Y la API espera a que termine bien:

Dos detalles que se pasan por alto: restart: "no" es imprescindible —con unless-stopped heredado de un ancla, el contenedor se reiniciaría en bucle eternamente al terminar—, y las comillas también, porque no sin ellas es el booleano false en YAML. Además, la condición exige código de salida 0: si la migración falla, la API ni siquiera se crea, y ese es justo el comportamiento correcto.

Con todo lo anterior, el arranque en frío está resuelto. Pero no los demás casos: si aurora-db se reinicia a las tres de la mañana por un fallo de disco, la API ya está corriendo y depends_on no vuelve a evaluarse; en un orquestador, los contenedores se reprograman en cualquier orden; y una caída de red de dos segundos no la arregla ningún fichero YAML.

depends_on resuelve el arranque; la reconexión es responsabilidad de la aplicación. Añade a api/server.js un reintento con retroceso exponencial:

Tres decisiones de diseño: el retroceso exponencial evita machacar una base de datos que está arrancando, el jitter aleatorio impide que diez réplicas reintenten al unísono, y la prueba SELECT 1 es lo que distingue "tengo un objeto de conexión" de "la base de datos me responde". La caché merece un trato distinto: si Redis no está, /libros debe seguir sirviendo desde PostgreSQL con origen: db. Una caché es un acelerador, nunca una dependencia dura.

Ciento treinta líneas comentadas que sustituyen a cincuenta líneas de bash y, sobre todo, expresan cosas que el guion no sabía decir: quién depende de quién, qué significa estar listo, y qué puede hablar con qué.

Lee la secuencia: las dos redes y el volumen primero, luego base de datos y caché hasta Healthy, después las migraciones hasta Exited con código 0, y solo entonces la API y la web. El orden ya no lo escribes tú: lo deduce Compose del grafo de dependencias.

La prueba de fuego: la cache-aside en funcionamiento y, después, la resiliencia que exigimos en el apartado 9.

Primera petición desde PostgreSQL, segunda desde Redis: los nueve títulos atravesando web → api → db → cache exactamente como se diseñó, y http://localhost:8080 en el navegador muestra el catálogo completo. Y con la caché parada, la API sigue sirviendo desde la base de datos: degradación elegante, se pierde velocidad, no servicio.

Eso es todo. Alguien que entra hoy en el equipo tiene la plataforma completa —cuatro servicios, dos redes, un volumen, migraciones aplicadas y sondas de salud verificadas— en menos de un minuto, y con exactamente la misma configuración que el resto del equipo, porque está en Git.

Usar el puerto publicado entre contenedores. DB_HOST=localhost:5432 desde la API no encuentra nada: dentro del contenedor, localhost es él mismo. Nombre de servicio y puerto interno, siempre.

Confiar en depends_on sin condition. Solo garantiza orden de arranque. Sin sondas de salud, seguirás teniendo carreras.

Sondar el puerto en lugar del servicio. nc -z aurora-db 5432 da verde mientras PostgreSQL aún rechaza conexiones. Usa pg_isready.

Olvidar restart: "no" en un servicio de un solo uso. Con una política heredada, la migración se reinicia en bucle y el service_completed_successfully nunca se cumple.

Suponer que depends_on reconecta. No vuelve a evaluarse tras el arranque. La reconexión con reintentos es de la aplicación.

Tratar la caché como dependencia dura. Si tu API muere porque Redis no responde, has convertido un acelerador opcional en un punto único de fallo.

Consejo: cuando dos servicios no se vean, la primera comprobación es siempre docker compose exec <origen> getent hosts <destino>. Si no resuelve, no es un problema de la aplicación: es que no comparten red.

Ejercicio 1. Añade a aurora-db el alias de red postgres y demuestra que la API puede conectarse indistintamente por aurora-db o por postgres, pero que aurora-web no resuelve ninguno de los dos.

Ejercicio 2. Rompe el arranque a propósito: haz que aurora-migraciones termine con código 1 (por ejemplo, command: ["sh", "-c", "echo 'migración fallida'; exit 1"]) y observa qué hace docker compose up -d --wait con la API y con la web. Explica el resultado y por qué es el comportamiento deseable.

Ejercicio 3. Demuestra que el aislamiento de trasera es real en las dos direcciones: (a) aurora-db no puede salir a Internet, (b) desde otra máquina de tu red local no se puede alcanzar el 5432, y (c) aurora-api sí puede salir a Internet. Explica por qué (c) funciona a pesar de estar en la red interna.

Solución 1.

La misma dirección para los dos nombres: el alias es una entrada DNS adicional en esa red, no otro contenedor. Para aurora-web, código 2 (no resuelve), porque los alias viven dentro de la red en la que se declaran y nginx no está en trasera. Este es el mecanismo con el que se migra un servicio sin tocar el código de sus clientes: primero se añade el alias nuevo, luego se cambia el nombre del servicio.

Solución 2.

Ni aurora-api ni aurora-web llegan a crearse. Compose corta la cadena: si una dependencia con service_completed_successfully sale con código distinto de 0, todo lo que depende de ella se cancela, y ese fallo se propaga en cascada a la web, que depende de la API.

Es exactamente lo que quieres. La alternativa —arrancar la API contra un esquema a medio migrar— produciría errores intermitentes, datos corruptos y una hora de depuración. Además, --wait devuelve código 1, así que un pipeline de CI se pone en rojo automáticamente en lugar de continuar sobre una base rota. Compara con el guion de bash del módulo 3: allí, si el paso 4 fallaba, los pasos 5, 6 y 7 se ejecutaban igual.

Solución 3.

(a) y (b) confirman el doble aislamiento: internal: true elimina la ruta por defecto de esa red, y al no haber ports en aurora-db, no existe ninguna regla en el host que redirija hacia ella —ni siquiera desde el propio host, y mucho menos desde otra máquina de la red local—.

(c) funciona porque aurora-api está en las dos redes. Un contenedor conectado a varias redes tiene una interfaz en cada una, y la ruta por defecto se la da frontal, que no es interna. De ahí que la API sea la "frontera": es el único punto por el que la zona de datos se comunica con el mundo, y por tanto el único que hay que vigilar de cerca.

Aurora Libros está montada de verdad. Sabes que los servicios se encuentran por el nombre del servicio —no el del contenedor— gracias al DNS interno de cada red, que los aliases añaden nombres extra dentro de la red donde se declaran, y que entre contenedores siempre se usa el puerto interno: la publicación de ports solo abre una puerta desde el host, y en esta arquitectura hay exactamente una, el 8080 de la web.

Has segmentado la plataforma en dos zonas: una frontal con la web y la API, y una trasera marcada como internal con los datos y las migraciones, y lo has demostrado en las dos direcciones —nginx no resuelve siquiera el nombre de la base de datos, y PostgreSQL no tiene ruta hacia Internet—, con aurora-api como única frontera por estar en ambas redes. Y tienes resuelto el arranque con la distinción que separa un fichero que funciona en tu portátil de uno que funciona siempre: arrancado no es lo mismo que listo. pg_isready y redis-cli ping como sondas honestas, condition: service_healthy para esperar a que lo estén, service_completed_successfully con restart: "no" para la migración que corre una vez, y el reintento con retroceso exponencial y jitter en la aplicación, porque depends_on cubre el arranque y nada más. La caché, tratada como lo que es: un acelerador cuya caída degrada el servicio pero no lo tumba.

El recuento habla solo: de quince pasos manuales a un guion de cincuenta líneas, y de ahí a git clone y docker compose up -d --wait. Pero el fichero todavía tiene las contraseñas escritas en claro, la versión de la imagen fijada a mano y los puertos incrustados: exactamente lo que impide usarlo en más de un entorno. En la lección siguiente, Variables de Entorno en Docker Compose, separarás los dos sistemas que todo el mundo confunde —la sustitución ${VAR} que Compose hace sobre el propio YAML, y las variables que ve el proceso dentro del contenedor—, con su tabla de precedencia completa, el fichero .env del proyecto y su .env.example versionado, y el bloque secrets: para que las credenciales dejen de ser visibles en un docker inspect.