Refactor: Dokumentation nach docs/ verschoben
- Alle Markdown-Dateien (außer README.md) nach docs/ verschoben - Referenzen in README.md aktualisiert - /docs zu .dockerignore hinzugefügt
This commit is contained in:
Hördle Bot
289
docs/CADDY_SETUP.md
Normal file
289
docs/CADDY_SETUP.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Caddy-Setup für Hördle
|
||||
|
||||
Diese Anleitung erklärt, wie du Caddy als Reverse-Proxy mit automatischen Let's Encrypt Wildcard-Zertifikaten für die Domains `hoerdle.de` und `hördle.de` (xn--hrdle-jua.de) einrichtest.
|
||||
|
||||
## Übersicht
|
||||
|
||||
Caddy übernimmt folgende Aufgaben:
|
||||
- Automatische SSL/TLS-Zertifikate via Let's Encrypt
|
||||
- Wildcard-Zertifikate für beide Domains (inkl. Subdomains)
|
||||
- Reverse Proxy zu deinem Hördle-Container
|
||||
- HTTP zu HTTPS Redirect
|
||||
- Optimierte Einstellungen für Audio-Streaming und Uploads
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
1. Docker und Docker Compose installiert
|
||||
2. Zugriff auf deine GoDaddy Domain-Verwaltung
|
||||
3. Ports 80 und 443 müssen frei sein (Caddy übernimmt diese)
|
||||
|
||||
## Schritt 1: GoDaddy DNS-API-Zugangsdaten erstellen
|
||||
|
||||
Für Wildcard-Zertifikate benötigt Caddy DNS-01 Challenge, was API-Zugriff auf dein GoDaddy-Konto erfordert.
|
||||
|
||||
### GoDaddy API-Keys erstellen
|
||||
|
||||
1. Gehe zu [GoDaddy Developer Portal](https://developer.godaddy.com/)
|
||||
2. Melde dich mit deinem GoDaddy-Konto an
|
||||
3. Klicke auf **"Keys"** in der Navigation
|
||||
4. Klicke auf **"Create New API Key"**
|
||||
5. Fülle das Formular aus:
|
||||
- **Key Name**: z.B. "Hördle Caddy DNS"
|
||||
- **Environment**: Production (für echte Domains)
|
||||
6. Klicke auf **"Create"**
|
||||
7. **Wichtig**: Kopiere dir den **API Key** und das **API Secret** - das Secret wird nur einmal angezeigt!
|
||||
|
||||
### Alternative: Manuelle DNS-TXT-Records (ohne API)
|
||||
|
||||
Wenn du keine API-Keys verwenden möchtest, kannst du die DNS-TXT-Records manuell setzen. **Hinweis**: Dies ist nur für die initiale Zertifikatsanfrage möglich, nicht für automatische Erneuerungen.
|
||||
|
||||
Siehe Abschnitt "Manuelle DNS-Konfiguration (ohne API)" weiter unten.
|
||||
|
||||
## Schritt 2: Environment-Variablen konfigurieren
|
||||
|
||||
Erstelle eine `.env`-Datei im Projektverzeichnis (oder erweitere die bestehende):
|
||||
|
||||
```bash
|
||||
# GoDaddy API-Credentials für DNS-01 Challenge
|
||||
GODADDY_API_KEY=your_api_key_here
|
||||
GODADDY_API_SECRET=your_api_secret_here
|
||||
|
||||
# Optional: Email für Let's Encrypt Benachrichtigungen
|
||||
CADDY_EMAIL=markus@hoerdle.de
|
||||
```
|
||||
|
||||
**Wichtig**: Die `.env`-Datei sollte nicht in Git committed werden (sollte bereits in `.gitignore` sein).
|
||||
|
||||
## Schritt 3: Docker-Netzwerk erstellen
|
||||
|
||||
Caddy und Hördle müssen im gleichen Docker-Netzwerk kommunizieren:
|
||||
|
||||
```bash
|
||||
# Prüfe, ob das Netzwerk bereits existiert
|
||||
docker network ls | grep hoerdle
|
||||
|
||||
# Falls das Netzwerk bereits existiert, aber falsche Labels hat:
|
||||
# 1. Stoppe alle Container, die das Netzwerk nutzen
|
||||
docker compose -f docker-compose.yml down
|
||||
|
||||
# 2. Lösche das alte Netzwerk (falls keine Container mehr dranhängen)
|
||||
docker network rm hoerdle_default
|
||||
|
||||
# 3. Erstelle das Netzwerk neu
|
||||
docker network create hoerdle_default
|
||||
|
||||
# Falls das Netzwerk nicht existiert, erstelle es:
|
||||
docker network create hoerdle_default
|
||||
```
|
||||
|
||||
**Hinweis**: Die docker-compose.caddy.yml ist so konfiguriert, dass sie das Netzwerk als externes Netzwerk nutzt. Das bedeutet, dass das Netzwerk bereits existieren muss, bevor Caddy gestartet wird.
|
||||
|
||||
## Schritt 4: Caddy starten
|
||||
|
||||
### Option A: Mit docker-compose (Empfohlen)
|
||||
|
||||
```bash
|
||||
# Starte Hördle + Caddy zusammen
|
||||
docker compose -f docker-compose.yml -f docker-compose.caddy.yml --profile production up -d
|
||||
|
||||
# Nur Caddy starten (wenn Hördle bereits läuft)
|
||||
docker compose -f docker-compose.caddy.yml --profile production up -d
|
||||
```
|
||||
|
||||
### Option B: Nur Caddy starten (Hördle läuft bereits)
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.caddy.yml --profile production up -d
|
||||
```
|
||||
|
||||
## Schritt 5: DNS-Konfiguration in GoDaddy
|
||||
|
||||
### Automatisch (mit API-Keys)
|
||||
|
||||
Wenn du API-Keys konfiguriert hast, wird Caddy automatisch die benötigten DNS-TXT-Records erstellen. Keine manuellen DNS-Änderungen nötig!
|
||||
|
||||
### Manuell (ohne API-Keys)
|
||||
|
||||
Wenn du die API-Keys nicht verwenden möchtest, musst du die DNS-TXT-Records manuell setzen:
|
||||
|
||||
#### Für hoerdle.de:
|
||||
|
||||
1. Gehe zu deinem [GoDaddy DNS-Verwaltung](https://dcc.godaddy.com/manage/YOUR_DOMAIN/dns)
|
||||
2. Für jedes Wildcard-Zertifikat benötigst du einen TXT-Record:
|
||||
- **Typ**: TXT
|
||||
- **Name**: `_acme-challenge`
|
||||
- **Wert**: (wird von Let's Encrypt generiert - siehe Caddy-Logs)
|
||||
- **TTL**: 600 (10 Minuten)
|
||||
|
||||
**Wichtig**: Für Wildcard-Zertifikate brauchst du:
|
||||
- Einen TXT-Record für `_acme-challenge.hoerdle.de` (Domain selbst)
|
||||
- Einen TXT-Record für `_acme-challenge.*.hoerdle.de` (Wildcard)
|
||||
|
||||
#### Für hördle.de (xn--hrdle-jua.de):
|
||||
|
||||
Das gleiche Vorgehen für die Punycode-Domain:
|
||||
- `_acme-challenge.xn--hrdle-jua.de`
|
||||
- `_acme-challenge.*.xn--hrdle-jua.de`
|
||||
|
||||
**Hinweis**: Die manuelle Methode funktioniert nur für die initiale Zertifikatsanfrage. Für automatische Erneuerungen benötigst du die API-Keys.
|
||||
|
||||
## Schritt 6: Prüfen, ob alles funktioniert
|
||||
|
||||
### Caddy-Logs ansehen
|
||||
|
||||
```bash
|
||||
docker logs -f hoerdle-caddy
|
||||
```
|
||||
|
||||
Du solltest sehen:
|
||||
- Caddy startet erfolgreich
|
||||
- Let's Encrypt-Zertifikate werden angefordert
|
||||
- Zertifikate sind gültig
|
||||
|
||||
### Zertifikate prüfen
|
||||
|
||||
```bash
|
||||
# Prüfe Zertifikate im Browser
|
||||
# Öffne: https://hoerdle.de
|
||||
# Öffne: https://hördle.de
|
||||
```
|
||||
|
||||
Oder via Command-Line:
|
||||
|
||||
```bash
|
||||
# Prüfe Zertifikat für hoerdle.de
|
||||
openssl s_client -connect hoerdle.de:443 -servername hoerdle.de < /dev/null 2>/dev/null | openssl x509 -noout -text | grep "Subject:"
|
||||
|
||||
# Prüfe Zertifikat für hördle.de
|
||||
openssl s_client -connect xn--hrdle-jua.de:443 -servername xn--hrdle-jua.de < /dev/null 2>/dev/null | openssl x509 -noout -text | grep "Subject:"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Caddy startet nicht
|
||||
|
||||
**Problem**: Container stoppt sofort nach Start.
|
||||
|
||||
**Lösung**:
|
||||
1. Prüfe Caddy-Logs: `docker logs hoerdle-caddy`
|
||||
2. Prüfe Caddyfile-Syntax: `docker run --rm -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile:ro caddy:2-alpine caddy validate --config /etc/caddy/Caddyfile`
|
||||
3. Prüfe, ob Ports 80/443 frei sind: `sudo netstat -tlnp | grep -E ':80|:443'`
|
||||
|
||||
### Zertifikate werden nicht erstellt
|
||||
|
||||
**Problem**: Let's Encrypt-Zertifikate werden nicht angefordert.
|
||||
|
||||
**Lösung**:
|
||||
1. Prüfe GoDaddy API-Credentials in `.env`
|
||||
2. Prüfe Caddy-Logs für DNS-Challenge-Fehler
|
||||
3. Stelle sicher, dass die Domains korrekt auf deinen Server zeigen (A-Records)
|
||||
4. Bei manueller DNS-Konfiguration: Prüfe, ob TXT-Records korrekt gesetzt sind
|
||||
|
||||
### DNS-Challenge schlägt fehl
|
||||
|
||||
**Problem**: DNS-01 Challenge kann DNS-Records nicht erstellen.
|
||||
|
||||
**Lösung**:
|
||||
1. Prüfe GoDaddy API-Permissions
|
||||
2. Stelle sicher, dass API-Keys Production-Keys sind (nicht Development)
|
||||
3. Prüfe Domain-Ownership in GoDaddy
|
||||
4. Warte einige Minuten - DNS-Propagierung kann dauern
|
||||
|
||||
### Audio-Dateien funktionieren nicht
|
||||
|
||||
**Problem**: MP3-Dateien werden nicht korrekt gestreamt.
|
||||
|
||||
**Lösung**:
|
||||
1. Prüfe Caddy-Logs: `docker logs hoerdle-caddy | grep -i range`
|
||||
2. Prüfe, ob Range-Header weitergegeben werden (Browser DevTools → Network)
|
||||
3. Stelle sicher, dass der `/uploads/` Handle korrekt konfiguriert ist
|
||||
|
||||
### Container können nicht kommunizieren
|
||||
|
||||
**Problem**: Caddy kann den hoerdle-Container nicht erreichen.
|
||||
|
||||
**Lösung**:
|
||||
1. Prüfe, ob beide Container im gleichen Netzwerk sind:
|
||||
```bash
|
||||
docker network inspect hoerdle_default
|
||||
```
|
||||
2. Prüfe, ob hoerdle-Container läuft: `docker ps | grep hoerdle`
|
||||
3. Teste Verbindung von Caddy zu Hördle:
|
||||
```bash
|
||||
docker exec hoerdle-caddy wget -O- http://hoerdle:3000/api/health
|
||||
```
|
||||
**Hinweis**: Der Container-Port ist 3000 (nicht 3010, das ist nur der Host-Port).
|
||||
|
||||
### Netzwerk-Warnung beim Deployment
|
||||
|
||||
**Problem**: Warnung `network hoerdle_default was found but has incorrect label`
|
||||
|
||||
**Erklärung**: Diese Warnung ist **harmlos** und kann ignoriert werden. Docker Compose funktioniert trotzdem einwandfrei. Sie entsteht, wenn das Netzwerk bereits existiert, aber nicht von Docker Compose erstellt wurde.
|
||||
|
||||
**Optional: Warnung beheben** (nur wenn sie stört):
|
||||
```bash
|
||||
# Reparatur-Skript ausführen (stoppt Container kurz)
|
||||
./scripts/fix-network.sh
|
||||
|
||||
# Danach Container neu starten
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**Hinweis**: Das Reparatur-Skript stoppt alle Container kurz, die das Netzwerk nutzen. In Produktion sollte dies außerhalb der Hauptnutzungszeit erfolgen.
|
||||
|
||||
## Deployment-Workflow
|
||||
|
||||
### Caddy nur in Produktion aktivieren
|
||||
|
||||
Die `docker-compose.caddy.yml` verwendet das `production`-Profile. Um Caddy zu aktivieren:
|
||||
|
||||
```bash
|
||||
# Mit Production-Profile
|
||||
docker compose -f docker-compose.yml -f docker-compose.caddy.yml --profile production up -d
|
||||
|
||||
# Ohne Caddy (nur Hördle)
|
||||
docker compose -f docker-compose.yml up -d
|
||||
```
|
||||
|
||||
### Caddy aktualisieren
|
||||
|
||||
```bash
|
||||
# Pull neues Caddy-Image
|
||||
docker compose -f docker-compose.caddy.yml pull
|
||||
|
||||
# Restart Caddy-Container
|
||||
docker compose -f docker-compose.caddy.yml --profile production restart caddy
|
||||
```
|
||||
|
||||
### Caddy-Konfiguration ändern
|
||||
|
||||
Nach Änderungen am Caddyfile:
|
||||
|
||||
```bash
|
||||
# Caddyfile validieren
|
||||
docker run --rm -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile:ro caddy:2-alpine caddy validate --config /etc/caddy/Caddyfile
|
||||
|
||||
# Caddy neu laden (ohne Downtime)
|
||||
docker compose -f docker-compose.caddy.yml --profile production exec caddy caddy reload --config /etc/caddy/Caddyfile
|
||||
```
|
||||
|
||||
## Sicherheit
|
||||
|
||||
### API-Keys schützen
|
||||
|
||||
- **Niemals** API-Keys in Git committen
|
||||
- Verwende `.env`-Dateien (sollten in `.gitignore` sein)
|
||||
- Setze minimale Berechtigungen für API-Keys in GoDaddy
|
||||
- Rotiere API-Keys regelmäßig
|
||||
|
||||
### Firewall
|
||||
|
||||
Stelle sicher, dass nur Ports 80 und 443 öffentlich erreichbar sind. Port 3010 (Hördle) sollte nicht öffentlich erreichbar sein.
|
||||
|
||||
## Weitere Ressourcen
|
||||
|
||||
- [Caddy Dokumentation](https://caddyserver.com/docs/)
|
||||
- [Caddy DNS-Provider](https://caddyserver.com/docs/modules/tls.dns)
|
||||
- [GoDaddy API Dokumentation](https://developer.godaddy.com/doc/endpoint/domains)
|
||||
- [Let's Encrypt Wildcard-Zertifikate](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge)
|
||||
|
||||
Reference in New Issue
Block a user