Chuleta Docker Compose (2026): toda clave y comando CLI

Descripción general

Docker Compose define aplicaciones multi-contenedor en un único archivo YAML. Esta chuleta cubre la estructura de compose.yaml, cada clave de servicio, opciones de entorno y configuración, redes y volúmenes, la CLI completa, archivos override y perfiles. Todos los ejemplos apuntan a Docker Compose v2 (el plugin docker compose) y la Especificación de Compose; la clave version: heredada es obsoleta e ignorada.

Estructura de compose.yaml

La estructura básica de un archivo Compose:

services:      # Define servicios contenerizados
volumes:       # Define volúmenes nombrados
networks:      # Define redes personalizadas
configs:       # Define configs (para swarm, opcional)
secrets:       # Define secretos (para swarm, opcional)

Servicios: claves básicas

Redes y puertos

Entorno y configuración

Almacenamiento: volúmenes y bind mounts

Nota: Define volúmenes nombrados en el nivel superior:

volumes:
  my_data:
    driver: local

Límites de recursos

Verificaciones de salud

Ejemplo completo:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 5s
  start_period: 10s
  retries: 3

Dependencias y orden de inicio

Precaución: condition: service_healthy requiere que el servicio tenga healthcheck. Sin él, la condición falla inmediatamente.

Ejemplo completo:

services:
  web:
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

Seguridad: secretos y configs

Definición en el nivel superior:

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

configs:
  nginx_config:
    file: ./nginx.conf

Acceso en contenedor:

# En shell: cat /run/secrets/db_password

Perfiles

Los perfiles permiten incluir servicios condicionalmente.

services:
  web:
    image: nginx:latest
    # Siempre incluido

  debug:
    image: busybox:latest
    profiles: [debug]
    # Solo incluido con --profile debug

  monitoring:
    image: prom/prometheus:latest
    profiles: [monitoring, prod]
    # Incluido con --profile monitoring O --profile prod

Uso:

docker compose up                        # Incluir solo servicios sin perfiles
docker compose --profile debug up        # Incluir web + debug
docker compose --profile monitoring up   # Incluir web + monitoring
docker compose --profile debug --profile monitoring up  # Incluir los tres

Redes (nivel superior)

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: br0

Uso de servicio:

services:
  web:
    networks: [frontend, backend]
  db:
    networks: [backend]

Volúmenes (nivel superior)

volumes:
  db_data:
    driver: local
  shared_cache:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs

Archivos override

Docker Compose carga automáticamente docker-compose.override.yaml y lo fusiona con compose.yaml.

compose.yaml (producción):

services:
  web:
    image: myapp:latest
    environment:
      LOG_LEVEL: warn

docker-compose.override.yaml (desarrollo local):

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      LOG_LEVEL: debug

Resultado cuando se ejecuta docker compose up:
– Imagen se construye desde ./Dockerfile (sobrescribe image: myapp:latest)
– Puerto 8000 se expone en el host
– LOG_LEVEL se establece a debug
– Mapeo de puerto y LOG_LEVEL se fusionan

Archivo override explícito:

docker compose -f compose.yaml -f compose.prod.yaml up

Comandos CLI

Patrones que reutilizarás

# Desarrollo con archivo override
# compose.yaml: configuración de producción
# docker-compose.override.yaml: ajustes de desarrollo local

# Base de datos con healthcheck y depends_on
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
  web:
    depends_on:
      db:
        condition: service_healthy

# Aplicación de múltiples niveles
services:
  web:
    networks: [frontend, backend]
  cache:
    networks: [backend]
  db:
    networks: [backend]

# Cargar entorno desde archivo con sobrescrituras
services:
  app:
    env_file: .env
    environment:
      LOG_LEVEL: debug  # Sobrescribir desde .env

# Perfiles para servicios opcionales
  monitoring:
    profiles: [monitoring]
  debug:
    profiles: [debug]

# Usar compose watch para recarga en vivo (Compose 2.22+)
# docker compose watch
watch:
  - path: ./src
    action: sync
    target: /app/src
  - path: ./requirements.txt
    action: rebuild

Preguntas frecuentes

¿Cuál es la diferencia entre docker-compose.yml y compose.yaml?

Ambos son compatibles. Docker prefiere compose.yaml (sin guión). Ambos son equivalentes; elige una convención y adhiérete a ella. La documentación moderna usa compose.yaml.

¿Cómo establezco variables de entorno en Docker Compose?

Usa la clave environment en un servicio, o carga desde un archivo con env_file: .env. Las variables pueden estar codificadas, del shell del host (${VAR_NAME}), o desde archivos .env. Usa secretos para valores sensibles.

¿Cómo me aseguro de que un servicio se inicie antes que otro?

Usa depends_on: db: condition: service_healthy (requiere HEALTHCHECK). Solo para orden de inicio sin validación, usa el formulario corto depends_on: [db]; solo ordena el inicio y no espera a estar listo.

¿Cómo uso archivos override de Docker Compose?

Crea docker-compose.override.yaml en el mismo directorio. Compose lo carga automáticamente y lo fusiona con compose.yaml. Sobrescribe servicios específicos sin editar el archivo principal. Útil para desarrollo local vs. producción.

¿Qué son los perfiles de Docker Compose?

Los perfiles permiten incluir servicios condicionalmente. Establece profiles: [debug] en un servicio, luego usa docker compose --profile debug up para incluirlo. Útil para servicios de depuración opcionales o pilas de monitoreo.