Tu compose.yaml de la lección anterior usa siete claves. La especificación de Compose define más de sesenta, pero no necesitas memorizarlas: la mayoría son la traducción directa de una opción de docker run que ya dominas del módulo 3.

Esta lección es la referencia práctica de un servicio, organizada por bloques y aplicada a Aurora Libros. Al final tendrás los cuatro servicios declarados en un solo fichero. La explicación de cómo interactúan entre sí es la lección 04-04, y las variables de entorno tienen lección propia, la 04-05.

1. Tabla maestra: claves de servicio y su equivalente en docker run
2. Imagen y construcción: image y build
3. Identidad: container_name y hostname
4. Ejecución: command, entrypoint, user, init y el apagado
5. Red y puertos: ports, expose, networks, alias
6. Datos: volumes, tmpfs, read_only
7. Salud y dependencias: healthcheck y depends_on
8. Recursos y reinicio: restart y deploy.resources
9. Etiquetas: labels
10. Bloques de nivel superior: volumes: y networks:
11. Anclas y referencias YAML para no repetirse
12. Aurora Libros: los cuatro servicios declarados

La única fila sin equivalente es depends_on, y no es casualidad: la relación entre servicios es exactamente lo que docker run no sabe expresar.

image toma una referencia igual que docker run: repositorio y etiqueta (postgres:16-alpine) o, mejor para producción, un digest inmutable (postgres@sha256:9f3d0e...).

build le dice a Compose que construya la imagen en lugar de descargarla. En forma corta es solo el contexto (build: ./api); en forma larga, todo lo que aprendiste en el módulo 2:

Cuando aparecen las dos claves juntas, build manda al construir e image da el nombre del resultado. Es la combinación más útil: docker compose build etiqueta la imagen con ese nombre y docker compose push la publica.

Con solo build, si no pones image, Compose etiqueta la imagen como <proyecto>-<servicio>.

container_name fija el nombre exacto y desactiva el prefijado de proyecto. Suena cómodo, y por eso mucha gente lo pone; tiene tres inconvenientes serios: impide docker compose up --scale (dos contenedores no pueden llamarse igual), impide levantar dos proyectos del mismo fichero en la misma máquina, y no lo necesitas, porque para hablar entre servicios se usa el nombre del servicio. Ponlo solo cuando algo externo —un script heredado, un agente de monitorización— exija un nombre concreto.

command y entrypoint admiten forma de cadena (command: node server.js, que pasa por el shell) y forma de lista (["node", "server.js"], ejecución directa). Prefiere la lista: es la forma exec y garantiza que tu proceso sea PID 1 y reciba SIGTERM, tal como viste en la lección 03-02. init: true inserta un init mínimo como PID 1 que reenvía señales y entierra zombis, útil cuando tu proceso lanza hijos y no los limpia. Y stop_grace_period acepta unidades (10s, 1m30s): para PostgreSQL, que necesita cerrar un checkpoint antes de morir, súbelo a 30 segundos.

ports publica un puerto del contenedor en el host. Forma corta, "[IP:]hostPort:contenedorPort[/protocolo]":

La forma larga es más verbosa pero explícita: - {target: 80, published: "8080", protocol: tcp, mode: host}, donde target es el puerto interno, published el del host y mode: ingress solo tiene sentido en Swarm.

expose no publica nada: documenta qué puertos escucha el contenedor. Es informativo, porque dentro de una red de usuario todos los puertos entre contenedores ya son accesibles.

networks conecta el servicio a las redes declaradas en el bloque de nivel superior. Sin esta clave, el servicio va a la red default del proyecto.

Un servicio puede estar en varias redes a la vez —es exactamente lo que hará aurora-api en la lección 04-04— y los aliases le dan nombres DNS extra, útiles para migrar sin tocar el código de los clientes.

La forma corta es la sintaxis origen:destino[:opciones] de docker run -v, y el origen decide el tipo de montaje:

La regla es la del módulo 3: si el origen empieza por . o / es un bind mount; si no, es un volumen con nombre que debe declararse en el bloque volumes: de nivel superior. La forma larga equivale a --mount:

Una diferencia importante: con la forma corta, si el origen de un bind no existe, Docker crea un directorio vacío; con la forma larga, falla con un error claro y te ahorra el clásico "monté un directorio donde esperaba un fichero".

read_only: true con un par de tmpfs es una de las medidas de endurecimiento más baratas que existen; el tema completo es la lección 05-03.

El healthcheck de Compose sustituye o complementa al HEALTHCHECK del Dockerfile:

Tres formas de escribir test:

start_period es la clave que casi nadie usa y casi todo el mundo necesita: PostgreSQL tarda unos segundos en aceptar conexiones la primera vez, y sin ese margen el contenedor se marca unhealthy antes de haber tenido oportunidad de arrancar.

depends_on en forma corta —depends_on: [aurora-db, aurora-cache]— solo garantiza el orden de arranque: Compose lanza el contenedor de PostgreSQL, espera a que el proceso esté en marcha y acto seguido lanza la API. Pero PostgreSQL tarda cinco segundos más en aceptar conexiones, así que la API arranca contra una base de datos que aún no responde. La forma larga resuelve exactamente eso:

La distinción entre "arrancado" y "listo" es la que separa un compose.yaml que funciona en tu máquina de uno que funciona siempre. Se desarrolla en la lección 04-04.

restart acepta los cuatro valores de docker run con el mismo significado: no (por defecto), always, on-failure[:n] y unless-stopped. Los límites, en cambio, viven bajo deploy, un bloque que originalmente era exclusivo de Swarm:

Aquí hay una confusión clásica que conviene aclarar: fuera de Swarm, docker compose sí aplica deploy.resources.limits. Lo que se ignora son replicas, placement, update_config y rollback_config, porque no tienen sentido en un solo host. Y recuerda de la lección 03-07 que limits es un techo duro —superar el de memoria significa OOM y código 137— mientras que reservations es una garantía blanda que influye en quién cede memoria bajo presión.

Admite también forma de lista (- "clave=valor"). Usa la notación de DNS inverso en las claves para no chocar con las de otras herramientas. Sirven para filtrar (docker ps --filter "label=..."), y muchas herramientas del ecosistema —proxies inversos automáticos, agentes de métricas— se configuran exclusivamente con etiquetas.

Todo volumen con nombre que uses en un servicio debe declararse arriba:

external: true es la protección definitiva para datos críticos: Compose asume que el volumen existe y ni siquiera down -v lo toca. Si no existe, el up falla en lugar de crear uno vacío en silencio.

Las redes siguen el mismo patrón:

internal: true es la clave que sostiene la segmentación de la lección 04-04: los contenedores de esa red no tienen ruta hacia el exterior, ni el exterior hacia ellos. Una base de datos ahí dentro no puede descargar nada de Internet aunque alguien logre ejecutar código en ella.

Cuando cuatro servicios comparten política de reinicio, logging y etiquetas, copiarlo cuatro veces es pedir que se desincronicen. YAML ofrece anclas (&), referencias (*) y fusión de mapas (<<:), y Compose añade las claves de extensión x-, que ignora al procesar el fichero:

Dos límites que conviene conocer: las anclas solo funcionan dentro del mismo fichero (no cruzan varios -f), y <<: fusiona al primer nivel, no en profundidad: si el ancla trae labels y el servicio también define labels, el del servicio sustituye al del ancla por completo, no los mezcla. Comprueba siempre el resultado con docker compose config.

Con todo lo anterior, este es el fichero completo. Las credenciales siguen escritas a mano —eso se arregla en la lección 04-05— y hay una sola red; la segmentación llega en la 04-04.

Cincuenta líneas de bash imperativo se han convertido en un fichero declarativo, versionable y legible, y de paso ha ganado cosas que el guion no tenía: sondas de salud en los cuatro servicios, rotación de logs y etiquetas coherentes. Valídalo y levántalo:

Los cuatro servicios healthy. Que hayan arrancado en el orden correcto es suerte, porque todavía no hay ni un depends_on; eso se arregla en la lección 04-04.

Poner container_name por costumbre. Rompe el escalado y la coexistencia de proyectos, y no aporta nada: para hablar entre servicios se usa el nombre del servicio.

Usar un volumen con nombre sin declararlo arriba. Compose falla con service refers to undefined volume. Los bind mounts no necesitan declaración; los volúmenes con nombre, sí.

Esperar que depends_on a secas espere a que el servicio esté listo. Solo espera a que arranque. Sin condition: service_healthy seguirás teniendo carreras de arranque.

Definir un healthcheck sin start_period. El servicio se marca unhealthy durante su arranque normal y arrastra a todo lo que dependa de él.

Escribir test: curl -f http://localhost/salud en una imagen Alpine. curl no viene instalado en las imágenes Alpine oficiales; wget sí. Un healthcheck que invoca un binario inexistente falla siempre, y el síntoma —unhealthy sin más pistas— despista mucho.

Consejo: empieza cada servicio nuevo con image, restart y healthcheck, y añade el resto solo cuando lo necesites. Un compose.yaml con claves que nadie sabe por qué están es tan malo como un guion de bash.

Ejercicio 1. Traduce a un servicio de Compose este comando, sin omitir ninguna opción, y explica dónde va cada una:

Ejercicio 2. El bloque x-comun del fichero de Aurora Libros incluye labels. Añade a aurora-db una etiqueta propia com.auroralibros.componente: "base-de-datos" y comprueba con docker compose config qué pasa con la etiqueta heredada. Explica el resultado y propón una solución.

Ejercicio 3. Declara un volumen aurora-copias que apunte a un volumen externo ya existente llamado respaldos-aurora, móntalo de solo lectura en aurora-db en /respaldos, y demuestra que docker compose down -v no lo borra.

Solución 1.

--name se omite deliberadamente (el nombre del servicio ya identifica al contenedor), --network pasa a networks, los límites bajan a deploy.resources.limits, --stop-timeout se convierte en stop_grace_period con unidades, y los argumentos posteriores a la imagen se convierten en command en forma de lista.

Solución 2. Añadiendo labels: { com.auroralibros.componente: "base-de-datos" } al servicio aurora-db:

La etiqueta com.auroralibros.proyecto ha desaparecido: <<: fusiona solo al primer nivel, y como el servicio define su propia clave labels, esta sustituye por completo al mapa heredado. La solución es una segunda ancla para el contenido de las etiquetas:

Ahora config muestra las dos. Regla general: cuando fusiones anclas, verifica siempre con docker compose config; lo que crees que hereda y lo que hereda de verdad no siempre coinciden.

Solución 3. Tras docker volume create respaldos-aurora, añade el montaje a aurora-db y la declaración externa:

down -v ha borrado aurora-libros_aurora-datos, que era del proyecto, pero respaldos-aurora sigue ahí: al ser external, Compose lo considera prestado y no lo gestiona. Es el mecanismo que debes usar para cualquier volumen cuya pérdida sea inaceptable.

Ya tienes la referencia completa de un servicio de Compose, y sobre todo el mapa mental que la sostiene: casi cada clave es una opción de docker run con otro nombre, y solo depends_on expresa algo que la CLI imperativa no sabía decir. Sabes cuándo usar image y cuándo build —y por qué a menudo las dos juntas—, por qué container_name sobra casi siempre, cómo se traducen command, entrypoint, user, init, stop_signal y stop_grace_period, y las dos formas —corta y larga— de ports y volumes, con el matiz de que la larga falla en lugar de crear un directorio vacío cuando el bind no existe.

Dominas el bloque healthcheck completo, incluido el start_period que evita marcar como enfermo a un servicio que solo está arrancando, y conoces la diferencia entre las tres condiciones de depends_on: service_started, service_healthy y service_completed_successfully. Sabes que restart tiene los mismos cuatro valores de siempre y que deploy.resources.limits sí se aplica fuera de Swarm. Declaras volúmenes y redes en los bloques de nivel superior, blindas los datos críticos con external: true, aíslas con internal: true, y evitas la repetición con anclas x-/&/*/<<: sabiendo que la fusión es superficial. Y tienes el compose.yaml con los cuatro servicios de Aurora Libros declarados.

En la lección siguiente, Comandos de Docker Compose, pasarás del fichero a la CLI: el ciclo de vida completo (up y su reconciliación, down y el peligro de -v, start, stop, restart, pause), la observación (ps, logs, top, stats, events), la diferencia esencial entre exec y run, la construcción y publicación, el escalado local con --scale y por qué choca con los puertos fijos, y la selección de ficheros y proyecto con -f, -p y COMPOSE_FILE.