Cómo utilizar Docker Compose

Docker Compose, ahora en su versión V5, es una de las herramientas más adoptadas en el ecosistema de contenedorización y, a estas alturas, una competencia básica para cualquiera que gestione infraestructura IT moderna. Lanzado originalmente como plugin de la CLI de Docker en 2021 bajo la etiqueta V2, fue renombrado a V5 en 2025 para evitar confusión con las versiones legacy del formato Compose file (2.x y 3.x), pero funcionalmente no cambió nada. 

Para sysadmins y Managed Service Providers (MSPs), dominarlo significa orquestar entornos multi-contenedor de forma declarativa, reproducible y versionable – reduciendo errores manuales y acortando los tiempos de intervención en los sitios de los clientes. 

En esta actualización de 2026 veremos qué es Docker Compose, cómo instalar la versión actual y qué comandos todo profesional IT debería tener en su toolkit diario. 

¿Qué es Docker Compose?

Docker Compose es una herramienta oficial de Docker que permite definir y ejecutar aplicaciones multi-contenedor basándose en los contenedores Docker estándar a partir de un único archivo de configuración YAML. En una arquitectura de microservicios – donde cada componente (autenticación, base de datos, frontend, reverse proxy, cola de mensajes, etc.) se ejecuta en su propio contenedor — Compose centraliza la definición de servicios, redes, volúmenes, secrets y configs en un único archivo declarativo, eliminando la necesidad de gestionar decenas de comandos docker run individuales.

Para un sysadmin o un MSP esto se traduce en tres ventajas operativas concretas:

• Reproducibilidad: el mismo archivo compose.yaml produce entornos idénticos en portátiles de desarrolladores, servidores de staging y sitios de producción de clientes.
• Versionabilidad: la configuración de todo el stack vive en Git junto al código o la documentación operativa, eliminando la desviación entre entornos.
• Velocidad de entrega y soporte: iniciar, detener o recrear una aplicación completa requiere un solo comando, lo que simplifica el despliegue, el mantenimiento y la resolución de problemas en flotas heterogéneas de clientes. 

Instalación de Docker Compose

Docker Compose V1, el binario Python original invocado como docker-compose (con guion), fue deprecado en 2022. El soporte, incluidos los parches de seguridad, finalizó a mediados de 2023, y el binario standalone fue eliminado permanentemente de Docker Desktop y de las imágenes de CI runners (como GitHub Actions) en abril de 2025. Si aún ves docker-compose con guion en scripts o pipelines, ya están rotos o a punto de estarlo. El estándar actual es Docker Compose V5 (aún comúnmente referido como V2 en muchos artículos y tutoriales), reescrito en Go y distribuido como plugin de la CLI de Docker, que se invoca como docker compose (sin guion, con un espacio). 

Docker Desktop (Windows y macOS)

En Windows y macOS no se requiere una instalación separada: Docker Compose viene incluido con Docker Desktop y está disponible de inmediato una vez que el cliente está instalado. Las instrucciones oficiales actualizadas están disponibles en la documentación de Docker.

Linux (Ubuntu, Debian y derivadas)

En sistemas Linux, el enfoque recomendado es instalar el paquete docker-compose-plugin desde el repositorio oficial de Docker (consulta la lista completa de distribuciones soportadas), de modo que las actualizaciones sigan el ciclo normal de parches del sistema operativo:

sudo apt-get update
sudo apt-get install docker-compose-plugin

En distribuciones basadas en RPM (RHEL, CentOS Stream, Fedora, Rocky Linux) el comando equivalente es:

sudo dnf install docker-compose-plugin

Una vez instalado, es buena práctica verificar inmediatamente la versión y la disponibilidad:

docker compose version

La salida debería mostrar una release v5.x (por ejemplo, v5.1.4 o posterior). Si ves una versión v2.x, el paquete de tu distribución podría estar desactualizado: verifica que estés descargando desde el repositorio oficial de Docker. 

La instalación del binario standalone legacy (docker-compose) ya no está soportada: el binario V1 ha sido eliminado de todos los canales de distribución oficiales desde abril de 2025. Solo debería considerarse en escenarios excepcionales de retrocompatibilidad en sistemas legacy que no pueden actualizarse, y aun así no recibirá más actualizaciones ni parches de seguridad. 

El archivo compose.yaml

El archivo de configuración es el corazón de Docker Compose: contiene la definición declarativa de todos los servicios, redes, volúmenes, secrets y configs que componen la aplicación. Dicho de otro modo, un Dockerfile describe cómo construir una única imagen de contenedor, mientras que el archivo Compose describe cómo ejecutar una aplicación multi-contenedor completa (servicios, networking, almacenamiento y todo lo demás). 

Una nota sobre la nomenclatura que a menudo genera confusión en proyectos de diferentes épocas: el nombre canónico recomendado por la Compose Specification es ahora compose.yaml, pero Compose sigue reconociendo automáticamente docker-compose.yml, docker-compose.yaml y compose.yml para garantizar la compatibilidad con archivos existentes. Para proyectos nuevos tiene sentido adoptar el nombre canónico.

Otra fuente frecuente de confusión: la clave top-level version (por ej. version: «3.8») que aparece en muchos tutoriales antiguos y proyectos existentes es ahora obsoleta e ignorada por Compose. Los archivos Compose modernos deberían comenzar directamente con services (no se necesita declaración de versión). Si la encuentras en stacks legacy, puede eliminarse sin problemas; mantenerla activará avisos de deprecación en las versiones actuales de Docker Desktop. 

A continuación, un ejemplo mínimo que muestra la disposición típica de un stack web de tres niveles (reverse proxy, aplicación, base de datos) con health checks y dependencias condicionales – un patrón muy común en contextos MSP:

services:
  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - db_data:/var/lib/postgresql/data
    secrets:
      - db_password
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

  app:
    image: registry.example.com/myapp:1.4.0
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    networks:
      - backend

  proxy:
    image: nginx:1.30-alpine
    restart: unless-stopped
    ports:
      - "443:443"
    depends_on:
      - app
    networks:
      - backend

volumes:
  db_data:

networks:
  backend:

secrets:
  db_password:
    file: ./secrets/db_password.txt

Para los escenarios más complejos típicos de entornos enterprise y MSP, la especificación Compose incluye una serie de funcionalidades que conviene conocer desde el principio:

• Profiles: habilitan servicios opcionales (por ej. monitorización, depuración, jobs batch) solo en entornos seleccionados, evitando la necesidad de mantener archivos separados para cada escenario.
• Override files: además de compose.yaml, un segundo archivo compose.override.yaml se fusiona automáticamente, permitiendo mantener separada la configuración base de los overrides locales o de staging.
• Directiva include: permite componer un proyecto a partir de múltiples archivos Compose independientes (include: – path: ./monitoring/compose.yaml), facilitando el mantenimiento de bloques reutilizables entre los stacks de clientes.
• Configs: los datos de configuración no sensibles (por ejemplo, un archivo de virtual host de Nginx o un archivo de configuración de la aplicación) pueden declararse bajo la clave top-level configs y montarse en los contenedores, manteniendo la configuración separada de las imágenes y las variables de entorno.
• Secrets: los datos sensibles como contraseñas y claves API se montan como archivos en /run/secrets/<name> dentro del contenedor, evitando su exposición a través de variables de entorno o su inclusión en las imágenes.
• Health checks con la condición service_healthy: permiten que un servicio se inicie solo después de que sus dependencias estén realmente operativas, no simplemente en ejecución – un detalle que marca la diferencia en producción. 

Nota de seguridad: en 2025 se identificó una vulnerabilidad de alta gravedad (CVE-2025-62725, CVSS 8.9) en la forma en que Docker Compose gestiona los artefactos OCI remotos. El problema afecta a las versiones desde la 2.34.0 hasta (sin incluir) la 2.40.2, y puede provocar la sobrescritura de archivos arbitrarios en el sistema incluso al ejecutar comandos aparentemente de solo lectura, como docker compose ps o docker compose config. Está corregido a partir de la versión 2.40.2. Si gestionas stacks de Compose que resuelven archivos remotos (por ejemplo, mediante la directiva include o registros OCI), asegúrate de utilizar una versión actualizada de Docker Compose V5 y evita resolver artefactos Compose procedentes de fuentes no verificadas.

Comandos de Docker Compose

La referencia completa de comandos está disponible en la documentación de la CLI de Docker. Todos los comandos deben ejecutarse desde el directorio que contiene el archivo compose.yaml. Los que se enumeran a continuación forman el flujo operativo diario para cualquiera que gestione infraestructura contenedorizada.

docker compose up Construye las imágenes (si es necesario), crea redes y volúmenes e inicia los contenedores definidos como servicios. Añadiendo el flag -d (docker compose up -d) se inicia el stack en modo detached, que es el enfoque estándar en servidores de producción. Si los contenedores ya están en ejecución y la configuración ha cambiado, Compose recrea automáticamente solo los afectados por los cambios, dejando el resto intacto.

docker compose start Inicia contenedores que ya existen, sin reconstruir imágenes ni recrear recursos. Útil después de una parada planificada o un reinicio del nodo. 

docker compose stop Detiene de forma ordenada los servicios en ejecución, manteniendo contenedores, redes, volúmenes e imágenes en su lugar. Es el comando preferido cuando se desea suspender temporalmente un stack preservando su estado. 

docker compose down Detiene los servicios y elimina los contenedores y las redes creados por Compose. Por defecto, los volúmenes con nombre y las imágenes se mantienen en el sistema: esto evita la pérdida accidental de datos persistentes, una protección valiosa en entornos de producción. 

• docker compose down --volumes también elimina los volúmenes con nombre asociados al stack (operación destructiva: úsala solo cuando genuinamente quieras empezar desde cero). 

• docker compose down --rmi all elimina todas las imágenes utilizadas por los servicios. 

Algunos comandos adicionales son esenciales para las operaciones diarias:

docker compose ps Lista el estado de los contenedores pertenecientes al stack actual, incluyendo los resultados de los health checks. Es el primer comando a invocar para una verificación rápida del estado.

docker compose logs -f Muestra en streaming los logs agregados de todos los servicios en tiempo real (o de un servicio individual, por nombre). Es el punto de partida para cualquier actividad de resolución de problemas.

docker compose pull Actualiza localmente las imágenes declaradas, en preparación para un posterior up para desplegar nuevas versiones en producción de forma controlada.

docker compose config Renderiza la configuración completamente resuelta, útil para validar la sintaxis y verificar la fusión de los archivos de override antes de aplicarlos.

docker compose exec Abre una sesión interactiva o ejecuta un comando puntual dentro de un contenedor en ejecución sin iniciar uno nuevo. Por ejemplo, docker compose exec db psql -U postgres te lleva directamente a una shell de PostgreSQL para un diagnóstico rápido. Es normalmente la vía más rápida para la resolución de problemas de un servicio que no funciona correctamente.

docker compose ls Lista todos los proyectos Compose activos en el host, independientemente del directorio en el que te encuentres. Para MSPs que gestionan múltiples stacks en un único servidor, proporciona una vista inmediata de qué está en ejecución y dónde.

docker compose restart Reinicia uno o más servicios sin destruir ni recrear los contenedores. Útil para aplicar cambios de configuración que solo requieren un reinicio del proceso (por ejemplo, después de actualizar un config de Nginx montado como volumen). 

Del setup a producción

Dominar Docker Compose no requiere un conocimiento profundo de Docker, pero para sysadmins y MSPs es una inversión de alto rendimiento: estandariza los despliegues, acorta el tiempo de onboarding para nuevos clientes, simplifica la documentación operativa de los stacks y reduce el margen de error en tareas repetitivas. El mismo compose.yaml puede ser consumido por runtimes alternativos como Podman Compose, ofreciendo flexibilidad en caso de necesitar alejarse de Docker Engine. 

El consejo práctico es partir de un escenario real – por ejemplo una aplicación web con una base de datos y un reverse proxy – escribir tu propio compose.yaml, hacer commit en Git e iterar añadiendo progresivamente health checks, secrets y profiles. En pocos ciclos se llega a una línea base reutilizable que puedes desplegar en todos tus clientes, con una ganancia neta clara en fiabilidad y tiempos de respuesta.

Si gestionas infraestructura contenedorizada para múltiples clientes, combinar Docker Compose con una sólida estrategia de backup y un flujo de trabajo fiable de soporte remoto marca la diferencia entre una operativa fluida y una estresante. Uranium Backup admite la copia de seguridad de máquinas virtuales, bases de datos y los datos que impulsan tus aplicaciones en contenedores.