Docker Compose Services

Estructura general compose.yaml

Docker Compose utiliza un archivo YAML denominado compose.yaml (o alternativamente docker-compose.yaml) para definir y orquestar múltiples contenedores como una aplicación completa. Este archivo sigue una estructura jerárquica específica que permite describir todos los componentes necesarios de manera declarativa.

Anatomía del archivo compose.yaml

La estructura de un archivo Compose se organiza en secciones de nivel superior (top-level) que definen los diferentes recursos de la aplicación:

# Ejemplo básico de estructura
services:
  web:
    image: nginx:1.29
    ports:
      - "80:80"
  
  database:
    image: mysql:9
    environment:
      MYSQL_ROOT_PASSWORD: secret

volumes:
  data_volume:

networks:
  app_network:

Secciones top-level principales

Docker Compose reconoce tres secciones principales en el nivel superior del archivo:

• services: Define los contenedores que componen la aplicación
• volumes: Declara volúmenes nombrados para persistencia de datos
• networks: Especifica redes personalizadas para comunicación entre servicios

La sección services

La sección services es el corazón del archivo Compose y donde se definen todos los contenedores de la aplicación. Cada servicio representa un contenedor con su configuración específica:

services:
  frontend:
    image: node:24
    ports:
      - "3000:3000"
    
  backend:
    image: python:3.13
    ports:
      - "8000:8000"
    
  cache:
    image: redis:latest

Cada clave bajo services (como frontend, backend, cache) define un servicio individual. El nombre del servicio se convierte automáticamente en el hostname que otros servicios pueden utilizar para comunicarse entre sí.

Convenciones de nomenclatura

Docker Compose aplica reglas de nomenclatura consistentes para facilitar la gestión:

• Nombres de servicios: Utilizan el formato snake_case y se convierten en hostnames DNS
• Prefijo de proyecto: Todos los recursos creados incluyen el nombre del directorio como prefijo
• Sufijos automáticos: Los contenedores reciben sufijos numéricos para evitar conflictos

services:
  web_server:    # Se convierte en hostname 'web_server'
    image: nginx:1.29
  
  api_service:   # Se convierte en hostname 'api_service'  
    image: node:24

Validación y sintaxis YAML

El archivo debe seguir sintaxis YAML válida con especial atención a:

• Indentación: Utilizar espacios (no tabs) de forma consistente
• Estructura jerárquica: Mantener la anidación correcta de elementos
• Comillas: Usar comillas para valores que contienen caracteres especiales

services:
  web:
    image: "nginx:1.29"  # Comillas recomendadas para tags
    container_name: "my-web-server"
    restart: always

Versionado y compatibilidad

Los archivos Compose modernos no requieren especificar una versión explícita. Docker Compose v2 detecta automáticamente la sintaxis y aplica las características más recientes disponibles:

# ❌ Ya no es necesario especificar version
# version: '3.8'

# ✅ Sintaxis moderna sin version
services:
  app:
    image: python:3.13

Esta estructura proporciona la base fundamental sobre la cual se construyen aplicaciones multi-contenedor, estableciendo un marco organizativo claro que facilita tanto el desarrollo como el mantenimiento de aplicaciones complejas.

Estructura de un servicio

Un servicio en Docker Compose representa la configuración completa de un contenedor específico dentro de la aplicación. Cada servicio se define mediante un conjunto de propiedades clave que determinan cómo se ejecutará el contenedor correspondiente.

Configuración básica de imagen

Todo servicio debe especificar la imagen base que utilizará para crear el contenedor. Esta es la configuración más fundamental:

services:
  web:
    image: nginx:1.29
    
  database:
    image: mysql:9
    
  api:
    image: python:3.13

La propiedad image acepta cualquier imagen válida disponible en registries públicos o privados, siguiendo la sintaxis estándar de Docker con formato nombre:tag.

Exposición de puertos

Los servicios pueden exponer puertos para permitir comunicación desde el host o entre contenedores:

services:
  frontend:
    image: node:24
    ports:
      - "3000:3000"    # host:contenedor
      - "3001:3001"
      
  backend:
    image: python:3.13
    ports:
      - "8000:8000"
      - "127.0.0.1:8001:8001"  # Bind específico a localhost

La sintaxis "puerto_host:puerto_contenedor" mapea puertos del sistema host hacia puertos internos del contenedor, facilitando el acceso externo a los servicios.

Configuración de nombres de contenedor

Por defecto, Docker Compose genera nombres automáticos para los contenedores, pero se pueden especificar nombres personalizados:

services:
  web:
    image: nginx:1.29
    container_name: my-nginx-server
    
  cache:
    image: redis:latest
    container_name: app-redis-cache

El uso de container_name proporciona nombres predecibles que facilitan la administración y el debugging de contenedores individuales.

Políticas de reinicio

Los servicios pueden configurar comportamientos de reinicio automático ante fallos o paradas del sistema:

services:
  database:
    image: postgres:17
    restart: always
    
  web:
    image: nginx:1.29
    restart: unless-stopped
    
  worker:
    image: python:3.13
    restart: on-failure

Las políticas disponibles incluyen:

• no: No reinicia automáticamente (por defecto)
• always: Reinicia siempre, incluso tras reboot del host
• unless-stopped: Reinicia excepto cuando se detiene manualmente
• on-failure: Reinicia solo ante códigos de salida de error

Verificaciones de salud

Docker Compose permite definir health checks para monitorear el estado de los servicios:

services:
  web:
    image: nginx:1.29
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
      
  database:
    image: mysql:9
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 20s
      timeout: 5s
      retries: 3

Los parámetros de healthcheck controlan:

• test: Comando de verificación a ejecutar
• interval: Frecuencia entre verificaciones
• timeout: Tiempo límite por verificación
• retries: Intentos antes de marcar como no saludable
• start_period: Período de gracia inicial

Configuración avanzada de servicios

Los servicios admiten configuraciones adicionales para casos específicos:

services:
  app:
    image: python:3.13
    working_dir: /app
    user: "1000:1000"
    stdin_open: true      # Equivale a -i en docker run
    tty: true            # Equivale a -t en docker run
    
  database:
    image: postgres:17
    shm_size: "256mb"
    ulimits:
      nofile:
        soft: 65536
        hard: 65536

Combinación de opciones de servicio

Un servicio completo puede combinar múltiples configuraciones para crear un contenedor completamente especificado:

services:
  api_server:
    image: node:24
    container_name: main-api
    ports:
      - "8080:8080"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    working_dir: /usr/src/app
    user: "node:node"

Esta estructura de configuración por servicio proporciona flexibilidad completa para definir el comportamiento específico de cada contenedor, manteniendo la simplicidad declarativa que caracteriza a Docker Compose y facilitando la gestión de aplicaciones multi-contenedor complejas.