portfolio/DEV_TESTING.md

🧪 Dev Branch Testing Guide

Übersicht

Dieses Dokument erklärt, wie du dein Portfolio-Projekt auf dem dev Branch testen kannst, bevor du es in Production deployst.

Voraussetzungen

1. ✅ n8n läuft bereits auf n8n.dk0.dev
2. ✅ Gitea Repository ist eingerichtet
3. ✅ Docker und Docker Compose sind installiert

Setup für lokales Testen mit n8n

1. Environment Variables konfigurieren

Erstelle eine .env.local Datei (oder aktualisiere deine bestehende .env):

# n8n Integration
N8N_WEBHOOK_URL=https://n8n.dk0.dev
N8N_API_KEY=dein-n8n-api-key
N8N_SECRET_TOKEN=dein-n8n-secret-token

# Application
NODE_ENV=development
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Database (wird automatisch von docker-compose.dev.minimal.yml gesetzt)
# DATABASE_URL=postgresql://portfolio_user:portfolio_dev_pass@localhost:5432/portfolio_dev?schema=public

# Redis (wird automatisch von docker-compose.dev.minimal.yml gesetzt)
# REDIS_URL=redis://localhost:6379

# Email Configuration
MY_EMAIL=contact@dk0.dev
MY_INFO_EMAIL=info@dk0.dev
MY_PASSWORD=dein-email-passwort
MY_INFO_PASSWORD=dein-info-email-passwort

# Analytics
NEXT_PUBLIC_UMAMI_URL=https://analytics.dk0.dev
NEXT_PUBLIC_UMAMI_WEBSITE_ID=b3665829-927a-4ada-b9bb-fcf24171061e

# Security
ADMIN_BASIC_AUTH=admin:dein-sicheres-passwort
LOG_LEVEL=debug

2. Lokal testen

# 1. Starte Datenbank und Redis
npm run dev:minimal

# 2. In einem neuen Terminal: Starte die Next.js App
npm run dev

# 3. Öffne http://localhost:3000

3. n8n Webhook testen

Teste die Verbindung zu deinem n8n Server:

# Teste den Status Endpoint
curl https://n8n.dk0.dev/webhook/denshooter-71242/status

# Teste den Chat Endpoint (wenn konfiguriert)
curl -X POST https://n8n.dk0.dev/webhook/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer DEIN_N8N_SECRET_TOKEN" \
  -d '{"message": "Hallo", "history": []}'

Staging Deployment auf dem Server

1. Gitea Variables und Secrets konfigurieren

Gehe zu deinem Gitea Repository → Settings → Secrets/Variables und füge hinzu:

Variables:

• NEXT_PUBLIC_BASE_URL = https://staging.dk0.dev (oder deine Staging URL)
• MY_EMAIL = contact@dk0.dev
• MY_INFO_EMAIL = info@dk0.dev
• NEXT_PUBLIC_UMAMI_URL = https://analytics.dk0.dev
• NEXT_PUBLIC_UMAMI_WEBSITE_ID = b3665829-927a-4ada-b9bb-fcf24171061e
• N8N_WEBHOOK_URL = https://n8n.dk0.dev
• LOG_LEVEL = debug

Secrets:

• MY_PASSWORD = Dein Email Passwort
• MY_INFO_PASSWORD = Dein Info Email Passwort
• ADMIN_BASIC_AUTH = admin:dein-sicheres-passwort
• N8N_API_KEY = Dein n8n API Key (optional)
• N8N_SECRET_TOKEN = Dein n8n Secret Token (optional)

2. Push zum dev Branch

# Stelle sicher, dass du auf dem dev Branch bist
git checkout dev

# Committe deine Änderungen
git add .
git commit -m "Test: Dev deployment"

# Push zum dev Branch (triggert automatisch Staging Deployment)
git push origin dev

3. Deployment überwachen

Nach dem Push:

1. Gehe zu deinem Gitea Repository → Actions
2. Überwache den Workflow CI/CD Pipeline (Dev/Staging)
3. Der Workflow wird:
   • Tests ausführen
   • Docker Image bauen
   • Staging Container auf Port 3001 deployen

4. Staging testen

# Auf deinem Server: Prüfe Container Status
docker ps | grep staging

# Prüfe Health Endpoint
curl http://localhost:3001/api/health

# Prüfe n8n Status Endpoint
curl http://localhost:3001/api/n8n/status

# Logs ansehen
docker logs portfolio-app-staging -f

5. Staging URL konfigurieren

Falls du eine Subdomain für Staging hast (z.B. staging.dk0.dev):

• Konfiguriere deinen Reverse Proxy (Nginx/Traefik) um auf Port 3001 zu zeigen
• Oder verwende direkt http://dein-server-ip:3001

Troubleshooting

Dev Container wird nicht erstellt

1. Prüfe Gitea Workflow:

   • Gehe zu Repository → Actions
   • Prüfe ob der Workflow ci-cd-dev-staging.yml existiert
   • Prüfe ob der Workflow auf dev Branch Push reagiert

2. Prüfe Gitea Variables:

   • Stelle sicher, dass alle erforderlichen Variables und Secrets gesetzt sind
   • Prüfe die Workflow Logs für fehlende Variablen

3. Prüfe Docker:

   # Auf deinem Server
   docker ps -a
   docker images | grep portfolio-app
   

n8n Verbindungsfehler

1. Prüfe n8n URL:

   # Teste ob n8n erreichbar ist
   curl https://n8n.dk0.dev/webhook/denshooter-71242/status
   

2. Prüfe Environment Variables:

   # Im Container
   docker exec portfolio-app-staging env | grep N8N
   

3. Prüfe n8n Webhook Konfiguration:

   • Stelle sicher, dass der Webhook in n8n aktiviert ist
   • Prüfe ob der Webhook-Pfad korrekt ist (/webhook/denshooter-71242/status)

Datenbank Fehler

# Prüfe ob die Datenbank läuft
docker ps | grep postgres-staging

# Prüfe Datenbank Logs
docker logs portfolio-postgres-staging

# Prüfe Verbindung
docker exec portfolio-postgres-staging pg_isready -U portfolio_user -d portfolio_staging_db

Workflow Übersicht

┌─────────────────┐
│  Push to dev    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Run Tests      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Build Docker   │
│  Image (staging) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Deploy Staging │
│  (Port 3001)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Health Check   │
└─────────────────┘

Nächste Schritte

1. ✅ Teste lokal mit npm run dev
2. ✅ Konfiguriere Gitea Variables und Secrets
3. ✅ Push zum dev Branch
4. ✅ Teste Staging auf Port 3001
5. ✅ Wenn alles funktioniert: Merge zu production Branch

---

Tipp: Verwende LOG_LEVEL=debug in Staging um mehr Informationen zu sehen!