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

