Aurora Libros ya está declarada y parametrizada, pero en la vida real la misma plataforma se levanta de tres maneras distintas: en el portátil de quien programa, en el runner de integración continua y en el servidor. Las diferencias son pocas —construir en vez de descargar, exponer o no ciertos puertos, límites más altos— y la tentación es duplicar el fichero.

Duplicarlo es el peor camino: dos ficheros divergen en una semana. Compose ofrece dos mecanismos complementarios para evitarlo: perfiles, que activan servicios opcionales bajo demanda, y ficheros de override, que se fusionan sobre una base común.

1. Perfiles: servicios que no siempre quieres
2. Perfiles y dependencias: las reglas
3. El override automático: compose.override.yaml
4. Overrides explícitos con varios -f
5. Las reglas de fusión
6. !reset y !override: sustituir en lugar de fusionar
7. La estrategia de Aurora Libros: base, desarrollo y producción
8. extends: reutilizar definiciones entre proyectos
9. include:: componer ficheros de varios equipos
10. Convenciones de nombres de fichero y de proyecto

Un servicio con la clave profiles: no se levanta salvo que su perfil esté activo. Es la forma de tener herramientas opcionales en el mismo fichero sin que molesten.

Un servicio puede pertenecer a varios perfiles (profiles: [herramientas, ci]), y se activa si alguno de ellos está activo.

Con Adminer levantado, http://localhost:8081 te da una interfaz web para explorar el catálogo sin instalar nada en tu máquina. Y COMPOSE_PROFILES=herramientas en tu .env local activa el perfil permanentemente para ti, sin afectar a nadie más.

Un uso muy práctico de un perfil para tareas puntuales:

Aquí hay tres comportamientos que conviene tener claros, porque son fuente de sorpresas:

Las dos filas importantes: nombrar un servicio con perfil lo activa implícitamente —docker compose up -d adminer funciona sin más—, y docker compose down deja huérfanos los servicios de perfil si no repites el perfil. Es la causa número uno de "he hecho down y sigue habiendo contenedores".

Regla de diseño: los servicios base nunca deben depender de un servicio con perfil. La dependencia va siempre en la dirección contraria.

Si existe un fichero llamado compose.override.yaml (o .yml) junto al compose.yaml, Compose lo carga y lo fusiona automáticamente, sin que tengas que indicar nada.

Es el mecanismo perfecto para el entorno de desarrollo: el compose.yaml describe la plataforma de forma neutra y el override añade lo que solo tiene sentido en tu máquina. Y como el override se ignora en el servidor —donde se usan otros ficheros explícitos—, no hay riesgo de que un puerto de depuración acabe en producción.

Cuando pases ficheros con -f, el override automático deja de cargarse: mandas tú.

Compose lee los ficheros en el orden indicado y fusiona cada uno sobre el resultado acumulado: el último gana. El orden importa y es una fuente clásica de errores; si inviertes los ficheros, el fichero base sobrescribe al específico.

Las rutas relativas se resuelven respecto al directorio del primer fichero, salvo que uses --project-directory. Si tus overrides viven en un subdirectorio, tenlo presente:

Lo que ocurre al fusionar depende del tipo de cada clave:

La distinción entre las dos primeras filas y la tercera explica el 90 % de las sorpresas. Un ejemplo:

environment se ha fusionado (NODE_ENV sobrevive, LOG_NIVEL se sustituye) y ports se ha concatenado (los dos puertos). Que las listas se concatenen es cómodo para añadir, pero significa que no puedes quitar un puerto o un volumen desde un override... salvo con lo que viene ahora.

Compose v2.24 introdujo dos etiquetas YAML que resuelven justo ese problema:

!reset vacía la clave heredada (y con null la elimina por completo), y !override sustituye el valor en lugar de fusionarlo. Son la única forma limpia de quitar en un override lo que la base añade, y evitan el antiguo apaño de mantener dos ficheros base casi idénticos.

La estructura recomendada son tres ficheros con responsabilidades bien separadas:

El base es el de la lección 04-04, con una regla añadida: nada específico de un entorno. Ni build, ni puertos de depuración, ni NODE_ENV fijado a mano.

El detalle de los bind mounts de código y de la recarga automática es la lección 04-07; aquí solo interesa dónde vive esa configuración: en el override, nunca en la base.

Fíjate en tres decisiones: la versión de la imagen es obligatoria (:?), porque desplegar latest es desplegar cualquier cosa; build: !reset null garantiza que el servidor jamás construya; y ports: !reset [] elimina el 3000 heredado, no lo añade.

Verifica siempre un despliegue antes de ejecutarlo:

Mientras que los overrides fusionan ficheros completos, extends importa un servicio concreto, incluso desde otro fichero o proyecto:

La limitación de depends_on es deliberada: una dependencia solo tiene sentido dentro del proyecto que la define. Usa extends para plantillas de configuración (imagen base, usuario, política de reinicio) y anclas YAML para repetición dentro del mismo fichero.

include: va un paso más allá: incorpora ficheros de Compose completos, con sus servicios, redes y volúmenes, como si estuvieran escritos en el tuyo.

La diferencia con -f es importante: con varios -f los ficheros se fusionan (se espera que hablen de los mismos servicios), mientras que include agrega ficheros independientes que aportan servicios propios. Cada fichero incluido mantiene su propio contexto de rutas y de variables, lo que permite que el equipo de pagos mantenga su compose.yaml sin coordinarse con el de plataforma. A cambio, los nombres de servicio deben ser únicos en el conjunto.

Y el nombre de proyecto por entorno, para que dos pilas convivan en la misma máquina sin pisarse:

Dos pilas completas, con contenedores, redes y volúmenes prefijados de forma distinta, sin compartir un solo dato. Lo único que sigue siendo global de la máquina son los puertos publicados: por eso el override de desarrollo usa 8080 y el de producción, 80.

Para no teclear los -f cien veces al día, fija el conjunto en el entorno:

Invertir el orden de los -f. -f compose.prod.yaml -f compose.yaml hace que la base sobrescriba a producción. El específico va siempre el último.

Esperar que un override quite un puerto. Las listas se concatenan. Para eliminar, !reset o !override.

Hacer down sin repetir el perfil. Los servicios con perfil se quedan corriendo. Repite --profile o usa --remove-orphans.

Poner build en el fichero base. Un servidor acabará construyendo la imagen en vez de descargar la versión probada. build va en el override de desarrollo.

Desplegar sin fijar la etiqueta de la imagen. latest en producción significa que dos servidores pueden estar corriendo código distinto. Usa ${AURORA_API_VERSION:?...}.

Suponer que extends trae las dependencias. No importa depends_on: hay que redeclararlo en el servicio que extiende.

Consejo: antes de cualquier despliegue, docker compose -f ... config y léelo. Treinta segundos de lectura evitan desplegar un puerto de depuración abierto a Internet.

Ejercicio 1. Crea un compose.override.yaml que, para aurora-api, cambie LOG_NIVEL a debug, añada el puerto 9229 y monte ./api/src. Sin levantar nada, demuestra con docker compose config que NODE_ENV heredado sobrevive, que hay dos puertos y que el volumen aparece junto a los de la base.

Ejercicio 2. Añade un servicio adminer bajo el perfil herramientas y responde con comandos: (a) ¿aparece en docker compose ps --services sin el perfil?, (b) ¿qué pasa si lo nombras explícitamente en up sin --profile?, y (c) ¿qué ocurre al hacer docker compose down sin el perfil? Propón la forma correcta de bajar todo.

Ejercicio 3. Escribe un compose.prod.yaml que elimine por completo la publicación del puerto 3000 de la API, exija la variable AURORA_API_VERSION e impida construir en el servidor. Demuestra con config que el resultado no contiene ni build ni el puerto 3000, y que falla de forma clara si no se define la versión.

Solución 1.

Se ven las tres reglas en acción: environment es un mapa, así que NODE_ENV sobrevive y solo se sustituye la clave coincidente; ports y volumes son listas, así que se concatenan. Fíjate también en que config ha normalizado la ruta relativa ./api/src a ruta absoluta: esa normalización es justo lo que hace fiable la revisión previa a un despliegue.

Solución 2.

(a) Sin el perfil, el servicio ni siquiera se considera. (b) Nombrarlo lo activa implícitamente: no hace falta --profile si lo pides por su nombre. (c) Y aquí la sorpresa: tras docker compose down, adminer sigue vivo, porque down sin perfil no lo contempla. Es un contenedor huérfano que sigue ocupando el puerto 8081 y con acceso a la base de datos.

Solución 3.

La imagen queda fijada a una etiqueta concreta, no aparecen ni build ni el puerto 3000 —!reset los ha eliminado, cosa que una simple redefinición no habría conseguido con las listas— y sin la variable el despliegue falla antes de tocar nada, con un mensaje que dice qué hacer. Ese fallo temprano es exactamente lo que quieres en un pipeline: mejor un config --quiet en rojo que un servidor sirviendo una versión imprevista.

Un mismo proyecto sirve ya para tres entornos sin duplicar un solo servicio. Los perfiles te dan servicios opcionales bajo demanda —adminer y mailhog bajo herramientas, semillas bajo datos—, activables con --profile, con COMPOSE_PROFILES o simplemente nombrando el servicio, con dos reglas que se olvidan: un servicio base nunca debe depender de uno con perfil, y down sin repetir el perfil deja contenedores huérfanos corriendo.

Los overrides cubren el resto: el compose.override.yaml automático para las comodidades de desarrollo y la combinación explícita con varios -f donde el último gana. Dominas las reglas de fusión —escalares que se sustituyen, mapas que se fusionan clave a clave, listas que se concatenan y bloques como command o healthcheck.test que se reemplazan enteros— y sabes salir del callejón de las listas con !reset y !override, la forma limpia de quitar un puerto de depuración en producción. La estrategia queda clara: un compose.yaml neutro sin build ni puertos de depuración, un override de desarrollo y un compose.prod.yaml con etiqueta de imagen obligatoria, restart: always, límites propios y logging configurado; y docker compose config leído antes de cada despliegue.

Sabes además cuándo usar cada herramienta de reutilización: anclas YAML dentro de un fichero, extends para plantillas de servicio entre proyectos —recordando que no arrastra depends_on—, e include: para agregar ficheros completos que mantienen otros equipos, cada uno con su contexto de rutas y variables. Y la convención de nombres de fichero y de proyecto (-p aurora-dev, -p aurora-prod) que permite que dos pilas convivan en la misma máquina sin compartir ni un byte, con COMPOSE_FILE para no repetir los -f.

Queda la parte que más vas a usar: el día a día. En la lección siguiente, Desarrollo Local con Docker Compose, convertirás ese override de desarrollo en un entorno de trabajo real: bind mount del código con la solución al eterno problema de node_modules, recarga automática con --watch de Node 22 y con el bloque nativo develop.watch de Compose, depuración paso a paso desde VS Code con el inspector en el puerto 9229, pruebas en contenedores efímeros con su base de datos en tmpfs, datos de desarrollo y reseteo en un comando, el rendimiento de los bind mounts en macOS y Windows, y un Makefile con los atajos del equipo.