homelab-brain/fuenfvoracht

FünfVorAcht

KI-gestützter Telegram-Kanal-Poster mit Dashboard — selbst gehostet, Docker-basiert.

FünfVorAcht automatisiert die tägliche Bespielung eines Telegram-Kanals. Artikel werden per KI generiert, im Dashboard redigiert, zeitgenau eingeplant und automatisch gepostet.

---

Was kann FünfVorAcht?

Feature	Beschreibung
✍️ KI-Artikel	Artikel per KI generieren (OpenRouter / GPT-4o, Claude, Mistral...)
📅 Zeitplanung	15-Minuten-Zeitslots, mehrere Artikel pro Tag möglich
🗓️ Redaktionskalender	7-Tage-Übersicht mit Umplanen & Löschen direkt im Board
👥 Multi-Reviewer	Mehrere Redakteure erhalten Review-Anfragen parallel
✅ Bot-Review	Artikel per Telegram freigeben oder zur Bearbeitung zurückgeben
⏰ Morgen-Briefing	Täglich 10:00 Uhr: Tagesplan + Ausblick 3 Tage
🔔 Nachmittags-Reminder	18:00 Uhr: Warnung wenn Artikel noch nicht freigegeben
🚨 Fehler-Alarm	Sofortbenachrichtigung bei Posting-Fehlern
🏷️ Markenzeichen	Wird automatisch unter jeden Beitrag angehängt
📚 Prompt-Bibliothek	Mehrere KI-Stile verwaltbar (Sarkastisch, Humorvoll, Sachlich...)
📊 JSON-Logging	Strukturiertes Logging aller Ereignisse
🐳 Docker	Kompletter Stack per Docker Compose

---

Schnellstart

# 1. Repository klonen
git clone https://github.com/Orbitalo/F-nf-vor-Acht.git fuenfvoracht
cd fuenfvoracht

# 2. Konfiguration anlegen
cp .env.example .env
nano .env  # Pflichtfelder ausfüllen

# 3. Stack starten
docker compose up -d --build

---

Voraussetzungen

Software	Version
Docker	24+
Docker Compose	2.x
Telegram Bot	Via @BotFather erstellen
OpenRouter Account	openrouter.ai

---

Konfiguration (.env)

cp .env.example .env

Pflichtfelder

Variable	Beschreibung
TELEGRAM_BOT_TOKEN	Bot-Token von @BotFather
TELEGRAM_CHANNEL_ID	Kanal-ID (z.B. -1001234567890)
REVIEW_CHAT_IDS	Chat-IDs der Redakteure (kommagetrennt)
OPENROUTER_API_KEY	API-Key von openrouter.ai
AUTH_USER	Dashboard-Benutzername
AUTH_PASS	Dashboard-Passwort

Optionale Felder

Variable	Standard	Beschreibung
POST_TIME	19:55	Standard-Posting-Zeit (HH:MM)
TIMEZONE	Europe/Berlin	Zeitzone
DB_PATH	/data/fuenfvoracht.db	Datenbankpfad

Eigene Chat-ID herausfinden

Nachricht an @userinfobot senden — er antwortet mit der Chat-ID.

Kanal-ID herausfinden

Den Bot zum Kanal als Admin hinzufügen, dann eine Nachricht senden und die Kanal-ID aus der Telegram API auslesen (beginnt mit -100).

---

Architektur

┌─────────────────────────────────────────────────┐
│  Docker Stack                                    │
│                                                  │
│  ┌──────────────────┐   ┌──────────────────────┐ │
│  │ fuenfvoracht-web │   │ fuenfvoracht-bot      │ │
│  │ Flask :8080      │   │ python-telegram-bot   │ │
│  │ Dashboard        │   │ APScheduler           │ │
│  └────────┬─────────┘   └──────────┬───────────┘ │
│           │                        │             │
│           └──────────┬─────────────┘             │
│                      ▼                           │
│              SQLite Datenbank                    │
│              /data/fuenfvoracht.db               │
└──────────────────────┬──────────────────────────┘
                       │
              ┌────────┴────────┐
              ▼                 ▼
       Telegram Bot        Telegram Kanal
       (Review)            (Posting)

---

Workflow

1. Quelle/Thema im Dashboard eingeben
         ↓
2. KI generiert Artikel (OpenRouter)
         ↓
3. Redigieren + Telegram-Vorschau
         ↓
4. Einplanen: Datum + 15-Min-Slot + Review-Zeit
         ↓
5. Bot schickt Review an alle Redakteure
         ↓
   [✅ Freigeben]  [✏️ Bearbeiten]
         ↓
6. Scheduler postet automatisch zum geplanten Zeitpunkt
         ↓
7. Markenzeichen wird automatisch angehängt

---

Bot-Befehle

Befehl	Funktion
/start	Übersicht & alle Befehle
/heute	Alle geplanten Slots des heutigen Tages
/queue	Nächste 3 Tage mit Slots
/skip	Hauptslot heute überspringen

---

Dashboard-Seiten

Seite	URL	Funktion
Studio	/	Artikel generieren, redigieren, einplanen
History	/history	Alle Posts der letzten 30 Tage
Prompts	/prompts	KI-Prompt Bibliothek verwalten
Einstellungen	/settings	Kanal, Reviewers, Posting-Zeit
Hilfe	/hilfe	Ausführliche Anleitung

---

Verzeichnisstruktur

fuenfvoracht/
├── docker-compose.yml       ← Docker Stack Definition
├── .env.example             ← Konfigurationsvorlage
├── README.md                ← Diese Datei
├── .gitignore               ← .env, data/, logs/ ausgeschlossen
└── src/
    ├── app.py               ← Flask Dashboard
    ├── bot.py               ← Telegram Bot + APScheduler
    ├── database.py          ← SQLite Datenbankschicht
    ├── openrouter.py        ← KI-API Client
    ├── logger.py            ← JSON-Logging
    ├── requirements.txt     ← Python-Abhängigkeiten
    ├── Dockerfile.web       ← Dashboard Container
    ├── Dockerfile.bot       ← Bot Container
    └── templates/           ← HTML-Templates (Jinja2)
        ├── index.html       ← Studio
        ├── history.html
        ├── prompts.html
        ├── settings.html
        └── hilfe.html

---

Öffentlicher Zugang via Cloudflare Tunnel

Für Zugriff ohne offene Firewall-Ports:

1. Cloudflare Zero Trust → Networks → Tunnels → Create
2. Hostname: fuenfvoracht.example.com
3. Service: http://localhost:8080
4. Den docker run cloudflare/cloudflared ...-Befehl ausführen

---

Bekannte Hinweise

Tailscale + Docker DNS: Falls der Host Tailscale verwendet, kann der Bot api.telegram.org nicht auflösen. Die docker-compose.yml enthält bereits den Fix:

dns:
  - 8.8.8.8
  - 8.8.4.4

---

Datensicherung

# Datenbank sichern
cp data/fuenfvoracht.db backups/fuenfvoracht_$(date +%Y%m%d).db

# Komplettes Verzeichnis sichern
tar -czf fuenfvoracht_backup_$(date +%Y%m%d).tar.gz data/ logs/ .env

---

Lizenz

MIT — frei verwendbar, anpassbar und weitergabe erlaubt.

---

Entwickelt von

Orbitalo — Homelab & Automatisierungsprojekte