From 94e1af0e6f9e3c756b99690e457879315a80b2c2 Mon Sep 17 00:00:00 2001 From: coding Date: Wed, 25 Mar 2026 09:39:38 +0000 Subject: [PATCH] Add comprehensive README.md with installation and usage guide Features documented: - Quick start guide with Docker - Complete feature list with emojis - Step-by-step usage instructions - Command reference table - Environment variables configuration - Remove.bg API setup - Docker management commands - Troubleshooting section - System requirements - Security notes - CI/CD information - Project structure overview - Support information --- README.md | 279 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..30c6419 --- /dev/null +++ b/README.md @@ -0,0 +1,279 @@ +# 🎨 Telegram Sticker Bot Manager + +Ein Telegram Bot zum Verwalten und Organisieren von Sticker-Paketen. Erstellt mit Python und der python-telegram-bot Bibliothek. + +## ✨ Features + +- **🆕 Neue Stickerpakete erstellen** - Einfacher 4-Schritte-Assistent +- **📥 Existierende Pakete importieren** - Bereits vorhandene Pakete hinzufügen +- **➕ Sticker hinzufügen** - Unterstützt Bilder (PNG, JPG, WebP) und GIFs +- **🎨 Automatische Bildoptimierung** - Konvertiert zu 512px WebP mit Transparenz +- **🎬 GIF zu Video-Sticker** - Automatische Konvertierung zu WebM (VP9) +- **✨ Hintergrundentfernung** - Optional mit lokalen oder API-basierten Tools +- **🏷 Emoji verwalten** - Emojis von Stickern ändern +- **✏️ Pakete umbenennen** - Titel einfach ändern +- **🗑 Sticker/Pakete löschen** - Mit Bestätigungsdialog +- **💎 Premium-Status** - Erkennt Telegram Premium Nutzer + +## 🚀 Schnellstart + +### Voraussetzungen + +- Docker und Docker Compose +- Einen Telegram Bot Token (von @BotFather) +- Deine Telegram User ID + +### Installation + +1. **Repository klonen:** +```bash +git clone http://192.168.88.201:3000/sarah/stickerbot.git +cd stickerbot +``` + +2. **Umgebungsvariablen konfigurieren:** +```bash +cp .env.example .env +``` + +3. **`.env` Datei bearbeiten:** +```bash +# Required +BOT_TOKEN=dein_bot_token_hier +OWNER_ID=deine_telegram_user_id + +# Optional: Für Hintergrundentfernung über API (50 Aufrufe/Monat kostenlos) +REMOVE_BG_API_KEY=dein_remove_bg_api_key +``` + +4. **Docker Container starten:** +```bash +sudo docker-compose up -d --build +``` + +5. **Überprüfen, ob der Bot läuft:** +```bash +sudo docker-compose logs -f +``` + +## 📖 Verwendung + +### Bot starten + +Schreibe dem Bot in Telegram: +``` +/start +``` + +Das Hauptmenü erscheint mit folgenden Optionen: + +- **➕ Neues Stickerpaket** - Erstellt ein neues Paket +- **📥 Existierendes hinzufügen** - Fügt bereits existierende Pakete hinzu +- **📦 Meine Stickerpakete** - Zeigt alle deine Pakete an +- **❓ Hilfe** - Zeigt Hilfeinformationen + +### Stickerpaket erstellen + +1. Auf "➕ Neues Stickerpaket" klicken +2. Kurzen Namen eingeben (z.B. `meine_sticker`) +3. Titel eingeben (z.B. "Meine coolen Sticker") +4. Emoji eingeben (z.B. 😎) +5. Bild senden (PNG, JPG oder GIF) +6. Optional: Hintergrund entfernen auswählen + +### Existierendes Paket hinzufügen + +1. Auf "📥 Existierendes hinzufügen" klicken +2. Den Namen des Pakets eingeben (z.B. `meine_alten_sticker`) +3. Der Bot fügt es automatisch zu deiner Liste hinzu + +### Sticker zu Paket hinzufügen + +1. Auf "📦 Meine Stickerpakete" klicken +2. Das gewünschte Paket auswählen +3. Auf "➕ Sticker hinzufügen" klicken +4. Bild oder GIF senden +5. Emoji eingeben + +**Bilder:** Werden automatisch zu 512px WebP konvertiert +**GIFs:** Werden zu animierten Video-Stickern (max. 3 Sekunden) + +### Hintergrundentfernung + +Wenn du ein Bild sendest, fragt der Bot: + +- **🤖 Lokal entfernen** - Kostenlos, läuft auf dem Server (etwas langsamer) +- **☁️ Remove.bg API** - Schneller, 50 Aufrufe/Monat kostenlos (falls API-Key gesetzt) +- **⏭️ Ohne Entfernung** - Bild wird so verwendet + +### Sticker löschen + +1. Den Sticker an den Bot weiterleiten +2. Bot zeigt Optionen zum Löschen + +### Paket löschen + +1. "📦 Meine Stickerpakete" wählen +2. Paket auswählen +3. "🗑 Paket löschen" wählen +4. Bestätigen + +⚠️ **Achtung:** Das Löschen kann nicht rückgängig gemacht werden! + +## 🛠️ Befehle + +| Befehl | Beschreibung | +|--------|--------------| +| `/start` | Bot starten und Hauptmenü anzeigen | +| `/hilfe` | Detaillierte Hilfe anzeigen | +| `/cancel` | Aktuelle Aktion abbrechen | + +## ⚙️ Konfiguration + +### Umgebungsvariablen + +| Variable | Beschreibung | Optional | +|----------|--------------|----------| +| `BOT_TOKEN` | Telegram Bot Token von @BotFather | Nein | +| `OWNER_ID` | Deine Telegram User ID | Nein | +| `REMOVE_BG_API_KEY` | API Key für remove.bg | Ja | +| `DATABASE_PATH` | Pfad zur SQLite DB (Standard: `sticker_bot.db`) | Ja | +| `PREMIUM_CHECK_INTERVAL` | Interval für Premium-Check in Stunden (Standard: 24) | Ja | + +### Remove.bg API Key (Optional) + +Um die Hintergrundentfernung über API zu nutzen: + +1. Bei [remove.bg](https://www.remove.bg/) registrieren +2. API Key generieren +3. In `.env` Datei eintragen: `REMOVE_BG_API_KEY=dein_key` + +**Hinweis:** 50 Aufrufe pro Monat sind kostenlos. + +## 🐳 Docker Verwaltung + +### Container starten +```bash +sudo docker-compose up -d +``` + +### Container stoppen +```bash +sudo docker-compose down +``` + +### Logs anzeigen +```bash +sudo docker-compose logs -f +``` + +### Neu bauen (nach Änderungen) +```bash +sudo docker-compose up -d --build --force-recreate +``` + +### Container-Status prüfen +```bash +sudo docker ps | grep stickerbot +``` + +## 📁 Projektstruktur + +``` +stickerbot/ +├── bot.py # Hauptbot mit allen Handlern +├── sticker_manager.py # Sticker-Verwaltungsfunktionen +├── image_processor.py # Bildverarbeitung (WebP, Resize) +├── gif_processor.py # GIF zu WebM Konvertierung +├── background_remover.py # Hintergrundentfernung +├── database.py # SQLite Datenbank +├── config.py # Konfigurationsmanagement +├── Dockerfile # Docker Konfiguration +├── docker-compose.yml # Docker Compose Setup +├── requirements.txt # Python Dependencies +├── .env.example # Beispiel-Umgebungsvariablen +└── data/ # Persistente Daten +``` + +## 🔄 Automatische Builds (CI/CD) + +Das Projekt enthält Gitea Actions Workflows für automatische Docker-Builds: + +### Auto-Build (bei jedem Push) +- **Trigger:** Push auf `main` oder `master` Branch +- **Ergebnis:** Docker Image wird gebaut und in die Registry gepusht +- **Tags:** `latest` und `v{nummer}-autobuild` + +### Manueller Build +- **Trigger:** Manuell über Gitea Web-Interface +- **Optionen:** + - Benutzerdefinierte Version (z.B. `1.0.0`) + - Zusätzliche Tags (z.B. `stable,production`) + - `latest` Tag optional + +### Registry +Standardmäßig wird das Image zu `192.168.88.201:5000` gepusht. + +## 🐛 Fehlerbehebung + +### Bot reagiert nicht +```bash +# Prüfen ob Container läuft +sudo docker ps | grep stickerbot + +# Logs anzeigen +sudo docker-compose logs -f +``` + +### Build fehlschlägt +```bash +# Mit force-recreate neu bauen +sudo docker-compose up -d --build --force-recreate +``` + +### Datenbank zurücksetzen +```bash +# ACHTUNG: Löscht alle Daten! +rm data/sticker_bot.db +sudo docker-compose restart +``` + +### Hintergrundentfernung langsam +Beim ersten Start lädt rembg das ML-Modell (~180MB). Dies dauert einmalig etwas länger. + +## 📋 Systemanforderungen + +- **RAM:** Mindestens 512MB (für rembg Modell empfohlen: 1GB+) +- **Speicherplatz:** ~500MB für Container + Datenbank +- **Netzwerk:** Internetverbindung für Telegram API +- **Betriebssystem:** Linux mit Docker Unterstützung + +## 📝 Technische Details + +- **Python:** 3.11 +- **Basis-Image:** python:3.11-slim (Debian) +- **Bot API:** python-telegram-bot 22.7 +- **Datenbank:** SQLite +- **Bildverarbeitung:** Pillow, rembg, FFmpeg + +## 🔒 Sicherheit + +- Der Bot ist nur für den `OWNER_ID` zugänglich +- Keine Gruppen-Unterstützung (nur private Chats) +- API-Keys werden in Umgebungsvariablen gespeichert +- Docker Container läuft als non-root User + +## 📄 Lizenz + +Dieses Projekt ist für private Nutzung bestimmt. + +## 🤝 Support + +Bei Fragen oder Problemen: +1. `/hilfe` in Telegram eingeben +2. Die `OPENCODE.md` konsultieren (technische Dokumentation) +3. Logs überprüfen: `sudo docker-compose logs -f` + +--- + +**Viel Spaß mit deinem Sticker Bot!** 🎨✨