fabricioveronez/harness-publico

docker-practices

Boas práticas, padrões de qualidade e validação para Dockerfile, imagens Docker e docker-compose.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/fabricioveronez/harness-publico --skill docker-practices

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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:

  1. Dockerfile e imagem — build e convenções de artefato
  2. Segurança — o que não pode entrar na imagem
  3. Docker Compose — orquestração local
  4. 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árioReference
Escrevendo Dockerfile do zero, decidindo quantos stages usar, ou debugando build lentoreferences/por-que-multi-stage-e-camadas.md
Em dúvida entre alpine/slim/distroless, ou imagem ficou enorme, ou falha "shared library" em runtimereferences/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 respondereferences/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 latest 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 artefatoMulti-stageGanho
Compilada (Go, Rust, C#, Java)ObrigatórioEnorme — 1 GB → 20 MB; runtime pode ser distroless ou scratch
Transpilada (TS, bundlers, Sass)ObrigatórioGrande — sai toolchain e devDependencies
Interpretada com extensões C (psycopg2, node-gyp, nokogiri)SimMé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)OpcionalPequeno — single-stage sobre base slim é aceitável
Assets estáticos → nginxObrigatórioNode 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.

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 AS para referenciar em COPY --from=
  • 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 RUN 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 .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
*.md

HEALTHCHECK

  • Defina HEALTHCHECK 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 ARG 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

  • ENTRYPOINT para o binário principal — não deve ser sobrescrito casualmente
  • CMD para argumentos default — fáceis de sobrescrever em docker run
  • Use forma exec (["cmd", "arg"]), 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
  • --no-install-recommends em apt, --no-cache em apk
  • Verifique tamanho com docker images e dive 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 — latest 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 root em runtime — crie um usuário dedicado ou use o do runtime oficial (ex.: USER node)
  • 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 ARG ou ENV para secrets — ficam gravados nas camadas e aparecem em docker history
  • Use BuildKit secrets com --mount=type=secret
  • Variáveis de runtime (senhas de banco, tokens) passam via docker run -e 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 (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.yaml como nome padrão (Compose V2) — docker-compose.yml ainda funciona mas é legado
  • Não declare version: — obsoleto no Compose V2
  • Organize em blocos: services, networks, volumes, configs, secrets
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

  • depends_on 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) — pg_isready, curl localhost, redis-cli ping
  • start_period 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 profiles 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

  • .env na 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:
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) — docker compose down preserva por padrão
  • Bind mounts para código em dev (hot reload) — não use em produção
  • :ro 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

  • compose.yaml é o arquivo base — descreve o cenário comum
  • compose.override.yaml é lido automaticamente e sobrescreve para dev (ports expostos, volumes bind, debug)
  • compose.prod.yaml 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 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.yaml 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 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ívelVerificaçãoFalha
1Linthadolint via container, com o .hadolint.yaml da skillpara
2BuildBuild do target final — se não constrói, nada mais importapara
3InspeçãoReprova: USER root ou vazio, secret em docker history, CMD/ENTRYPOINT em forma shell, base latest. Avisa: tamanho, HEALTHCHECK ausentepara / avisa
4Subidaup -d --wait — serviços atingem healthy no timeoutpara
5SustentaçãoRestartCount == 0 e status == running após ~30spara
6Respostacurl do host na porta publicada → 2xxcondicional
—Teardowndown -v no projeto isolado, em trap, inclusive em falhasempre

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:

NaturezaNíveis
Serviço HTTP1–6
Worker / consumer / cron1–5 (não expõe porta)
CLI / job batch1–3 + exit code 0 — critério invertido: container que termina é sucesso
Sem compose.yaml1–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ívelResultadoEvidência
1Lint✅hadolint exit 0, 0 findings
2Build✅--target runtime ok, imagem 66 MB
3Inspeção✅USER=app, forma exec, sem secret em history, base pinada
4Subida✅app e db healthy
5Sustentação✅RestartCount=0, running após 30s
6Resposta✅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/a com a razão (worker não expõe porta) — não some da tabela
  • Nível não executado entra como ⚠️ não executado 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

  • FROM <imagem>:latest — imprevisibilidade, builds não reprodutíveis
  • COPY . . 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 (lint, test) que ninguém consome via --target — peso morto
  • RUN apt-get install sem rm -rf /var/lib/apt/lists/* — infla layer
  • Secrets em ARG ou ENV — gravados na história da imagem
  • Rodar como root em runtime
  • Healthcheck externo (curl para outro serviço) — falha em cascata durante incidentes
  • depends_on sem condition: service_healthy quando há ordem real de inicialização
  • compose.yaml com version: — obsoleto, gera warning
  • Bind mount de node_modules/.venv do host para dentro do container — arquitetura do host pode diferir
  • Adicionar serviço de teste ao compose.yaml 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 curl nem shell
  • docker compose down -v sem project name isolado — apaga o volume de dados do desenvolvedor
  • Tratar up -d 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
from this repository

More skills

All skills