Hm Deploy

/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 && 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 | 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rodrigohighermind
• Source: rodrigohighermind/highermind-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.