padrões-docker

Padrões Docker

Práticas recomendadas para Docker e Docker Compose no desenvolvimento conteinerizado.

Docker Compose para Desenvolvimento Local

Pilha Web Padrão

# docker-compose.yml
services:
  app:
    build:
      context: .
      target: dev                     # Use o estágio dev do Dockerfile multi-estágio
    ports:
      - "3000:3000"
    volumes:
      - .:/app                        # Montagem bind para hot reload
      - /app/node_modules             # Volume anônimo -- preserva as dependências do contêiner
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev
      - REDIS_URL=redis://redis:6379/0
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app_dev
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data

  mailpit:                            # Teste de email local
    image: axllent/mailpit
    ports:
      - "8025:8025"                   # Interface Web
      - "1025:1025"                   # SMTP

volumes:
  pgdata:
  redisdata:

Dockerfile de Desenvolvimento vs Produção

# Estágio: dependências
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Estágio: dev (hot reload, ferramentas de depuração)
FROM node:22-alpine AS dev
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "run", "dev"]

# Estágio: build
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm prune --production

# Estágio: produção (imagem mínima)
FROM node:22-alpine AS production
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser
COPY --from=build --chown=appuser:appgroup /app/dist ./dist
COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=build --chown=appuser:appgroup /app/package.json ./
ENV NODE_ENV=production
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]

Arquivos de Override

# docker-compose.override.yml (carregado automaticamente, configurações apenas para dev)
services:
  app:
    environment:
      - DEBUG=app:*
      - LOG_LEVEL=debug
    ports:
      - "9229:9229"                   # Depurador Node.js

# docker-compose.prod.yml (explícito para produção)
services:
  app:
    build:
      target: production
    restart: always
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

# Desenvolvimento (carrega override automaticamente)
docker compose up

# Produção
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Redes

Descoberta de Serviços

Serviços na mesma rede Compose se resolvem pelo nome do serviço:

# Do contêiner "app":
postgres://postgres:postgres@db:5432/app_dev    # "db" resolve para o contêiner db
redis://redis:6379/0                             # "redis" resolve para o contêiner redis

Redes Personalizadas

services:
  frontend:
    networks:
      - frontend-net

  api:
    networks:
      - frontend-net
      - backend-net

  db:
    networks:
      - backend-net              # Apenas acessível pela api, não pelo frontend

networks:
  frontend-net:
  backend-net:

Expondo Apenas o Necessário

services:
  db:
    ports:
      - "127.0.0.1:5432:5432"   # Apenas acessível do host, não da rede
    # Omita portas completamente em produção -- acessível apenas dentro da rede Docker

Estratégias de Volume

volumes:
  # Volume nomeado: persiste entre reinicializações do contêiner, gerenciado pelo Docker
  pgdata:

  # Montagem bind: mapeia diretório do host para o contêiner (para desenvolvimento)
  # - ./src:/app/src

  # Volume anônimo: preserva conteúdo gerado pelo contêiner da substituição da montagem bind
  # - /app/node_modules

Padrões Comuns

services:
  app:
    volumes:
      - .:/app                   # Código fonte (montagem bind para hot reload)
      - /app/node_modules        # Protege node_modules do contêiner do host
      - /app/.next               # Protege cache de build

  db:
    volumes:
      - pgdata:/var/lib/postgresql/data          # Dados persistentes
      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql  # Scripts de inicialização

Segurança de Contêineres

Endurecimento de Dockerfile

# 1. Use tags específicas (nunca :latest)
FROM node:22.12-alpine3.20

# 2. Execute como não-root
RUN addgroup -g 1001 -S app && adduser -S app -u 1001
USER app

# 3. Remova capacidades (no compose)
# 4. Sistema de arquivos raiz somente leitura, quando possível
# 5. Sem segredos nas camadas da imagem

Segurança no Compose

services:
  app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
      - /app/.cache
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE          # Apenas se necessário para vincular portas < 1024

Gerenciamento de Segredos

# BOM: Use variáveis de ambiente (injetadas em tempo de execução)
services:
  app:
    env_file:
      - .env                     # Nunca commit .env no git
    environment:
      - API_KEY                  # Herda do ambiente do host

# BOM: Segredos do Docker (modo Swarm)
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  db:
    secrets:
      - db_password

# RUIM: Hardcoded na imagem
# ENV API_KEY=sk-proj-xxxxx      # NUNCA FAÇA ISSO

Harnesses de Instalação CLI Seguros

Use contêineres para testar o comportamento do instalador em cópias descartáveis do projeto sem permitir que o teste modifique a cópia fonte original.

Respeite o Limite da Plataforma

• Execute contêineres reais para distribuições Linux, como Debian e Ubuntu.
• macOS não pode ser executado como contêiner Docker porque o Docker compartilha o kernel Linux. Execute o mesmo ponto de entrada de teste sem shell nativamente no macOS.
• Contêineres Windows exigem um motor Docker Windows. Execute lógica independente de plataforma em um runner CI nativo do Windows e reserve contêineres Windows para um host Windows.
• Mantenha uma matriz CI nativa de Ubuntu/macOS/Windows para caminhos específicos do host, shims de comando, aspas e comportamento do sistema de arquivos.

Não afirme que um contêiner Linux valida o comportamento do macOS ou Windows.

Aplique o Contrato de Isolamento

• Fixe as imagens base por digest imutável e fixe as versões CLI instaladas.
• Execute como UID/GID numérico não-root quando os nomes de conta da distribuição diferirem.
• Monte o repositório e o projeto fonte como somente leitura.
• Copie o projeto fonte para um workspace tmpfs gravável antes de qualquer mutação.
• Monte /workspace com noexec, UID/GID 1000 e mode=0700 para que apenas o usuário do contêiner possa inspecionar os dados do projeto.
• Mantenha o cache executável do npm e npx em NPM_CONFIG_CACHE=/tmp/npm-cache na montagem executável /tmp. Seu tamanho padrão é 2 GiB e pode ser ajustado com ECC_TMPFS_SIZE; ECC_WORKSPACE_SIZE controla separadamente a montagem do workspace privado.
• Defina read_only: true, no-new-privileges:true, cap_drop: [ALL] e um pids_limit finito.
• Mantenha os serviços CLI reais padrão em network_mode: none. Adicione acesso à rede apenas por meio de um serviço opt-in visivelmente nomeado para uma sessão autenticada do provedor; nunca torne isso um padrão acidental impulsionado pelo ambiente.
• Crie apenas os caminhos temporários graváveis de que a ferramenta precisa.
• Não passe credenciais do host para o contêiner por padrão.
• Padrão para uma execução a seco (dry-run) e coloque na lista de permissões apenas os modos explícitos dry-run, install, plugin e shell.
• Use arrays de argumentos ou spawnSync(..., { shell: false }) para runners multiplataforma. Nunca interpole caminhos de projeto em um comando shell.

Exercite o Harness de Configuração do Plugin ECC

Use docker/plugin-setup/compose.yaml como a implementação de referência. Ele fornece:

• fixture-tests para o conjunto focado de manifesto de instalação, alvo e executor.
• real-cli para a imagem Linux genérica baseada em Debian fixada.
• real-cli-ubuntu para a imagem Ubuntu fixada.

Valide o modelo Compose antes de construir:

docker compose -f docker/plugin-setup/compose.yaml config --quiet

Construa ambas as imagens Linux reais:

docker compose -f docker/plugin-setup/compose.yaml \
  build real-cli real-cli-ubuntu

Execute o fluxo padrão seguro em cada imagem:

docker compose -p ecc-plugin-debian-test \
  -f docker/plugin-setup/compose.yaml \
  run --rm -T real-cli dry-run

docker compose -p ecc-plugin-ubuntu-test \
  -f docker/plugin-setup/compose.yaml \
  run --rm -T real-cli-ubuntu dry-run

A execução a seco executa o contrato de comando público atual:

ecc install --profile core --target claude-project --dry-run --json

Antes desse comando ser executado, o contêiner cria um artefato npm empacotado localmente a partir do checkout somente leitura com npm pack --ignore-scripts. Ele extrai o tarball auto-criado em /tmp, valida o nome do pacote ecc-universal, os manifestos de instalação necessários e o mapeamento bin.ecc do package.json confinado, então invoca o executável ecc extraído. O tempo de execução permanece em network_mode: none, não executa scripts de ciclo de vida do pacote e não depende do node_modules do host; suas dependências de produção exatas e fixadas já estão presentes na imagem.

O harness rejeita um plano vazio, um alvo diferente de claude-project, qualquer operação fora de /workspace/project/.claude ou qualquer execução a seco que crie o diretório alvo. install realiza a aplicação isolada duas vezes, verifica seu estado de instalação gerenciado, lista o alvo instalado e executa doctor.

Inicie, Abra, Reconecte e Limpe uma Sessão Nomeada

Inicie um contêiner destacado sem --rm para que sair do terminal não remova a sessão:

docker compose -p ecc-plugin-session \
  -f docker/plugin-setup/compose.yaml \
  run --detach --name ecc-plugin-shell real-cli shell

O contêiner copia a fixture somente leitura para o diretório privado estável /workspace/project. Confirme que está em execução e, em seguida, emita o lado Docker do contrato de dados do terminal-opener v1:

docker inspect --format '{{.State.Running}}' ecc-plugin-shell
node docker/plugin-setup/interactive-plan.js \
  --container ecc-plugin-shell \
  --workdir /workspace/project \
  --json \
  -- bash

O resultado JSON tem exatamente um limite executable e argv (além de contractVersion: 1): o executável é docker e argv começa com exec, -it e -w. Passe esses dados para o skill separado do terminal-opener quando ele estiver instalado. Este harness Docker deliberadamente não importa um adaptador de terminal, interpola um comando shell ou gerencia um processo GUI do host. Até lá, abra o mesmo PTY no terminal do host atual diretamente:

docker exec -it -w /workspace/project ecc-plugin-shell bash

Saia do shell sem parar o contêiner destacado. Reconecte com o mesmo comando docker exec -it. Quando terminar, remova o contêiner nomeado exato e seus recursos do projeto Compose:

docker rm --force ecc-plugin-shell
docker compose -p ecc-plugin-session \
  -f docker/plugin-setup/compose.yaml \
  down --remove-orphans

As credenciais do host estão ausentes por padrão e os diretórios de credenciais nunca são montados. O serviço padrão também não tem acesso à rede. Quando uma sessão autenticada do provedor realmente precisar de uma rede, construa real-cli primeiro e então opte ativamente com docker compose --profile networked run real-cli-networked shell. Prefira autenticar dentro dessa sessão descartável. Se uma execução de CI precisar herdar uma credencial de ambiente do host, torne essa opção ativa na invocação com uma flag explícita --env NAME do Compose, entenda que o valor é inspecionável e pode ser exfiltrado durante a vida útil do contêiner e remova o contêiner nomeado exato imediatamente após.

Execute o mesmo conjunto focado nativamente no host:

npm run test:plugin-setup-platform

Inspecione a identidade e o ambiente produzidos antes de confiar na imagem:

docker image inspect ecc-plugin-setup:debian ecc-plugin-setup:ubuntu

Limpe cada projeto de teste nomeado sem excluir volumes ou imagens não relacionados:

docker compose -p ecc-plugin-debian-test \
  -f docker/plugin-setup/compose.yaml down --remove-orphans
docker compose -p ecc-plugin-ubuntu-test \
  -f docker/plugin-setup/compose.yaml down --remove-orphans

.dockerignore

node_modules
.git
.env
.env.*
dist
coverage
*.log
.next
.cache
docker-compose*.yml
Dockerfile*
README.md
tests/

Depuração

Comandos Comuns

# Visualizar logs
docker compose logs -f app           # Seguir logs do app
docker compose logs --tail=50 db     # Últimas 50 linhas do db

# Executar comandos no contêiner em execução
docker compose exec app sh           # Shell no app
docker compose exec db psql -U postgres  # Conectar ao postgres

# Inspecionar
docker compose ps                     # Serviços em execução
docker compose top                    # Processos em cada contêiner
docker stats                          # Uso de recursos

# Reconstruir
docker compose up --build             # Reconstruir imagens
docker compose build --no-cache app   # Forçar reconstrução completa

# Limpar
docker compose down                   # Parar e remover contêineres
docker compose down -v                # Também remover volumes (DESTRUTIVO)
docker system prune                   # Remover imagens/contêineres não utilizados

Depuração de Problemas de Rede

# Verificar resolução DNS dentro do contêiner
docker compose exec app nslookup db

# Verificar conectividade
docker compose exec app wget -qO- http://api:3000/health

# Inspecionar rede
docker network ls
docker network inspect <projeto>_default

Anti-Padrões

# RUIM: Us...