Fehlerbehebung

Fang mit dem Log an: docker compose logs --tail 100 checky (Cloudflare: Worker → Logs oder wrangler tail) und curl -s <BASE_URL>/health.

Der Container startet nicht

• Invalid configuration: mit einer Liste — korrigier die genannten Variablen in der .env. Typisch: BETTER_AUTH_SECRET: required in production, ein Secret mit weniger als 32 Zeichen oder uses a published example value; generate a random one (ein Beispiel-Secret wurde kopiert).
• Port schon belegt — setz CHECKY_PORT=3001 (oder einen anderen freien Port) in der .env.
• Permission denied auf /data — das Image läuft als uid 65532. Wenn du statt des benannten Volumes ein Host-Verzeichnis einbindest, gib es mit chown -R 65532:65532 frei.

Es kommen keine E-Mails an

• In der ersten Logzeile steht email: console? Dann ist SMTP_URL nicht gesetzt — E-Mails werden nur geloggt.
• Such im Log nach SMTP-Fehlern (Anmeldung, TLS). Port 465 braucht smtps://, Port 587 smtp://.
• Zugestellt, aber im Spam: SPF, DKIM und DMARC für die Domain aus EMAIL_FROM einrichten.
• Erinnerungen folgen der Benachrichtigungseinstellung jeder Person (alle, nur bei Fälligkeit, nur zur Deadline, keine) und gehen während Abwesenheiten und an Feiertagen nicht raus.

Antworten beantworten den Check-in nicht

• EMAIL_REPLY_DOMAIN muss gesetzt sein, bevor die Erinnerung rausgeht (die Reply-To-Adresse steht in der E-Mail).
• Docker: INBOUND_WEBHOOK_SECRET gesetzt, und der Anbieter schickt mit dem Secret an /api/v1/inbound/email. 401 = falsches Secret, 404 = Webhook aus (kein Secret konfiguriert).
• Antworten zählen bis sieben Tage nach der Deadline, einmal pro Check-in.

Probleme bei der Anmeldung

• Falsche Weiterleitung oder Cookies halten nicht — BASE_URL muss genau die URL im Browser sein (Schema, Host, Port, kein Schrägstrich am Ende).
• Passkeys scheitern — Passkeys brauchen https:// (oder localhost) und hängen am Host aus BASE_URL. Nach einem Domainwechsel legen alle neue Passkeys an.
• „Registrierung nicht erlaubt“ — bei Self-Hosting ist nur das erste Konto frei; alle anderen brauchen eine Einladung oder eine verifizierte Domain mit automatischem Beitritt.
• Alle wurden abgemeldet — BETTER_AUTH_SECRET hat sich geändert.
• One-Tap-Links sind „ungültig“ — APP_SECRET hat sich geändert, oder der Link ist zu alt.

Live-Updates erscheinen nicht

Das Dashboard aktualisiert sich über Server-Sent Events auf /api/v1/events. Hinter einem Proxy das Puffern abschalten: Caddy flush_interval -1, nginx proxy_buffering off;. Ein Neuladen der Seite zeigt immer den aktuellen Stand.

Rate Limiting wirkt hinter einem Proxy falsch

Ohne TRUST_PROXY=true scheinen alle Anfragen von der Adresse des Proxys zu kommen und teilen sich ein Limit. Setz TRUST_PROXY=true (und CLIENT_IP_HEADERS, falls dein Proxy einen anderen Header nutzt).

SSO und Domains

• Domain-Verifizierung scheitert — der TXT-Eintrag ist noch nicht sichtbar (DNS kann Stunden dauern). Prüfen mit dig TXT _checky-verification.example.com. Kommt dein Server nicht an cloudflare-dns.com, setz DNS_OVER_HTTPS_URL.
• „Domain schon vergeben“ — eine andere Organisation hat sie verifiziert.
• Interner IdP abgelehnt — SSO_ALLOW_PRIVATE_IDP=true setzen und die Origin in TRUSTED_ORIGINS eintragen.
• SSO geht nach dem Umzug nicht mehr — Redirect-/ACS-URLs beim IdP anpassen und Client-Secrets neu eintragen, falls der Export ohne Passphrase lief.

Feiertage lassen sich nicht importieren

Der Feiertagsimport fragt Nager.Date ab (HOLIDAYS_API_URL). Auf einem Server ohne Internetzugang betreibst du ein eigenes Nager.Date und zeigst die Variable darauf — oder trägst Feiertage als Abwesenheiten ein.

Import abgelehnt

• import.version_unsupported — die Datei stammt aus einem neueren Checky; aktualisiere zuerst das Ziel.
• Eine selbst betriebene Installation nimmt einen Import nur an, solange sie leer ist — starte mit einem frischen Volume.

Immer noch nicht weiter?

Schreib an [email protected] mit der Version (/health), wie du Checky betreibst, und den passenden Logzeilen (vorher Secrets entfernen).