Guia Completo de Docker Compose

Por Que Usar Docker Compose?

Docker Compose é uma ferramenta para definir e executar aplicações multi-container usando um único arquivo YAML. Ele simplifica a orquestração de serviços complexos e é essencial para desenvolvimento local e ambientes de teste.

Simples

Arquivo único YAML

Rápido

Setup em minutos

Portável

Mesmo ambiente em qualquer lugar

Escalável

Replicas com um comando

Conceitos Fundamentais do Docker Compose

Entenda os componentes essenciais da orquestração com Docker Compose

docker-compose.yml

Arquivo de configuração principal que define serviços, redes, volumes e variáveis de ambiente.

Services

Definem os containers que compõem sua aplicação, incluindo imagem, portas, volumes e dependências.

Networks

Permite que containers se comuniquem entre si e com o mundo exterior de forma isolada e segura.

Volumes

Gerenciam dados persistentes entre reinicializações de containers, essenciais para bancos de dados.

Environment Variables

Configurações externas que permitem diferentes comportamentos em diferentes ambientes.

Dependências

Controlam a ordem de inicialização dos serviços para garantir que dependências estejam prontas.

Primeiros Passos com Docker Compose

Instalação e comandos básicos para começar

Instalação do Docker Compose

O Compose atual é um plugin do Docker. O comando leva espaço: docker compose. Docker Desktop já inclui o plugin. No Linux, instale o pacote docker-compose-plugin pelo repositório oficial do Docker.

docker compose version
docker compose up -d

Comandos Essenciais

docker compose up - Iniciar serviços
docker compose down - Parar e remover serviços
docker compose build - Construir/reconstruir imagens
docker compose logs - Visualizar logs
docker compose ps - Listar containers em execução
docker compose exec - Executar comandos em serviços

Configuração Básica do docker-compose.yml

Estrutura e sintaxe do arquivo de configuração principal

# docker-compose.yml
services:
  web:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
      - redis
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://user:password@db:5432/myapp
    volumes:
      - ./app:/app
      - node_modules:/app/node_modules

  db:
    image: postgres:18
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

volumes:
  db_data:
  node_modules:

networks:
  default:
    driver: bridge

Compose file

A chave version no topo do YAML está obsoleta. O plugin ignora o campo e avisa. O arquivo começa em services.

Services

Definem os containers da aplicação

Volumes

Gerenciam armazenamento persistente

Arquitetura de Rede com Docker Compose

Como os serviços se comunicam entre si e com o mundo exterior

Web

Porta 3000

Database

Porta 5432

Redis

Porta 6379

# Configuração avançada de rede
services:
  web:
    image: nginx
    ports:
      - "80:80"
      - "443:443"
    networks:
      - frontend
      - backend

  api:
    build: ./api
    networks:
      - backend

  db:
    image: postgres
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # Isolada do mundo exterior

Gestão de Ambientes

Configuração diferente para desenvolvimento, teste e produção

Arquivo .env

Variáveis de ambiente compartilhadas entre todos os serviços.

# .env
DATABASE_HOST=db
DATABASE_PORT=5432
REDIS_HOST=redis
REDIS_PORT=6379
NODE_ENV=development

Múltiplos arquivos Compose

Sobrescreva configurações para diferentes ambientes.

# docker-compose.prod.yml
services:
  web:
    build:
      context: .
      args:
        - NODE_ENV=production
    ports:
      - "80:3000"
    environment:
      - NODE_ENV=production

# Comando para usar múltiplos arquivos
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Recursos Avançados

Funcionalidades poderosas para cenários complexos

Escalabilidade

Escalone serviços horizontalmente com o comando scale ou defina deploy no arquivo.

Segurança

Use secrets para gerenciar credenciais sensíveis e evite hardcode de senhas.

Health Checks

Defina verificações de saúde para garantir que serviços estejam funcionando corretamente.

Extensibilidade

Use extends para reutilizar configurações entre diferentes arquivos Compose.

# Exemplo de health check e secrets
services:
  web:
    image: myapp:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

Docker Compose em Produção

Estratégias e melhores práticas para ambientes de produção

1

Imagens Oficiais

Use uma tag de major ainda suportada. PostgreSQL 13 saiu do suporte da comunidade em novembro de 2025. O exemplo abaixo usa a 18. Evite latest.

# Bom
image: postgres:18

# Evite
image: postgres:latest

2

Limites de Recursos

Defina limites de CPU e memória para evitar consumo excessivo de recursos.

services:
  web:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

3

Logs Estruturados

Configure drivers de log para melhor monitoramento e análise.

services:
  web:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

4

Atualizações Contínuas

Use estratégias de atualização como rolling updates para zero downtime.

services:
  web:
    deploy:
      update_config:
        parallelism: 2
        delay: 10s
        order: start-first

Segurança em Docker Compose

Práticas essenciais para manter suas aplicações seguras

Princípios de Segurança

1. Princípio do Menor Privilégio

Execute containers como usuário não-root sempre que possível.

2. Scanning de Vulnerabilidades

Verifique imagens regularmente em busca de vulnerabilidades conhecidas.

3. Segredos vs Variáveis

Use secrets para dados sensíveis e variáveis de ambiente para configurações não sensíveis.

4. Redes Internas

Isole serviços críticos em redes internas sem acesso ao mundo exterior.

5. Atualizações Regulares

Mantenha suas imagens base e dependências sempre atualizadas.

Usuário Não-Root

services:
  web:
    user: "1000:1000"

Secrets

secrets:
  db_password:
    external: true

Dica Importante

Nunca armazene senhas, tokens ou chaves de API diretamente no arquivo docker-compose.yml. Use sempre secrets ou variáveis de ambiente carregadas de arquivos externos.

Padrões Comuns de Arquitetura

Exemplos práticos para cenários comuns de aplicação

Desenvolvimento Web

Aplicação web com Node.js, PostgreSQL e Redis para cache.

E-commerce

Loja virtual com frontend, backend, banco de dados, cache e serviço de email.

Data Science

Ambiente Jupyter com bibliotecas científicas, banco de dados e armazenamento de dados.

Monitoramento

Stack de observabilidade com Prometheus, Grafana, Loki e Alertmanager.

Solução de Problemas

Comandos e técnicas para diagnosticar e resolver problemas comuns

Diagnóstico de Problemas

docker compose logs -f service - Logs em tempo real
docker compose config - Validação do arquivo YAML
docker compose top - Processos em execução
docker stats - Uso de recursos

Problemas Comuns

Portas em conflito
Volumes não montando
Dependências não resolvidas
Variáveis de ambiente ausentes

Cenário em setembro de 2026

Compose v2 é plugin. docker compose up, down, logs e exec substituem o binário com hífen. Docker Desktop já traz o plugin. No Linux, o pacote é docker-compose-plugin, do repositório oficial do Docker.

Arquivos de override continuam válidos: docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d. O nome do arquivo pode ser compose.yaml ou docker-compose.yml.

Imagens dos exemplos: postgres:18 e redis:7-alpine. A 13 do Postgres e a 6 do Redis ficaram velhas para um stack novo. Fixe a major que você testou. latest muda por baixo de você.