Deploy

Este guia cobre todos os procedimentos de deploy do Neemias: Worker (backend), Cloudflare Pages (frontend + docs), migrações D1 e CI/CD automatizado.

Visão geral

Camada	Plataforma	Comando
Backend (Worker)	Cloudflare Workers	pnpm deploy:worker
Frontend (SPA)	Cloudflare Pages	pnpm build:app && wrangler pages deploy app/dist (online-only: pnpm build:online — guards the ON flag)
Docs (VitePress)	Cloudflare Pages	pnpm deploy:docs
Database (D1)	Cloudflare D1	pnpm db:migrate:local / db:migrate:remote

Deploy rápido (script único)

O script scripts/deploy.sh automatiza o fluxo completo — testes, build e deploy:

./scripts/deploy.sh          # dev (padrão)
./scripts/deploy.sh staging  # staging
./scripts/deploy.sh prod     # produção

O script executa:

1. pnpm -r test — todos os testes do monorepo
2. NODE_ENV=production DEPLOY_ENV=$ENV pnpm build:app — build do frontend; para ENV=prod o script adiciona VITE_ONLINE_ONLY=true e roda bash scripts/verify-online-build.sh (guarda #703 — falha se o flag foi omitido)
3. npx wrangler deploy — deploy do Worker
4. npx wrangler pages deploy app/dist — deploy do frontend

Deploy do Worker

pnpm deploy:worker

Este comando invoca o wrangler deploy para publicar o Worker no Cloudflare. O Worker fica disponível no domínio configurado no wrangler.toml.

Deploy da documentação

pnpm deploy:docs

O script scripts/deploy-docs.sh:

1. Executa pnpm docs:build para gerar o build VitePress com OpenAPI + TypeDoc
2. Publica docs/.vitepress/dist via wrangler pages deploy --project-name neemias-docs

Migrações D1

As migrações do banco de dados D1 são gerenciadas com Wrangler:

Comando	Descrição
pnpm db:migrate:local	Aplica migrações no D1 local (--local)
pnpm db:migrate:remote	Aplica migrações no D1 remoto (produção)

As migrações ficam no diretório migrations/ e são aplicadas sequencialmente. Certifique-se de testar as migrações localmente antes de executar no ambiente remoto.

Seed de dados

O seed popula o banco com dados de demonstração (150 alunos por padrão — SEED_STUDENT_COUNT —, 7 turmas, 20 núcleos, 4 slots de turma, 8 semanas de presença). Não executa em produção.

pnpm db:seed

A guarda de seed (__DEPLOY_ENV__) impede a execução quando DEPLOY_ENV=production. Veja Environments para detalhes sobre a matriz de ambientes.

CI/CD (GitHub Actions)

Instância	Workflow	Trigger
Demo (app.neemias.app / api.neemias.app)	deploy-demo.yml	push em main (automático) ou workflow_dispatch
IJCP (ijcp.neemias.app / api-ijcp.neemias.app)	deploy-ijcp.yml	tag ijcp-v* ou workflow_dispatch

Ambos rodam no runner auto-hospedado e executam: migrações D1 → deploy do Worker → build do frontend → deploy no Cloudflare Pages → smoke check de health.

Para disparar um deploy do IJCP, crie e envie uma tag:

git tag -s ijcp-v1.0.0 -m "deploy ijcp v1.0.0"
git push origin ijcp-v1.0.0

Ambientes

O Neemias utiliza três ambientes controlados pela variável build-time DEPLOY_ENV (que vira __DEPLOY_ENV__ no bundle — não existe VITE_DEPLOY_ENV):

Ambiente	DEPLOY_ENV	Seed	URL	Backend API
Dev (local)	dev	✅ Full	localhost:5173	(none — offline-only)
Demo (public)	production	✅ Demo	app.neemias.app	api.neemias.app
IJCP (prod)	production	❌ Skip	ijcp.neemias.app	api-ijcp.neemias.app

Consulte Environments para configuração detalhada dos ambientes, secrets do Cloudflare Pages e fluxo de dados.

Instância IJCP (primeira produção real)

ijcp.neemias.app (frontend) + api-ijcp.neemias.app (Worker) é a primeira instância de produção real (o app.neemias.app é a demo pública — ver environments.md). Tudo dela é dedicado: Worker api-ijcp (workers/wrangler.ijcp.toml), D1 ijcp, R2 ijcp-uploads, Pages neemias-ijcp, secret AUTH_JWT_SECRET próprio, licença LICENSE (módulos nucleus/volunteers) e email transacional via Resend (RESEND_API_KEY secret; RESEND_FROM_EMAIL=contato@neemias.app — domínio verificado em resend.com).

Deploy manual (equivalente ao que o workflow deploy-ijcp.yml faz):

# 1. Migrações (D1 remoto)
npx wrangler d1 migrations apply ijcp --remote --config workers/wrangler.ijcp.toml

# 2. Worker
npx wrangler deploy --config workers/wrangler.ijcp.toml

# 3. Secret (só no primeiro deploy — rotacionar derruba todas as sessões)
echo "$AUTH_JWT_SECRET" | npx wrangler secret put AUTH_JWT_SECRET --config workers/wrangler.ijcp.toml

# 4. Frontend
DEPLOY_ENV=production VITE_BACKEND_URL=https://api-ijcp.neemias.app VITE_DEMO_MODE=false VITE_ONLINE_ONLY=true pnpm build:app
# Release hardening (#703): fails the release if the ON flag was dropped.
bash scripts/verify-online-build.sh
npx wrangler pages deploy app/dist --project-name neemias-ijcp --branch main

O deploy automatizado é feito por .github/workflows/deploy-ijcp.yml (trigger: tags ijcp-v* ou workflow_dispatch), rodando no runner auto-hospedado com os secrets CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN e IJCP_AUTH_JWT_SECRET.

---

Fonte: README.md, scripts/deploy-docs.sh