feat: exemplos e documentacao da automacao de deploy GitOps (v1.0.0)

2026-05-30 14:41:27 +02:00
commit 928afe8697
12 changed files with 526 additions and 0 deletions
@@ -0,0 +1,24 @@
+# 01 — Arquitetura Multi-VPS
+
+| Servidor | IP (VPN WireGuard) | Função principal | Papel no deploy |
+|---|---|---|---|
+| **VPS 1 — App** | `10.99.0.1` | Produção (containers Docker) | Recebe os arquivos da VPS 4 e roda os containers |
+| **VPS 3 — Data/Git** | `10.99.0.3` | **Gitea** + PostgreSQL | Repositório central + banco |
+| **VPS 4 — Builder** | `10.99.0.4` | Dev / build | Roda o listener e os scripts de deploy |
+
+## Princípios
+
+1. **A fonte de verdade é o Gitea (VPS3).** O deploy sempre faz `git reset --hard origin/main`
+   antes de buildar — nunca confia em arquivos soltos na VPS de build.
+2. **Produção não recebe edição manual.** O `rsync --delete` sobrescreve tudo no próximo deploy.
+3. **Docker rootless na VPS 1.** Sempre usar `DOCKER_HOST=unix:///run/user/1000/docker.sock`.
+   O daemon root fica desabilitado de propósito (ver `04-seguranca-deploy.md`).
+4. **Comunicação entre VPS é pela VPN** (`10.99.0.x`), via chave SSH do usuário `deploy`.
+
+```
+  [ VPS 4: Builder ] ──git push──► [ VPS 3: Gitea/DB ]
+          │                               ▲
+   (rsync artefato/fonte)          (git fetch/reset)
+          ▼                               │
+  [ VPS 1: Produção ] ◄───────────────────┘
+```
@@ -0,0 +1,32 @@
+# 02 — Fluxo GitOps (do push ao container no ar)
+
+```mermaid
+sequenceDiagram
+    participant Dev as Dev (VPS4)
+    participant Gitea as Gitea (VPS3)
+    participant Listener as Listener (VPS4:porta)
+    participant Build as deploy-*.sh (VPS4)
+    participant Prod as Docker (VPS1)
+
+    Dev->>Gitea: git push origin main
+    Gitea->>Listener: POST /webhook?token=...
+    Listener->>Listener: valida token + trava de concorrência
+    Listener->>Gitea: status = pending
+    Listener->>Build: executa deploy-*.sh (background)
+    Build->>Gitea: git fetch & reset --hard
+    Build->>Build: build / version bump
+    Build->>Prod: rsync (artefato ou fonte)
+    Build->>Prod: ssh docker compose up -d [--build]
+    Build->>Gitea: git push (chore(deploy): bump version)
+    Note over Listener: commit de bump é IGNORADO (anti-loop)
+    Build-->>Listener: exit 0
+    Listener->>Gitea: status = success
+```
+
+## Pontos importantes do listener
+
+- **Resposta 202 imediata**: evita timeout do webhook do Gitea; o build roda em background.
+- **Trava `isBuilding`**: retorna `429` se já houver build rodando (sem deploys concorrentes).
+- **Anti-loop de CI**: commits cuja mensagem casa com `^chore\(deploy\): bump version` são
+  **ignorados** — senão o `git push` do bump dispararia um novo deploy infinitamente.
+- **Status no Gitea**: `pending` → `success`/`failure`, aparecendo o ✔/✘ ao lado do commit.
@@ -0,0 +1,52 @@
+# 03 — Configurar o Webhook no Gitea + Listener
+
+## A) Subir o listener na VPS 4 (um por projeto, porta única)
+
+```bash
+# 1. Copiar o exemplo e ajustar variáveis
+cp webhook-listener/config.example.env /home/deploy/stack/webhook-listener/<projeto>.env
+nano /home/deploy/stack/webhook-listener/<projeto>.env
+#   PORT=9003
+#   WEBHOOK_TOKEN=<token-forte>
+#   DEPLOY_SCRIPT=/home/deploy/stack/<projeto>/deploy-prod-onhost.sh
+#   GITEA_TOKEN=<token-da-API-do-gitea>
+
+# 2. Instalar a unit systemd
+sudo cp webhook-listener/webhook-listener.service /etc/systemd/system/webhook-<projeto>.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now webhook-<projeto>
+
+# 3. Conferir
+systemctl status webhook-<projeto>
+```
+
+## B) Criar o webhook no Gitea (VPS 3)
+
+No repositório → **Settings → Webhooks → Add Webhook → Gitea**:
+
+| Campo | Valor |
+|---|---|
+| Target URL | `http://10.99.0.4:9003/webhook?token=<WEBHOOK_TOKEN>` |
+| HTTP Method | `POST` |
+| Content Type | `application/json` |
+| Trigger | *Push events* (branch `main`) |
+| Branch filter | `main` |
+
+> O `GITEA_TOKEN` (para reportar status) é gerado em **Settings → Applications → Generate Token**
+> com escopo `repo:status` (ou `write:repository`).
+
+## C) Testar
+
+```bash
+# Push de teste dispara o deploy:
+git commit --allow-empty -m "test: dispara webhook" && git push origin main
+
+# Acompanhar:
+tail -f /home/deploy/stack/webhook-listener/deploy.log
+```
+
+## Pré-requisitos
+
+- Chave SSH do usuário `deploy` (VPS4) com acesso **sem senha** à VPS 1 (`ssh deploy@10.99.0.1 echo ok`).
+- Chave SSH do `deploy` com permissão de **push** no repositório do Gitea.
+- Porta do listener liberada apenas na rede VPN (`10.99.0.0/24`).
@@ -0,0 +1,32 @@
+# 04 — Segurança do Deploy
+
+## Segredos
+- **Nunca** commitar tokens, senhas, JWT ou secrets. Use `.env` (no `.gitignore`) e
+  `EnvironmentFile=` no systemd.
+- Tokens distintos por projeto: **WEBHOOK_TOKEN** (Gitea → listener) e **GITEA_TOKEN** (listener → API).
+- Rotacionar tokens periodicamente.
+
+## SSH
+- Comunicação VPS↔VPS só pela VPN (`10.99.0.x`).
+- Chave do usuário `deploy` sem passphrase para automação, com acesso restrito (produção + push no Gitea).
+- Usar `-o BatchMode=yes` nos scripts (falha rápido em vez de pedir senha).
+
+## Docker rootless na VPS 1 (⚠️ crítico)
+- A VPS 1 roda **Docker rootless**. O `docker.service` (root) fica **desabilitado de propósito**.
+- Sempre exportar `DOCKER_HOST=unix:///run/user/1000/docker.sock` nos comandos remotos.
+- Se o daemon root for reativado e `deploy` estiver no grupo `docker`, um `docker compose up` sem
+  `DOCKER_HOST` cria containers **root paralelos**, invisíveis ao `docker ps` rootless e ao Traefik,
+  e pode prender portas (`docker-proxy` zumbi).
+
+```bash
+# Estado correto da VPS 1:
+sudo systemctl status docker     # deve estar: inactive (dead)
+groups deploy                    # NÃO deve conter "docker"
+DOCKER_HOST=unix:///run/user/1000/docker.sock docker ps
+```
+
+## Boas práticas
+- **Commite antes de buildar**: o deploy faz `git reset --hard` e descarta mudanças locais.
+- **Nunca edite arquivos direto na VPS 1**: serão sobrescritos pelo `rsync --delete`.
+- Trava de concorrência (lock file / `isBuilding`) sempre ativa.
+- Acompanhar o `deploy.log` e o status do commit no Gitea após cada deploy.