Mini CRCON Bot for Discord

Discord-Steuerungsoberfläche für Hell-Let-Loose-Server über die CRCON-API.

Documentation · Report Bug · Request Feature

Inhaltsverzeichnis

• Über das Projekt
• Funktionen
• Technik
• Projektstruktur
• Voraussetzungen
• Konfiguration
• Installation mit Docker Compose
• Lokale Installation
• Discord-Befehle
• Berechtigungen
• CRCON-Berechtigungen
• Sicherheit
• Roadmap
• Lizenz
• Kontakt

---

Über das Projekt

Der Mini CRCON Bot for Discord stellt ein dauerhaftes Steuerungs-Panel in Discord bereit. Berechtigte Administratoren können darüber Spieler benachrichtigen, Karten wechseln, Spieler kicken, bestrafen oder unmittelbar das Team wechseln lassen.

Die Kommunikation erfolgt über die HTTP-API einer bestehenden CRCON-Installation. Der Bot ersetzt CRCON nicht, sondern bietet eine kompakte Discord-Oberfläche für häufig benötigte Administrationsaufgaben.

---

Funktionen

• Persistentes Discord-Steuerungs-Panel
• Nachricht an einzelne Spieler
• Nachricht an Allies, Axis oder alle Spieler
• Spielerauswahl mit Pagination
• Kartenwechsel anhand einer konfigurierbaren maps.json
• Spieler kicken, bestrafen und sofort ins andere Team verschieben
• API-Diagnose mit Erreichbarkeit, Version und Spielerzahl
• Rollen-, Benutzer-, Owner- und Administrator-Prüfung
• Wiederholungsversuche und Timeouts bei API-Aufrufen
• Rotierende Logdateien
• Optionales Panel-Banner
• Docker- und Docker-Compose-Unterstützung

---

Technik

• Python: 3.12
• Discord: discord.py 2.4+
• HTTP: requests mit Retry-Strategie
• Konfiguration: YAML und Umgebungsvariablen
• Deployment: Docker und Docker Compose
• Zielsystem: Hell Let Loose CRCON API

---

Projektstruktur

Mini-CRCon-Bot4Discord/
├── assets/
├── cogs/
│   ├── diagnostics.py
│   └── messaging.py
├── utils/
│   └── permissions.py
├── views/
│   └── message.py
├── api_client.py
├── bot.py
├── logging_setup.py
├── maps.json
├── .env.example
├── config.example.yml
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

---

Voraussetzungen

• Discord-Bot-Anwendung
• erreichbare CRCON-Installation mit API-Zugang
• Docker und Docker Compose, alternativ Python 3.12

Der Discord-Bot benötigt typischerweise:

• Kanäle ansehen
• Nachrichten senden
• Links einbetten
• Dateien anhängen
• Nachrichtenverlauf lesen
• Nachrichten verwalten, falls der Steuerungskanal beim Start bereinigt werden soll

---

Konfiguration

Repository klonen:

git clone https://github.com/FwSchultz/Mini-CRCon-Bot4Discord.git
cd Mini-CRCon-Bot4Discord

Vorlagen kopieren:

cp .env.example .env
cp config.example.yml config.yml

Windows PowerShell:

Copy-Item .env.example .env
Copy-Item config.example.yml config.yml

.env anpassen:

DISCORD_TOKEN=DEIN_DISCORD_BOT_TOKEN
API_BASE_URL=https://crcon.example.com
API_TOKEN=DEIN_CRCON_API_TOKEN
CONFIG_PATH=config.yml
LOG_LEVEL=INFO

In config.yml mindestens Steuerungskanal und berechtigte Rollen eintragen:

app:
  control_channel_id: 123456789012345678
  log_channel_id: 0
  purge_control_channel_on_start: true

permissions:
  allow_admin_perm: false
  allow_guild_owner: true
  role_ids:
    - 123456789012345678
  user_ids: []

Alle IDs in der Vorlage sind absichtlich leer oder 0.

---

Installation mit Docker Compose

docker compose up -d --build

Status und Logs:

docker compose ps
docker compose logs -f mini-crcon-bot

Stoppen:

docker compose down

Die Logdateien bleiben im lokalen Ordner logs/ erhalten.

---

Lokale Installation

python -m venv .venv

Linux/macOS:

source .venv/bin/activate

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

pip install -r requirements.txt
python bot.py

---

Discord-Befehle

Befehl	Funktion
/panel	Steuerungs-Panel erneut senden
/diag	geschützte CRCON-API-Diagnose anzeigen

Die eigentlichen Serveraktionen werden über Buttons, Auswahllisten und Dialoge im Panel ausgeführt.

---

Berechtigungen

Zugriff erhält ein Benutzer, wenn mindestens eine aktivierte Regel zutrifft:

• explizite Benutzer-ID
• Discord-Serverbesitzer
• Discord-Berechtigung Administrator
• eine konfigurierte Rollen-ID

Für eine kontrollierte Einrichtung empfiehlt sich allow_admin_perm: false und die Freigabe über konkrete Rollen.

---

CRCON-Berechtigungen

Der API-Token benötigt abhängig von den aktivierten Funktionen Zugriff auf:

• get_players
• get_detailed_players
• message_player
• set_map
• kick
• punish
• switch_player_now

Vergib nur die tatsächlich benötigten Rechte.

---

Sicherheit

• .env und config.yml werden nicht versioniert.
• Tokens niemals in Screenshots, ZIP-Dateien oder Issues veröffentlichen.
• Das Diagnosekommando ist auf berechtigte Benutzer beschränkt.
• Der Steuerungskanal wird nur bereinigt, wenn purge_control_channel_on_start aktiviert ist.
• Bei Discord-Reconnects wird die Initialisierung nicht mehrfach ausgeführt.
• Administratorrechte nur vergeben, wenn einzelne Discord-Rechte nicht ausreichen.

---

Roadmap

• Persistentes Bedienpanel
• Spieler- und Seitennachrichten
• Kartenwechsel
• Kick, Punish und Teamwechsel
• Docker-Unterstützung
• Audit-Log für ausgeführte Adminaktionen
• Tests für API-Client und Rechteprüfung
• optionale Bestätigungsdialoge für kritische Aktionen

---

Lizenz

Veröffentlicht unter der MIT-Lizenz. Weitere Informationen stehen in LICENSE.

---

Kontakt

Fw.Schultz

• GitHub: @FwSchultz
• Website: fwschultz.de
• LinkedIn: Oliver Blume
• Fehler und Vorschläge: GitHub Issues