name: hm-deploy
description: Validação de deploy por distribution model. Use antes de subir pra produção pela primeira vez, quando o ambiente local parou de funcionar, quando mudou infra, ou para validar que qualquer pessoa consegue subir o projeto do zero. Cobre 6 modelos distintos com checks próprios — Container/Docker, Serverless/Edge (Vercel/CF), Desktop (Electron), Mobile (Expo/RN), Library/SDK (npm/PyPI), CLI tool. Security Gate primeiro: se falha, não continua.
/hm-deploy — Validação de Deploy (v3)
Você está agora em modo deploy. Seu trabalho e garantir que o projeto está pronto pra sair do local e ir pro mundo. Ou que o ambiente local esta saudavel e reprodutivel.
Princípio central
Deploy não é o último passo. E uma camada de engenharia. Se o deploy e frágil, o produto e frágil. Se levantar o ambiente depende de conhecimento tribal, o projeto não está pronto. Segurança de deploy não é checklist final — e pré-requisito.
Quando usar
- Antes de subir pra produção pela primeira vez
- Quando o ambiente local parou de funcionar
- Quando mudou infra (novo servico, nova porta, nova variavel)
- Pra validar que qualquer pessoa consegue subir o projeto do zero
- Depois de uma refatoracao significativa
O que você valida
0. Distribution Model (PRIMEIRO — define os checks aplicaveis)
Identifique o modelo de distribuicao antes de qualquer auditoria. Cada modelo tem checks próprios — pular o que não se aplica e parte do trabalho.
| Modelo | Exemplos | Checks aplicaveis |
|---|
| Container/Docker | API com Postgres+Redis, monolitos | DOMÍNIO 1 inteiro, secrets em compose, multi-stage |
| Serverless/Edge | Vercel, Netlify, CF Workers | Cold start, env vars no dashboard, edge runtime, build output |
| Desktop (Electron) | macOS .app, Windows .exe | electron-builder config, contextIsolation, nodeIntegration false, code signing, secrets embedded warning, auto-update |
| Mobile (Expo/RN) | Apps na App Store / Play | EAS build, certs, App Transport Security, OTA updates, native modules ABI |
| Library/SDK | npm package, PyPI | semver, exports, types, lock file, supply chain, provenance, sem ANY no surface |
| CLI tool | Binario standalone | Cross-platform builds, signing, install path, autoupdate via release |
Pula seções que não se aplicam. Ex: app Electron NÃO tem .dockerignore — pule DOMÍNIO 1.1. Library NPM NÃO tem migrations — pule DOMÍNIO 3.
Checks por modelo (além do Security Gate)
Container/Docker (cobre DOMÍNIO 1 inteiro abaixo)
Serverless/Edge:
- Build output dentro do limite (Vercel: 50MB unzipped por function)?
- Cold start <1s pra rotas criticas? Se não, considerar warming ou edge runtime.
- Env vars sensíveis no dashboard, NUNCA em
next.config.js?
- Edge runtime constraints respeitadas (sem
node: modules, sem fs, sem better-sqlite3)?
- ISR/cache headers configurados?
- Domain + SSL configurados pré-deploy?
Desktop (Electron):
contextIsolation: true + nodeIntegration: false + sandbox: true (default em Electron 28+)?- Sem preload script expondo APIs perigosas? Se tem preload, exporta apenas APIs minimas via
contextBridge?
webSecurity: true (NUNCA false)?- Code signing configurado (mesmo que sem identity em dev — documentar warning)?
- Auto-update via electron-updater? Ou ship manual?
- Secrets bundled na .app:
.env.local ou similar copiado pro Resources/ — distribuir publicamente vaza secrets. Documentar.
- Native modules (better-sqlite3, sharp) com ABI Electron rebuild correto?
app.disableHardwareAcceleration() se necessario?setAppUserModelId (Windows) e bundle id (macOS) corretos?- Versão Electron com zero CVEs HIGH?
bun audit / npm audit limpo?
Mobile (Expo/RN):
- EAS build profile (development, preview, production) configurado?
- Certificados/provisioning iOS via EAS?
- Android keystore versionado em local seguro (NÃO no repo)?
app.json com bundle ID, version, build number corretos?- Permissions declaradas (camera, location, etc) com justificativa?
- App Transport Security: zero
NSAllowsArbitraryLoads = true em prod?
- OTA updates configuradas (
expo-updates) ou versão nativa pinada?
- Native modules com versões compatíveis com SDK Expo?
- Firebase/analytics SDKs com config files certos por env?
Library/SDK:
- Lock file commitado (package-lock.json, poetry.lock)?
package.json com exports map definido (ESM + CJS quando aplicavel)?- Types em
.d.ts ou types field correto?
files field limita o que vai pro registry (sem node_modules, sem .env, sem testes)?- Zero
any no surface público?
- Semver respeitado: breaking change = major bump?
- README com installation + quick start + API reference?
- Provenance (npm provenance ou cosign) configurado pra supply chain?
- CI pública via OIDC (sem NPM_TOKEN secreto)?
- Tag git assinada pra cada release?
CLI tool:
- Cross-platform builds (Linux x64/arm64, macOS x64/arm64, Windows x64)?
- Signed binaries (Apple Developer ID, Authenticode)?
- Install path padroniza (Homebrew fórmula, Scoop manifest, .deb, AUR)?
- Help text (
--help, -h) cobre todos os comandos?
- Versão reportada via
--version?
- Update check opt-in (sem auto-update silencioso)?
- Logs vao pra path padrão do OS (XDG_STATE_HOME, ~/Library/Logs, %APPDATA%)?
1. Security Gate (Container — pular se modelo != Docker)
Esta seção é bloqueante. Se qualquer item CRÍTICO falhar, o deploy NÃO está pronto. Não importa se tudo mais funciona.
| Check | Criterio | Severidade |
|---|
.dockerignore | Existe em CADA servico com Dockerfile. Exclui: .env, .env.*, .git, node_modules, __pycache__, .venv, .next | CRÍTICO — sem isso, secrets vazam nas layers da imagem Docker. Qualquer pessoa com acesso a imagem extrai .env |
| Dockerfile prod-ready | Multi-stage build. Sem gcc/dev-headers na imagem final. Sem npm run dev. Sem --reload. Sem --debug. | CRÍTICO — dev server em produção = hot reload instável + source maps expostos + info leak |
| Non-root user | Container roda como user não-root (USER appuser) | ALTO — se o container for comprometido, atacante tem root |
| Build secrets | Nenhum secret em Dockerfile (COPY, ARG, ENV com valores reais) | CRÍTICO — visível em docker history, irrecuperavel |
| Secrets em compose | docker-compose.yml usa ${VAR} ou env_file, nunca valores literais de secrets | CRÍTICO — compose commitado no git = secrets públicos |
| Entrypoint separado | dev (com --reload) e prod (sem --reload) sao entrypoints diferentes | ALTO — um único entrypoint tenta servir dois propositos e falha em ambos |
| Dependency audit | Zero CVEs HIGH/CRITICAL em dependências (npm audit, pip audit) | ALTO — vulnerabilidade conhecida e porta aberta |
| CORS | Configurável via env var. Nunca * em produção. Nunca hardcoded localhost. | ALTO — CORS * permite qualquer origem fazer requests autenticados |
| Swagger/Debug | /docs, /redoc, debug mode desabilitados quando APP_ENV != development | ALTO — endpoints de documentação expoe toda a API surface |
Se .dockerignore não existe: PARA TUDO. Cria antes de continuar a validação.
1. Docker & Containers
Subida:
docker compose up sobe todos os servicos sem erro?- Todos os containers ficam healthy? (não só running — healthy)
- A ordem de dependência esta correta? (banco antes da API, etc)
- Logs dos containers mostram startup limpo?
Rebuild:
- Mudancas de código sao refletidas apos
docker compose build <service> && docker compose up -d <service>?
- O Dockerfile usa multi-stage build?
- Cache de layers esta otimizado? (deps antes de code copy)
- Imagem final não tem ferramentas de dev desnecessarias?
- Tamanho da imagem final e razoável? (Python slim < 200MB, Node alpine < 150MB)
Dados sagrados:
- Volumes sao nomeados (nunca anonymous)?
docker compose down (sem -v) preserva todos os dados?- Dados do banco sobrevivem a rebuild de container?
- Se tem dados de produção local, estao protegidos contra
down -v?
2. Environment & Configuração
.env.example existe e tem TODAS as variaveis necessarias?- Nenhum secret esta hardcoded no código ou no docker-compose.yml?
- Variaveis sensíveis estao marcadas como tal no .env.example? (com
change-me ou your-key-here)
- Valores padrão fazem sentido pra dev local?
- Ports estao documentados e não colidem com outros projetos?
Checklist de ports:
Manter um registro vivo dos ports usados por todos os projetos do mesmo ecossistema que rodam em paralelo na máquina do dev. Cada projeto novo deve consultar e reservar ports que não colidem.
Estrutura típica de port allocation:
| Projeto | API/Backend | Web/Frontend | Postgres | Redis | Outros (MinIO/S3, etc) |
|---|
| 8000 | 3000 | 5432 | 6379 | — |
| 8001 | 3001 | 5433 | 6380 | — |
| 8002 | 3002 | 5434 | 6381 | MinIO 9000-9001 |
Faixa sugerida pra novo projeto: API 8000+N, Web 3000+N, Postgres 5432+N, Redis 6379+N — onde N e o próximo livre.
Anti-patterns:
- Dois projetos disputando porta 5432 ou 3000.
- Ports hardcoded em código (deve ser env var).
- Ports diferentes em
.env.example vs docker-compose.yml.
3. Database & Migrations
- Migrations rodam automaticamente no boot do container?
- Migrations estao em ordem e não tem gaps?
- Nenhuma migration e destrutiva sem ser reversível?
- Schema atual reflete todas as migrations aplicadas?
- Conexão do app com o banco funciona logo apos subir?
4. Health & Monitoramento
- Endpoint de health check existe? (
/health ou /api/health)
- Health check retorna status dos servicos dependentes (banco, cache, etc)?
- Health check NÃO retorna só
{"status": "ok"} — verifica conexão real com DB e Redis
- Logs sao estruturados e úteis (não verbose demais)?
- Erros sao logados com contexto suficiente pra debuggar?
5. Reprodutibilidade
O teste definitivo: clone limpo.
- Clone o repo
- Copie
.env.example pra .env
- Rode
docker compose up
- O projeto funciona?
Se qualquer passo extra é necessário, esta faltando documentação ou automação.
6. Segurança de deploy (checklist complementar)
Além do Security Gate (seção 0), verificar:
- Nenhum port desnecessario exposto
- HTTPS configurado (se produção/homologacao)
- Secrets não estao nos logs de build
.env esta no .gitignore- Rate limiting em endpoints públicos
- Security headers configurados (X-Content-Type-Options, X-Frame-Options, etc.)
- Logs não contem secrets, tokens, ou senhas
7. Scripts & DX
- Existe um README ou ARCHITECTURE.md com instrucoes de setup?
- O setup é um comando (ou no máximo dois)?
- Scripts de desenvolvimento estao documentados? (como rodar testes, como rebuildar, etc)
- Makefile ou scripts de conveniencia existem se necessario?
Formato do output
SECURITY GATE
[Check]: PASSED/FAILED (detalhes)
Gate: PASSED / BLOCKED (N criticos, M altos)
CONTAINERS
[Servico]: healthy/unhealthy (detalhes)
Build: OK/FALHOU (detalhes)
Dados: protegidos/em risco (detalhes)
ENVIRONMENT
.env.example: completo/incompleto (variaveis faltando)
Secrets: seguros/expostos (detalhes)
Ports: OK/conflito (detalhes)
DATABASE
Migrations: OK/falhou (detalhes)
Conexão: OK/falhou
Dados persistentes: sim/não
HEALTH
Endpoint: existe/não existe
Servicos: todos healthy/X unhealthy
REPRODUTIBILIDADE
Clone limpo: funciona/falha no passo X
SEGURANÇA COMPLEMENTAR
[Check]: OK/issue (detalhes)
VEREDICTO
Pronto pra deploy / BLOQUEADO — X criticos, Y altos pra resolver primeiro
Para auditoria de segurança completa (OWASP ASVS, LLM, multi-tenant, business logic), usar /hm-security apos o deploy estar funcional.
Regras
- Security Gate é a PRIMEIRA coisa que roda. Se falha, não continua.
- Nunca assuma que "funciona na minha máquina" e suficiente
- Dados sao sagrados. Se a validação mostra risco de perda de dados, é CRÍTICO.
- Todo finding tem fix especifico. Não só "configure melhor."
- Se o projeto não sobe do zero com um comando, é finding.
- Se um secret está exposto, é CRÍTICO. Sem exceção.
- Se
.dockerignore não existe, é CRÍTICO. Ponto.
- Se Dockerfile roda dev server ou --reload, é CRÍTICO. Ponto.
- Se container roda como root, é ALTO. Ponto.
- Teste o clone limpo mentalmente (ou de fato). Cada passo manual e divida técnica.
- O padrão: um engenheiro novo entra no time na segunda-feira e tem o projeto rodando antes do almoco.
