From 8b1715a3da6a70a4cc64068a7b39c3842612762b Mon Sep 17 00:00:00 2001 From: Esdras Renan Date: Wed, 8 Oct 2025 14:54:38 -0300 Subject: [PATCH] docs: add setup history (pitfalls & decisions) and link from README --- README.md | 3 +- docs/SETUP-HISTORICO.md | 89 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 docs/SETUP-HISTORICO.md diff --git a/README.md b/README.md index df362ab..c254384 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,8 @@ Aplicação Next.js 15 com Convex e Better Auth para gestão de tickets da Rever > Se o CLI perguntar sobre configuração do projeto Convex, escolha criar um novo deployment local (opção padrão) e confirme. As credenciais são armazenadas em `.convex/` automaticamente. ### Deploy em produção (Traefik + Convex self‑hosted) -- Guia completo: consulte `docs/OPERACAO-PRODUCAO.md:1`. +- Guia completo: `docs/OPERACAO-PRODUCAO.md:1`. +- Histórico de setup/decisões: `docs/SETUP-HISTORICO.md:1`. - Stack Swarm: `stack.yml:1` (roteado por Traefik, rede `traefik_public`). ### Variáveis de ambiente diff --git a/docs/SETUP-HISTORICO.md b/docs/SETUP-HISTORICO.md new file mode 100644 index 0000000..585ce42 --- /dev/null +++ b/docs/SETUP-HISTORICO.md @@ -0,0 +1,89 @@ +# Histórico de Setup e Decisões — Sistema de Chamados + +> Registro das etapas realizadas, problemas encontrados e decisões tomadas para colocar o projeto em produção (Traefik + Swarm + Convex self‑hosted) com CI/CD via runner self‑hosted. + +## Arquitetura final +- Frontend Next.js (app) em `tickets.esdrasrenan.com.br`. +- Convex self‑hosted (backend realtime) em `convex.esdrasrenan.com.br`. +- Traefik no Docker Swarm (rede `traefik_public`) roteando por hostname (HTTPS/LE). +- Banco Prisma (SQLite) persistente via volume `sistema_db`. +- Estado do Convex persistente via volume `convex_data`. +- Runner GitHub Actions self‑hosted na VPS (usuário `renan`). + +## Mudanças no repositório +- `stack.yml` — Stack Swarm (web + convex_backend + convex_dashboard opcional). +- `.env.example` e `apps/desktop/.env.example` — exemplos de ambiente. +- `.github/workflows/ci-cd-web-desktop.yml` — pipeline de deploy web + desktop + deploy do Convex. +- `docs/OPERACAO-PRODUCAO.md` — runbook de operação (deploy, seeds, CI/CD, troubleshooting). +- `docs/SETUP-HISTORICO.md` — este histórico. +- `pnpm-workspace.yaml` — restrito a `packages: ['.']` para evitar o apps/desktop no deploy (corrige lockfile/CI). +- `scripts/deploy-from-git.sh` — fallback de deploy pull‑based na VPS (sem Actions). + +## Gestão de .env +- `.env` não é commitado; usamos o arquivo local na VPS: `/srv/apps/sistema/.env`. +- Workflow atualizado para NÃO apagar `.env` no destino (rsync com filtros `protect`). +- Valor com espaços deve ter aspas: `MAILER_SENDER_EMAIL="Nome "`. +- Em self‑hosted, comentar `CONVEX_DEPLOYMENT`, e usar `NEXT_PUBLIC_CONVEX_URL=https://convex...`. + +## Stack (Traefik/Swarm) +- Binds absolutos (Portainer/Swarm exigem): `/srv/apps/sistema:/app`. +- Volumes: `sistema_db` → `/app/data` (SQLite), `convex_data` → `/convex/data`. +- Labels Traefik por hostname; WebSocket do Convex funciona via TLS. + +## Convex self‑hosted +- Evitamos `convex dev` no Swarm (CLI interativo). Adotada imagem oficial `ghcr.io/get-convex/convex-backend`. +- Geração de Admin Key dentro do container: `./generate_admin_key.sh`. +- Publicação de functions com `pnpm exec convex deploy` via container Node (`CONVEX_SELF_HOSTED_URL` + `CONVEX_SELF_HOSTED_ADMIN_KEY`). +- Adicionado `convex_dashboard` opcional (DNS `convex-admin.*`). + +## CI/CD (GitHub Actions) +- Runner self‑hosted `vps-sistema` com labels `self-hosted, linux, vps`. +- Job Deploy (web) roda sempre em push para `main`. +- Job Deploy Convex functions roda apenas quando arquivos em `convex/**` mudam (paths-filter). +- rsync com `--filter='protect .env*'` para preservar `.env` local. +- Secrets no repositório: `CONVEX_SELF_HOSTED_URL`, `CONVEX_SELF_HOSTED_ADMIN_KEY` (e secrets do desktop se usados). + +## Problemas e soluções (pitfalls) +1) WebSocket 1006 no front +- Causa: Convex não rodando corretamente (CLI interativo) → migração para imagem oficial self‑hosted. + +2) `.env` sendo apagado pelo rsync +- Causa: `--delete` no rsync no job de deploy. +- Solução: adicionar filtros `protect` e `exclude` para `.env*` (raiz/desktop/convex). + +3) `MAILER_SENDER_EMAIL` com erro de parsing +- Causa: valor com espaços sem aspas quando foi "sourced" por shell. +- Solução: sempre usar aspas. Depois, com backend oficial, não foi mais necessário `source`. + +4) `prisma: not found` no build +- Causa: instalar só prod deps. +- Solução: `NPM_CONFIG_PRODUCTION=false` e `pnpm install --prod=false` no container de build. + +5) Lockfile/Workspace quebrando CI +- Causa: incluir `apps/desktop` no workspace. +- Solução: `pnpm-workspace.yaml` com `packages: ['.']`. + +6) Bind relativo no Swarm/Portainer +- Causa: `./:/app` vira path inválido. +- Solução: usar path absoluto: `/srv/apps/sistema:/app`. + +7) Flags `--port/--hostname` no `convex dev` +- Causa: versão do CLI. +- Solução: remover flags, e posteriormente substituir por backend oficial. + +8) Billing do GitHub bloqueado +- Causa: cobrança travada bloqueia todos workflows (mesmo self‑hosted). +- Solução: regularizar billing; opcionalmente usar `scripts/deploy-from-git.sh` até normalizar. + +## Checklists de operação +- Deploy manual (pull‑based): `bash /srv/apps/sistema/scripts/deploy-from-git.sh`. +- Deploy via Actions: commit em `main`. +- Seeds: `https://tickets.../dev/seed` e `docker exec ... pnpm auth:seed`. +- Verificação: `docker stack services sistema` e logs dos serviços. + +## Melhorias futuras +- Rodar job de "Detect changes" também em runner self‑hosted (zero minutos GitHub‑hosted). +- Fixar versão do `convex-backend` (ao invés de `latest`) para releases mais controladas. +- Substituir bind‑mount por imagens construídas no CI (tempo de deploy menor, reprodutibilidade). +- Adicionar cache de dependências pnpm no container de build. +