Docker Compose Depends on

Health checks

Los health checks permiten verificar el estado real de funcionamiento de un servicio, más allá de que el contenedor esté simplemente ejecutándose. Un contenedor puede estar en estado "running" pero el servicio que contiene puede no estar respondiendo correctamente debido a errores internos, problemas de red o fallos en la inicialización.

Definición básica de health checks

En Docker Compose, definimos un health check usando la clave healthcheck dentro de un servicio. Esta verificación se ejecuta periódicamente para determinar si el servicio está saludable y listo para recibir tráfico.

services:
  web:
    image: nginx:1.25
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Parámetros de configuración

Los health checks en Docker Compose admiten varios parámetros de configuración que controlan cómo y cuándo se ejecutan las verificaciones:

• test: Define el comando que se ejecuta para verificar el estado del servicio. Puede usar formato de array o string.

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres"]
  # O alternativamente:
  # test: pg_isready -U postgres

• interval: Tiempo entre verificaciones consecutivas (por defecto 30s).

• timeout: Tiempo máximo que el comando puede tardar antes de considerarse fallido (por defecto 30s).

• retries: Número de fallos consecutivos antes de marcar el contenedor como unhealthy (por defecto 3).

• start_period: Tiempo de gracia durante el cual los fallos no cuentan para el contador de reintentos (por defecto 0s).

Ejemplos prácticos por tecnología

Base de datos PostgreSQL:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: mypassword
      POSTGRES_DB: myapp
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d myapp"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 30s

Base de datos MySQL:

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: appdb
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 20s
      timeout: 10s
      retries: 3
      start_period: 60s

Aplicación web con API:

services:
  api:
    image: node:24-alpine
    command: node server.js
    healthcheck:
      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

Estados de salud

Docker reconoce tres estados de salud principales:

• starting: El contenedor acaba de iniciarse y está dentro del período de gracia (start_period)
• healthy: El health check se ejecuta correctamente
• unhealthy: El health check ha fallado el número de veces especificado en retries

Verificar el estado de salud

Podemos consultar el estado de salud de nuestros servicios usando varios comandos:

# Ver estado general de todos los servicios
docker compose ps

# Ver detalles específicos del health check
docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Health}}"

# Inspeccionar logs del health check
docker inspect <container_name> --format='{{json .State.Health}}'

Buenas prácticas para health checks

• Verificaciones específicas: No te limites a verificar que el puerto esté abierto. Comprueba funcionalidades específicas del servicio.

# Mejor práctica: verificar endpoint específico
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]

# Evitar: solo verificar puerto
healthcheck:
  test: ["CMD", "nc", "-z", "localhost", "8080"]

• Timeouts apropiados: Ajusta los tiempos según las características de tu aplicación. Las bases de datos suelen necesitar más tiempo de inicialización.

• Endpoints dedicados: Crea endpoints /health o /ready en tus aplicaciones que verifiquen dependencias críticas como conexiones a base de datos.

services:
  app:
    build: .
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

Los health checks son fundamentales para crear arquitecturas resilientes donde los servicios pueden detectar y responder automáticamente a fallos de dependencias, preparando el terreno para usar correctamente las dependencias entre servicios.

Depends on

La directiva depends_on establece dependencias entre servicios en Docker Compose, controlando el orden de inicio y creando relaciones lógicas entre contenedores. Sin embargo, es importante entender tanto sus capacidades como sus limitaciones para utilizarla correctamente en entornos de desarrollo y producción.

Dependencia básica de orden de inicio

La forma más simple de depends_on controla únicamente el orden de inicio de los servicios. Docker Compose iniciará primero los servicios de los que depende otro servicio, pero no espera a que estén completamente listos.

services:
  web:
    image: nginx:1.25
    depends_on:
      - api
      - redis
      
  api:
    image: node:24
    depends_on:
      - postgres
      
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: mypassword
      
  redis:
    image: redis:7-alpine

En este ejemplo, Docker Compose iniciará los servicios en este orden: postgres → redis → api → web. Sin embargo, no garantiza que PostgreSQL esté listo para aceptar conexiones cuando se inicie api.

Limitaciones del depends_on básico

El depends_on tradicional solo espera que el contenedor esté en estado "running", no que el servicio interno esté operativo. Esto puede causar errores cuando un servicio intenta conectarse a una dependencia que aún se está inicializando.

services:
  app:
    image: python:3.13
    command: python app.py
    depends_on:
      - mysql
      # La aplicación puede fallar si MySQL aún no está listo
      
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
    # MySQL puede tardar 30-60 segundos en estar completamente listo

Depends_on con condiciones de salud

La solución más robusta combina depends_on con health checks usando la sintaxis extendida. Esto permite esperar hasta que las dependencias estén realmente saludables antes de iniciar los servicios dependientes.

services:
  web:
    image: nginx:1.25
    depends_on:
      api:
        condition: service_healthy
        
  api:
    build: ./api
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
        
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secretpass
      POSTGRES_DB: myapp
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d myapp"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
      
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

Condiciones disponibles

Docker Compose ofrece tres condiciones principales para depends_on:

• service_started: Espera solo que el contenedor esté ejecutándose (comportamiento por defecto)
• service_healthy: Espera que el health check del servicio reporte estado "healthy"
• service_completed_successfully: Espera que el servicio termine con código de salida 0

Ejemplo práctico: Stack web completo

services:
  nginx:
    image: nginx:1.25
    ports:
      - "80:80"
    depends_on:
      webapp:
        condition: service_healthy
        
  webapp:
    build: ./app
    environment:
      DATABASE_URL: postgresql://user:pass@postgres:5432/webapp
      REDIS_URL: redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 20s
      
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: webapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d webapp"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
      
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3

volumes:
  postgres_data:

Gestión de dependencias circulares

Docker Compose detecta y rechaza dependencias circulares automáticamente. Si intentas crear una dependencia circular, recibirás un error al ejecutar docker compose up.

# Esto causará un error
services:
  service-a:
    image: alpine
    depends_on:
      - service-b
      
  service-b:
    image: alpine
    depends_on:
      - service-a  # Error: dependencia circular

Comportamiento durante el shutdown

Cuando ejecutas docker compose down, los servicios se detienen en orden inverso a las dependencias. En el ejemplo anterior, se detendrían en este orden: nginx → webapp → postgres/redis.

Alternativas para dependencias complejas

Para escenarios más complejos donde necesitas lógica de inicialización personalizada, considera usar scripts de espera dentro de tus contenedores:

services:
  app:
    image: node:24
    command: |
      sh -c "
        npm run wait-for-deps &&
        npm start
      "
    depends_on:
      - postgres
      
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: password

El uso correcto de depends_on combinado con health checks apropiados garantiza que tu aplicación multi-contenedor se inicie de forma ordenada y confiable, eliminando los errores de conexión prematura y creando un entorno de desarrollo más estable.