Force HTTPS mit Let's Encrypt

Einrichtung

Über die UI

Der Toggle sitzt im Route-Wizard in Step 2 — Transport.

Route erstellen oder bearbeiten
In Step 2 Force HTTPS Toggle aktivieren (Default: an)
Speichern

Es gibt keine weitere Konfiguration — Caddy erledigt alles automatisch. Siehe auch den Hinweis oben: der Toggle hat auf dem aktuellen Stand keine schaltende Wirkung.

Über die API

# HTTPS aktivieren
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "https_enabled": true
  }'

ACME Email konfigurieren

Die ACME Email wird global in den GateControl-Einstellungen oder per Umgebungsvariable gesetzt:

# In docker-compose.yml oder .env
GC_CADDY_EMAIL=admin@example.com

# Optionale alternative ACME CA (z.B. Staging)
GC_CADDY_ACME_CA=https://acme-staging-v02.api.letsencrypt.org/directory

Wichtige Hinweise

DNS muss korrekt zeigen. Die Domain muss per A/AAAA-Record auf die öffentliche IP des GateControl-Servers zeigen. Ohne korrekte DNS-Auflösung schlägt die ACME Challenge fehl.
Ports 80 und 443 müssen offen sein. Let's Encrypt nutzt Port 80 für die HTTP-01 Challenge. Port 443 wird für HTTPS benötigt. Beide Ports müssen von außen erreichbar sein.
Kein Cloudflare Proxy. Wenn die Domain hinter Cloudflare Proxy (orangene Wolke) steht, schlägt die HTTP-01 Challenge fehl. Verwende DNS Only (graue Wolke) oder wechsle zu DNS-01 Challenge (nicht von GateControl unterstützt).
Rate Limits beachten. Let's Encrypt hat Rate Limits: max 50 Zertifikate pro registrierter Domain pro Woche. Bei vielen Subdomains kann das relevant werden.
Zertifikate werden in Caddys Datenspeicher abgelegt (/data/caddy/) und überleben Container-Neustarts.
Wenn Force HTTPS in der UI deaktiviert wird, bleibt die Route trotzdem auf :443 erreichbar und Caddy versucht weiter, ein Zertifikat zu holen (siehe Implementation-Hinweis oben). Soll eine Route wirklich nur über HTTP erreichbar sein, muss das auf Infrastruktur-Ebene (Reverse-Proxy-Konfiguration / Firewall) erzwungen werden.

Troubleshooting

Problem	Ursache	Lösung
Zertifikat wird nicht ausgestellt	DNS zeigt nicht auf Server	A-Record prüfen, `dig` oder `nslookup` verwenden
ACME Challenge fehlgeschlagen	Port 80 blockiert	Firewall / Router prüfen, Port 80 freigeben
Too many certificates	Let's Encrypt Rate Limit	1 Stunde warten, dann erneut versuchen
Zertifikat abgelaufen	Caddy konnte nicht erneuern	Caddy Logs prüfen, DNS und Port 80 prüfen

Siehe auch

guides/certificates.md — Zertifikate verwalten und Fehler debuggen
concepts/routing.md — srv0-Listener und Host-Matching
BACKEND-HTTPS.md — TLS auf dem Caddy-zu-Backend-Leg