name: setup-compose-stack locale: es source_locale: en source_commit: 6f65f316 translator: claude-sonnet-4-6 translation_date: 2026-03-16 description: > Configurar stacks Docker Compose multi-servicio de propósito general con redes, volúmenes, healthchecks, y perfiles de entorno. Cubrir patrones para aplicaciones web con bases de datos, colas de mensajes, cachés, y proxies inversos. Usar cuando se necesite orquestar múltiples servicios interconectados para desarrollo o producción. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: containerization complexity: intermediate language: multi tags: docker-compose, stack, multi-service, orchestration, networking

Configurar Stack Compose

Configurar stacks Docker Compose multi-servicio con redes, volúmenes y healthchecks.

Cuándo Usar

• Orquestando aplicaciones web con bases de datos y servicios de soporte
• Configurando entornos de desarrollo que replican producción
• Gestionando stacks con colas de mensajes, cachés y proxies
• Necesitando reproducibilidad en entornos multi-servicio
• Creando entornos de demostración o staging locales

Entradas

• Requerido: Lista de servicios y sus relaciones
• Requerido: Dockerfiles o imágenes para cada servicio
• Opcional: Esquemas de base de datos para inicialización
• Opcional: Archivos de configuración por servicio
• Opcional: Certificados TLS para HTTPS local

Procedimiento

Paso 1: Diseñar la Arquitectura del Stack

Mapear servicios, dependencias y redes.

# Arquitectura típica:
# frontend -> api -> database
#                 -> cache (Redis)
#                 -> queue (RabbitMQ)
# proxy (nginx) -> frontend, api

Esperado: Diagrama claro de servicios y sus interacciones.

En caso de fallo: Comenzar con los servicios mínimos necesarios y agregar más iterativamente.

Paso 2: Escribir docker-compose.yml Completo

version: '3.8'

services:
  proxy:
    image: nginx:1.25-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
    depends_on:
      frontend:
        condition: service_healthy
      api:
        condition: service_healthy
    networks:
      - frontend-net
    restart: unless-stopped

  frontend:
    build:
      context: ./frontend
      target: production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 15s
      timeout: 5s
      retries: 3
    networks:
      - frontend-net
    restart: unless-stopped

  api:
    build:
      context: ./api
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
      - REDIS_URL=redis://cache:6379
      - RABBITMQ_URL=amqp://user:pass@queue:5672
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
      queue:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 15s
      timeout: 5s
      retries: 3
    networks:
      - frontend-net
      - backend-net
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./db/init:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend-net
    restart: unless-stopped

  cache:
    image: redis:7-alpine
    volumes:
      - redis-data:/data
    networks:
      - backend-net
    restart: unless-stopped

  queue:
    image: rabbitmq:3.12-management-alpine
    environment:
      RABBITMQ_DEFAULT_USER: user
      RABBITMQ_DEFAULT_PASS: pass
    ports:
      - "15672:15672"
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      interval: 15s
      timeout: 10s
      retries: 5
    networks:
      - backend-net
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:
  rabbitmq-data:

networks:
  frontend-net:
    driver: bridge
  backend-net:
    driver: bridge

Esperado: Todos los servicios definidos con healthchecks, redes segmentadas, y volúmenes para persistencia.

En caso de fallo: Validar sintaxis con docker compose config, verificar que las imágenes existen.

Paso 3: Configurar Entornos Múltiples

# docker-compose.override.yml (desarrollo - se aplica automáticamente)
services:
  api:
    volumes:
      - ./api/src:/app/src
    environment:
      - DEBUG=true
    command: ["npm", "run", "dev"]

  db:
    ports:
      - "5432:5432"

# docker-compose.prod.yml
services:
  api:
    environment:
      - NODE_ENV=production
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 512M
          cpus: '0.5'

# Desarrollo (usa override automáticamente)
docker compose up

# Producción
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Esperado: Los archivos de override permiten configuración específica por entorno sin duplicar la configuración base.

En caso de fallo: Verificar el orden de precedencia de archivos con docker compose config.

Paso 4: Gestionar Ciclo de Vida

# Iniciar todos los servicios
docker compose up -d

# Ver estado y logs
docker compose ps
docker compose logs -f api

# Escalar un servicio
docker compose up -d --scale api=3

# Reiniciar un servicio específico
docker compose restart api

# Detener sin eliminar datos
docker compose stop

# Detener y eliminar todo (incluyendo volúmenes)
docker compose down -v

Esperado: Los servicios se gestionan de forma independiente, los datos persisten entre reinicios.

En caso de fallo: Revisar logs de servicios individuales, verificar healthchecks, comprobar uso de recursos.

Validación

• Todos los servicios inician y alcanzan estado saludable
• Las redes segmentan correctamente el tráfico (backend no accesible desde frontend)
• Los volúmenes persisten datos entre reinicios
• Los healthchecks detectan servicios no saludables
• Las variables de entorno se inyectan correctamente
• Los archivos de override funcionan para cada entorno

Errores Comunes

• Red plana sin segmentación: Segmentar frontend y backend en redes separadas para seguridad.
• Healthchecks faltantes: Sin healthchecks, depends_on no espera a que los servicios estén listos.
• Volúmenes anónimos: Usar volúmenes nombrados para persistencia predecible.
• Credenciales hardcodeadas: Usar archivos .env o Docker secrets para credenciales.
• No usar restart policy: Agregar restart: unless-stopped para recuperación automática.
• Puertos innecesariamente expuestos: Solo exponer puertos al host cuando sea necesario.

Habilidades Relacionadas

• setup-docker-compose - Docker Compose para entornos R específicos
• configure-nginx - Configuración detallada de Nginx como proxy
• configure-reverse-proxy - Patrones de proxy inverso con Nginx/Traefik
• create-dockerfile - Crear Dockerfiles para cada servicio del stack