docker-compose: orquestar varios servicios juntos

Hasta ahora has ejecutado contenedores individuales con docker run. Está bien para aprender, pero en el mundo real las aplicaciones no viven solas. Un pipeline de datos típico necesita: una base de datos (PostgreSQL), un cache (Redis), una herramienta de visualización (Jupyter), y tu código Python que los conecta todos. ¿Vas a escribir 4 docker run diferentes, recordar todos los flags, los puertos, las variables de entorno, y ejecutarlos en el orden correcto cada mañana? No. Para eso existe docker-compose.

docker-compose es como el DIRECTOR DE ORQUESTA de tus contenedores. Tú escribes una "partitura" (un archivo YAML llamado docker-compose.yml) que describe todos los servicios que necesitas, cómo se conectan entre sí, qué puertos exponen, qué variables de entorno usan — y luego con UN SOLO COMANDO (docker compose up) toda la orquesta empieza a tocar. PostgreSQL arranca, Redis se levanta, Jupyter se conecta a ambos, y tu script puede hablar con todos.

### Tu primer docker-compose.yml

Un docker-compose.yml es un archivo en formato YAML (un formato legible por humanos, como JSON pero más limpio) que describe tu infraestructura. Veamos uno simple con PostgreSQL:

1# Archivo: docker-compose.yml
2services:
3  db:
4    image: postgres:16
5    environment:
6      POSTGRES_USER: datos
7      POSTGRES_PASSWORD: secreto123
8      POSTGRES_DB: ventas
9    ports:
10      - "5432:5432"

1# Levantar todos los servicios definidos en docker-compose.yml
2docker compose up
3
4# Levantar en background (detached)
5docker compose up -d
6
7# Ver qué servicios están corriendo
8docker compose ps
9
10# Parar todos los servicios
11docker compose down
12
13# Parar y BORRAR los volúmenes (borra datos)
14docker compose down -v

Compara esto con el docker run equivalente: docker run -d --name db -e POSTGRES_USER=datos -e POSTGRES_PASSWORD=secreto123 -e POSTGRES_DB=ventas -p 5432:5432 postgres:16. El docker-compose.yml es infinitamente más legible, versionable (va en Git), y escalable (añadir un servicio más es añadir unas líneas).

### Múltiples servicios: la potencia real

La verdadera magia de docker-compose llega cuando tienes VARIOS servicios que necesitan hablar entre sí. Veamos un ejemplo con PostgreSQL + Redis + una app Python:

1# Archivo: docker-compose.yml — entorno multi-servicio
2services:
3  db:
4    image: postgres:16
5    environment:
6      POSTGRES_USER: datos
7      POSTGRES_PASSWORD: secreto123
8      POSTGRES_DB: analytics
9    ports:
10      - "5432:5432"
11
12  cache:
13    image: redis:7-alpine
14    ports:
15      - "6379:6379"
16
17  app:
18    build: .
19    environment:
20      DATABASE_URL: postgresql://datos:secreto123@db:5432/analytics
21      REDIS_URL: redis://cache:6379
22    depends_on:
23      - db
24      - cache
25    ports:
26      - "8000:8000"

### depends_on: el orden importa

Observa la clave depends_on en el servicio "app". Le dice a Docker Compose: "no arranques la app hasta que db y cache estén levantados". Es como decir "no empieces a cocinar la paella hasta que el fuego esté encendido". Sin depends_on, los servicios arrancan en cualquier orden y tu app podría intentar conectarse a PostgreSQL antes de que esté listo.

1# Healthcheck: Compose espera a que el servicio esté DE VERDAD listo
2services:
3  postgres:
4    image: postgres:16
5    environment:
6      POSTGRES_PASSWORD: secreto123
7    healthcheck:
8      test: ["CMD-SHELL", "pg_isready -U postgres"]
9      interval: 3s
10      timeout: 3s
11      retries: 5
12
13  etl:
14    build: .
15    depends_on:
16      postgres:
17        condition: service_healthy   # ← espera al healthcheck, no solo al arranque

### La magia del DNS interno: los servicios se encuentran por nombre

Fíjate en DATABASE_URL: postgresql://datos:secreto123@db:5432/analytics. El "db" en esa URL NO es localhost — es el NOMBRE del servicio definido en docker-compose.yml. Docker Compose crea una red interna donde cada servicio puede encontrar a los demás por su nombre. Es como si en un edificio de oficinas cada empresa tuviera un buzón con su nombre en el hall — no necesitas saber el número de puerta, solo el nombre.

1# Dentro de docker-compose, los servicios se encuentran POR NOMBRE:
2# - db      → accesible como "db" desde otros contenedores
3# - cache   → accesible como "cache" desde otros contenedores
4# - app     → accesible como "app" desde otros contenedores
5
6# Ejemplo: desde el contenedor "app", PostgreSQL está en:
7# host: db (NO localhost)
8# port: 5432
9
10# Desde tu ordenador (fuera de Docker), PostgreSQL está en:
11# host: localhost
12# port: 5432 (el que mapeaste con ports)

### build vs image: usar tu propio Dockerfile

Has visto que "db" y "cache" usan image: (imágenes pre-hechas de Docker Hub), pero "app" usa build: . (construye una imagen desde tu Dockerfile local). Puedes mezclar ambos estilos libremente:

• ▹image: postgres:16 → "Usa la imagen postgres:16 de Docker Hub tal cual"
• ▹build: . → "Construye una imagen usando el Dockerfile que está en el directorio actual"
• ▹build: ./mi-servicio → "Construye usando el Dockerfile dentro de la carpeta mi-servicio"

### Comandos esenciales de docker-compose

1# Levantar servicios en background
2docker compose up -d
3
4# Ver logs de todos los servicios
5docker compose logs
6
7# Ver logs de UN servicio específico, en tiempo real
8docker compose logs -f db
9
10# Parar servicios sin borrarlos
11docker compose stop
12
13# Parar y borrar contenedores + redes (datos en volúmenes se mantienen)
14docker compose down
15
16# Reconstruir imágenes (cuando cambias tu Dockerfile o código)
17docker compose up -d --build
18
19# Ejecutar un comando dentro de un servicio que ya está corriendo
20docker compose exec db psql -U datos -d analytics
21
22# Escalar un servicio (crear múltiples instancias)
23docker compose up -d --scale app=3