portfolio/docs/PRODUCTION_TROUBLESHOOTING.md

Production Troubleshooting Guide

502 Bad Gateway Errors

Symptome

• Website zeigt 502 Bad Gateway
• Activity Feed zeigt nur "Loading"
• Chat funktioniert nicht
• API-Endpunkte geben 502 zurück

Ursachen

1. Container läuft nicht - Der portfolio-app Container ist gestoppt oder crashed
2. Proxy Netzwerk fehlt - Das proxy Netzwerk existiert nicht oder Container ist nicht verbunden
3. Nginx Proxy Manager Konfiguration - Falsche Hostname/IP oder Port-Konfiguration
4. Container Health Check fehlgeschlagen - Container läuft, aber die Anwendung ist nicht bereit

Lösungsschritte

1. Diagnose ausführen

./scripts/diagnose-production.sh

Dieses Script prüft:

• Container-Status
• Netzwerk-Verbindungen
• Health Checks
• API-Endpunkte
• Environment Variables

2. Automatischer Fix

./scripts/fix-production.sh

Dieses Script:

• Erstellt das proxy Netzwerk falls es fehlt
• Verbindet den Container mit dem proxy Netzwerk
• Startet den Container neu falls nötig
• Prüft Health Checks

3. Manuelle Schritte

Container-Status prüfen:

docker ps -a | grep portfolio-app
docker logs portfolio-app --tail=50

Proxy Netzwerk prüfen:

docker network ls | grep proxy
docker inspect portfolio-app | grep -A 10 Networks

Container neu starten:

cd /workspace/denshooter/portfolio
docker compose -f docker-compose.production.yml restart portfolio

Container mit Proxy-Netzwerk verbinden:

# Falls Netzwerk fehlt
docker network create proxy

# Container neu erstellen
docker compose -f docker-compose.production.yml up -d --force-recreate

4. Nginx Proxy Manager Konfiguration prüfen

1. Gehe zu Nginx Proxy Manager → Hosts → Proxy Hosts
2. Öffne die Konfiguration für dk0.dev
3. Details Tab prüfen:
   • Forward Hostname/IP: Muss portfolio-app sein (NICHT localhost oder 127.0.0.1)
   • Forward Port: 3000
   • Forward Scheme: http
4. Advanced Tab prüfen:

   proxy_set_header Host $host;
   proxy_set_header X-Real-IP $remote_addr;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   proxy_set_header X-Forwarded-Proto $scheme;
   

5. Container-Logs prüfen

# Alle Logs
docker logs portfolio-app

# Letzte 100 Zeilen
docker logs portfolio-app --tail=100

# Logs in Echtzeit
docker logs portfolio-app -f

React Hydration Error #418

Symptome

• Browser Console zeigt: Error: Minified React error #418
• Website funktioniert, aber es gibt Warnungen
• Unterschiede zwischen Server- und Client-Rendering

Ursachen

1. Client-only Komponenten werden auf dem Server gerendert
2. Unterschiedliche Daten zwischen Server und Client
3. Browser-spezifische APIs auf dem Server

Lösung

ActivityFeed Komponente:

• Die Komponente ist bereits als "use client" markiert
• Verwendet ClientOnly Wrapper für client-only Features
• Loading-State verhindert Hydration-Mismatches

Wenn der Fehler weiterhin auftritt:

1. Browser Cache leeren
2. Hard Refresh (Ctrl+Shift+R / Cmd+Shift+R)
3. Container-Logs auf React-Fehler prüfen

Activity Feed zeigt nur "Loading"

Ursachen

1. n8n Webhook nicht erreichbar - N8N_WEBHOOK_URL ist nicht gesetzt oder falsch
2. API-Endpunkt gibt Fehler zurück - /api/n8n/status funktioniert nicht
3. CORS-Probleme - n8n blockiert Requests
4. Rate Limiting - Zu viele Requests

Lösung

1. Environment Variables prüfen:

docker exec portfolio-app printenv | grep N8N

2. API-Endpunkt direkt testen:

# Von außen
curl https://dk0.dev/api/n8n/status

# Von innen
docker exec portfolio-app curl http://localhost:3000/api/n8n/status

3. n8n Webhook testen:

# Ersetze WEBHOOK_URL mit deiner tatsächlichen URL
curl "https://n8n.dk0.dev/webhook/denshooter-71242/status"

4. Gitea Variables prüfen:

• Gehe zu Gitea → Repository → Settings → Variables
• Prüfe ob N8N_WEBHOOK_URL, N8N_SECRET_TOKEN, N8N_API_KEY gesetzt sind
• Stelle sicher, dass diese auch in docker-compose.production.yml verwendet werden

Chat funktioniert nicht

Ursachen

1. n8n Webhook nicht erreichbar - Gleiche Ursache wie Activity Feed
2. API-Endpunkt gibt 502 zurück - Container-Problem
3. CORS-Probleme - n8n blockiert Requests
4. Timeout - n8n antwortet zu langsam

Lösung

1. API-Endpunkt testen:

# POST Request testen
curl -X POST https://dk0.dev/api/n8n/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

2. Container-Logs prüfen:

docker logs portfolio-app | grep -i "chat\|n8n"

3. n8n Webhook direkt testen:

curl -X POST "https://n8n.dk0.dev/webhook/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "history": []}'

Häufige Probleme und Lösungen

Problem: Container startet, aber Health Check schlägt fehl

Lösung:

# Prüfe ob curl im Container verfügbar ist
docker exec portfolio-app which curl

# Teste Health Endpoint manuell
docker exec portfolio-app curl -f http://localhost:3000/api/health

Problem: Container läuft, aber Port 3000 ist nicht erreichbar

Lösung:

# Prüfe Port-Mapping
docker port portfolio-app

# Teste von innen
docker exec portfolio-app curl http://localhost:3000/api/health

# Teste von außen (sollte funktionieren wenn Port gemappt ist)
curl http://localhost:3000/api/health

Problem: Proxy Netzwerk existiert nicht

Lösung:

# Erstelle Proxy Netzwerk
docker network create proxy

# Verbinde Container
docker network connect proxy portfolio-app

# Oder Container neu erstellen
docker compose -f docker-compose.production.yml up -d --force-recreate

Problem: Nginx Proxy Manager kann Container nicht erreichen

Lösung:

1. Stelle sicher, dass beide im proxy Netzwerk sind:

   docker network inspect proxy
   

2. Prüfe Nginx Proxy Manager Container:

   docker ps | grep nginx
   docker inspect <nginx-container> | grep -A 10 Networks
   

3. Teste Verbindung von Nginx Container zu Portfolio Container:

   docker exec <nginx-container> ping portfolio-app
   

Nützliche Befehle

# Container-Status
docker ps -a | grep portfolio

# Container-Logs
docker logs portfolio-app --tail=100 -f

# Container-Netzwerke
docker inspect portfolio-app | grep -A 20 Networks

# Health Check Status
docker inspect portfolio-app --format='{{.State.Health.Status}}'

# Environment Variables
docker exec portfolio-app printenv

# Shell im Container öffnen
docker exec -it portfolio-app sh

# Container neu starten
docker compose -f docker-compose.production.yml restart portfolio

# Container neu erstellen
docker compose -f docker-compose.production.yml up -d --force-recreate

# Alle Container stoppen
docker compose -f docker-compose.production.yml down

# Container mit Logs starten
docker compose -f docker-compose.production.yml up

Support

Wenn die Probleme weiterhin bestehen:

1. Führe ./scripts/diagnose-production.sh aus
2. Speichere die Ausgabe
3. Prüfe Container-Logs: docker logs portfolio-app --tail=100
4. Prüfe Nginx Proxy Manager Logs
5. Erstelle ein Issue mit allen Informationen