🚀 Deploy V.1.0.0 — Automação GitOps (Gitea + Multi-VPS)

Versão 1.0.0 da documentação do pipeline de deploy automático. Todos os exemplos de código estão sanitizados (sem tokens/segredos reais).

1. Visão geral

A cada git push na branch main, o Gitea (VPS 3) dispara um webhook para um listener na VPS 4 (Builder), que executa o script de deploy do projeto e reporta o status do commit de volta ao Gitea. O resultado vai para a VPS 1 (Produção) em Docker.

Servidor	IP (VPN)	Função
VPS 1 — App	`10.99.0.1`	Produção (containers Docker rootless)
VPS 3 — Data/Git	`10.99.0.3`	Gitea + PostgreSQL
VPS 4 — Builder	`10.99.0.4`	Listener + build + disparo do deploy

Dev (VPS4) ──push──► Gitea (VPS3) ──webhook──► listener (VPS4) ──► deploy-*.sh ──► Docker (VPS1)

2. O listener do webhook

Um listener por projeto, cada um numa porta própria (ex.: 9000, 9002, 9003). Responsabilidades:

Valida o token (?token= ou header x-gitea-token).
Trava de concorrência (isBuilding) → responde 429 se já há build rodando.
Ignora commits chore(deploy): bump version → evita loop de CI.
Responde 202 imediatamente e roda o deploy-*.sh em background.
Reporta status ao Gitea via API: pending → success/failure (✔/✘ no commit).

Código de referência: webhook-listener/listener.js. Serviço: webhook-<projeto>.service (systemd).

3. Dois modelos de deploy

🅰️ Builder-to-Host (build na VPS 4)

A VPS 4 compila e envia apenas os artefatos (dist/, node_modules) para a VPS 1, que só reinicia os containers. Ideal para frontends pesados (Next/Vite). Script: scripts/deploy-prod-builder.sh.

git reset --hard ► build (VPS4) ► rsync artefato ► ssh VPS1 "docker compose up -d"

🅱️ Build no host (build na VPS 1)

A VPS 4 envia o código-fonte e a VPS 1 builda a imagem Docker e troca o container (--no-deps, quase sem downtime). Ideal para apps leves (ex.: Node servindo estáticos). Script: scripts/deploy-prod-onhost.sh.

git reset --hard ► rsync fonte ► ssh VPS1 "docker compose build app && up -d --no-deps app"

Há ainda scripts/deploy-to-prod.sh para promoção manual Staging(VPS4) → Produção(VPS1).

4. Configurar um novo projeto (passo a passo)

Listener (VPS 4):

cp webhook-listener/config.example.env /home/deploy/stack/webhook-listener/<projeto>.env
# editar PORT, WEBHOOK_TOKEN, DEPLOY_SCRIPT, GITEA_TOKEN
sudo cp webhook-listener/webhook-listener.service /etc/systemd/system/webhook-<projeto>.service
sudo systemctl daemon-reload && sudo systemctl enable --now webhook-<projeto>

Webhook no Gitea (repo → Settings → Webhooks → Gitea):
- URL: http://10.99.0.4:<porta>/webhook?token=<WEBHOOK_TOKEN>
- Método POST, evento Push, branch main.
Token de status: Settings → Applications → Generate Token (escopo repo:status).
Testar: git commit --allow-empty -m "test" && git push e acompanhar tail -f /home/deploy/stack/webhook-listener/deploy.log.

5. Segurança (resumo)

Sem segredos no Git — usar .env + EnvironmentFile=.
VPS 1 = Docker rootless: sempre DOCKER_HOST=unix:///run/user/1000/docker.sock; daemon root permanece desabilitado de propósito.
SSH do usuário deploy (sem passphrase, BatchMode=yes), só pela VPN.
Commite antes de buildar — o deploy faz git reset --hard e descarta mudanças locais.
Nunca editar arquivos na VPS 1 — o rsync --delete sobrescreve no próximo deploy.

6. Troubleshooting

Problema	Diagnóstico	Solução
Webhook não dispara	`systemctl status webhook-<projeto>`	Reiniciar o listener
`429` no webhook	build concorrente	Aguardar o build atual terminar
`rsync`/`ssh` falha	`ssh deploy@10.99.0.1 echo ok`	Checar chave SSH e VPN
Build falha na VPS 1	`docker logs` no container	Ver erro de `npm`/Dockerfile
Deploy em loop	commit de bump redisparando	Conferir regex anti-loop no listener

Changelog — v1.0.0: primeira versão (listener, modelos A/B, configuração Gitea, segurança).