Documentos-Unicos/desuso/newwhats_Deploy_VPS_Flow_2026-06-17.md

⚠️ EM DESUSO desde 2026-06-17 — consolidado em /home/deploy/stack/documentos-unicos/ (ver LEIA-PRIMEIRO.md). Mantido só como histórico; NÃO usar como referência.

---

🚀 Fluxo de Deploy Multi-VPS (VPS 1, VPS 3 e VPS 4)

Este guia descreve detalhadamente o fluxo GitOps e despacho de arquivos compilados entre os servidores do ecossistema NewWhats.

---

🗺️ Mapa de Papéis dos Servidores

  [ VPS 4: Builder ]  ───(git push)───►  [ VPS 3: Git/DB ]
          │                                      ▲
          │                                      │
   (rsync compiles)                       (DB Connections)
          │                                      │
          ▼                                      │
  [ VPS 1: Produção ] ───────────────────────────┘

Servidor	IP VPN	Função Principal	Fluxo de Código
VPS 1 (App Server)	10.99.0.1	Execução em Produção	Recebe os arquivos compilados da VPS 4
VPS 3 (Data Server)	10.99.0.3	Banco PostgreSQL & Gitea	Centraliza o Git e o banco de dados
VPS 4 (Build Server)	10.99.0.4	Desenvolvimento & Compilação	Compila a plataforma e despacha via Rsync

---

🔄 Fluxo de Deploy Passo a Passo

O ciclo de deploy adota o modelo Builder-to-Host para garantir que servidores de execução de produção (VPS 1) não consumam recursos excessivos de CPU com compilações pesadas de Webpack/Next.js e TypeScript.

sequenceDiagram
    participant Dev as Desenvolvedor (VPS 4)
    participant Gitea as Gitea (VPS 3)
    participant Builder as Build Process (VPS 4)
    participant Prod as Produção Docker (VPS 1)

    Dev->>Gitea: git push origin main
    Dev->>Builder: Executa deploy-prod-builder.sh
    Builder->>Gitea: git fetch & reset --hard
    Builder->>Builder: Incrementa versão (update-version.js)
    Builder->>Builder: Compila Backend, Plugins & Frontend
    Builder->>Prod: rsync /dist e /node_modules
    Builder->>Prod: ssh restart containers
    Builder->>Gitea: git push (version bump)

---

🖥️ Detalhamento por Máquina

1️⃣ VPS 4 — O Motor de Compilação (Build / Builder)

Todas as modificações de código e atualizações são criadas e validadas nesta máquina.

1. O desenvolvedor realiza as alterações no código local.

2. Faz o commit e envia para a VPS 3:

   git add .
   git commit -m "feat: minha nova funcionalidade"
   git push origin main
   

3. Executa o script centralizador de deploy:

   bash /home/deploy/stack/clube67/deploy-prod-builder.sh
   

   • O script limpa e reseta a pasta local para bater com a origin/main.
   • Roda update-version.js para incrementar o build (ex: v1.0.9 (build #9)).
   • Compila o backend, gera tipos Prisma, compila plugins e roda next build.

4. Sincronizar o incremento de versão no Gitea (Obrigatório): Após o deploy com sucesso, os arquivos de versão estarão alterados localmente. É vital comitá-los para não apagar o contador de deploys no Gitea na próxima execução:

   git add deploys.json version.json frontend/public/deploys.json frontend/public/version.json
   git commit -m "chore(deploy): bump version"
   git push origin main
   

2️⃣ VPS 3 — O Orquestrador e Repositório (Git & Banco de Dados)

A VPS 3 é o coração dos dados do ecossistema. Ela roda o banco PostgreSQL diretamente no host e serve o Gitea.

• Recebimento de Alterações (Push): Quando a VPS 4 faz git push, a VPS 3 valida a autenticação de chaves SSH ou JWT e atualiza o branch main.
• Disponibilização (Pull): Durante o deploy automático, a VPS 4 executa git fetch e git reset apontando de volta para a VPS 3 para garantir consistência.

3️⃣ VPS 1 — O Servidor de Produção (App Server)

A VPS 1 roda os containers Docker newwhats-backend-prod e newwhats-frontend-prod.

• Sem Compilação Local: Ela nunca roda npm run build ou instala dependências de desenvolvimento.
• Recebimento de Binários: O script da VPS 4 envia apenas as pastas /dist, /node_modules, package.json e os arquivos do frontend prontos (.next/, /public/) via rsync de alta velocidade.
• Reinício de Containers: Após os arquivos serem transferidos para a pasta local da VPS 1, a VPS 4 faz um comando SSH seguro que dispara:

  docker compose restart newwhats-backend-prod newwhats-frontend-prod
  

---

🚦 Boas Práticas e Resolução de Conflitos

• Nunca altere código diretamente na VPS 1: Qualquer edição em produção será apagada no próximo deploy, pois o rsync --delete substitui todos os arquivos pelos compilados na VPS 4.
• Commite antes de Buildar: Lembre-se sempre de subir suas alterações para o Gitea (git push) antes de rodar o deploy-prod-builder.sh, pois o script reseta a árvore de diretórios local para bater com o Git remoto.