Docker Compose: Orquestrar Múltiples Contenedores desde Cero con YAML

Docker Compose es la herramienta oficial para definir y ejecutar aplicaciones multi-contenedor. En vez de ejecutar 3 comandos docker run largos con opciones difíciles de recordar, describes toda la stack en un archivo YAML y subes todo con docker compose up.

Instalación

# Docker Compose v2 já vem integrado ao Docker Engine (como plugin)
docker compose version    # deve retornar v2.x

# Se não estiver disponível, instalar o plugin
sudo apt install docker-compose-plugin -y

# Versão standalone (legado, ainda funciona)
sudo apt install docker-compose -y   # docker-compose (com hífen)

Estructura del docker-compose.yml

version: "3.9"

services:
  app:
    build: .                          # usa o Dockerfile na raiz
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://user:senha@db:5432/meudb
    depends_on:
      db:
        condition: service_healthy    # espera o banco estar pronto

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER:     user
      POSTGRES_PASSWORD: senha
      POSTGRES_DB:       meudb
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:     # volume nomeado, persiste entre restarts

Comandos Esenciales

# Subir todos os serviços em background
docker compose up -d

# Ver logs de todos (ou de um serviço específico)
docker compose logs -f
docker compose logs -f app

# Listar containers do projeto
docker compose ps

# Parar e remover containers (mantém volumes)
docker compose down

# Parar, remover containers E volumes
docker compose down -v

# Rebuildar imagem e recriar container
docker compose up -d --build app

# Rodar comando em container em execução
docker compose exec app bash
docker compose exec db psql -U user meudb

Variables de Entorno con .env

Nunca coloques contraseñas directamente en el docker-compose.yml. Usa un archivo .env en la misma carpeta (y agrégalo al .gitignore):

# .env
POSTGRES_USER=user
POSTGRES_PASSWORD=senha_super_segura
POSTGRES_DB=meudb

# docker-compose.yml — referencia com ${VAR}
environment:
  POSTGRES_USER:     ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB:       ${POSTGRES_DB}

Volúmenes: Persistencia de Datos

services:
  app:
    volumes:
      # Volume nomeado (gerenciado pelo Docker)
      - dados_app:/app/uploads

      # Bind mount (pasta do host mapeada no container)
      # Útil em desenvolvimento para hot-reload
      - ./src:/app/src

      # Arquivo único montado no container
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro

volumes:
  dados_app:

Los bind mounts son excelentes para desarrollo — editas el archivo en el host y el contenedor ve el cambio inmediatamente. En producción, es mejor usar volúmenes nombrados ya que son gestionados por Docker y más fáciles de respaldar.

Redes: Comunicación entre Servicios

Por defecto, todos los servicios en un mismo docker-compose.yml están en la misma red y pueden comunicarse usando el nombre del servicio como hostname. El servicio app accede a la base de datos en db:5432, no en localhost:5432.

# Redes customizadas (para isolamento)
networks:
  frontend:
  backend:

services:
  nginx:
    networks: [frontend, backend]
  app:
    networks: [backend]
  db:
    networks: [backend]

Ejemplo Real: WordPress + MySQL + Nginx

version: "3.9"
services:
  nginx:
    image: nginx:alpine
    ports: ["80:80"]
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - wordpress:/var/www/html
    depends_on: [wordpress]

  wordpress:
    image: wordpress:php8.2-fpm
    environment:
      WORDPRESS_DB_HOST:     db
      WORDPRESS_DB_USER:     ${DB_USER}
      WORDPRESS_DB_PASSWORD: ${DB_PASS}
      WORDPRESS_DB_NAME:     wordpress
    volumes:
      - wordpress:/var/www/html

  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE:      wordpress
      MYSQL_USER:          ${DB_USER}
      MYSQL_PASSWORD:      ${DB_PASS}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASS}
    volumes:
      - dbdata:/var/lib/mysql

volumes:
  wordpress:
  dbdata:

Docker Compose vs Kubernetes

Compose es para una máquina; Kubernetes es para un cluster. Para proyectos con 1–5 servicios en un servidor, Compose es la elección correcta — simple, sin curva de aprendizaje de K8s, fácil de respaldar y migrar. Usa Kubernetes cuando necesites auto-escalamiento horizontal o alta disponibilidad con múltiples nodes.