Update Docker setup documentation for HexaHost, enhancing clarity on prerequisites, configuration steps, and troubleshooting. Added detailed instructions for setting up Traefik, environment variables, and Discord integration.

2026-07-21 17:55:26 +02:00
parent 9bcde844da
commit 7dca4fb77a
1 changed files with 192 additions and 10 deletions
--- a/DOCKER.md
+++ b/DOCKER.md
@@ -1,19 +1,201 @@
-# Docker
+# HexaHost — Docker-Setup (Traefik)

-Copy `.env.docker.example` to `.env`, fill in secrets, then:
+Dashboard: **https://bot.hexahost.de**  
+Bot-API: nur intern (`http://bot:8000`) — nicht öffentlich.
+
+---
+
+## Voraussetzungen
+
+1. **Docker** + **Docker Compose** auf dem Server
+2. **Traefik** läuft bereits und ist am Netzwerk `traefik-network` angeschlossen
+3. DNS: `bot.hexahost.de` zeigt auf die IP deines Traefik-Servers (A/AAAA)
+4. Discord-Anwendung (Bot + OAuth) im [Discord Developer Portal](https://discord.com/developers/applications)
+
+Traefik erwartet typischerweise:
+
+| Einstellung | Wert (Standard hier) |
+|-------------|----------------------|
+| Externes Netzwerk | `traefik-network` |
+| HTTP-Entrypoint | `web` (Port 80) |
+| HTTPS-Entrypoint | `websecure` (Port 443) |
+| Cert-Resolver | `letsencrypt` |
+
+Falls dein Cert-Resolver anders heißt → später `TRAEFIK_CERT_RESOLVER` in `.env` setzen.
+
+---
+
+## 1. Projekt auf den Server holen
+
+```bash
+git clone <dein-repo-url> HexaHost
+cd HexaHost
+```
+
+Oder Dateien per SCP/SFTP hochladen und in den Projektordner wechseln.
+
+---
+
+## 2. Traefik-Netzwerk prüfen
+
+```bash
+docker network ls | grep traefik-network
+```
+
+Falls es fehlt (nur wenn Traefik es nicht schon angelegt hat):
+
+```bash
+docker network create traefik-network
+```
+
+**Wichtig:** Traefik selbst muss an `traefik-network` hängen. Sonst erreicht Traefik das Dashboard nicht.
+
+---
+
+## 3. Secrets / `.env` anlegen
+
+```bash
+cp .env.docker.example .env
+nano .env   # oder vim / code
+```
+
+### Pflichtfelder ausfüllen
+
+| Variable | Bedeutung |
+|----------|-----------|
+| `TOKEN` | Bot-Token (Discord → Bot → Reset Token) |
+| `OWNER_IDS` | Deine Discord-User-ID (Komma bei mehreren) |
+| `DASHBOARD_ADMIN_IDS` | IDs für Bot-Admin-API (meist = Owner) |
+| `DASHBOARD_API_KEY` | Langes zufälliges Geheimnis (Bot ↔ Dashboard) |
+| `NEXTAUTH_SECRET` | Anderes langes zufälliges Geheimnis |
+| `DISCORD_CLIENT_ID` | Application ID der Discord-App |
+| `DISCORD_CLIENT_SECRET` | OAuth2 → Client Secret |
+| `ADMIN_IDS` | Dashboard-Admins (Discord-User-IDs) |
+| `NEXT_PUBLIC_ADMIN_IDS` | Gleich wie `ADMIN_IDS` |
+
+Secrets erzeugen (Beispiel):
+
+```bash
+openssl rand -hex 32   # für DASHBOARD_API_KEY
+openssl rand -hex 32   # für NEXTAUTH_SECRET
+```
+
+Discord-User-ID: Discord → Einstellungen → Erweitert → Entwicklermodus → Rechtsklick auf dich → „ID kopieren“.
+
+---
+
+## 4. Discord Developer Portal
+
+### Bot
+
+1. Application öffnen → **Bot** → Token kopieren → in `.env` als `TOKEN`
+2. Privileged Gateway Intents aktivieren, die der Bot braucht (z. B. Server Members, Message Content — je nach Features)
+3. Bot auf den Server einladen (OAuth2 → URL Generator → `bot` + benötigte Permissions)
+
+### OAuth fürs Dashboard
+
+1. **OAuth2 → General**
+2. Redirects hinzufügen:
+
+```text
+https://bot.hexahost.de/api/auth/callback/discord
+```
+
+3. **Client ID** und **Client Secret** in `.env` eintragen (`DISCORD_CLIENT_ID` / `DISCORD_CLIENT_SECRET`)
+
+---
+
+## 5. Container starten
+
+Im Projektroot (dort wo `docker-compose.yml` liegt):

 ```bash
-docker network create traefik-network   # only if it does not exist yet
 docker compose up -d --build
 ```

-| Service | Container | Exposure |
-|---------|-----------|----------|
-| Bot + FastAPI | `hexahost-bot` | Internal (`bot:8000`) — Discord Gateway outbound |
-| Dashboard | `hexahost-dashboard` | Traefik → `https://bot.hexahost.de` |
+Erster Build kann einige Minuten dauern (Python-Deps + Next.js-Build).

-Data volumes: `bot-db`, `bot-jsondb`, `bot-logs`.
+Status prüfen:

-Discord OAuth redirect: `https://bot.hexahost.de/api/auth/callback/discord`
+```bash
+docker compose ps
+docker compose logs -f bot
+docker compose logs -f dashboard
+```

-If your Traefik cert resolver is not named `letsencrypt`, set `TRAEFIK_CERT_RESOLVER` in `.env`. Entrypoints expected: `web` (80) and `websecure` (443).
+Erwartung:
+
+- `hexahost-bot` — online, Discord-Login, API auf Port 8000
+- `hexahost-dashboard` — läuft, Traefik routet `bot.hexahost.de`
+
+---
+
+## 6. Testen
+
+1. Browser: **https://bot.hexahost.de**
+2. Mit Discord anmelden
+3. Guilds sollten erscheinen (Bot muss auf dem Server sein + du brauchst Manage Server / Admin)
+
+---
+
+## Alltag: Updates & Wartung
+
+```bash
+# Neueste Version holen und neu bauen
+git pull
+docker compose up -d --build
+
+# Nur Neustart
+docker compose restart
+
+# Stoppen
+docker compose down
+
+# Logs
+docker compose logs -f --tail=100
+```
+
+Daten liegen in Docker-Volumes (`bot-db`, `bot-jsondb`, `bot-logs`) und bleiben bei `docker compose down` erhalten.  
+Volumes **löschen** (Daten weg): `docker compose down -v` — nur bewusst nutzen.
+
+---
+
+## Troubleshooting
+
+| Problem | Check |
+|---------|--------|
+| 502 / Gateway Timeout | `docker compose ps` — läuft `hexahost-dashboard`? Traefik am richtigen Netzwerk? |
+| Kein HTTPS-Zertifikat | DNS auf Server? Cert-Resolver-Name (`TRAEFIK_CERT_RESOLVER`)? Entrypoints `web`/`websecure`? |
+| Login schlägt fehl | Redirect-URL exakt wie oben? `NEXTAUTH_URL` = `https://bot.hexahost.de/`? |
+| Dashboard leer / API-Fehler | Gleiches `DASHBOARD_API_KEY`? Bot-Logs: `API_ENABLED` / Startfehler? |
+| Bot offline | `TOKEN` gültig? Intents? `docker compose logs bot` |
+| Traefik sieht Container nicht | Beide an `traefik-network`? Label `traefik.enable=true`? |
+
+Netzwerk-Check:
+
+```bash
+docker network inspect traefik-network
+```
+
+Dort sollten u. a. Traefik, `hexahost-bot` und `hexahost-dashboard` erscheinen.
+
+---
+
+## Architektur (kurz)
+
+```text
+Internet
+   │
+   ▼
+Traefik (traefik-network)
+   │  Host: bot.hexahost.de
+   ▼
+hexahost-dashboard :3000
+   │  DASHBOARD_API_URL=http://bot:8000/api/v1
+   ▼
+hexahost-bot :8000  (nur Docker-intern)
+   │
+   └── Discord Gateway (ausgehend)
+```
+
+Die Bot-API wird **nicht** über Traefik veröffentlicht; das Dashboard spricht sie nur im internen Netzwerk an.