meldestelle/docs/07_Infrastructure/Guides/Caddy_Pangolin_Deployment_Runbook.md

type, status, owner

type	status	owner
How-to	ACTIVE	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:

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

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.