Como usar o Docker Compose para desenvolvimento local em 2026: guia completo

{
“@context”: “https://schema.org”,
“@type”: “TechArticle”,
“headline”: “Como usar o Docker Compose para desenvolvimento local em 2026: guia completo”,
“description”: “Master Docker Compose para desenvolvimento local em 2026 – configuração de vários serviços, hot reload, rede, volumes, segredos e paridade de produção.”,
“url”: “https://techpulsesite.com/how-to-use-docker-compose-for-local-deve-pt/”,
“datePublished”: “2026-06-28T10:35:00+00:00”,
“dateModified”: “2026-06-29T04:14:18+00:00”,
“author”: {
“@type”: “Organization”,
“name”: “TechPulse Editorial Team”,
“url”: “https://techpulsesite.com”
},
“publisher”: {
“@type”: “Organization”,
“name”: “TechPulse”,
“url”: “https://techpulsesite.com”
},
“inLanguage”: “pt”
}

{
“@context”: “https://schema.org”,
“@type”: “TechArticle”,
“headline”: “Como usar o Docker Compose para desenvolvimento local em 2026: guia completo”,
“description”: “Master Docker Compose para desenvolvimento local em 2026 – configuração de vários serviços, hot reload, rede, volumes, segredos e paridade de produção.”,
“url”: “https://techpulsesite.com/how-to-use-docker-compose-for-local-deve-pt/”,
“datePublished”: “2026-06-28T10:35:00+00:00”,
“dateModified”: “2026-06-28T18:21:08+00:00”,
“author”: {
“@type”: “Organization”,
“name”: “TechPulse Editorial Team”,
“url”: “https://techpulsesite.com”
},
“publisher”: {
“@type”: “Organization”,
“name”: “TechPulse”,
“url”: “https://techpulsesite.com”
},
“inLanguage”: “pt”
}

Docker Compor transforma o desenvolvimento local de “funciona na minha máquina” em ambientes reproduzíveis, semelhantes a produção, que cada membro da equipe pode criar em minutos. Em 2026, com o Docker Compose v2 integrado ao Docker Desktop e CLI, não há ferramenta melhor para gerenciar pilhas locais de vários serviços.

Por que Docker Compose para desenvolvimento?

• Ative Postgres, Redis, sua API e um trabalhador de fila com um comando
• Elimine “funciona na minha máquina” — todo desenvolvedor tem ambientes idênticos
• Combine a topologia do serviço de produção localmente sem executar o Kubernetes
• Alterne facilmente entre versões do Node, versões de banco de dados ou configurações de serviço

Configuração do Projeto: Aplicação Full-Stack

Criaremos uma configuração de composição para: frontend Next.js, backend FastAPI, PostgreSQL, Redis e um trabalhador Celery.

myapp/
├── docker-compose.yml
├── docker-compose.override.yml    # local dev overrides
├── frontend/
│   ├── Dockerfile
│   └── ...
├── backend/
│   ├── Dockerfile
│   └── ...
└── .env.local

Núcleo docker-compose.yml

version: "3.9"

services:
  # ── PostgreSQL ─────────────────────────────────────────────
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${DB_NAME:-myapp}
      POSTGRES_USER: ${DB_USER:-postgres}
      POSTGRES_PASSWORD: ${DB_PASS:-devpassword}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backend/scripts/init.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  # ── Redis ──────────────────────────────────────────────────
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru

  # ── FastAPI Backend ────────────────────────────────────────
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    volumes:
      - ./backend:/app                    # hot reload: source mounted
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://postgres:devpassword@db:5432/myapp
      REDIS_URL: redis://redis:6379/0
      ENV: development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

  # ── Celery Worker ──────────────────────────────────────────
  worker:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    volumes:
      - ./backend:/app
    environment:
      DATABASE_URL: postgresql://postgres:devpassword@db:5432/myapp
      REDIS_URL: redis://redis:6379/0
    depends_on: [db, redis]
    command: celery -A app.tasks worker --loglevel=info

  # ── Next.js Frontend ───────────────────────────────────────
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    volumes:
      - ./frontend:/app
      - /app/node_modules              # anonymous volume prevents override
    ports:
      - "3000:3000"
    environment:
      NEXT_PUBLIC_API_URL: http://localhost:8000
    command: npm run dev

volumes:
  postgres_data:

Dockerfile de desenvolvimento para Hot Reload

# backend/Dockerfile.dev
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
# Don't copy source — it's mounted as volume for hot reload
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--reload"]

# frontend/Dockerfile.dev
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
# Source mounted as volume; node_modules stays in container
CMD ["npm", "run", "dev"]

Substituir arquivo para personalização local

# docker-compose.override.yml (not committed to git)
# Each developer's personal overrides

services:
  backend:
    environment:
      DEBUG: "true"
      LOG_LEVEL: debug
    ports:
      - "8000:8000"
      - "5678:5678"    # debugger port

  db:
    ports:
      - "5432:5432"    # expose to host for TablePlus/DBeaver access

Docker Compose mescla automaticamentedocker-compose.override.yml com o arquivo base — não há necessidade de especificar-f.

Comandos essenciais

# Start everything
docker compose up -d

# View logs (all services)
docker compose logs -f

# View logs for one service
docker compose logs -f backend

# Run a command in a service
docker compose exec backend python manage.py migrate
docker compose exec db psql -U postgres -d myapp

# Rebuild a specific service after Dockerfile change
docker compose up -d --build backend

# Stop and remove everything (keep volumes)
docker compose down

# Stop, remove containers AND volumes (fresh slate)
docker compose down -v

# Scale a service
docker compose up -d --scale worker=3

Gerenciando segredos corretamente

# .env.local (gitignored)
DB_PASS=mylocalsecretpassword
SECRET_KEY=dev-only-not-production

# docker-compose.yml references env vars
environment:
  DB_PASS: ${DB_PASS}

# Or use Docker secrets for production-like setups
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  backend:
    secrets: [db_password]

Rede entre serviços

Os serviços no mesmo arquivo Compose se comunicam por nome de serviço. Seu back-end se conecta ao PostgreSQL emdb:5432, nãolocalhost:5432. Isso corresponde exatamente à rede de contêineres de produção:

# backend connects to other services by service name
DATABASE_URL=postgresql://postgres:pass@db:5432/myapp
REDIS_URL=redis://redis:6379/0

# NOT localhost — that would be the container itself
# NOT the host IP — that breaks portability

Verificações de integridade e dependências de serviços

services:
  backend:
    depends_on:
      db:
        condition: service_healthy    # waits for DB to pass healthcheck
      redis:
        condition: service_started    # just waits for container to start

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

Arquivos de composição de produção vs desenvolvimento

# Use specific files explicitly
docker compose -f docker-compose.yml up -d                          # dev
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d  # prod

# In production: remove volume mounts, use built images, add resource limits
# docker-compose.prod.yml
services:
  backend:
    image: myapp-backend:1.2.0    # pinned production image
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512m

Perguntas Frequentes

P: Docker Compose vs Kubernetes para desenvolvimento local?
R: Docker Compose para desenvolvimento local. Kubernetes para produção. Minikube ou k3d para testar configurações do Kubernetes localmente. O Compose é mais simples, rápido e suficiente para fluxos de trabalho de desenvolvimento.

P: Por que minha alteração de código não é refletida mesmo com montagens de volume?
R: O hot reload depende da estrutura (FastAPI –reload, servidor de desenvolvimento Next.js). Se não estiver funcionando, verifique se o caminho de montagem do volume está correto e se o diretório de trabalho do contêiner corresponde. Reinicie também o serviço:docker compose restart backend.

P: Como executo migrações de banco de dados automaticamente?
R: Adicione um comando ao seu serviço ou use um serviço de migração separado:docker compose run --rm backend alembic upgrade head. Ou adicione-o ao entrypoint.sh antes de iniciar o servidor.

P: Como compartilho dados entre serviços?
R: Através de volumes nomeados para dados de banco de dados. Através de variáveis de ambiente para configuração. Através da rede para comunicação serviço a serviço. Evite arquivos de montagem vinculada entre contêineres – em vez disso, use a API de serviço.

P: Como depuro um serviço em execução no Docker?
R: Mapeie a porta do depurador em seu arquivo de composição, configure seu IDE (VS Code’s Remote – Containers ou Python debugpy). Ou exec no contêiner:docker compose exec backend bash.

Conclusão

Docker Compose é a ferramenta definitiva para desenvolvimento multisserviço local em 2026. A configuração neste guia – arquivo de composição base + arquivo de substituição + montagens de volume adequadas + verificações de integridade – oferece paridade de produção local, recarga a quente para desenvolvimento rápido e início de um comando para novos membros da equipe. Invista de 2 a 3 horas configurando isso corretamente e economize centenas de horas de depuração “funciona na minha máquina”.