Docker Practices
Guia prescritivo de boas práticas para Dockerfile, imagens Docker e docker-compose. Aplique estas convenções diretamente ao código sem explicar cada decisão — o objetivo é consistência, segurança e performance, não ensinar conceitos.
O documento tem quatro partes:
- Dockerfile e imagem — build e convenções de artefato
- Segurança — o que não pode entrar na imagem
- Docker Compose — orquestração local
- Validação de qualidade — como verificar que o artefato está correto
Quando aprofundar
Os guias em
aprofundam o "porquê" das práticas e cobrem casos do mundo real. Carregue sob demanda quando:
| Cenário | Reference |
|---|
| Escrevendo Dockerfile do zero, decidindo quantos stages usar, ou debugando build lento | references/por-que-multi-stage-e-camadas.md
|
| Em dúvida entre alpine/slim/distroless, ou imagem ficou enorme, ou falha "shared library" em runtime | references/escolhendo-base-image.md
|
| Antes de subir imagem em produção pela primeira vez, ou alguém menciona "scan", "supply chain", "CVE" | references/seguranca-em-containers.md
|
| Montando ambiente local com banco/Redis/fila, ou sobe mas app não responde | references/praticas-docker-compose.md
|
| Executando o gate de validação, montando o , ou o gate falhou e não está claro por quê | references/validacao-de-qualidade.md
|
Parte 1 — Dockerfile e imagem
Base image
- Use tags pinadas com versão específica — nunca em produção
- Prefira variantes slim/alpine/distroless quando compatíveis com o runtime — reduzem superfície de ataque e tamanho
- Distroless para binários estáticos (Go, Rust, Java com jlink) — sem shell, sem package manager
- Alpine apenas quando a lib C (musl vs glibc) não for problema — alguns binários Python/Node precisam glibc
dockerfile
# Bom — tag pinada e slim
FROM node:20.11.1-slim
# Ruim — latest e base cheia
FROM node:latest
Decisão de multi-stage
Antes de escrever os stages, decida se precisa deles e quantos. Três eixos independentes.
Eixo 1 — vale a pena? O ganho depende de quanto o artefato final difere do necessário para produzi-lo.
| Natureza do artefato | Multi-stage | Ganho |
|---|
| Compilada (Go, Rust, C#, Java) | Obrigatório | Enorme — 1 GB → 20 MB; runtime pode ser distroless ou |
| Transpilada (TS, bundlers, Sass) | Obrigatório | Grande — sai toolchain e devDependencies |
| Interpretada com extensões C (, , ) | Sim | Médio — sai o . Atenção: os stages precisam da mesma libc, senão o do builder não carrega no runtime |
| Interpretada pura (Python puro, PHP) | Opcional | Pequeno — single-stage sobre base slim é aceitável |
| Assets estáticos → nginx | Obrigatório | Node constrói, nginx serve |
Eixo 2 — quantos stages?
- 2 (builder + runtime) — default. Não invente um terceiro sem nomear o problema que ele resolve
- 3 (deps + build + runtime) — quando dependências e código mudam em ritmos diferentes; isolar o install dá cache estável
- Extras (, ) — só se algo externo consome via . Stage não consumido é peso morto
Eixo 3 — o que atravessa o ? Só o artefato e as dependências de runtime, nunca o diretório de build inteiro.
dockerfile
# Ruim — desfaz o multi-stage
COPY --from=builder /app /app
# Bom — só o que roda
COPY --from=builder /app/dist ./dist
Heurística de parada: se o stage final contém algo que você não executaria em produção — compilador, gerenciador de pacotes, código-fonte de linguagem compilada — falta um stage. Se você não sabe explicar por que um arquivo está na imagem final, ele não deveria estar.
Multi-stage builds
- Separe estágios de build e runtime — imagem final carrega só o necessário para rodar
- Nomeie estágios com para referenciar em
- Stage final deve ser mínimo — sem compiladores, sem dev dependencies
dockerfile
FROM node:20.11.1-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20.11.1-slim AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER node
CMD ["node", "dist/index.js"]
Ordem de camadas e cache
- Instruções que mudam menos vão primeiro — cache é invalidado em cascata
- Copie manifestos de dependência antes do código-fonte, instale, depois copie o resto
- Agrupe comandos relacionados com para reduzir camadas, sem sacrificar legibilidade
dockerfile
# Bom — manifestos antes do código
COPY package*.json ./
RUN npm ci
COPY . .
# Ruim — qualquer mudança de código reinstala dependências
COPY . .
RUN npm ci
.dockerignore
- Sempre criar — arquivos desnecessários em build context degradam performance e podem vazar secrets
- Incluir: , , , , diretórios de IDE, artefatos de build local
.git
.gitignore
node_modules
npm-debug.log*
.env
.env.*
!.env.example
.vscode
.idea
dist
build
coverage
*.md
HEALTHCHECK
- Defina para imagens de serviço — orquestradores usam para rotear tráfego
- Intervalos conservadores (30s–60s) para não pressionar o app
dockerfile
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD curl -fsS http://localhost:3000/health || exit 1
Labels (OCI annotations)
- Adicione labels OCI para rastreabilidade — úteis em registries e scanners
- Passe via para não fixar valores no Dockerfile
dockerfile
ARG VERSION=dev
ARG COMMIT_SHA=unknown
LABEL org.opencontainers.image.source="https://github.com/org/repo" \
org.opencontainers.image.version="${VERSION}" \
org.opencontainers.image.revision="${COMMIT_SHA}" \
org.opencontainers.image.licenses="MIT"
ENTRYPOINT vs CMD
- para o binário principal — não deve ser sobrescrito casualmente
- para argumentos default — fáceis de sobrescrever em
- Use forma exec (), não forma shell — garante que sinais (SIGTERM) cheguem ao processo
dockerfile
ENTRYPOINT ["node"]
CMD ["dist/index.js"]
Tamanho de imagem
- Instale só o necessário — evite ferramentas de debug em runtime
- Limpe cache de package managers na mesma camada em que instalou
- em apt, em apk
- Verifique tamanho com e antes de publicar
dockerfile
RUN apt-get update && \
apt-get install -y --no-install-recommends curl ca-certificates && \
rm -rf /var/lib/apt/lists/*
Parte 2 — Segurança
Regras prescritivas abaixo. O "porquê" de cada uma, incidentes reais e o que fazer diante de um scan com 200 CVEs estão em
references/seguranca-em-containers.md
.
Procedência da imagem
- Prefira imagens oficiais ou de fornecedores confiáveis (Microsoft, Bitnami, Chainguard)
- Tag pinada não é só reprodutibilidade, é segurança — significa que o conteúdo da sua imagem muda sem você saber
- Em contexto sensível, pine por digest:
FROM node:20.11.1-slim@sha256:...
Non-root user
- Nunca rode como em runtime — crie um usuário dedicado ou use o do runtime oficial (ex.: )
- Ajuste ownership antes de mudar para non-root
dockerfile
RUN addgroup --system --gid 1001 app && \
adduser --system --uid 1001 --ingroup app app
COPY --chown=app:app . .
USER app
Secrets
- Nunca use ou para secrets — ficam gravados nas camadas e aparecem em
- Use BuildKit secrets com
- Variáveis de runtime (senhas de banco, tokens) passam via ou gerenciador de secrets, nunca via Dockerfile
dockerfile
# syntax=docker/dockerfile:1.7
RUN --mount=type=secret,id=npm_token \
NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
Scan de vulnerabilidades
- Escaneie a imagem antes de publicar (, )
- CVE em base image se resolve atualizando a base, não remendando o app
- Base menor = menos CVEs: boa parte dos achados vem de pacotes do sistema que a app nunca usa
Parte 3 — Docker Compose
Estrutura base
- Use como nome padrão (Compose V2) — ainda funciona mas é legado
- Não declare — obsoleto no Compose V2
- Organize em blocos: , , , ,
yaml
services:
api:
build: .
ports:
- "3000:3000"
environment:
DATABASE_URL: postgres://postgres:postgres@db:5432/app
depends_on:
db:
condition: service_healthy
db:
image: postgres:16.2-alpine
volumes:
- db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
retries: 10
volumes:
db-data:
depends_on com healthcheck
- simples apenas espera o container iniciar — não espera o serviço estar pronto
- Use
condition: service_healthy
para aguardar o healthcheck passar
- Todo serviço com dependências deve ter healthcheck declarado
Healthchecks em serviços
- Healthcheck local (sem depender de rede externa) — , ,
- suficiente para o serviço subir antes da primeira checagem começar a contar como falha
yaml
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 10
start_period: 10s
profiles
- Use para serviços opcionais (observability, seeders, ferramentas de dev) que não devem subir por padrão
- Ative com
docker compose --profile <name> up
yaml
services:
app:
image: myapp
grafana:
image: grafana/grafana
profiles: ["observability"]
Variáveis de ambiente
- na raiz é lido automaticamente — commitar , nunca
- Use interpolação com default e obrigatório
- Arquivos específicos por serviço via
yaml
services:
api:
env_file:
- .env.local
environment:
NODE_ENV: ${NODE_ENV:-development}
DATABASE_URL: ${DATABASE_URL:?precisa estar definida}
Volumes
- Named volumes para dados persistentes (bancos, filas) — preserva por padrão
- Bind mounts para código em dev (hot reload) — não use em produção
- para volumes que devem ser read-only
yaml
services:
api:
volumes:
- ./src:/app/src # bind mount — hot reload em dev
- /app/node_modules # evita sobrescrever node_modules do container
- configs:/app/configs:ro # named volume read-only
Override pattern
- é o arquivo base — descreve o cenário comum
- é lido automaticamente e sobrescreve para dev (ports expostos, volumes bind, debug)
- para produção, ativado com
-f compose.yaml -f compose.prod.yaml
yaml
# compose.yaml
services:
api:
image: myapp:${TAG:-latest}
# compose.override.yaml
services:
api:
build: .
volumes:
- ./src:/app/src
ports:
- "9229:9229" # debug port
Parte 4 — Validação de qualidade
Verifica o artefato Docker — build reproduz, imagem está sã, aplicação sobe e se sustenta. Não verifica a corretude do código: executar a suíte de testes do projeto é etapa anterior, de outra responsabilidade.
A validação é não-invasiva: não adiciona serviço ao
, não cria arquivo de override, não altera nada no projeto. Observa o container de fora.
Todo o gate roda sob project name isolado —
PROJ="$(basename "$PWD")-qa"
— que é o que torna o
seguro.
Quando executar — automático, sem esperar o pedido
O gate é parte do trabalho, não um extra opcional. Dispare-o no mesmo turno, sem perguntar antes, sempre que:
- criar ou alterar , , ou arquivo de override
- o usuário pedir revisão de artefatos Docker existentes — dizer "está bom" sem rodar o gate é palpite
Validar não é ação destrutiva: roda sob project name isolado e derruba tudo no
. Só interrompa para perguntar se o gate precisar mexer em algo
fora desse isolamento — parar um container do dev, liberar porta ocupada, apagar volume que não é da validação.
Quando um nível não puder rodar (daemon indisponível, build exige secret ausente, projeto sem
),
reporte o nível como não executado com o motivo e siga com os demais. Nunca silencie: nível omitido é lido como nível aprovado.
| # | Nível | Verificação | Falha |
|---|
| 1 | Lint | via container, com o da skill | para |
| 2 | Build | Build do target final — se não constrói, nada mais importa | para |
| 3 | Inspeção | Reprova: root ou vazio, secret em , / em forma shell, base . Avisa: tamanho, ausente | para / avisa |
| 4 | Subida | — serviços atingem healthy no timeout | para |
| 5 | Sustentação | e após ~30s | para |
| 6 | Resposta | do host na porta publicada → 2xx | condicional |
| — | Teardown | no projeto isolado, em , inclusive em falha | sempre |
Fail-fast entre níveis.
O nível 5 não é opcional. retorna exit 0 e imprime
para container em restart loop quando o serviço não declara
— comportamento verificado. Sem checar
, o gate aprova imagem que não roda.
Aplicabilidade por projeto:
| Natureza | Níveis |
|---|
| Serviço HTTP | 1–6 |
| Worker / consumer / cron | 1–5 (não expõe porta) |
| CLI / job batch | 1–3 + exit code 0 — critério invertido: container que termina é sucesso |
| Sem | 1–3 |
Comandos exatos, o
e as armadilhas de cada nível estão em
references/validacao-de-qualidade.md
.
Relatório de criação e validação
A entrega ao usuário termina sempre com um relatório de duas partes. É ele que transforma "criei os arquivos" em "criei e provei que funcionam".
Parte A — o que foi criado ou alterado. Um item por arquivo, cada um carregando a decisão de projeto embutida: quantos stages e por quê, base escolhida, usuário de runtime, mecanismo do healthcheck, serviços do compose e como se ordenam. Nunca só "criei o Dockerfile".
Parte B — o gate, uma linha por nível:
| # | Nível | Resultado | Evidência |
|---|
| 1 | Lint | ✅ | hadolint exit 0, 0 findings |
| 2 | Build | ✅ | ok, imagem 66 MB |
| 3 | Inspeção | ✅ | , forma exec, sem secret em , base pinada |
| 4 | Subida | ✅ | app e db |
| 5 | Sustentação | ✅ | , após 30s |
| 6 | Resposta | ✅ | → 200 |
| — | Teardown | ✅ | , idêntico antes/depois |
Regras do relatório:
- Evidência, não adjetivo — , não "container estável". O número é a prova; o adjetivo é opinião
- Nível não aplicável entra como com a razão () — não some da tabela
- Nível não executado entra como com o motivo
- Falha vem com a causa provável e o trecho de log ou comando que a evidencia, nunca só ❌
- Achados fora do escopo Docker encontrados no caminho (secret hardcoded no código, dependência de teste no requirements de produção) vão numa seção curta ao final, explicitamente marcados como não corrigidos
- Não anuncie aprovação sem a tabela — o relatório é a prova, não o resumo dela
Anti-patterns
- — imprevisibilidade, builds não reprodutíveis
- antes dos manifestos de dependência — invalida cache a cada commit
COPY --from=builder /app /app
— copiar o diretório de build inteiro desfaz o multi-stage
- Stage final com compilador, gerenciador de pacotes ou código-fonte de linguagem compilada
- Stage extra (, ) que ninguém consome via — peso morto
- sem
rm -rf /var/lib/apt/lists/*
— infla layer
- Secrets em ou — gravados na história da imagem
- Rodar como root em runtime
- Healthcheck externo (curl para outro serviço) — falha em cascata durante incidentes
- sem
condition: service_healthy
quando há ordem real de inicialização
- com — obsoleto, gera warning
- Bind mount de / do host para dentro do container — arquitetura do host pode diferir
- Adicionar serviço de teste ao do projeto só para validar — polui o artefato e valida uma configuração que não é a real
- Validar com
docker compose exec ... curl
— a imagem mínima que a skill manda construir não tem nem shell
- sem project name isolado — apaga o volume de dados do desenvolvedor
- Tratar bem-sucedido como aplicação funcionando — restart loop passa despercebido
- Entregar Dockerfile ou compose sem rodar o gate — "deve funcionar" não é validação
- Perguntar "quer que eu valide?" — o gate é isolado e não destrutivo, roda por padrão
- Relatar aprovação sem a tabela de evidências, ou omitir da tabela um nível que não rodou