feat: complete telegram cms system with workflows and deployment guide
- Add ULTIMATE-Telegram-CMS-COMPLETE.json with all commands - Add Docker Event workflows with Gitea integration - Add comprehensive deployment guide for fresh installs - Add quick reference and testing checklist - Include all n8n workflow exports Commands: /start, /list, /search, /stats, /preview, /publish, /delete, .review Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
541
TELEGRAM_CMS_DEPLOYMENT.md
Normal file
541
TELEGRAM_CMS_DEPLOYMENT.md
Normal file
@@ -0,0 +1,541 @@
|
||||
# 🚀 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
|
||||
Reference in New Issue
Block a user