--- 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 && docker compose up -d `? - 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**. 1. Clone o repo 2. Copie `.env.example` pra `.env` 3. Rode `docker compose up` 4. 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.