Emailsorter/docs/deployment/GITEA_WEBHOOK_SETUP.md

Gitea Webhook Setup - Automatisches Deployment

Diese Anleitung erklärt, wie du einen Gitea-Webhook einrichtest, um automatisch zu deployen, wenn Code gepusht wird.

Übersicht

Der Webhook funktioniert folgendermaßen:

1. Push auf Gitea → Gitea sendet Webhook-Event an deinen Server
2. Webhook-Handler empfängt das Event und verifiziert die Signatur
3. Deployment-Skript wird ausgeführt:
   • Git Pull (falls auf Server)
   • Frontend Build (npm run build)
   • Upload auf Production-Server (via SCP/SSH)
   • Backend Neustart (optional, via PM2)

Voraussetzungen

• ✅ Gitea-Repository mit deinem Code
• ✅ Production-Server mit SSH-Zugriff
• ✅ Node.js auf dem Server installiert
• ✅ PM2 installiert (optional, für Backend-Neustart)

Schritt 1: Webhook-Secret generieren

Generiere ein sicheres Secret für die Webhook-Signatur-Verification:

# Generiere ein zufälliges Secret (32 Zeichen)
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

Wichtig: Speichere dieses Secret sicher - du brauchst es in Schritt 3 und 4.

Schritt 2: Environment Variables konfigurieren

Füge folgende Variablen zu deiner server/.env Datei hinzu:

# Gitea Webhook Secret (aus Schritt 1)
GITEA_WEBHOOK_SECRET=dein_generiertes_secret_hier

# Optional: Authorization Header Token
GITEA_WEBHOOK_AUTH_TOKEN=dein_auth_token_hier

# Server-Deployment (optional, nur wenn automatischer Upload gewünscht)
DEPLOY_SERVER_HOST=91.99.156.85
DEPLOY_SERVER_USER=root
DEPLOY_SERVER_PATH=/var/www/emailsorter
DEPLOY_SSH_KEY=/path/to/ssh/private/key  # Optional, falls SSH-Key benötigt wird
DEPLOY_FRONTEND_PATH=/var/www/emailsorter/client/dist
DEPLOY_BACKEND_PATH=/var/www/emailsorter/server

# PM2 für Backend-Neustart (optional)
USE_PM2=true

Schritt 3: Webhook in Gitea konfigurieren

1. Öffne dein Repository in Gitea

2. Gehe zu Settings → Webhooks

3. Klicke auf Add Webhook → Gitea

4. Fülle die Felder aus:

   • Target URL:

     https://emailsorter.webklar.com/api/webhook/gitea
     

     (Ersetze mit deiner tatsächlichen Domain)

   • HTTP Method: POST

   • Post Content Type: application/json

   • Secret:

     dein_generiertes_secret_hier
     

     (Das gleiche Secret wie in Schritt 1)

   • Authorization Header: (Optional)

     Bearer dein_auth_token_hier
     

   • Trigger On:

     • ✅ Push Events (wichtig!)
     • Optional: Create, Delete (falls gewünscht)

   • Branch Filter: main oder master (je nach deinem Standard-Branch)

5. Klicke auf Add Webhook

Schritt 4: Webhook testen

Option A: Test über Gitea UI

1. Gehe zurück zu Settings → Webhooks
2. Klicke auf deinen Webhook
3. Klicke auf Test Delivery → Push Events
4. Prüfe die Antwort:
   • ✅ Status 202 = Webhook empfangen, Deployment gestartet
   • ❌ Status 401 = Secret falsch
   • ❌ Status 500 = Server-Fehler (prüfe Server-Logs)

Option B: Test über Git Push

1. Mache eine kleine Änderung (z.B. Kommentar in einer Datei)
2. Committe und pushe:

   git add .
   git commit -m "test: Webhook test"
   git push
   

3. Prüfe die Server-Logs:

   # Auf dem Server
   pm2 logs emailsorter-backend
   # Oder
   tail -f /var/log/emailsorter/webhook.log
   

4. Du solltest sehen:

   📥 Gitea Webhook empfangen
   🚀 Starte Deployment...
   📦 Baue Frontend...
   ✅ Deployment erfolgreich abgeschlossen
   

Schritt 5: Deployment-Logs prüfen

Die Webhook-Handler loggen alle Schritte. Prüfe die Logs:

# PM2 Logs
pm2 logs emailsorter-backend

# Oder direkt im Server
tail -f server/logs/webhook.log

Fehlerbehebung

Webhook wird nicht ausgelöst

• ✅ Prüfe, ob die Target URL korrekt ist
• ✅ Prüfe, ob der Server erreichbar ist (curl https://emailsorter.webklar.com/api/webhook/status)
• ✅ Prüfe Gitea-Logs: Settings → Webhooks → Delivery Log

"Ungültige Webhook-Signatur" (401)

• ✅ Prüfe, ob GITEA_WEBHOOK_SECRET in server/.env gesetzt ist
• ✅ Prüfe, ob das Secret in Gitea genau gleich ist (keine Leerzeichen!)
• ✅ Prüfe, ob der Webhook "application/json" als Content-Type verwendet

Deployment schlägt fehl

• ✅ Prüfe Server-Logs für detaillierte Fehlermeldungen
• ✅ Prüfe, ob SSH-Zugriff funktioniert: ssh root@91.99.156.85
• ✅ Prüfe, ob npm und node auf dem Server installiert sind
• ✅ Prüfe, ob die Pfade (DEPLOY_SERVER_PATH) korrekt sind

Frontend-Build fehlgeschlagen

• ✅ Prüfe, ob alle Dependencies installiert sind: cd client && npm install
• ✅ Prüfe, ob .env.production korrekt konfiguriert ist
• ✅ Prüfe Build-Logs für TypeScript/ESLint-Fehler

Backend startet nicht neu

• ✅ Prüfe, ob PM2 installiert ist: pm2 --version
• ✅ Prüfe, ob USE_PM2=true in .env gesetzt ist
• ✅ Prüfe PM2-Status: pm2 list

Sicherheit

Best Practices

1. Webhook-Secret: Verwende immer ein starkes, zufälliges Secret
2. HTTPS: Stelle sicher, dass dein Server HTTPS verwendet (Let's Encrypt)
3. Firewall: Beschränke Webhook-Endpoint auf Gitea-IPs (optional)
4. Rate Limiting: Der Webhook-Endpoint ist bereits rate-limited
5. Logs: Prüfe regelmäßig die Webhook-Logs auf verdächtige Aktivitäten

Alternative: Lokales Deployment ohne Server-Upload

Falls du den automatischen Upload auf den Server nicht möchtest, kannst du:

1. DEPLOY_SERVER_HOST nicht setzen
2. Das Deployment-Skript erstellt nur den Build lokal
3. Du lädst die Dateien manuell hoch oder verwendest ein anderes Tool

Der Webhook wird trotzdem ausgelöst und erstellt den Build, aber überspringt den Upload-Schritt.

Manuelles Deployment auslösen

Du kannst das Deployment auch manuell auslösen:

# Auf dem Server
cd /var/www/emailsorter
node scripts/deploy-to-server.mjs

Nächste Schritte

Nach erfolgreichem Setup:

1. ✅ Teste den Webhook mit einem kleinen Push
2. ✅ Prüfe, ob die Website aktualisiert wurde
3. ✅ Überwache die Logs für die ersten Deployments
4. ✅ Dokumentiere deine spezifische Konfiguration

Support

Bei Problemen:

• Prüfe die Server-Logs
• Prüfe Gitea Webhook Delivery Logs
• Prüfe die Environment Variables
• Teste SSH-Verbindung manuell