Introducción a Docker Compose

CLI docker compose

La interfaz de línea de comandos de Docker Compose es la herramienta principal para gestionar aplicaciones multi-contenedor. A diferencia de los comandos docker tradicionales que operan sobre contenedores individuales, la CLI de Compose v2 trabaja con el concepto de servicios definidos en un archivo de configuración, permitiendo orquestar múltiples contenedores como una unidad cohesiva.

Docker Compose v2 se integra directamente con el comando docker utilizando la sintaxis docker compose (con espacio), reemplazando la versión standalone docker-compose (con guión). Esta integración nativa ofrece mejor rendimiento y consistencia con el ecosistema Docker moderno.

El archivo compose.yml

Para trabajar con Docker Compose, necesitamos un nuevo archivo, el archivo compose.yaml. Este archivo es el que contendrá toda la estructura de contenedores que hay que crear y gestionar con docker compose. 

Veremos su sintaxis en la siguiente lección, de momento nos enfocaremos en entender los comandos básicos de docker compose para ejecutar y parar contenedores de un compose.yaml.

También cabe destacar que este archivo puede llamarse de diferentes maneras:

• compose.yaml (PREFERIDO y recomendado)
• compose.yml (también preferido)
• docker-compose.yaml (compatibilidad hacia atrás)
• docker-compose.yml (compatibilidad hacia atrás)

Incluso también es posible ponerle un nombre personalizado, por ejemplo: backend-apps.yml

Comandos esenciales del ciclo de vida

Los comandos fundamentales para gestionar aplicaciones Compose siguen un patrón lógico que refleja las operaciones típicas de desarrollo y despliegue.

Crear y arrancar servicios:

docker compose up

Este comando lee el archivo compose.yaml del directorio actual, crea las redes y volúmenes necesarios, y ejecuta todos los servicios definidos. La salida muestra los logs en tiempo real de todos los contenedores.

Ejecutar en segundo plano:

docker compose up -d

El flag -d (detached) ejecuta los servicios en modo daemon, liberando la terminal para otras tareas. Es la forma más común de ejecutar aplicaciones en desarrollo y producción.

Si usas un nombre personalizado para tu archivo docker compose usa el parámetro -f con la ruta al archivo:

# si estás en el mismo directorio que el archivo yml:
docker compose -f mi-archivo-custom.yml up -d

# si estás en directorios más arriba que el archivo yml:
docker compose -f src/main/docker/archivo-custom-yml up -d

Forzar recreación de imágenes:

docker compose up --build

El parámetro --build instruye a Compose para reconstruir las imágenes antes del arranque, útil cuando se han modificado Dockerfiles o código fuente.

Gestión del estado de servicios

Una vez que los servicios están en ejecución, Compose proporciona comandos específicos para controlar su estado sin afectar la configuración subyacente.

Detener servicios:

docker compose stop

Detiene todos los contenedores de forma elegante, enviando señales SIGTERM y esperando su finalización. Los contenedores permanecen creados pero inactivos.

Arrancar servicios detenidos:

docker compose start

Reinicia contenedores previamente detenidos sin recrearlos. Mantiene la configuración, redes y volúmenes existentes.

Reiniciar servicios:

docker compose restart

Combina stop y start en una sola operación, útil para aplicar cambios de configuración que requieren reinicio del proceso.

Diferencias clave entre up y start

La distinción entre up y start es fundamental para comprender el modelo de gestión de Compose:

• docker compose up: Crea recursos (redes, volúmenes, contenedores) si no existen, luego los ejecuta. Puede recrear contenedores si detecta cambios en la configuración.
• docker compose start: Solo arranca contenedores existentes sin modificar la infraestructura. Falla si los contenedores no fueron creados previamente.

En el flujo típico de desarrollo, up se utiliza para inicialización y cambios de configuración, mientras que start sirve para reanudar servicios tras una pausa temporal.

Observabilidad y monitorización

Compose incluye herramientas integradas para inspeccionar el estado y comportamiento de los servicios en ejecución.

Listar servicios activos:

docker compose ps

Muestra una tabla con el estado actual de todos los servicios: nombres, comandos, puertos expuestos y estado de salud.

Seguir logs en tiempo real:

docker compose logs -f

Agrega logs de todos los servicios con timestamps y prefijos de identificación. El flag -f (follow) mantiene la conexión activa para monitorización continua.

Logs de servicios específicos:

docker compose logs web database

Filtra la salida a servicios particulares, útil para debugging dirigido en aplicaciones complejas.

Limpieza y finalización

El comando más importante para limpiar recursos es down, que desmonta completamente la aplicación:

docker compose down

Detiene y elimina contenedores, redes creadas por Compose, pero preserva volúmenes con nombre para mantener la persistencia de datos. Este comportamiento conservador protege información valiosa durante el desarrollo.

Para una limpieza completa incluyendo volúmenes:

docker compose down -v

El flag -v elimina también los volúmenes asociados, útil para reset completo del entorno de desarrollo.

La CLI de Docker Compose transforma la gestión de aplicaciones multi-contenedor en un flujo intuitivo y reproducible, estableciendo las bases para patrones avanzados de desarrollo y despliegue que exploraremos en las siguientes lecciones.

Arranque y ciclo de vida

El ciclo de vida de una aplicación Docker Compose sigue un patrón predecible de estados que facilita tanto el desarrollo iterativo como la gestión en producción. Comprender estos estados y las transiciones entre ellos es fundamental para optimizar el flujo de trabajo con aplicaciones multi-contenedor.

Estados del ciclo de vida

Una aplicación Compose puede encontrarse en varios estados distintos, cada uno con características específicas que determinan las operaciones disponibles:

• Inexistente: No hay recursos creados. Estado inicial antes del primer up o después de down
• Creado pero detenido: Contenedores, redes y volúmenes existen pero los servicios no están ejecutándose
• En ejecución: Todos los servicios están activos y funcionales
• Parcialmente activo: Algunos servicios funcionan mientras otros están detenidos o fallando
• En transición: Estado temporal durante operaciones como arranque, parada o reinicio

Flujo de arranque completo

El proceso de arranque con docker compose up ejecuta una secuencia coordinada de operaciones que establece el entorno completo de la aplicación:

docker compose up -d

Durante esta operación, Compose realiza las siguientes verificaciones y acciones:

• Valida la sintaxis del archivo de configuración
• Crea redes personalizadas si no existen
• Descarga imágenes faltantes desde registries
• Crea volúmenes con nombre declarados
• Instancia contenedores respetando dependencias
• Configura conectividad de red entre servicios
• Expone puertos según la configuración

Este proceso es idempotente, lo que significa que ejecutar up múltiples veces produce el mismo resultado sin efectos secundarios negativos.

Transiciones de estado controladas

Las transiciones entre estados permiten gestionar la aplicación sin perder configuración ni datos persistentes:

# Pausar temporalmente sin destruir recursos
docker compose stop

# Reanudar desde estado detenido
docker compose start

# Ciclo completo de reinicio
docker compose restart

La diferencia fundamental radica en la preservación del contexto: stop y start mantienen la configuración de contenedores, mientras que down y up pueden recrear recursos según cambios detectados.

Gestión de dependencias durante arranque

Compose respeta automáticamente las dependencias implícitas derivadas de enlaces de red y volúmenes compartidos. Durante el arranque, los servicios se inician en orden lógico:

# Los servicios base (bases de datos, caches) arrancan primero
# Seguidos por servicios de aplicación que los consumen
# Finalmente servicios de frontend o proxy

Sin embargo, arranque no implica disponibilidad. Un contenedor puede estar ejecutándose pero el servicio interno aún no estar listo para aceptar conexiones. Este concepto será crucial cuando veamos health checks en lecciones posteriores.

Estrategias de actualización en caliente

Durante el desarrollo, es común necesitar aplicar cambios sin reiniciar toda la aplicación:

# Reconstruir servicios específicos
docker compose up --build web

# Recrear solo servicios modificados
docker compose up --force-recreate api

Compose detecta automáticamente cambios en configuración y determina qué servicios requieren recreación versus simple reinicio. Esta inteligencia minimiza interrupciones y acelera iteraciones de desarrollo.

Finalización ordenada

El comando down ejecuta una secuencia de finalización que preserva la integridad de datos:

docker compose down

La secuencia incluye:

• Envío de señales SIGTERM a procesos principales
• Espera de finalización elegante (timeout configurable)
• Forzado con SIGKILL si es necesario
• Eliminación de contenedores y redes temporales
• Preservación de volúmenes con nombre

Monitorización del estado del ciclo

La visibilidad del estado es esencial para operaciones efectivas:

# Estado actual de servicios
docker compose ps --format table

# Eventos del ciclo de vida en tiempo real
docker compose logs --follow --timestamps

Estos comandos proporcionan información contextual sobre el estado actual y histórico de transiciones, facilitando debugging y monitorización operacional.

Recuperación ante fallos

Compose incluye mecanismos de recuperación automática para servicios que fallan durante el ciclo de vida:

• Reintentos automáticos según políticas de restart
• Detección de servicios no saludables
• Logs persistentes para análisis post-fallo
• Mantenimiento de estado de red y almacenamiento

La comprensión del ciclo de vida permite anticipar comportamientos y diseñar estrategias robustas de despliegue y mantenimiento, estableciendo las bases sólidas para configuraciones más avanzadas en las próximas lecciones del módulo.