elpatron/hoerdle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9006b208afff039358b231998c4f79fbb0902e14
hoerdle/docs/CADDY_SETUP.md
Hördle Bot e3a09864a6 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
2025-12-01 17:58:32 +01:00

290 lines
9.4 KiB
Markdown
Raw Blame History

# 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 View Git Blame Copy Permalink