Cómo utilizar Docker Compose

Docker Compose, ahora en su versión V5, es una de las herramientas más extendidas del ecosistema de la contenerización y, a estas alturas, una habilidad básica para cualquiera que gestione infraestructura IT moderna. Anunciado como Compose V2 en 2020 y disponible con carácter general (GA) desde abril de 2022 como plugin de la CLI de Docker, en 2025 fue rebautizado como V5 para evitar confusiones con las versiones heredadas del formato de archivos Compose (2.x y 3.x), pero funcionalmente no cambió nada.

Para los sysadmins y los Managed Service Providers (MSP), dominarlo significa orquestar entornos multicontenedor de forma declarativa, reproducible y versionable, reduciendo los errores manuales y acortando los tiempos de intervención en las instalaciones de los clientes.

En esta actualización de 2026 vemos qué es Docker Compose, cómo instalar la versión actual y qué comandos debería tener cualquier profesional de IT en su caja de herramientas diaria.

¿Qué es Docker Compose?

Docker Compose es una herramienta oficial de Docker que te permite definir y ejecutar aplicaciones multicontenedor basadas en 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 los portátiles de los desarrolladores, en los servidores de staging y en los sitios de producción de los clientes.
• Versionabilidad: la configuración de todo el stack vive en Git junto al código o a la documentación operativa, eliminando el drift entre entornos.
• Rapidez de entrega y de soporte: iniciar, detener o recrear una aplicación completa requiere un solo comando, lo que simplifica el despliegue, el mantenimiento y el troubleshooting en parques de clientes heterogéneos.

Instalar Docker Compose

Docker Compose V1, el binario original en Python que se invoca como docker-compose (con guion), llegó al final de su vida útil (end of life) en junio de 2023. Fue eliminado de Docker Desktop a partir de la versión 4.23.0 y de las imágenes de runner de GitHub Actions en julio de 2024. Si todavía ves docker-compose con guion en scripts o pipelines, comprueba a qué se resuelve: en Docker Desktop ahora apunta al binario de Compose V2, pero en los runners alojados por GitHub el antiguo comando V1 falla, y cualquier instalación V1 que quede no tiene soporte ni recibe parches. El estándar actual es Docker Compose V5 (que en muchos artículos y tutoriales se sigue llamando V2), 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 hace falta ninguna instalación aparte: Docker Compose viene incluido con Docker Desktop y está disponible en cuanto instalas el cliente. Las instrucciones oficiales actualizadas están en la documentación de Docker.

Linux (Ubuntu, Debian y derivadas)

En los sistemas Linux, el enfoque recomendado es instalar el paquete docker-compose-plugin desde el repositorio oficial de Docker (consulta la lista completa de distribuciones compatibles), de modo que las actualizaciones sigan el ciclo normal de parches del sistema operativo. Primero hay que configurar el repositorio: sigue las instrucciones de configuración del repositorio de tu distribución y después ejecuta:

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

En las distribuciones basadas en RPM (RHEL y compatibles, CentOS Stream, Fedora) el comando equivalente es:

sudo dnf install docker-compose-plugin

Una vez instalado, conviene verificar enseguida la versión y la disponibilidad:

docker compose version

La salida debería mostrar una versión v5.x (por ejemplo, v5.6.0). Docker sigue dando soporte también a la línea v2.x, pero si ves una versión más antigua, comprueba que estás descargando los paquetes del repositorio oficial de Docker para recibir las últimas actualizaciones.

Instalar Compose V1 (el docker-compose en Python) no está soportado: llegó al final de su vida útil en junio de 2023 y no recibe parches de seguridad. Docker todavía documenta una instalación standalone del binario V2, pero está etiquetada como legacy y el plugin sigue siendo el método recomendado.

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 multicontenedor completa (servicios, red, almacenamiento y todo lo demás).

Una nota sobre nombres que suele generar confusión en proyectos de distintas épocas: el nombre canónico que recomienda 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 los archivos existentes. En los proyectos nuevos tiene sentido adoptar el nombre canónico.

Otra fuente frecuente de confusión: la clave de nivel superior version (por ejemplo version: «3.8»), que aparece en muchos tutoriales antiguos y proyectos existentes, está ahora obsoleta y es ignorada por Compose. Los archivos Compose modernos deberían empezar directamente con services (no hace falta declarar ninguna versión). Si te la encuentras en stacks heredados, puedes eliminarla sin problema: Compose la ignora y muestra un aviso indicando que el atributo está obsoleto.

A continuación, un ejemplo mínimo que muestra la estructura típica de un stack web de tres capas (reverse proxy, aplicación, base de datos) con health checks y dependencias condicionales – un patrón muy habitual 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 los entornos empresariales y MSP, la especificación de Compose incluye varias funcionalidades que conviene conocer desde el principio:

• Profiles: activan servicios opcionales (por ejemplo monitorización, depuración, tareas por lotes) solo en determinados entornos, evitando mantener archivos separados para cada escenario.
• Override files: además de compose.yaml, un segundo archivo compose.override.yaml se fusiona automáticamente, lo que te permite mantener separada la configuración base de los overrides locales o de staging.
• Directiva include: permite componer un proyecto a partir de varios archivos Compose independientes (include: – path: ./monitoring/compose.yaml), facilitando el mantenimiento de bloques reutilizables entre los stacks de los clientes.
• Configs: los datos de configuración no sensibles (por ejemplo un archivo de virtual host de Nginx o un archivo de ajustes de la aplicación) se pueden declarar bajo la clave de nivel superior configs y montar en los contenedores, manteniendo la configuración separada de las imágenes y de las variables de entorno.
• Secrets: los datos sensibles, como contraseñas y claves de API, se montan como archivos en /run/secrets/<name> dentro del contenedor, evitando exponerlos mediante variables de entorno o incluirlos en las imágenes.
• Health checks con la condición service_healthy: hacen que un servicio arranque solo cuando sus dependencias están realmente operativas, no simplemente en ejecución – un detalle que en producción marca la diferencia.

Nota de seguridad: en 2025 se identificó una vulnerabilidad de alta gravedad (CVE-2025-62725, puntuación CVSS v4 de 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 la 2.40.2 (sin incluirla) y puede provocar la sobrescritura de archivos arbitrarios en el host, incluso al ejecutar comandos aparentemente de solo lectura como docker compose ps o docker compose config. Está corregido desde la versión 2.40.2, por lo que todas las versiones de Compose V5 quedan fuera del problema. Si gestionas stacks de Compose que resuelven archivos remotos (por ejemplo mediante la directiva include o registros OCI) en hosts que aún ejecutan una versión 2.x, actualiza a la última versión y evita resolver artefactos de 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 siguientes forman el flujo operativo diario de cualquiera que gestione infraestructura contenerizada.

docker compose up Construye las imágenes (si hace falta), crea redes y volúmenes y arranca los contenedores definidos como servicios. Añadiendo el flag -d (docker compose up -d) el stack arranca en modo detached, el enfoque estándar en servidores de producción. Si los contenedores ya se están ejecutando y la configuración ha cambiado, Compose recrea automáticamente solo los afectados por los cambios, dejando intactos los demás.

docker compose start Arranca los contenedores que ya existen, sin reconstruir imágenes ni recrear recursos. Útil tras una parada programada o el reinicio de un nodo.

docker compose stop Detiene de forma ordenada los servicios en ejecución manteniendo en su sitio contenedores, redes, volúmenes e imágenes. Es el comando preferible cuando quieres suspender temporalmente un stack conservando 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 quedan en el sistema: así evitas la pérdida accidental de datos persistentes, una salvaguarda valiosa en entornos de producción.

• docker compose down --volumes elimina también los volúmenes con nombre asociados al stack (operación destructiva: úsalo solo cuando de verdad quieras empezar de cero).
• docker compose down --rmi all elimina todas las imágenes que usan los servicios.

Algunos comandos adicionales son esenciales para las operaciones del día a día:

docker compose ps Muestra el estado de los contenedores del stack actual, incluidos los resultados de los health checks. Es el primer comando que conviene lanzar para una comprobación rápida del estado.

docker compose logs -f Muestra en tiempo real los logs agregados de todos los servicios (o de un solo servicio, indicando su nombre). Es el punto de partida de cualquier tarea de troubleshooting.

docker compose pull Descarga en local las imágenes declaradas, como paso previo a un up posterior para desplegar nuevas versiones en producción de forma controlada.

docker compose config Muestra la configuración completamente resuelta, útil para validar la sintaxis y comprobar 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. Suele ser el camino más rápido para hacer troubleshooting de un servicio que no se comporta como debería.

docker compose ls Muestra todos los proyectos Compose activos en el host, sin importar el directorio en el que te encuentres. Para los MSP que gestionan varios stacks en un mismo servidor, ofrece una visión inmediata de qué se está ejecutando y dónde.

docker compose restart Reinicia uno o varios servicios sin destruir ni recrear los contenedores. Útil para aplicar cambios de configuración que solo requieren reiniciar el proceso (por ejemplo, tras actualizar una configuración de Nginx montada como volumen).

De la configuración a producción

Dominar Docker Compose no requiere un conocimiento profundo de Docker, pero para sysadmins y MSP es una inversión de alto retorno: estandariza los despliegues, acorta el tiempo de onboarding de los nuevos clientes, simplifica la documentación operativa de los stacks y reduce el margen de error en las tareas repetitivas. Como Compose es una especificación abierta, el mismo compose.yaml puede ser utilizado también por runtimes alternativos como Podman Compose, lo que te da flexibilidad si algún día necesitas dejar 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 llegas a una baseline reutilizable que puedes desplegar en todos tus clientes, con una clara mejora de fiabilidad y de tiempos de respuesta. Cuando un solo host ya no basta y necesitas escalabilidad o alta disponibilidad en varios nodos, es el momento de mirar los orquestadores: consulta Docker vs Kubernetes para entender en qué se diferencian ambas capas.

Si gestionas infraestructura contenerizada para varios clientes, combinar Docker Compose con una estrategia de backup sólida y un flujo de soporte remoto fiable marca la diferencia entre una operación fluida y una estresante. Uranium Backup protege archivos y carpetas, bases de datos (SQL Server, MySQL, MariaDB) y máquinas virtuales (VMware, Hyper-V), incluidos los datos de los hosts en los que se ejecutan tus aplicaciones contenerizadas.