Comandos Básicos

docker compose version

Mostra a versão do Docker Compose instalada.

docker compose up

Sobe todos os serviços definidos no docker-compose.yml.

docker compose up -d

Sobe os serviços em background (modo detached).

docker compose down

Para e remove containers, redes e volumes padrão.

docker compose restart

Reinicia todos os serviços.

Status e Logs

docker compose ps

Lista os serviços em execução e seus status.

docker compose logs

Mostra logs de todos os serviços.

docker compose logs -f

Acompanha logs em tempo real (follow).

docker compose logs app

Mostra logs de um serviço específico.

docker compose logs --tail 100 app

Mostra apenas as últimas 100 linhas de log de um serviço.

Build e Imagens

docker compose build

Builda todas as imagens dos serviços que usam build.

docker compose build app

Builda apenas a imagem de um serviço específico.

docker compose up --build

Força rebuild das imagens antes de subir os serviços.

docker compose build --no-cache

Builda ignorando o cache de layers anteriores.

docker compose pull

Baixa as imagens mais recentes dos serviços que usam image.

Gerenciamento de Serviços

docker compose start

Inicia serviços que foram parados (sem recriar containers).

docker compose stop

Para serviços sem remover containers.

docker compose pause

Pausa os processos dos serviços (congela).

docker compose unpause

Retoma serviços pausados.

docker compose up -d --scale app=3

Sobe 3 instâncias do serviço app (escalonamento horizontal).

docker compose up -d app

Sobe apenas um serviço específico (e suas dependências).

Acesso aos Containers

docker compose exec app bash

Acessa o terminal bash de um container em execução.

docker compose exec app sh

Alternativa quando bash não está disponível (Alpine, por exemplo).

docker compose exec db psql -U postgres -d app_db

Acessa o PostgreSQL diretamente dentro do container.

docker compose run app npm install

Executa um comando pontual em um novo container do serviço.

docker compose run --rm app npx prisma migrate dev

Executa um comando e remove o container ao finalizar.

docker compose cp app:/app/dist ./dist

Copia arquivos de um container para a máquina local.

Limpeza

docker compose down -v

Remove containers e volumes (cuidado: apaga dados persistidos).

docker compose down --rmi all

Remove containers, redes e todas as imagens dos serviços.

docker compose down --rmi local

Remove apenas imagens buildadas localmente (não as baixadas do registry).

docker compose rm -f

Remove containers parados sem confirmação.

docker system prune -a --volumes

Limpa tudo do Docker: containers parados, redes não usadas, imagens e volumes órfãos.

Estrutura do docker-compose.yml

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: app
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    container_name: postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app_db
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  cache:
    image: redis:7-alpine
    container_name: redis
    ports:
      - "6379:6379"
    restart: unless-stopped

volumes:
  pgdata:

Redes

networks:
  app-network:
    driver: bridge

Definição de uma rede customizada com driver bridge.

services:
  app:
    networks:
      - app-network
  db:
    networks:
      - app-network

Conecta serviços à mesma rede para comunicação interna.

docker network ls

Lista todas as redes Docker.

docker network inspect <nome_da_rede>

Mostra detalhes de uma rede (IPs, containers conectados).

Multi-stage e Profiles

services:
  app:
    profiles:
      - dev
  tests:
    profiles:
      - test
  monitoring:
    profiles:
      - prod

Profiles permitem ativar grupos de serviços por contexto.

docker compose --profile dev up -d

Sobe apenas os serviços do profile dev.

docker compose --profile dev --profile test up -d

Sobe serviços de múltiplos profiles simultaneamente.

Variáveis de Ambiente

services:
  app:
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://user:pass@db:5432/app

Variáveis inline no compose.

services:
  app:
    env_file:
      - .env
      - .env.local

Carrega variáveis de arquivos .env (múltiplos arquivos aceitos).

docker compose --env-file .env.staging up -d

Usa um arquivo de variáveis específico ao subir os serviços.

Health Checks

services:
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

Define verificação de saúde do container com intervalo, timeout e retries.

services:
  app:
    depends_on:
      db:
        condition: service_healthy

Garante que o serviço app só inicia quando o db estiver saudável.

Limites de Recursos

services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "0.5"
        reservations:
          memory: 256M
          cpus: "0.25"
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Define limites de CPU, memória e configuração de logging por serviço.

Boas Práticas

  • Use env_file para variáveis sensíveis em vez de hardcode no compose
  • Prefira nomes explícitos com container_name para facilitar debug
  • Use depends_on com condition: service_healthy para ordem confiável de inicialização
  • Evite latest em produção — use tags fixas como postgres:16-alpine
  • Separe arquivos compose para dev e prod: docker-compose.yml + docker-compose.prod.yml
  • Configure restart: unless-stopped em produção
  • Use volumes nomeados para dados persistentes
  • Sempre defina health checks nos serviços de banco de dados
  • Use .dockerignore para reduzir contexto de build
  • Prefira imagens Alpine para menor tamanho