portfolio/TELEGRAM_CMS_DEPLOYMENT.md

# 🚀 Telegram CMS - Complete Deployment Guide

**Für andere PCs / Fresh Install**

---

## 📋 Was du bekommst

Ein vollständiges Telegram-Bot-System zur Verwaltung deines DK0 Portfolios:

### ✨ Features

- **Dashboard** (`/start`) - Übersicht mit Draft-Zählern und Quick Actions
- **Listen** (`/list projects|books`) - Paginierte Listen mit Action-Buttons
- **Suche** (`/search <term>`) - Durchsucht Projekte & Bücher
- **Statistiken** (`/stats`) - Analytics Dashboard (Views, Kategorien, Ratings)
- **Vorschau** (`/preview<ID>`) - Zeigt EN + DE Übersetzungen
- **Publish** (`/publish<ID>`) - Veröffentlicht Items (auto-detect: Project/Book)
- **Delete** (`/delete<ID>`) - Löscht Items permanent
- **Delete Review** (`/deletereview<ID>`) - Löscht nur Review-Text
- **AI Review** (`.review <HC_ID> <RATING> <TEXT>`) - Generiert EN+DE Reviews via Gemini

### 🤖 Automatisierungen

- **Docker Events** - Erkennt neue Deployments, fragt ob AI Beschreibung generieren soll
- **Book Reviews** - AI generiert DE+EN Reviews aus deinem Input
- **Status API** - Spotify, Discord, WakaTime Integration (bereits vorhanden)

---

## 📦 Workflows zum Importieren

### 1. **ULTIMATE Telegram CMS** ⭐ (HAUPT-WORKFLOW)

**Datei:** `n8n-workflows/ULTIMATE-Telegram-CMS-COMPLETE.json`

**Beschreibung:**
- Zentraler Command Router für alle `/` Befehle
- Enthält alle Handler: Dashboard, List, Search, Stats, Preview, Publish, Delete, AI Reviews
- **Aktivieren:** Ja (Telegram Trigger)

**Credentials:**
- Telegram API: `DK0_Server` (ID: `ADurvy9EKUDzbDdq`)
- Directus Token: `RF2QytqhcLXuVy6FO3PzWlsoR-ysCTwB` (hardcoded in Nodes)
- OpenRouter API: `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`

---

### 2. **Docker Event Extended** (Optional, empfohlen)

**Datei:** `n8n-workflows/Docker Event (Extended).json`

**Beschreibung:**
- Reagiert auf Docker Webhooks (`https://n8n.dk0.dev/webhook/docker-event`)
- Erkennt eigene Projekte (`denshooter/dk0`) vs. CI/CD Container
- Holt letzten Commit + README von Gitea
- Fragt per Telegram-Button: Auto-generieren, Selbst beschreiben, Ignorieren

**Credentials:**
- Telegram API: `DK0_Server`
- Gitea Token: `gitea-token` (noch anzulegen!)

**Setup:**
1. Gitea Token erstellen: https://git.dk0.dev/user/settings/applications
   - Name: `n8n-api`
   - Permissions: ✅ `repo` (read)
2. In n8n: Credentials → New → HTTP Header Auth
   - Name: `gitea-token`
   - Header Name: `Authorization`
   - Value: `token <YOUR_GITEA_TOKEN>`

---

### 3. **Docker Callback Handler** (Required if using Docker Events)

**Datei:** `n8n-workflows/Docker Event - Callback Handler.json`

**Beschreibung:**
- Verarbeitet Button-Klicks aus Docker Event Workflow
- Auto: Ruft AI (Gemini) mit Commit+README Context
- Manual: Fragt nach manueller Beschreibung
- Ignore: Bestätigt ignorieren

**Credentials:**
- Telegram API: `DK0_Server`
- OpenRouter API: (same as above)

---

### 4. **Book Review** (Legacy - kann ersetzt werden)

**Datei:** `n8n-workflows/Book Review.json`

**Status:** ⚠️ Wird von ULTIMATE CMS ersetzt (nutzt `.review` Command)

**Optional behalten falls:**
- Separate Webhook gewünscht
- Andere Trigger-Quelle (z.B. Hardcover API direkt)

---

### 5. **Reading / Finished Books** (Andere Features)

**Dateien:**
- `finishedBooks.json` - Hardcover finished books webhook
- `reading (1).json` - Currently reading books

**Status:** Optional, wenn du Hardcover Integration nutzt

---

## 🛠️ Schritt-für-Schritt Installation

### **Schritt 1: n8n Credentials prüfen**

Öffne n8n → Settings → Credentials

**Benötigt:**

| Name | Type | ID | Notes |
|------|------|-----|-------|
| `DK0_Server` | Telegram API | `ADurvy9EKUDzbDdq` | Telegram Bot Token |
| `gitea-token` | HTTP Header Auth | neu erstellen | Für Commit-Daten |
| OpenRouter | (hardcoded) | - | In Code Nodes |

---

### **Schritt 2: Workflows importieren**

1. **ULTIMATE Telegram CMS:**
   ```
   n8n → Workflows → Import from File
   → Wähle: n8n-workflows/ULTIMATE-Telegram-CMS-COMPLETE.json
   → ✅ Activate Workflow
   ```

2. **Docker Event Extended:**
   ```
   → Wähle: n8n-workflows/Docker Event (Extended).json
   → Credentials mappen: DK0_Server + gitea-token
   → ✅ Activate Workflow
   ```

3. **Docker Callback Handler:**
   ```
   → Wähle: n8n-workflows/Docker Event - Callback Handler.json
   → Credentials mappen: DK0_Server
   → ✅ Activate Workflow
   ```

---

### **Schritt 3: Gitea Token erstellen**

1. Gehe zu: https://git.dk0.dev/user/settings/applications
2. **Generate New Token**
   - Token Name: `n8n-api`
   - Select Scopes: ✅ `repo` (Repository Read)
3. Kopiere Token: `<YOUR_TOKEN_HIER>`
4. In n8n:
   ```
   Credentials → New → HTTP Header Auth
   Name: gitea-token
   Header Name: Authorization
   Value: token <YOUR_TOKEN_HIER>
   ```

---

### **Schritt 4: Test Commands**

Öffne Telegram → DK0_Server Bot:

```bash
/start
# Expected: Dashboard mit Quick Stats + Buttons

/list projects
# Expected: Liste aller Draft Projekte

/stats
# Expected: Analytics Dashboard

/search nextjs
# Expected: Suchergebnisse

.review 427565 5 Great book about AI!
# Expected: AI generiert EN+DE Review, sendet Vorschau
```

---

## 🔧 Konfiguration anpassen

### Telegram Chat ID ändern

Aktuell: `145931600` (dein Telegram Account)

**Ändern in:**
1. Öffne Workflow: `ULTIMATE-Telegram-CMS-COMPLETE`
2. Suche Node: `Telegram Trigger`
3. Additional Fields → Chat ID → `<NEUE_CHAT_ID>`

**Chat ID herausfinden:**
```bash
curl https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
# Schick dem Bot eine Nachricht, dann findest du in "chat":{"id":123456}
```

---

### Directus API Token ändern

Aktuell: `RF2QytqhcLXuVy6FO3PzWlsoR-ysCTwB`

**Ändern in allen Code Nodes:**
```javascript
// Suche nach:
"Authorization": "Bearer RF2QytqhcLXuVy6FO3PzWlsoR-ysCTwB"

// Ersetze mit:
"Authorization": "Bearer <NEUER_TOKEN>"
```

**Betroffene Nodes:**
- Dashboard Handler
- List Handler
- Search Handler
- Stats Handler
- Preview Handler
- Publish Handler
- Delete Handler
- Delete Review Handler
- Create Review Handler

---

### OpenRouter AI Model ändern

Aktuell: `google/gemini-2.0-flash-exp:free`

**Alternativen:**
- `google/gemini-2.5-flash` (besser, aber kostenpflichtig)
- `openrouter/free` (fallback)
- `anthropic/claude-3.5-sonnet` (premium)

**Ändern in:**
- Node: `Create Review Handler` (ULTIMATE CMS)
- Node: `Generate AI Description` (Docker Callback)

```javascript
// Suche:
"model": "google/gemini-2.0-flash-exp:free"

// Ersetze mit:
"model": "google/gemini-2.5-flash"
```

---

## 📊 Command Reference

### Basic Commands

| Command | Beschreibung | Beispiel |
|---------|--------------|----------|
| `/start` | Dashboard anzeigen | `/start` |
| `/list projects` | Alle Draft-Projekte | `/list projects` |
| `/list books` | Alle Draft-Bücher | `/list books` |
| `/search <term>` | Suche in Projekten & Büchern | `/search nextjs` |
| `/stats` | Statistiken anzeigen | `/stats` |

### Item Management

| Command | Beschreibung | Beispiel |
|---------|--------------|----------|
| `/preview<ID>` | Vorschau (EN+DE) | `/preview42` |
| `/publish<ID>` | Veröffentlichen (auto-detect) | `/publish42` |
| `/delete<ID>` | Löschen (auto-detect) | `/delete42` |
| `/deletereview<ID>` | Nur Review-Text löschen | `/deletereview42` |

### AI Review Creation

```bash
.review <HARDCOVER_ID> <RATING> <YOUR_REVIEW_TEXT>

# Beispiel:
.review 427565 5 Great book about AI and the future of work!

# Generiert:
# - EN Review (erweitert deinen Text)
# - DE Review (übersetzt + erweitert)
# - Setzt Rating auf 5/5
# - Erstellt Draft in Directus
# - Sendet Vorschau mit /publish Button
```

---

## 🐛 Troubleshooting

### "Item not found"

**Ursache:** ID existiert nicht in Directus

**Fix:**
```bash
# Prüfe in Directus:
https://cms.dk0.dev/admin/content/projects
https://cms.dk0.dev/admin/content/book_reviews
```

---

### "Error loading dashboard"

**Ursache:** Directus API nicht erreichbar oder Token falsch

**Fix:**
```bash
# Test Directus API:
curl -H "Authorization: Bearer RF2QytqhcLXuVy6FO3PzWlsoR-ysCTwB" \
  https://cms.dk0.dev/items/projects?limit=1

# Expected: JSON mit Projekt-Daten
# Falls 401: Token abgelaufen/falsch
```

---

### AI Review schlägt fehl

**Ursache:** OpenRouter API Problem oder Model nicht verfügbar

**Fix:**
```bash
# Test OpenRouter:
curl -X POST https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer sk-or-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-2.0-flash-exp:free","messages":[{"role":"user","content":"test"}]}'

# Falls 402: Credits aufgebraucht
# → Wechsel zu kostenpflichtigem Model
# → Oder nutze "openrouter/free"
```

---

### Telegram antwortet nicht

**Ursache:** Workflow nicht aktiviert oder Webhook Problem

**Fix:**
1. n8n → Workflows → ULTIMATE Telegram CMS → ✅ Active
2. Check Executions:
   ```
   n8n → Executions → Filter by Workflow
   → Suche nach Fehlern (red icon)
   ```
3. Test Webhook manuell:
   ```bash
   curl -X POST https://n8n.dk0.dev/webhook-test/telegram-cms-webhook-001 \
     -H "Content-Type: application/json" \
     -d '{"message":{"text":"/start","chat":{"id":145931600}}}'
   ```

---

### Docker Event erkennt keine Container

**Ursache:** Webhook wird nicht getriggert

**Fix:**

**1. Prüfe Docker Event Source:**
```bash
# Auf Server (wo Docker läuft):
docker events --filter 'event=start' --format '{{json .}}'

# Expected: JSON output bei neuen Containern
```

**2. Test Webhook manuell:**
```bash
curl -X POST https://n8n.dk0.dev/webhook/docker-event \
  -H "Content-Type: application/json" \
  -d '{
    "container":"portfolio-dev",
    "image":"denshooter/portfolio:latest",
    "timestamp":"2026-04-02T10:00:00Z"
  }'

# Expected: Telegram Nachricht mit Buttons
```

**3. Setup Docker Event Forwarder:**

Auf Server erstellen: `/opt/docker-event-forwarder.sh`
```bash
#!/bin/bash
docker events --filter 'event=start' --format '{{json .}}' | while read event; do
  container=$(echo "$event" | jq -r '.Actor.Attributes.name')
  image=$(echo "$event" | jq -r '.Actor.Attributes.image')
  timestamp=$(echo "$event" | jq -r '.time')
  
  curl -X POST https://n8n.dk0.dev/webhook/docker-event \
    -H "Content-Type: application/json" \
    -d "{\"container\":\"$container\",\"image\":\"$image\",\"timestamp\":\"$timestamp\"}"
done
```

Systemd Service: `/etc/systemd/system/docker-event-forwarder.service`
```ini
[Unit]
Description=Docker Event Forwarder to n8n
After=docker.service
Requires=docker.service

[Service]
ExecStart=/opt/docker-event-forwarder.sh
Restart=always
User=root

[Install]
WantedBy=multi-user.target
```

Aktivieren:
```bash
chmod +x /opt/docker-event-forwarder.sh
systemctl daemon-reload
systemctl enable docker-event-forwarder
systemctl start docker-event-forwarder
```

---

## 📝 Environment Variables (Optional)

Falls du Tokens nicht hardcoden willst, nutze n8n Environment Variables:

**In `.env` (n8n Docker):**
```env
DIRECTUS_TOKEN=RF2QytqhcLXuVy6FO3PzWlsoR-ysCTwB
OPENROUTER_API_KEY=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
TELEGRAM_CHAT_ID=145931600
```

**In Workflows nutzen:**
```javascript
// Statt:
"Authorization": "Bearer RF2QytqhcLXuVy6FO3PzWlsoR-ysCTwB"

// Nutze:
"Authorization": `Bearer ${process.env.DIRECTUS_TOKEN}`
```

---

## 🔄 Backup & Updates

### Workflows exportieren

```bash
# In n8n:
Workflows → ULTIMATE Telegram CMS → ... → Download

# Speichern als:
n8n-workflows/ULTIMATE-Telegram-CMS-COMPLETE-v2.json
```

### Git Push

```bash
cd /pfad/zum/portfolio
git add n8n-workflows/
git commit -m "chore: update telegram cms workflows"
git push origin telegram-cms-deployment
```

---

## 🚀 Production Checklist

- [ ] Alle Workflows importiert
- [ ] Credentials gemappt (DK0_Server, gitea-token)
- [ ] Gitea Token erstellt & getestet
- [ ] `/start` Command funktioniert
- [ ] `/list projects` zeigt Daten
- [ ] `/stats` zeigt Statistiken
- [ ] AI Review generiert Text (`.review` Test)
- [ ] Docker Event Webhook getestet
- [ ] Inline Buttons funktionieren
- [ ] Error Handling in n8n Executions geprüft
- [ ] Workflows in Git committed

---

## 📚 Weitere Dokumentation

- **System Architecture:** `docs/TELEGRAM_CMS_SYSTEM.md`
- **Workflow Details:** `n8n-workflows/ULTIMATE-Telegram-CMS-COMPLETE-README.md`
- **Quick Reference:** `n8n-workflows/QUICK-REFERENCE.md`
- **Testing Checklist:** `n8n-workflows/TESTING-CHECKLIST.md`

---

## 🎯 Quick Start (TL;DR)

```bash
# 1. Clone Repo
git clone <REPO_URL>
cd portfolio

# 2. Import Workflows
# → n8n UI → Import → Select:
#   - ULTIMATE-Telegram-CMS-COMPLETE.json
#   - Docker Event (Extended).json
#   - Docker Event - Callback Handler.json

# 3. Create Gitea Token
# → https://git.dk0.dev/user/settings/applications
# → Name: n8n-api, Scope: repo
# → Copy token → n8n Credentials → HTTP Header Auth

# 4. Activate Workflows
# → n8n → Workflows → ✅ Active (alle 3)

# 5. Test
# → Telegram: /start
```

**Done!** 🎉

---

**Version:** 1.0.0  
**Last Updated:** 2026-04-02  
**Author:** Dennis Konkol  
**Status:** ✅ Production Ready