hoerdle/docs/CADDY_SETUP.md

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
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):

# 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:

# 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)

# 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)

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
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

docker logs -f hoerdle-caddy

Du solltest sehen:

• Caddy startet erfolgreich
• Let's Encrypt-Zertifikate werden angefordert
• Zertifikate sind gültig

Zertifikate prüfen

# Prüfe Zertifikate im Browser
# Öffne: https://hoerdle.de
# Öffne: https://hördle.de

Oder via Command-Line:

# 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:

   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:

   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):

# 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:

# 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

# 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:

# 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
• Caddy DNS-Provider
• GoDaddy API Dokumentation
• Let's Encrypt Wildcard-Zertifikate