Hasta ahora has aprendido a construir imágenes y a lanzar contenedores uno a uno con docker run. Eso funciona bien cuando trabajas con un único contenedor, pero las aplicaciones reales casi nunca son tan simples: una web suele necesitar, además, una base de datos, quizá una caché y otros servicios auxiliares. Coordinar todo eso a mano, con varios comandos docker run larguísimos, se vuelve tedioso y propenso a errores. En esta lección descubrirás Docker Compose, la herramienta que permite definir y ejecutar aplicaciones multi-contenedor de forma declarativa, usando un único archivo de texto. Es una de las herramientas más útiles del ecosistema Docker y la base del Módulo 4.

• Entender qué problema resuelve Docker Compose frente a múltiples docker run.
• Conocer qué es el archivo docker-compose.yml y cómo se estructura.
• Distinguir entre docker compose (v2) y docker-compose (v1) y saber cuál usar.
• Comprender la estructura básica de un archivo Compose.
• Escribir y ejecutar tu primer ejemplo mínimo con Compose.

Imagina que quieres levantar una aplicación web sencilla con un servidor Nginx y una base de datos PostgreSQL, ambos conectados en la misma red y con datos persistentes. Sin Compose, tendrías que ejecutar algo parecido a esto:

Analiza lo que ocurre aquí:

• Son cuatro comandos distintos que debes recordar y ejecutar en el orden correcto.
• Cada docker run lleva una larga lista de opciones (--network, -e, -v, -p) fáciles de teclear mal.
• Si un compañero quiere replicar tu entorno, tienes que pasarle todos estos comandos y confiar en que los ejecute bien.
• Para apagar todo, tendrías que parar y borrar cada contenedor, la red y, si quieres, el volumen, uno por uno.

Este enfoque es imperativo: describes paso a paso cómo construir el entorno. No escala bien y es difícil de versionar y compartir.

Docker Compose te permite describir toda esa aplicación de forma declarativa en un único archivo llamado docker-compose.yml. En lugar de explicar cómo montar el entorno, declaras cuál es el estado deseado y dejas que Compose se encargue del resto.

Las ventajas frente a múltiples docker run son claras:

Con Compose, todo el ejemplo anterior se reduce a un archivo y a un solo comando para arrancarlo (docker compose up) y otro para apagarlo (docker compose down).

El docker-compose.yml es un archivo de texto escrito en formato YAML que describe los componentes de tu aplicación. YAML es un formato legible para humanos basado en pares clave-valor y en la indentación (los espacios al principio de cada línea) para marcar la jerarquía.

Conceptos esenciales que describe el archivo:

• Servicios (services): los contenedores que forman tu aplicación (la web, la base de datos, etc.).
• Redes (networks): cómo se comunican esos servicios entre sí.
• Volúmenes (volumes): dónde se guardan los datos que deben persistir.

Importante sobre YAML: la indentación debe hacerse siempre con espacios, nunca con tabuladores. Lo habitual son 2 espacios por nivel. Un error de indentación es la causa más común de fallos en un archivo Compose.

Aquí hay un detalle que suele confundir a quien empieza. Existen dos formas de invocar Compose:

• v1 (docker-compose): era una herramienta separada que se instalaba aparte. Hoy está obsoleta y ya no recibe nuevas funcionalidades.
• v2 (docker compose): es la versión actual, integrada directamente dentro de la CLI de Docker como un subcomando. Fíjate en que se escribe docker compose (con un espacio, sin guion).

En este curso usaremos siempre la sintaxis moderna docker compose (v2). Si encuentras documentación antigua con docker-compose, ten en cuenta que los comandos son casi idénticos.

Si tienes una versión reciente de Docker Desktop (Windows o macOS) o de Docker Engine (Linux), Compose v2 ya viene incluido y no tienes que instalar nada. Puedes comprobarlo así:

• Si todo está bien, verás algo como Docker Compose version v2.x.x.
• Si en cambio obtienes un error de "comando no encontrado", necesitas actualizar Docker o instalar el plugin de Compose siguiendo la documentación oficial para tu sistema operativo.

Un archivo docker-compose.yml típico tiene esta estructura general:

Desglose de cada bloque de nivel superior:

• services: es el bloque obligatorio y más importante. Dentro de él, cada clave es el nombre de un servicio (por ejemplo web o db), y bajo ese nombre se configura el contenedor correspondiente.
• networks: opcional. Permite definir redes propias para conectar servicios. Si no la incluyes, Compose crea automáticamente una red por defecto donde todos los servicios pueden comunicarse.
• volumes: opcional. Declara volúmenes con nombre para que los datos persistan entre reinicios.

Nota: en versiones antiguas el archivo empezaba con una línea version: "3.8". En Compose v2 esa clave ya no es necesaria y se considera obsoleta, por lo que en este curso la omitiremos.

Vamos a crear el "Hola Mundo" de Docker Compose: un único servicio que ejecuta un servidor web Nginx. Es lo más sencillo posible para entender el flujo.

Crea una carpeta vacía para el proyecto y, dentro, un archivo llamado exactamente docker-compose.yml con este contenido:

Explicación línea a línea, pensada para principiantes:

• services:: abre el bloque que contiene todos los servicios de la aplicación.
• web:: el nombre que le damos a nuestro servicio. Podríamos llamarlo como quisiéramos (servidor, front, etc.); aquí elegimos web.
• image: nginx:latest: indica que este servicio se basa en la imagen oficial nginx, en su etiqueta latest. Compose la descargará de Docker Hub si no la tienes ya.
• ports:: abre la lista de puertos que se publican hacia el host.
• - "8080:80": mapea el puerto 8080 del host (izquierda) al puerto 80 del contenedor (derecha), que es donde Nginx escucha por defecto. Así podrás acceder desde tu navegador en http://localhost:8080.

Desde la misma carpeta donde está el docker-compose.yml, ejecuta:

• Compose lee el archivo, descarga la imagen si hace falta, crea una red por defecto y arranca el contenedor.
• Verás los registros (logs) de Nginx en tiempo real en tu terminal.
• Abre http://localhost:8080 en el navegador: deberías ver la página de bienvenida de Nginx.

Para arrancarlo en segundo plano (detached), sin quedar atado a la terminal, añade la opción -d:

Cuando termines, detén y elimina todo lo que creó Compose con:

• Este comando para y elimina los contenedores y la red por defecto que se crearon.
• Por defecto no borra los volúmenes con nombre, de modo que tus datos persistentes se conservan.

Con esto has completado el ciclo básico: definir, arrancar y apagar una aplicación con un único archivo y un par de comandos.

• Usar tabuladores en lugar de espacios: YAML no admite tabuladores para la indentación. Configura tu editor para que inserte espacios y usa 2 por nivel.
• Indentación inconsistente: todos los elementos de un mismo nivel deben tener exactamente la misma sangría. Un espacio de más o de menos rompe el archivo.
• Confundir docker compose con docker-compose: recuerda que la forma moderna lleva un espacio y no un guion. Si un comando no funciona, comprueba cuál estás usando.
• Nombrar mal el archivo: debe llamarse docker-compose.yml (o compose.yml) para que Compose lo detecte automáticamente. Si usas otro nombre, tendrás que indicarlo con -f.
• Ejecutar el comando desde otra carpeta: Compose busca el archivo en el directorio actual. Asegúrate de estar en la carpeta correcta antes de lanzar docker compose up.
• Consejo: empieza siempre con un ejemplo mínimo que funcione y añade servicios poco a poco. Es más fácil depurar un archivo que crece de forma controlada.

Comprueba qué versión de Docker Compose tienes instalada y averigua si estás usando la v1 o la v2.

Crea un docker-compose.yml mínimo que levante un servidor Nginx accesible en el puerto 9090 del host.

Explica con tus palabras qué hacen los comandos docker compose up -d y docker compose down, y en qué se diferencian.

Solución al Ejercicio 1

Si el comando funciona y devuelve algo como Docker Compose version v2.x.x, estás usando la v2. La sintaxis con espacio (docker compose) corresponde siempre a la versión moderna. La v1 se invocaría como docker-compose version (con guion) y hoy está obsoleta.

Solución al Ejercicio 2

Archivo docker-compose.yml:

La clave está en el mapeo "9090:80": el puerto 9090 es el del host (lo que escribes en el navegador) y el 80 es el interno del contenedor, donde Nginx escucha. Arráncalo con docker compose up -d y visita http://localhost:9090.

Solución al Ejercicio 3

• docker compose up -d: arranca todos los servicios definidos en el archivo en segundo plano (modo detached), creando contenedores, redes y volúmenes según haga falta. La opción -d libera la terminal para que sigas trabajando.
• docker compose down: detiene y elimina los contenedores y la red por defecto creados por Compose. Es la operación inversa a up.

La diferencia principal es que up pone en marcha la aplicación y down la apaga y limpia. Además, up -d no bloquea la terminal, mientras que up (sin -d) muestra los logs y queda en primer plano.

En esta lección has entendido qué problema resuelve Docker Compose frente a la coordinación manual de múltiples docker run: pasa de un enfoque imperativo y propenso a errores a uno declarativo, reproducible y fácil de versionar. Has conocido el archivo docker-compose.yml, su estructura básica (services, networks, volumes), la diferencia entre la v1 (docker-compose, obsoleta) y la v2 (docker compose, actual), y has lanzado tu primer ejemplo mínimo con Nginx.

En la siguiente lección, Definiendo Servicios en Docker Compose, profundizaremos en el bloque services y en sus claves más importantes (image, build, ports, volumes, depends_on, networks, restart), para que aprendas a describir contenedores con todo el detalle que necesitan tus aplicaciones reales.