Cómo usar
- Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
- Consulta las herramientas, credenciales y entornos necesarios en el documento original.
- Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/fabricioveronez/harness-publico --skill docker-practicesAntes de empezar
- La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
- Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.
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 references/ 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 docker compose up sobe mas app não responde | references/praticas-docker-compose.md |
Executando o gate de validação, montando o .hadolint.yaml, 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
latestem 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
# Bom — tag pinada e slim
FROM node:20.11.1-slim
# Ruim — latest e base cheia
FROM node:latestDecisã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 scratch |
| Transpilada (TS, bundlers, Sass) | Obrigatório | Grande — sai toolchain e devDependencies |
Interpretada com extensões C (psycopg2, node-gyp, nokogiri) | Sim | Médio — sai o build-essential. Atenção: os stages precisam da mesma libc, senão o .so 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 (`lint`, `docs`) — só se algo externo consome via
--target. Stage não consumido é peso morto
Eixo 3 — o que atravessa o `COPY --from`? Só o artefato e as dependências de runtime, nunca o diretório de build inteiro.
# Ruim — desfaz o multi-stage
COPY --from=builder /app /app
# Bom — só o que roda
COPY --from=builder /app/dist ./distHeurí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
ASpara referenciar emCOPY --from= - Stage final deve ser mínimo — sem compiladores, sem dev dependencies
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
RUNrelacionados com&¶ reduzir camadas, sem sacrificar legibilidade
# 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
.dockerignore— arquivos desnecessários em build context degradam performance e podem vazar secrets - Incluir:
.git,node_modules,.env*,*.log, diretórios de IDE, artefatos de build local
.git
.gitignore
node_modules
npm-debug.log*
.env
.env.*
!.env.example
.vscode
.idea
dist
build
coverage
*.mdHEALTHCHECK
- Defina
HEALTHCHECKpara imagens de serviço — orquestradores usam para rotear tráfego - Intervalos conservadores (30s–60s) para não pressionar o app
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD curl -fsS http://localhost:3000/health || exit 1Labels (OCI annotations)
- Adicione labels OCI para rastreabilidade — úteis em registries e scanners
- Passe via
ARGpara não fixar valores no 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
ENTRYPOINTpara o binário principal — não deve ser sobrescrito casualmenteCMDpara argumentos default — fáceis de sobrescrever emdocker run- Use forma exec (
["cmd", "arg"]), não forma shell — garante que sinais (SIGTERM) cheguem ao processo
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
--no-install-recommendsem apt,--no-cacheem apk- Verifique tamanho com
docker imagesediveantes de publicar
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 —
latestsignifica 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
rootem runtime — crie um usuário dedicado ou use o do runtime oficial (ex.:USER node) - Ajuste ownership antes de mudar para non-root
RUN addgroup --system --gid 1001 app && \
adduser --system --uid 1001 --ingroup app app
COPY --chown=app:app . .
USER appSecrets
- Nunca use
ARGouENVpara secrets — ficam gravados nas camadas e aparecem emdocker history - Use BuildKit secrets com
--mount=type=secret - Variáveis de runtime (senhas de banco, tokens) passam via
docker run -eou gerenciador de secrets, nunca via Dockerfile
# syntax=docker/dockerfile:1.7
RUN --mount=type=secret,id=npm_token \
NPM_TOKEN=$(cat /run/secrets/npm_token) npm ciScan de vulnerabilidades
- Escaneie a imagem antes de publicar (
docker scout cves,trivy image) - 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
compose.yamlcomo nome padrão (Compose V2) —docker-compose.ymlainda funciona mas é legado - Não declare
version:— obsoleto no Compose V2 - Organize em blocos:
services,networks,volumes,configs,secrets
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
depends_onsimples apenas espera o container iniciar — não espera o serviço estar pronto- Use
condition: service_healthypara 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) —
pg_isready,curl localhost,redis-cli ping start_periodsuficiente para o serviço subir antes da primeira checagem começar a contar como falha
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 10
start_period: 10sprofiles
- Use
profilespara serviços opcionais (observability, seeders, ferramentas de dev) que não devem subir por padrão - Ative com
docker compose --profile <name> up
services:
app:
image: myapp
grafana:
image: grafana/grafana
profiles: ["observability"]Variáveis de ambiente
.envna raiz é lido automaticamente — commitar.env.example, nunca.env- Use interpolação
${VAR}com default${VAR:-default}e obrigatório${VAR:?mensagem} - Arquivos específicos por serviço via
env_file:
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) —
docker compose downpreserva por padrão - Bind mounts para código em dev (hot reload) — não use em produção
:ropara volumes que devem ser read-only
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-onlyOverride pattern
compose.yamlé o arquivo base — descreve o cenário comumcompose.override.yamlé lido automaticamente e sobrescreve para dev (ports expostos, volumes bind, debug)compose.prod.yamlpara produção, ativado com-f compose.yaml -f compose.prod.yaml
# compose.yaml
services:
api:
image: myapp:${TAG:-latest}
# compose.override.yaml
services:
api:
build: .
volumes:
- ./src:/app/src
ports:
- "9229:9229" # debug portParte 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 compose.yaml, 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 down -v 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
Dockerfile,.dockerignore,compose.yamlou 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 trap. 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 compose.yaml), 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 | hadolint via container, com o .hadolint.yaml da skill | para |
| 2 | Build | Build do target final — se não constrói, nada mais importa | para |
| 3 | Inspeção | Reprova: USER root ou vazio, secret em docker history, CMD/ENTRYPOINT em forma shell, base latest. Avisa: tamanho, HEALTHCHECK ausente | para / avisa |
| 4 | Subida | up -d --wait — serviços atingem healthy no timeout | para |
| 5 | Sustentação | RestartCount == 0 e status == running após ~30s | para |
| 6 | Resposta | curl do host na porta publicada → 2xx | condicional |
| — | Teardown | down -v no projeto isolado, em trap, inclusive em falha | sempre |
Fail-fast entre níveis.
O nível 5 não é opcional. up -d --wait retorna exit 0 e imprime Healthy para container em restart loop quando o serviço não declara HEALTHCHECK — comportamento verificado. Sem checar RestartCount, 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 compose.yaml | 1–3 |
Comandos exatos, o .hadolint.yaml 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 | ✅ | --target runtime ok, imagem 66 MB |
| 3 | Inspeção | ✅ | USER=app, forma exec, sem secret em history, base pinada |
| 4 | Subida | ✅ | app e db healthy |
| 5 | Sustentação | ✅ | RestartCount=0, running após 30s |
| 6 | Resposta | ✅ | GET / → 200 |
| — | Teardown | ✅ | down -v, docker volume ls idêntico antes/depois |
Regras do relatório:
- Evidência, não adjetivo —
RestartCount=0 após 30s, não "container estável". O número é a prova; o adjetivo é opinião - Nível não aplicável entra como
n/acom a razão (worker não expõe porta) — não some da tabela - Nível não executado entra como
⚠️ não executadocom 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
FROM <imagem>:latest— imprevisibilidade, builds não reprodutíveisCOPY . .antes dos manifestos de dependência — invalida cache a cada commitCOPY --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 (
lint,test) que ninguém consome via--target— peso morto RUN apt-get installsemrm -rf /var/lib/apt/lists/*— infla layer- Secrets em
ARGouENV— gravados na história da imagem - Rodar como root em runtime
- Healthcheck externo (curl para outro serviço) — falha em cascata durante incidentes
depends_onsemcondition: service_healthyquando há ordem real de inicializaçãocompose.yamlcomversion:— obsoleto, gera warning- Bind mount de
node_modules/.venvdo host para dentro do container — arquitetura do host pode diferir - Adicionar serviço de teste ao
compose.yamldo 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 temcurlnem shell docker compose down -vsem project name isolado — apaga o volume de dados do desenvolvedor- Tratar
up -dbem-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
