chore: Docs umstrukturiert, Client-Updates, Scripts nach scripts/
This commit is contained in:
219
docs/deployment/GITEA_WEBHOOK_SETUP.md
Normal file
219
docs/deployment/GITEA_WEBHOOK_SETUP.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user