fabricioveronez/harness-publico

docker-practices

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

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/fabricioveronez/harness-publico --skill docker-practices

Antes 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.
Documento original del Skill

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:

  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
del mismo repositorio

Más Skills

Todos los Skills