Reverse-Proxy

Im Betrieb läuft Klokk hinter einem Reverse-Proxy, der HTTPS übernimmt. Klokk selbst lauscht auf einfachem HTTP, Port 8080.

Einstellungen in Klokk

Setzen Sie diese beiden Variablen, sobald Klokk hinter HTTPS läuft:

Variable	Wert	Wofür
BASE_URL	https://zeit.example.de (ohne Schrägstrich am Ende)	Links in E-Mails, Kalender-Abos und die Adresse, an die Passkeys gebunden sind
SESSION_SECURE_COOKIE	true (im Betrieb Standard)	Cookies werden nur über HTTPS gesendet

Achtung

Passkeys sind an die Domain aus BASE_URL gebunden (sofern WEBAUTHN_RPID nichts anderes sagt, siehe Sicherheit). Zieht Klokk auf eine andere Domain um, gelten vorhandene Passkeys nicht mehr und müssen neu hinzugefügt werden.

Proxy-Konfiguration

Caddy

Caddyfile

zeit.example.de {
  reverse_proxy klokk:8080
}

Caddy holt und erneuert die TLS-Zertifikate selbst und reicht X-Forwarded-For und X-Forwarded-Proto von sich aus weiter.

nginx

/etc/nginx/conf.d/klokk.conf

server {
    listen 443 ssl;
    http2 on;
    server_name zeit.example.de;

    # ssl_certificate / ssl_certificate_key, z. B. von certbot

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        # Live-Aktualisierungen (Server-Sent Events) bleiben lange offen.
        proxy_read_timeout 1h;
    }
}

Traefik

docker-compose.yml (Auszug)

services:
  klokk:
    image: klokkme/klokk:stable
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.klokk.rule=Host(`zeit.example.de`)"
      - "traefik.http.routers.klokk.entrypoints=websecure"
      - "traefik.http.routers.klokk.tls.certresolver=letsencrypt"
      - "traefik.http.services.klokk.loadbalancer.server.port=8080"

networks:
  proxy:
    external: true

Klokk braucht dann keinen veröffentlichten Port (ports: kann entfallen).

Live-Aktualisierungen: Klokk hält für Benachrichtigungen und die Stempeluhr eine Verbindung offen (/api/events, Server-Sent Events). nginx und Traefik bittet es, sie nicht zu puffern; schließt ein Proxy sie trotzdem, verbindet sich der Browser selbst neu.

Echte Client-Adressen

Klokk protokolliert die IP-Adresse der Clients (Audit-Log, Begrenzung von Anmeldeversuchen, IP-Freigabeliste für Admins). Hinter einem Proxy liest es X-Forwarded-For – aber nur von Proxys, denen es vertraut, damit niemand eine Adresse vortäuschen kann, indem er den Header selbst mitschickt.

• Ein Proxy auf demselben Host oder im privaten Netz (der Normalfall): nichts einzustellen. Klokk vertraut dem direkten Proxy, wenn seine Adresse privat oder Loopback ist, und übernimmt den Eintrag, den er angehängt hat.
• Mehrere Proxys hintereinander (etwa Cloudflare → eine WAF → Klokk): die äußeren in TRUSTED_PROXIES eintragen:

Wert	Vertraut
cloudflare	den veröffentlichten Adressbereichen von Cloudflare; CF-Connecting-IP gilt dann von dort
private	allen privaten und Loopback-Bereichen – für Ketten innerhalb eines privaten Netzes
203.0.113.10, 198.51.100.0/24	einzelnen Adressen oder CIDR-Bereichen

Mehrere Werte trennen Sie mit Kommas, zum Beispiel TRUSTED_PROXIES=cloudflare,private.

Tipp

Zur Kontrolle: anmelden und den eigenen Eintrag im Audit-Log ansehen. Steht dort die Adresse des Proxys statt Ihrer eigenen, fehlt eine Station in TRUSTED_PROXIES.