GigalativBot/README.md

GigalativBot (Telegram Counter Bot)

Ein schlanker Telegram-Bot zum Verwalten einfacher Integer-Counter. Läuft per Long Polling in einem Docker-Container.

Features

• /add – legt Counter (0) an
• /remove – löscht Counter
• /increment – erhöht Counter um 1 (Antwort mit neuem Wert)
• /decrement – verringert Counter um 1 (Antwort mit neuem Wert)
• /list – zeigt alle Counter
• /help – Übersicht
• Counter-Namen case-insensitive (intern lowercase gespeichert)
• Persistenz als JSON unter /data/counters.json (Docker Volume)
• Zugriffsbeschränkung via allowed_chat_ids in config.yaml
• Startup-Benachrichtigung an definierte Chats via ENV STARTUP_ANNOUNCE_CHAT_IDS
• Begrüßung neuer Mitglieder (optional) via ENV ANNOUNCE_ALL_JOINS=true
• Automatische Willkommens-Nachricht, wenn der Bot einer Gruppe hinzugefügt wird

Struktur

.
├─ bot.py
├─ requirements.txt
├─ Dockerfile
├─ docker-compose.yaml
├─ config.example.yaml (umbenennen zu config.yaml und anpassen)
└─ README.md

Konfiguration

Passe config.example.yaml an und benenne sie zu config.yaml.

Beispiel:

bot_token: "123456:ABCDEF..."  # oder via ENV BOT_TOKEN
allowed_chat_ids: [123456789, -1001122334455]
initial_counters:
  beispiel: 5
log_level: INFO

Wenn allowed_chat_ids leer oder fehlt, sind alle Chats erlaubt.

Wichtige Environment Variablen

Variable	Beschreibung	Beispiel
BOT_TOKEN	Telegram Bot Token (sensitiv, nicht committen)	123456:ABCDEF
STARTUP_ANNOUNCE_CHAT_IDS	Kommagetrennte Liste von Chat IDs für Start-Meldung	-4549916385,-1001122334455
ANNOUNCE_ALL_JOINS	true um alle neuen Mitglieder zu begrüßen	true
CONFIG_FILE	Pfad zur Config Datei	/app/config.yaml
DATA_DIR	Verzeichnis für Persistenz	/data

Start (Docker Compose)

Setze dein Bot Token als Environment Variable oder trage es in der config.yaml ein.

Variante 1: Token via .env

Datei .env anlegen:

BOT_TOKEN=123456:ABCDEF...

Dann:

docker compose up -d --build

Variante 2: Token in config.yaml

Trage bot_token: dort ein und entferne den BOT_TOKEN Eintrag aus docker-compose.yaml oder lass die ENV leer.

Startup Ankündigung aktivieren

Füge in .env hinzu (optional):

STARTUP_ANNOUNCE_CHAT_IDS=-4549916385
ANNOUNCE_ALL_JOINS=true

Persistenz / Volume

Alle Counter werden nach jeder Änderung in /data/counters.json gespeichert. Das Volume counterbot_data stellt dauerhafte Speicherung sicher.

Sicherheit

• Non-root User appuser
• Kein Port-Expose (Long Polling)

Docker Image veröffentlichen

Zum Bauen und Pushen des Images mit latest-Tag und einem datierten Tag (z. B. 2025-09-30) steht das Skript publish.py bereit. Stelle vorher sicher, dass du in der Registry git.beging.de angemeldet bist.

python publish.py --date 2025-09-30

Ohne --date wird automatisch das heutige UTC-Datum verwendet. Mit --dry-run kannst du die Docker-Kommandos nur anzeigen lassen:

python publish.py --dry-run

Falls du den latest Tag nicht veröffentlichen möchtest, verwende --no-latest.

Logging

Standard: INFO. Anpassbar über log_level in der Config.

Antwort-Ausgabe nutzt jetzt HTML-Formatierung (statt MarkdownV2) um Parse-Fehler bei Sonderzeichen zu vermeiden.

Beispiel-Interaktion

/add test
Counter test wurde angelegt (Wert 0).
/increment test
Counter test steht jetzt auf 1.
/list
Aktuelle Counter:
- test: 1
/remove test
Counter test wurde gelöscht.

Erweiterungsideen

• /set
• /rename
• Export als CSV/JSON über /export
• Webhook-Modus + Traefik Labels
• Rate Limiting pro User

Lizenz

Keine explizite Lizenz enthalten (privat). Ergänze bei Bedarf.

Viel Spaß!