From bcb7c3d85678ac70da075941bdc28994ef7dc5cd Mon Sep 17 00:00:00 2001 From: VPS 4 Builder Date: Thu, 14 May 2026 21:04:18 +0200 Subject: [PATCH] docs(scoreodonto): adiciona guia completo de deploy e versionamento --- scoreodonto/deploy.md | 204 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 scoreodonto/deploy.md diff --git a/scoreodonto/deploy.md b/scoreodonto/deploy.md new file mode 100644 index 0000000..a8c4352 --- /dev/null +++ b/scoreodonto/deploy.md @@ -0,0 +1,204 @@ +# 🚀 Deploy ScoreOdonto — Guia Completo (VPS 4 → VPS 1) + +Este documento detalha o processo de deploy contínuo do ScoreOdonto e o sistema de versionamento automático. + +--- + +## 🔁 Visão Geral do Pipeline + +``` +Developer (VPS 4) + └─► git push origin main + └─► Gitea Webhook → POST http://10.99.0.4:9002/webhook?token=... + └─► listener-scoreodonto.js (porta 9002, VPS 4) + └─► deploy-prod-scoreodonto.sh + ├─► git pull (VPS 4) + ├─► rsync → VPS 1 (10.99.0.1) + └─► ssh VPS 1 → docker compose up -d --build + └─► update-version.js (auto-bump patch) + └─► vite build → nginx:alpine +``` + +--- + +## 📦 Versionamento do Sistema + +### Arquivo de versão +``` +frontend/constants.ts +``` +```ts +export const APP_VERSION = 'V1.0.6'; +``` + +### Como funciona o auto-incremento + +A cada `docker compose up -d --build`, o script `update-version.js` (na raiz do projeto) é chamado automaticamente pelo comando de build do frontend: + +```json +// frontend/package.json +"scripts": { + "build": "node ../update-version.js && vite build" +} +``` + +O script incrementa o **patch** (terceiro número) da versão: +- `V1.0.5` → `V1.0.6` → `V1.0.7` → ... + +> [!WARNING] +> O incremento ocorre **dentro do container Docker durante o build**. Os arquivos no repositório Git não são modificados automaticamente. A nova versão aparece na interface em produção, mas o `constants.ts` no Git permanece com o valor anterior ao build. + +### Tabela de tipos de versão + +| Tipo | Exemplo | Quando usar | Como fazer | +|------|---------|-------------|------------| +| **Patch** (automático) | `V1.0.5 → V1.0.6` | Cada deploy/build | Automático — `update-version.js` cuida | +| **Minor** (manual) | `V1.0.x → V1.1.0` | Nova feature significativa ou sprint | Editar `constants.ts`, zerar patch, commitar | +| **Major** (manual) | `V1.x.x → V2.0.0` | Rewrite, mudança arquitetural grande | Editar `constants.ts`, zerar minor e patch, commitar | + +### Bumpar versão Minor ou Major manualmente + +```bash +# 1. Editar o arquivo diretamente +nano /home/deploy/stack/scoreodonto.com/frontend/constants.ts +# Alterar: export const APP_VERSION = 'V1.1.0'; + +# 2. Commitar +cd /home/deploy/stack/scoreodonto.com +git add frontend/constants.ts +git commit -m "chore(version): bump para V1.1.0" +git push origin main +# → webhook dispara o deploy automaticamente +``` + +--- + +## 🤖 Webhook — Configuração + +| Parâmetro | Valor | +|-----------|-------| +| URL | `http://10.99.0.4:9002/webhook?token=scoreodonto_deploy_token_9002` | +| Método | `POST` | +| Eventos | Push na branch `main` | +| Listener | `/home/deploy/instrucoes/scoreodonto/listener-scoreodonto.js` | +| Deploy script | `/home/deploy/instrucoes/scoreodonto/deploy-prod-scoreodonto.sh` | + +### Verificar se o listener está ativo + +```bash +ps aux | grep listener-scoreodonto +# Deve aparecer: node /home/deploy/instrucoes/scoreodonto/listener-scoreodonto.js +``` + +### Reiniciar o listener (se parou) + +```bash +pkill -f listener-scoreodonto || true +nohup node /home/deploy/instrucoes/scoreodonto/listener-scoreodonto.js \ + > /tmp/scoreodonto-webhook.log 2>&1 & +echo $! > /tmp/scoreodonto-webhook.pid +``` + +--- + +## 🛠️ Deploy Manual (sem webhook) + +Use quando o webhook não está disponível ou para forçar um rebuild imediato: + +```bash +# Na VPS 4 +bash /home/deploy/instrucoes/scoreodonto/deploy-prod-scoreodonto.sh +``` + +O script executa: +1. `git pull origin main` — garante código atualizado na VPS 4 +2. `rsync` — sincroniza arquivos para VPS 1 (`10.99.0.1`), excluindo `node_modules`, `.env` e `.git` +3. `docker compose up -d --build` — reconstrói e reinicia os containers na VPS 1 + +--- + +## 🐳 Arquitetura Docker (Produção) + +### Frontend +``` +Dockerfile: frontend/Dockerfile +Build context: . (raiz do projeto) +``` +```dockerfile +# Stage 1: Build +FROM node:20-alpine AS builder +WORKDIR /app +COPY update-version.js . # ← script de versionamento vem da raiz +COPY frontend/package*.json frontend/ +WORKDIR /app/frontend +RUN npm install +COPY frontend/ . +RUN npm run build # → chama update-version.js + vite build + +# Stage 2: Serve +FROM nginx:alpine +COPY --from=builder /app/frontend/dist /usr/share/nginx/html +EXPOSE 3013 +``` + +### Backend +``` +Dockerfile: backend/Dockerfile +Porta: 8018 +Runtime: Node.js 20 +``` + +### Nginx (Proxy) +``` +Porta externa: 8020 +Traefik labels: scoreodonto.com / www.scoreodonto.com → HTTPS (Let's Encrypt) +``` + +--- + +## 🔍 Verificação Pós-Deploy + +```bash +# 1. Checar containers na VPS 1 +ssh deploy@10.99.0.1 "docker ps | grep scoreodonto" + +# 2. Checar versão em produção +curl -s https://scoreodonto.com | grep -o 'V[0-9]*\.[0-9]*\.[0-9]*' | head -1 + +# 3. Ver logs do último build +ssh deploy@10.99.0.1 "docker logs scoreodontocom-scoreodonto-frontend-1 --tail 30" + +# 4. Ver logs do backend +ssh deploy@10.99.0.1 "docker logs scoreodontocom-scoreodonto-backend-1 --tail 30" +``` + +--- + +## ⚠️ Troubleshooting + +| Problema | Diagnóstico | Solução | +|----------|-------------|---------| +| Webhook não dispara | `ps aux | grep listener` | Reiniciar o listener (ver acima) | +| Versão não atualiza na UI | Versão incrementa no container, não no git | Normal — a versão no git é a base; o build incrementa | +| `rsync` falha | `ssh deploy@10.99.0.1 echo ok` | Checar chave SSH e VPN WireGuard | +| Docker build falha | `docker logs` na VPS 1 | Ver logs do container; checar `npm install` | +| Frontend em branco | nginx config / dist vazia | Verificar se `vite build` completou sem erro | + +--- + +## 📌 Comandos Git Rápidos (fluxo diário) + +```bash +cd /home/deploy/stack/scoreodonto.com + +# Ver estado +git status + +# Commitar e enviar (dispara deploy automaticamente) +git add -p # adicionar seletivamente +git commit -m "feat: descrição" # mensagem em português +git push origin main # → webhook → deploy automático +``` + +> [!TIP] +> Quando trabalhando com Claude Code (worktrees), o merge para `main` acontece ao final da sessão. O push para `main` é quem efetivamente dispara o deploy — não o commit em si.