---
type: How-to
status: ACTIVE
owner: DevOps Engineer
---

# Runbook: Caddy & Pangolin Deployment (Plan-B Setup)

Dieses Dokument sichert das Wissen über die Konfiguration von Caddy als Webserver/Reverse-Proxy in Kombination mit Pangolin-Tunneln, welches während der "Plan-B" Online-Nennung erarbeitet wurde.

## 1. Architektur-Übersicht

*   **Pangolin:** Stellt den sicheren Tunnel vom lokalen Netzwerk (Zora) ins Internet her (ersetzt Cloudflare). Leitet Traffic auf spezifische lokale Ports weiter.
*   **Caddy:** Agiert als Reverse-Proxy und TLS-Terminierungspunkt. Nimmt Traffic von Pangolin (und lokalem Netz) an und routet ihn zu den internen Docker-Services (z.B. Frontend-Web, API-Gateway).

## 2. Caddy Konfiguration (`Caddyfile`)

Die Konfiguration befindet sich in `config/docker/caddy/web-app/Caddyfile`.

### Wichtige Erkenntnisse / Fallstricke:
*   **TLS/SSL:** Caddy wurde mit `auto_https off` konfiguriert, da die SSL-Terminierung extern (Pangolin/Edge) erfolgt. Caddy läuft intern auf Port 80.
*   **Same-Origin Strategy:** Um CORS-Probleme im Browser zu vermeiden, werden alle API-Anfragen (`/api/*`) über Caddy an den `mail-service:8085` geproxt. Dies macht die App robuster gegen Browser-Security-Policies.
*   **MIME-Types:** Explizite Setzung von `application/wasm` für `.wasm` Dateien ist für KMP-Web-Apps kritisch (siehe Snippet).
*   **COOP/COEP Header:** Für WASM/KMP-Web-Apps sind `Cross-Origin-Embedder-Policy "require-corp"` und `Cross-Origin-Opener-Policy "same-origin"` essentiell, damit SharedArrayBuffer etc. funktionieren.
*   **Caching:** 
    *   Assets mit Hashes im Namen sind `immutable` (max-age 1 Jahr).
    *   `.wasm` und `.js` Dateien wurden während Plan-B auf `no-store, no-cache, must-revalidate` gesetzt, um sicherzustellen, dass Teilnehmer immer die aktuellste Logik erhalten.
*   **Header-Weiterleitung:** Wichtige Header für das Backend: `X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto`.

### Aktuelles Plan-B Snippet:
```caddyfile
{
	auto_https off
}

:80 {
	root * /usr/share/caddy
	
	header {
		Cross-Origin-Embedder-Policy "require-corp"
		Cross-Origin-Opener-Policy "same-origin"
	}

	# API Proxy (Same-Origin Strategy)
	handle /api/* {
		reverse_proxy mail-service:8085 {
			header_up Host {upstream_hostport}
			header_up X-Real-IP {remote_host}
			header_up X-Forwarded-For {remote_host}
			header_up X-Forwarded-Proto {scheme}
		}
	}

	# Wasm MIME & Caching
	@wasm path *.wasm
	header @wasm Content-Type "application/wasm"

	@wasm_js path *.wasm *.js
	header @wasm_js Cache-Control "no-store, no-cache, must-revalidate"

	# SPA Fallback
	handle {
		try_files {path} /index.html
		file_server
	}
}
```

## 3. Pangolin Konfiguration

### Erkenntnisse aus Plan-B:
*   **Tunnel-Endpunkt:** Pangolin leitet den Traffic von der öffentlichen Domain (z.B. `meldestelle.mo-code.at`) auf den lokalen Port der Zora-Instanz weiter (standardmäßig Port 80, gemappt auf Host-Port via Docker).
*   **Stabilität:** Der Pangolin-Client läuft als persistenter Dienst auf der Zora-Node. Er ist extrem stabil gegenüber IP-Wechseln des ISP (DSL-Reconnect).
*   **Konfiguration:** Erfolgt primär über das Pangolin-Dashboard (Web-UI). Wichtig ist das Mapping der Resource auf die interne IP von Zora.

## 4. Deployment-Workflow (Erkenntnisse)

### SMTP-Härtung (Plan-B Mail-Service)
In `dc-planb.yaml` wurden folgende Einstellungen für World4You (SMTP) als stabil verifiziert:
```yaml
SPRING_MAIL_HOST: "smtp.world4you.com"
SPRING_MAIL_PORT: "587"
SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE: "true"
SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_REQUIRED: "true"
```
Wichtig: `STARTTLS_REQUIRED` verhindert den Versand, falls keine verschlüsselte Verbindung aufgebaut werden kann.

### Infrastruktur-Optimierung
*   **Zero-Downtime:** `docker compose exec web-app caddy reload --config /etc/caddy/Caddyfile` ermöglicht Konfigurationsänderungen ohne Container-Neustart.
*   **Health-Check:** Der `/health` Endpunkt in Caddy wurde genutzt, um die Erreichbarkeit des Containers zu prüfen.
*   **In-Memory DB:** Für Plan-B wurde die H2-Datenbank (In-Memory) genutzt, da keine Persistenz über den Turnier-Zeitraum hinaus (außer E-Mail-Kopien) nötig war. Dies vereinfachte das Deployment massiv.

---
*Hinweis: Dieses Dokument basiert auf den erfolgreichen Feld-Tests vom April 2026.*