Second Brain

Docker Compose

Created Updated 3 min read

Ideia central

Docker Compose é uma ferramenta para definir e executar aplicações multi-container usando um arquivo compose.yaml (ou docker-compose.yml). Com um único comando (docker compose up), você sobe toda a stack (banco de dados, API, cache, proxy reverso) com as configurações corretas de rede, volumes e dependências.

Estrutura do compose.yaml

# Versão não é mais necessária no Compose V2+
services:
  # Nome do serviço (funciona como hostname na rede interna)
  api:
    build: .                          # build do Dockerfile no dir atual
    image: minha-api:latest           # ou usar imagem pronta
    container_name: api               # nome explícito (opcional)
    ports:
      - "3000:3000"                   # host:container
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://db:5432/app
    env_file:
      - .env                          # carregar de arquivo
    depends_on:
      db:
        condition: service_healthy    # aguarda db estar saudável
    restart: unless-stopped
    networks:
      - backend
 
  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data  # volume nomeado
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql  # bind mount
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: user
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d app"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend
 
  redis:
    image: redis:7-alpine
    networks:
      - backend
 
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - api
    networks:
      - frontend
      - backend
 
networks:
  frontend:
  backend:
 
volumes:
  postgres_data:    # volume gerenciado pelo Docker (persiste entre restarts)

Comandos essenciais

# Subir toda a stack (em background)
docker compose up -d
 
# Subir e forçar rebuild das imagens
docker compose up -d --build
 
# Parar e remover containers (mantém volumes e imagens)
docker compose down
 
# Parar, remover containers E volumes
docker compose down -v
 
# Ver status dos serviços
docker compose ps
 
# Ver logs de todos os serviços
docker compose logs -f
 
# Ver logs de um serviço específico
docker compose logs -f api
 
# Executar comando em um serviço
docker compose exec api sh
 
# Escalar um serviço (múltiplas réplicas)
docker compose up -d --scale api=3
 
# Recriar apenas um serviço específico
docker compose up -d --no-deps api

Múltiplos arquivos (override)

Útil para ter configurações base + ambiente específico:

# Padrão: lê compose.yaml + compose.override.yaml automaticamente
docker compose up
 
# Especificar arquivos manualmente
docker compose -f compose.yaml -f compose.prod.yaml up -d

Exemplo de compose.override.yaml para desenvolvimento:

services:
  api:
    build:
      target: dev           # stage de dev no multi-stage build
    volumes:
      - .:/app              # hot reload
    environment:
      - NODE_ENV=development
    command: npm run dev

Healthcheck e depends_on

O depends_on simples apenas espera o container iniciar, não estar pronto. Para aguardar o serviço estar de fato funcional, use condition: service_healthy com um healthcheck definido:

depends_on:
  db:
    condition: service_healthy  # aguarda healthcheck passar
  redis:
    condition: service_started  # apenas aguarda iniciar (padrão)

Boas práticas

  • Use volumes nomeados para dados persistentes (banco, uploads), evitando depender do filesystem do container
  • Prefira redes customizadas: o Compose cria uma por projeto automaticamente
  • Use .env para secrets e variáveis de ambiente sensíveis (não commite no git)
  • Defina healthcheck nos serviços críticos para depends_on funcionar corretamente
  • Use profiles para serviços opcionais (ex: ferramentas de debug que só sobem quando necessário)

Conexões

Referências

Graph View

Backlinks