# 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:

```bash
# 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:

```bash
# 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:
   ```bash
   git add .
   git commit -m "test: Webhook test"
   git push
   ```
3. Prüfe die Server-Logs:
   ```bash
   # 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:

```bash
# 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:

```bash
# 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