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:

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

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:

// 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)

// 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

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

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

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

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

   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:

# Auf Server (wo Docker läuft):
docker events --filter 'event=start' --format '{{json .}}'

# Expected: JSON output bei neuen Containern

2. Test Webhook manuell:

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

#!/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

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

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

DIRECTUS_TOKEN=RF2QytqhcLXuVy6FO3PzWlsoR-ysCTwB
OPENROUTER_API_KEY=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
TELEGRAM_CHAT_ID=145931600

In Workflows nutzen:

// Statt:
"Authorization": "Bearer RF2QytqhcLXuVy6FO3PzWlsoR-ysCTwB"

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

---

🔄 Backup & Updates

Workflows exportieren

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

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

Git Push

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)

# 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