Kurz gesagt

Problem: Nachdem ich Traefik GeoBlock eingeschaltet hatte, funktionierte der Connector von Claude zu Home Assistant nicht mehr. Home Assistant selbst lief für alle zu Hause ganz normal.

Lösung: Der Connector ruft von den Servern von Anthropic in den USA an, und GeoBlock ließ nur meine eigenen Länder durch. Ein Eintrag in allowedIPAddresses mit dem veröffentlichten IP-Bereich des Anbieters hat das Problem gelöst.

Getestet mit: Traefik 3, GeoBlock-Plugin (PascalMinder) 0.3.8, Home Assistant mit einem MCP-Server für Claude

In Traefik absichern habe ich GeoBlock vor jeden Dienst gesetzt: Nur Besucher aus den Ländern, in denen meine Familie lebt, kommen durch, alle anderen bekommen eine 403. Das hat genau wie geplant funktioniert. Etwas zu gut, wie sich herausstellte: Es hat auch einen Besucher ausgesperrt, den ich haben wollte, meinen eigenen KI-Assistenten.

Das ist eine kurze Geschichte über eine Sicherheitsmaßnahme, die ihren Job macht, dabei etwas kaputt macht, das du brauchst, und wie du herausfindest, welche es war.

1. Das Symptom

Ich nutze Claude mit einem Connector zu Home Assistant, damit ich Sensoren, Automationen und Logs in normaler Sprache abfragen kann. Kurz nach dem Absichern erreichte der Connector Home Assistant nicht mehr. Jeder Versuch scheiterte.

Gleichzeitig war mit Home Assistant alles in Ordnung: Das Dashboard lud zu Hause, die App auf dem Handy funktionierte, die Automationen liefen. Betroffen war nur dieser eine Client.

2. Was ich zuerst geprüft habe (und warum mich das in die Irre geführt hat)

Ein Connector, der sich per OAuth anmeldet, hat viele Teile, die kaputtgehen können. Also schaut man zuerst dort:

• Anmeldung und Tokens: Ein abgelaufenes Token oder eine kaputte OAuth-Einrichtung würde einen streikenden Client erklären. Neu verbinden hilft aber nicht, wenn die Anfragen blockiert werden, bevor sie ankommen.
• Home-Assistant-Logs: nichts. Kein fehlgeschlagener Login, kein Fehler der MCP-Integration, nicht einmal eine Anfrage.
• Die URL: Sie öffnet sich im Browser ganz normal.

Das leere Home-Assistant-Log war der eigentliche Hinweis, und man liest es leicht falsch. „Keine Fehler“ klang nach „in Home Assistant ist alles in Ordnung“. Tatsächlich hieß es: Die Anfragen kamen nie an. Etwas vor Home Assistant hat sie beantwortet. Und „im Browser geht es“ bewies gar nichts, denn mein Browser kommt aus einem erlaubten Land.

3. Die eigentliche Ursache: Traefik GeoBlock hat seinen Job gemacht

Die Connectors von Claude laufen nicht in meinem Browser oder auf meinem Handy. Sie rufen meinen Server aus der Infrastruktur von Anthropic auf, und die steht in den USA. Für GeoBlock ist das einfach eine weitere Anfrage aus einem Land, das nicht auf der Liste steht.

Zwei Logs zeigen es. GeoBlock schreibt jede abgelehnte Anfrage in eine eigene Datei. Eine Zeile sieht so aus (Beispieladresse):

INFO: GeoBlock: 2026/10/16 09:14:52 geoblock@docker: request denied [203.0.113.17] for country [US] due to: country is not allowed

Und das Access-Log von Traefik zeigt die 403 mit leerem Backend ("-" nach dem Router-Namen). Der Strich heißt: Die Anfrage hat den Dienst nie erreicht (wieder eine Beispielzeile):

203.0.113.17 - - [16/Oct/2026:09:14:52 +0000] "POST /api/webhook/… HTTP/1.1" 403 0 "-" "-" 4711 "homeassistant@docker" "-" 1ms

Das Log ist voll mit Scannern aus aller Welt, die Anfragen des Connectors fallen darin also nicht von selbst auf. Vergleichst du die abgelehnten Adressen mit dem Bereich, den Anthropic für seinen ausgehenden Verkehr veröffentlicht, dann schon.

4. Die Lösung: den veröffentlichten IP-Bereich erlauben

GeoBlock hat genau dafür eine Option: allowedIPAddresses. Adressen in dieser Liste kommen durch, egal aus welchem Land. Ein Label mehr am Traefik-Container:

      # Claude connectors call from Anthropic's published outbound range
      # source: https://platform.claude.com/docs/en/api/ip-addresses
      - "traefik.http.middlewares.geoblock.plugin.geoblock.allowedIPAddresses[0]=160.79.104.0/21"

Dann den Container neu erstellen, damit Traefik die neuen Labels liest:

docker compose up -d traefik

Der Bereich oben ist der, den Anthropic zum Zeitpunkt des Schreibens angibt. Prüf auf der Seite mit den IP-Adressen von Anthropic den aktuellen Stand, bevor du ihn übernimmst. Derselbe Weg funktioniert für jeden anderen Dienst, der dich aus dem Ausland erreichen muss, solange der Anbieter seine IP-Bereiche veröffentlicht.

5. So prüfst du es

1. Prüfen, ob Traefik das Label übernommen hat:
   docker inspect traefik --format '{{ index .Config.Labels "traefik.http.middlewares.geoblock.plugin.geoblock.allowedIPAddresses[0]" }}'
2. Den Connector einmal benutzen (bei mir: Claude nach einem Sensorwert fragen).
3. Sicherstellen, dass der Bereich nicht mehr als abgelehnt auftaucht:
   grep -E '\[160\.79\.1(0[4-9]|1[01])\.' traefik-logs/geoblock.log | tail
   Keine neuen Zeilen nach dem Neustart heißt: GeoBlock lässt den Connector durch.

Was ich gelernt habe

• „Im Browser geht es“ ist kein Test für eine Geo-Sperre. Frag dich, von wo der streikende Client wirklich anruft.
• Ein leeres Log der Anwendung ist ein Befund, keine Sackgasse: Die Anfrage wurde vorher gestoppt.
• Bevor du eine Allow-Liste einschaltest, schreib jeden Dienst auf, der von außen anruft: KI-Connectors, Webhooks, Monitoring, Push-Dienste. Jeder davon braucht eine bewusste Ausnahme oder einen anderen Weg.

Das komplette Setup mit GeoBlock und CrowdSec steht in Traefik absichern: Geo-Blocking, CrowdSec und Single Sign-on.

Kurz gesagt

Problem: Jeder Login über einen neuen OAuth2/OpenID-Provider in Authentik scheitert mit invalid_request: „The request is otherwise malformed“.

Lösung: Der Provider wurde über die API angelegt, und seine Liste grant_types war leer. Setz sie auf authorization_code und refresh_token und teste danach die Authorize-URL mit curl.

Getestet mit: Authentik 2026.8, WordPress mit dem Plugin OpenID Connect Generic 3.11

Die meisten Apps lege ich in Authentik über die Admin-Oberfläche an. Für diesen Blog wollte ich es per Skript machen und habe den OAuth2-Provider mit einem einzigen API-Aufruf erstellt. Der Aufruf klappte, die Anwendung tauchte auf, das WordPress-Plugin war mit der richtigen Client-ID, dem Secret und den Endpunkten eingerichtet. Und dann funktionierte kein einziger Login.

Die Lösung war am Ende ein einziges Feld. Sie zu finden hat länger gedauert als nötig, weil die Fehlermeldung in die falsche Richtung zeigt.

1. Das Symptom: „request is otherwise malformed“

Ein Klick auf „Login with OpenID Connect“ in WordPress schickte mich zu Authentik, und Authentik schickte mich sofort zurück, mit einer Fehlerseite statt eines Login-Formulars:

invalid_request
The request is otherwise malformed

Keine Abfrage von Benutzername oder Passwort. Authentik hat die Anfrage abgelehnt, bevor der Login-Flow überhaupt begonnen hat.

2. Was ich zuerst geprüft habe (und warum mich das in die Irre geführt hat)

„Malformed request“ klingt so, als hätte der Client etwas Falsches geschickt. Also bin ich die üblichen Verdächtigen auf der WordPress-Seite durchgegangen:

• Redirect-URI: Zeichen für Zeichen mit dem Provider verglichen. Authentik vergleicht strikt, schon ein fehlender Schrägstrich oder ein anderer Query-String reicht für einen Fehler. Sie stimmte.
• Client-ID: noch einmal kopiert, keine Leerzeichen am Rand.
• Scopes: openid email profile, alle drei im Provider vorhanden.
• Endpunkte: aus der .well-known/openid-configuration des Providers übernommen.

Alles war richtig. Die Anfrage von WordPress war in Ordnung. Das Problem lag auf der Seite von Authentik, und das verrät dir die Fehlermeldung im Browser nicht.

3. Die eigentliche Ursache: eine leere grant_types-Liste

Das Server-Log von Authentik hatte die hilfreichere Meldung. Mit Docker Compose:

docker compose logs server --since 10m | grep -i grant

Dort stand „Invalid grant_type for provider“. Jeder OAuth2-Provider in Authentik hat eine Liste erlaubter Grant Types. Legst du einen Provider in der Admin-Oberfläche an, füllt das Formular sinnvolle Standardwerte ein. Die API macht das nicht: grant_types ist ein optionales Feld, und wenn du es weglässt, wird der Provider mit einer leeren Liste gespeichert. Eine leere Liste heißt: kein Grant Type ist erlaubt, nicht einmal der normale Authorization-Code-Flow.

Mein API-Aufruf sah ungefähr so aus (gekürzt):

curl -X POST https://id.example.com/api/v3/providers/oauth2/ \
  -H "Authorization: Bearer $AUTHENTIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Provider for My Blog",
    "client_type": "confidential",
    "authorization_flow": "<flow uuid>",
    "invalidation_flow": "<flow uuid>",
    "redirect_uris": [
      {"matching_mode": "strict",
       "url": "https://blog.example.com/wp-admin/admin-ajax.php?action=openid-connect-authorize"}
    ],
    "signing_key": "<certificate uuid>",
    "property_mappings": ["<openid>", "<email>", "<profile>"]
  }'

Alle Pflichtfelder sind da, also nimmt die API den Aufruf ohne Warnung an. Genau das eine Feld, an dem hängt, ob sich überhaupt jemand anmelden kann, fehlt.

4. Die Lösung

Setz die Grant Types am bestehenden Provider. Ein Login-Flow für eine Website braucht authorization_code, und refresh_token, wenn die App ihre Tokens erneuert:

curl -X PATCH https://id.example.com/api/v3/providers/oauth2/<provider id>/ \
  -H "Authorization: Bearer $AUTHENTIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grant_types": ["authorization_code", "refresh_token"]}'

Du kannst den Provider auch in der Admin-Oberfläche öffnen und ihn dort mit beiden Grant Types angehakt speichern. Bei neuen Providern gehört die Zeile gleich in den Aufruf zum Anlegen:

    "grant_types": ["authorization_code", "refresh_token"],

Wenn du schon dabei bist, vergleich auch die Token-Laufzeiten (access_token_validity, refresh_token_threshold) mit einem Provider, den du in der Oberfläche angelegt hast. Über die API angelegte Provider bekommen nicht immer dieselben Werte, und gleich eingestellte Provider sind leichter zu pflegen.

5. So prüfst du es (ohne Browser)

Um einen Provider zu testen, musst du dich nicht durch den Login klicken. Ruf den Authorize-Endpunkt mit curl auf und schau, wohin Authentik dich schickt:

curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' \
  "https://id.example.com/application/o/authorize/?client_id=<client id>&response_type=code&scope=openid&redirect_uri=https%3A%2F%2Fblog.example.com%2Fwp-admin%2Fadmin-ajax.php%3Faction%3Dopenid-connect-authorize"

• Funktioniert: ein 302 zum Login-Flow von Authentik, zum Beispiel /if/flow/default-authentication-flow/….
• Kaputt: ein 302 zurück zur Redirect-URI deiner App mit error=… in der URL. Der Name des Fehlers sagt dir, was Authentik nicht gepasst hat.

Was ich gelernt habe

• „Malformed request“ im Browser heißt nicht, dass der Client falsch ist. Lies das Server-Log des Identity Providers, bevor du in der App etwas änderst.
• Admin-Oberfläche und API legen nicht dasselbe Objekt an. Die Oberfläche füllt Standardwerte ein, die API speichert genau das, was du schickst.
• Ein curl-Test der Authorize-URL prüft einen Provider in Sekunden, ganz ohne Login.

Wie der Blog-Login von Anfang bis Ende eingerichtet ist, steht in Single Sign-on für WordPress mit Authentik. Alle Felder eines Providers beschreibt die offizielle Authentik-Dokumentation.

Kurz gesagt

Problem: Ein Nextcloud-Container läuft in einer Minute. Damit er schnell ist, über HTTPS erreichbar, ohne Warnungen in der Admin-Übersicht und sicher zu sichern, braucht es deutlich mehr als docker run nextcloud.

Lösung: Ein Compose-Projekt mit Nextcloud, PostgreSQL, Redis und einem Cron-Container, veröffentlicht über Traefik, Anmeldung über Authentik, Dokumente im Browser mit dem eingebauten Collabora-Server und ein nächtliches Backup im Wartungsmodus.

Getestet mit: Nextcloud 35 (offizielles Image nextcloud:35, PHP 8.5), PostgreSQL 16, Redis, Traefik 3.7, Authentik, Docker Compose auf einem kleinen Heimserver

Nextcloud ist der Dienst in meinem Homelab, den die ganze Familie wirklich nutzt: Dateien, Kalender, Kontakte, Notizen und seit Kurzem auch Office-Dokumente. Deshalb ist es auch der Dienst, den ich am wenigsten kaputt machen möchte. Dieser Artikel geht meine Konfiguration durch: die Container, die Einstellungen, auf die es hinter einem Reverse Proxy ankommt, Single Sign-on, Nextcloud Office, die Pflege nach Updates und wie ich alles sichere. Er baut auf meinem Traefik-Artikel auf; wenn du noch keinen Reverse Proxy hast, fang dort an.

1. Der Stack im Überblick

Das Tag nextcloud:35 ist eine bewusste Entscheidung. Es folgt den Minor- und Patch-Versionen von Version 35, mein Update-Skript (es führt dreimal pro Woche docker compose pull && docker compose up -d aus) holt Sicherheitsupdates also von selbst. Eine neue Hauptversion kommt dagegen nie überraschend. Nextcloud kann immer nur eine Hauptversion auf einmal springen, und vor diesem Schritt möchte ich die Release Notes lesen und ein frisches Backup haben.

2. Die .env-Datei

Alles, was sich von Installation zu Installation unterscheidet, und jedes Passwort steht in einer .env-Datei neben der Compose-Datei. Mach sie nur für ihren Besitzer lesbar: chmod 600 .env.

NEXTCLOUD_IMAGE_TAG=nextcloud:35
NEXTCLOUD_HOSTNAME=cloud.example.com
NEXTCLOUD_URL=https://cloud.example.com
NEXTCLOUD_TIMEZONE=Europe/Berlin

NEXTCLOUD_DB_NAME=nextcloud
NEXTCLOUD_DB_USER=nextcloud
NEXTCLOUD_DB_PASSWORD=bitte-aendern-lang-und-zufaellig

NEXTCLOUD_REDIS_PASSWORD=bitte-auch-aendern

# wird nur beim allerersten Start gelesen
NEXTCLOUD_ADMIN_USERNAME=admin
NEXTCLOUD_ADMIN_PASSWORD=bitte-ebenfalls-aendern

Gute Passwörter erzeugst du zum Beispiel mit openssl rand -base64 32. Admin-Benutzer und -Passwort liest Nextcloud nur, wenn es sich beim ersten Start installiert. Sie später in der .env zu ändern, bewirkt nichts.

3. Datenbank, Redis und Cron

networks:
  nextcloud-network:
  proxy:
    external: true

volumes:
  nextcloud-app:
  nextcloud-postgres:
  redis-data:

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - nextcloud-postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${NEXTCLOUD_DB_NAME}
      POSTGRES_USER: ${NEXTCLOUD_DB_USER}
      POSTGRES_PASSWORD: ${NEXTCLOUD_DB_PASSWORD}
    networks:
      - nextcloud-network
    healthcheck:
      test: ["CMD", "pg_isready", "-q", "-d", "${NEXTCLOUD_DB_NAME}", "-U", "${NEXTCLOUD_DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 60s

  redis:
    image: redis
    restart: unless-stopped
    command: ["redis-server", "--requirepass", "${NEXTCLOUD_REDIS_PASSWORD}"]
    volumes:
      - redis-data:/data
    networks:
      - nextcloud-network
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  nextcloud-cron:
    image: ${NEXTCLOUD_IMAGE_TAG}
    restart: unless-stopped
    entrypoint: /cron.sh
    volumes:
      - nextcloud-app:/var/www/html
      - /srv/nextcloud/data:/var/www/html/data
    networks:
      - nextcloud-network

Ein paar Details, die man leicht übersieht:

• Datenbank und Redis hängen nur im nextcloud-network. Sie haben keine veröffentlichten Ports, und Traefik sieht sie nicht. Nur Nextcloud spricht mit ihnen.
• Die Healthchecks sind hier wichtig. Nextcloud wartet auf service_healthy (siehe unten) und startet seine Installation oder sein Upgrade deshalb nie gegen eine Datenbank, die noch hochfährt.
• Der Cron-Container nutzt dasselbe Image und dieselben Volumes wie Nextcloud, startet aber /cron.sh, das alle 5 Minuten cron.php aufruft. Stell Nextcloud nach dem ersten Start von AJAX auf Cron um: occ background:cron (oder Verwaltungseinstellungen → Grundeinstellungen).

4. Der Nextcloud-Container

  nextcloud:
    image: ${NEXTCLOUD_IMAGE_TAG}
    restart: unless-stopped
    volumes:
      - nextcloud-app:/var/www/html
      - /srv/nextcloud/data:/var/www/html/data
    environment:
      TZ: ${NEXTCLOUD_TIMEZONE}
      POSTGRES_HOST: postgres
      POSTGRES_DB: ${NEXTCLOUD_DB_NAME}
      POSTGRES_USER: ${NEXTCLOUD_DB_USER}
      POSTGRES_PASSWORD: ${NEXTCLOUD_DB_PASSWORD}
      REDIS_HOST: redis
      REDIS_HOST_PORT: 6379
      REDIS_HOST_PASSWORD: ${NEXTCLOUD_REDIS_PASSWORD}
      NEXTCLOUD_ADMIN_USER: ${NEXTCLOUD_ADMIN_USERNAME}
      NEXTCLOUD_ADMIN_PASSWORD: ${NEXTCLOUD_ADMIN_PASSWORD}
      NEXTCLOUD_TRUSTED_DOMAINS: ${NEXTCLOUD_HOSTNAME}
      # hinter dem Reverse Proxy
      OVERWRITEHOST: ${NEXTCLOUD_HOSTNAME}
      OVERWRITEPROTOCOL: https
      OVERWRITECLIURL: ${NEXTCLOUD_URL}
      TRUSTED_PROXIES: 172.16.0.0/12
      # große Uploads und Office
      PHP_MEMORY_LIMIT: 8G
      PHP_UPLOAD_LIMIT: 8G
    networks:
      - nextcloud-network
      - proxy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 90s
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

Zwei Speicherorte. Das benannte Volume nextcloud-app enthält die Anwendung selbst, samt config/config.php und den Apps, die du aus dem App-Store installierst (custom_apps). Die Dateien der Benutzer liegen in einem Bind-Mount auf einer großen Platte (hier /srv/nextcloud/data). Durch die Trennung kann ich die Daten auf eine eigene SSD legen und beides unterschiedlich sichern. Vergiss nur das Volume nicht: config.php enthält das Secret und den Passwort-Salt der Instanz, und ohne sie wird eine Wiederherstellung nur aus den Daten deutlich schwieriger.

Die Reverse-Proxy-Einstellungen. Nextcloud bekommt von Traefik nur einfaches HTTP auf Port 80. Ohne diese vier Variablen baut es falsche Links, lehnt Anmeldungen über den „nicht vertrauenswürdigen“ Hostnamen ab oder zeigt jeden Besucher mit der IP-Adresse von Traefik:

172.16.0.0/12 deckt die Standard-Netzbereiche von Docker ab, in denen Traefik läuft. Trag ein, was docker network inspect proxy auf deinem Host anzeigt, und nicht mehr: Jeder Bereich, dem du vertraust, kann Client-IPs fälschen.

5. Veröffentlichen über Traefik

    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.nextcloud.rule=Host(`cloud.example.com`)"
      - "traefik.http.routers.nextcloud.entrypoints=websecure"
      - "traefik.http.routers.nextcloud.tls.certresolver=letsencrypt"
      - "traefik.http.routers.nextcloud.middlewares=nextcloud-dav,nextcloud-wellknown,nextcloud-compress,nextcloud-hsts"
      - "traefik.http.services.nextcloud.loadbalancer.server.port=80"

      # CalDAV/CardDAV-Erkennung für Handys und Kalender-Apps
      - "traefik.http.middlewares.nextcloud-dav.redirectregex.permanent=true"
      - "traefik.http.middlewares.nextcloud-dav.redirectregex.regex=https?://([^/]*)/.well-known/(card|cal)dav"
      - "traefik.http.middlewares.nextcloud-dav.redirectregex.replacement=https://$${1}/remote.php/dav/"

      # alle anderen .well-known-URLs (webfinger, nodeinfo, ...)
      - "traefik.http.middlewares.nextcloud-wellknown.redirectregex.permanent=true"
      - "traefik.http.middlewares.nextcloud-wellknown.redirectregex.regex=https?://([^/]*)(/.well-known[^#]*)"
      - "traefik.http.middlewares.nextcloud-wellknown.redirectregex.replacement=https://$${1}/index.php$${2}"

      - "traefik.http.middlewares.nextcloud-compress.compress=true"
      - "traefik.http.middlewares.nextcloud-hsts.headers.stsSeconds=15552000"

Die beiden Weiterleitungen beheben die häufigste Warnung in der Admin-Übersicht („Dein Webserver ist nicht richtig eingerichtet, um /.well-known/caldav aufzulösen“). Außerdem finden Handys damit Kalender und Kontakte, wenn du nur den Hostnamen eingibst. Das $$ ist nötig, weil Compose ${1} sonst als Variable liest.

HSTS (die Zeile mit stsSeconds) sagt Browsern, dass sie diesen Host die nächsten 180 Tage nur noch über HTTPS aufrufen sollen. Das beseitigt eine weitere Warnung. Bei mir setzt eine allgemeine Security-Header-Middleware am Entrypoint websecure HSTS ohnehin für jeden Dienst (siehe den Artikel zum Absichern). Die Zeile bleibt trotzdem hier, damit der Nextcloud-Stack HSTS auch dann bekommt, wenn ich daran einmal etwas ändere.

Für große Uploads brauchst du übrigens keine Buffering-Middleware. Traefik hat standardmäßig keine Größenbegrenzung für Anfragen, und die Nextcloud-Clients laden große Dateien ohnehin in Stücken hoch.

6. Anmeldung mit Authentik

Wie die meisten meiner Dienste nutzt Nextcloud Single Sign-on mit Authentik. Ich verwende die offizielle App OpenID Connect user backend (user_oidc). Die Einrichtung auf der Authentik-Seite (ein OAuth2/OpenID-Provider plus eine Anwendung) ist dieselbe wie in meinem Artikel zu WordPress-SSO. Die Redirect-URI für Nextcloud ist https://cloud.example.com/apps/user_oidc/code.

Danach im Nextcloud-Container:

alias occ='docker compose exec -u www-data nextcloud php occ'

occ app:install user_oidc

occ user_oidc:provider Authentik \
  --clientid="<Client-ID aus Authentik>" \
  --clientsecret="<Client-Secret aus Authentik>" \
  --discoveryuri="https://id.example.com/application/o/nextcloud/.well-known/openid-configuration" \
  --scope="openid email profile" \
  --mapping-uid=preferred_username \
  --mapping-display-name=name \
  --mapping-email=email \
  --unique-uid=0

Entscheidend sind die letzten beiden Optionen. --mapping-uid=preferred_username zusammen mit --unique-uid=0 macht den Nextcloud-Benutzernamen gleich dem Authentik-Benutzernamen statt eines langen Hashes. Ein Authentik-Benutzer anna landet so im bestehenden Nextcloud-Konto anna mit all ihren Dateien, und die Pfade bleiben lesbar.

Die Anmeldeseite zeigt jetzt einen Button „Log in with Authentik“. Die normale Nextcloud-Anmeldung bleibt darunter verfügbar. Die behalte ich mit Absicht: Wenn Authentik ausfällt, funktioniert das lokale Admin-Konto trotzdem. Desktop- und Handy-Clients melden sich über den Browser an und nutzen damit ebenfalls SSO.

7. Nextcloud Office ohne zusätzlichen Container

Um .docx-, .xlsx- und .odt-Dateien im Browser zu öffnen, nutze ich Nextcloud Office mit dem eingebauten CODE-Server (Collabora Online Development Edition). Er läuft im Nextcloud-Container: kein zusätzlicher Container, kein zusätzlicher Hostname, kein zusätzliches Zertifikat. Für einen Haushalt mit einer Handvoll Benutzer reicht das völlig.

occ app:install richdocumentscode   # der eingebaute Collabora-Server (auf ARM: richdocumentscode_arm64)
occ app:install richdocuments       # die App Nextcloud Office
occ richdocuments:activate-config

Danach sollte unter Verwaltungseinstellungen → Office stehen, dass der eingebaute Server verwendet wird. Die WOPI-URL zeigt auf https://cloud.example.com/custom_apps/richdocumentscode/proxy.php?req=.

Prüf auch, ob die Version der Office-App zu deiner Nextcloud-Hauptversion passt. Nach einem Upgrade bleibt manchmal eine ältere, nicht kompatible Version installiert; occ app:update --all behebt das.

8. Saubere Admin-Übersicht nach einem Update

Nach einem Hauptversions-Upgrade zeigt Verwaltungseinstellungen → Übersicht meistens ein paar neue Warnungen. Diese Befehle habe ich gebraucht, ungefähr in dieser Reihenfolge (mit frischem Backup):

# neue Datenbank-Indizes, die mit dem Upgrade kamen (dauert Sekunden bis Minuten)
occ db:add-missing-indices

# nur wenn die Übersicht es vorschlägt; kann bei großen Instanzen dauern
occ maintenance:repair --include-expensive

# Telefonnummern in Profilen ohne Ländervorwahl
occ config:system:set default_phone_region --value="DE"

# aufwendige Hintergrundjobs nachts ausführen (Stunde in UTC, 1 = 01:00-05:00)
occ config:system:set maintenance_window_start --type=integer --value=1

# dieselben Prüfungen wie die Admin-Übersicht, auf der Kommandozeile
occ setupchecks

Den Speicher-Cache richtet das offizielle Image selbst ein: APCu für den lokalen Cache und Redis für die Datei-Sperren, sobald REDIS_HOST gesetzt ist. Prüfen kannst du das mit occ config:system:get memcache.locking.

9. Backups

Nextcloud wird jede Nacht von einem Skript auf dem Host gesichert, nicht innerhalb des Stacks. Die Reihenfolge ist wichtig:

1. occ maintenance:mode --on, damit sich während der Kopie keine Datei und keine Datenbankzeile ändert
2. pg_dump der Datenbank in eine einfache SQL-Datei (nie die laufenden Datenbankdateien kopieren)
3. rsync des Datenordners in einen Snapshot mit Datum, mit Bandbreitenlimit, damit die Platten nutzbar bleiben
4. eine Kopie von config/, custom_apps/ und themes/ aus dem App-Volume, dazu die Compose-Datei und die .env
5. occ maintenance:mode --off, in einem trap, damit das auch passiert, wenn ein Schritt fehlschlägt

In einer normalen Nacht dauert der Wartungsmodus ein paar Minuten. Unveränderte Dateien sind zwischen den Snapshots per Hardlink verknüpft, 14 Tage Verlauf kosten also kaum mehr Platz als eine Kopie. Wie Snapshots, Datenbank-Dumps und die Offline-Kopie zusammenspielen, steht in meinem Backup-Artikel.

10. Wenn etwas nicht funktioniert

Die nützlichsten Befehle für den Rest:

# die neuesten Fehler aus dem Nextcloud-Log
occ log:tail 20

# worüber sich die Admin-Übersicht beschweren würde
occ setupchecks

# welche Labels (und damit welche Traefik-Middlewares) der Container wirklich hat
docker inspect nextcloud-nextcloud-1 --format '{{json .Config.Labels}}'

Was ich gelernt habe

• Die Hauptversion festlegen. Mit nextcloud:35 bekomme ich Sicherheitsupdates automatisch, und das große Upgrade passiert, wenn ich es entscheide, mit Backup.
• Die Reverse-Proxy-Einstellungen sind nicht optional. Die meisten seltsamen Nextcloud-Probleme hinter Traefik lagen an OVERWRITEPROTOCOL oder TRUSTED_PROXIES.
• Prüfen, was wirklich läuft. Ein Label, das von einem späteren überschrieben wird, erzeugt keinen Fehler. docker inspect zeigt die Wahrheit, die Compose-Datei nur die Absicht.
• Das App-Volume gehört ins Backup. Lange habe ich nur den Datenordner und die Datenbank gesichert. Ohne config.php ist eine Wiederherstellung deutlich schwieriger.
• SSO über OIDC, nicht über Forward-Auth. Die Sync-Clients funktionieren weiter, und die lokale Anmeldung ist mein Notausgang.

Kurz gesagt

Problem: Ein Container, der still und leise stoppt, eine Platte, die vollläuft, ein Dienst, der die falsche Seite liefert: Auf einem Heimserver merkt man das meist erst, wenn jemand aus der Familie sagt „es geht nicht“.

Lösung: Home Assistant überwacht den Docker-Host so, wie es auch den Rest des Hauses überwacht: eine Entität pro Container, Host-Werte, HTTP-Prüfungen von außen, den Backup-Status und eine Handvoll Automationen, die eine Telegram-Nachricht schicken, wenn etwas nicht stimmt.

Getestet mit: Home Assistant 2026.10, der Portainer-Integration, meinem eigenen Add-on SSH Linux Management (MQTT), etwa 25 Containern auf einem Docker-Host, Telegram und der Companion-App für Benachrichtigungen

Home Assistant weiß schon, wie es mir sagt, dass ein Fenster offen oder eine Batterie leer ist. Statt also ein eigenes Monitoring für meinen Server zu betreiben, lasse ich Home Assistant auch den überwachen. Alles landet an einem Ort: ein Dashboard, ein Benachrichtigungskanal und Automationen, die ich ohnehin schreiben kann. Dieser Artikel zeigt die zwei Integrationen, mit denen ich den Docker-Host in Home Assistant bringe, die Alarme, die darauf aufbauen, und was ich dabei gelernt habe.

1. Zwei Integrationen, zwei Aufgaben

Home Assistant läuft in einer VM, die Container auf dem Host daneben. Um in den Host hineinzuschauen, nutze ich zwei Integrationen, weil jede in etwas anderem gut ist:

Für die Alarme unten nutze ich die Status-Sensoren von Portainer für die Container und das SSH-Add-on für alles rund um den Host. Wenn du nur eine willst, fang mit Portainer an: Das ist eine eingebaute Integration und liefert pro Container am meisten.

2. Die Portainer-Integration

Läuft Portainer schon auf deinem Docker-Host, ist das der schnellste Einstieg:

1. In Portainer dein Benutzerprofil öffnen → Access tokens → Add access token, und den Token kopieren.
2. In Home Assistant: Einstellungen → Geräte & Dienste → Integration hinzufügen → Portainer, die Adresse von Portainer und den Token eintragen.
3. Home Assistant legt ein Gerät pro Container an, mit Entitäten wie binary_sensor.<container>_status, sensor.<container>_memory_usage, sensor.<container>_restart_count und update.<container>_image_update_available.

Eine Sache macht Portainer nicht: Löschst du einen Container, bleibt sein Gerät in Home Assistant als „nicht verfügbar“ stehen. Entferne es von Hand (Einstellungen → Geräte, das Gerät, Löschen), sonst füllen sich deine Dashboards und Automationen langsam mit toten Entitäten.

3. Das SSH-Add-on: Host-Werte ohne root

Für den Host selbst (Platte, CPU, RAM, VMs) habe ich ein kleines Home-Assistant-Add-on geschrieben, SSH Linux Management. Es öffnet eine ausgehende SSH-Verbindung zum Host und veröffentlicht, was es findet, per MQTT-Discovery, sodass die Entitäten ohne YAML in Home Assistant erscheinen:

• Docker: Der entfernte Docker-Socket wird durch die SSH-Verbindung weitergeleitet. Es wird kein Docker-TCP-Port geöffnet, und Änderungen an Containern kommen sofort über den Docker-Event-Stream an.
• Host-Werte: CPU, Speicher und Plattenbelegung pro Mountpoint (ich beobachte / und die Datenplatte von Nextcloud).
• VMs: libvirt-VMs als Schalter mit Neustart-Button, über virsh auf derselben Verbindung.
• Das SSH-Konto ist nicht root: Es ist ein normaler Benutzer in der Gruppe docker (und libvirt), und der Host-Schlüssel wird bei der ersten Verbindung festgehalten.

Eine Lehre aus dem Betrieb: Die ersten Versionen haben jede Docker-Entität nach der ID des Containers benannt. Jedes docker compose up nach einem Update erzeugt aber einen neuen Container mit neuer ID, also bekam Home Assistant jedes Mal eine neue Entität, und nach ein paar Wochen hatte ich switch.…_traefik, …_traefik_2 bis …_traefik_5. Version 0.11.0 benennt die Entitäten nach dem Namen des Containers und entfernt Discovery-Einträge von Containern, die es nicht mehr gibt. Wenn du selbst MQTT-Discovery schreibst: Nimm für die unique_id etwas, das ein Neuerstellen überlebt.

4. Alarm: ein Container ist gestoppt

Die wichtigste Automation ist auch die einfachste: Ist der Status-Sensor eines Containers zwei Minuten lang aus, kommt eine Nachricht mit seinem Namen. Die zwei Minuten verhindern Fehlalarme bei normalen Neustarts (Updates, Neuerstellen):

alias: System - Docker - Container Down Alert
description: Ein überwachter Container läuft 2 Minuten nicht → Telegram + Push.
mode: parallel
max: 10
triggers:
  - trigger: state
    entity_id:
      - binary_sensor.traefik_status
      - binary_sensor.crowdsec_status
      - binary_sensor.authentik_server_status
      - binary_sensor.nextcloud_nextcloud_1_status
      - binary_sensor.vaultwarden_status
      - binary_sensor.zigbee2mqtt_status
      # … eine Zeile pro Container, der dir wichtig ist
    to: "off"
    for:
      minutes: 2
actions:
  - action: telegram_bot.send_message
    data:
      title: "🔴 Docker-Container gestoppt"
      message: "{{ trigger.to_state.attributes.friendly_name }} läuft seit 2 Minuten nicht."
  - action: notify.mobile_app_dein_handy
    data:
      title: "🔴 Docker-Container gestoppt"
      message: "{{ trigger.to_state.attributes.friendly_name }} läuft seit 2 Minuten nicht."

• mode: parallel: Startet Docker selbst neu, stoppen mehrere Container gleichzeitig. Jeder soll seine eigene Nachricht bekommen, nicht nur der erste.
• to: "off", nicht „nicht an“: Ein Sensor, der unavailable wird (Portainer nicht erreichbar, Container gelöscht), löst nicht aus. Das ist Absicht: Es verhindert eine Flut von Alarmen, wenn Portainer neu startet, heißt aber auch, dass ein gelöschter Container still aus der Überwachung fällt.

5. Laufen heißt nicht funktionieren: HTTP-Prüfungen

Ein Container kann „laufen“, während der Dienst darin eine Fehlerseite liefert oder der Reverse Proxy davor den Verkehr ins Leere schickt. Deshalb ruft Home Assistant alle zehn Minuten auch die öffentlichen Adressen auf, so wie es ein Besucher tun würde, und prüft den HTTP-Statuscode. Die Aufrufe sind shell_command-Einträge in der configuration.yaml:

shell_command:
  curl_check_nextcloud: "curl -s -o /dev/null -w '%{http_code}' --max-time 10 https://cloud.example.com/status.php"
  curl_check_traefik: "curl -s -o /dev/null -w '%{http_code}' --max-time 10 https://traefik.example.com/dashboard/"

Die Automation führt jeden Befehl aus, liest den Statuscode aus der Antwort und vergleicht ihn mit dem, was dieser Dienst antworten sollte:

triggers:
  - trigger: time_pattern
    minutes: "/10"
actions:
  - action: shell_command.curl_check_traefik
    response_variable: traefik
  - if:
      - condition: template
        value_template: "{{ traefik.stdout not in ['302', '401'] }}"
    then:
      - action: telegram_bot.send_message
        data:
          title: "🔴 Prüfung Traefik-Dashboard fehlgeschlagen"
          message: "Erwartet war ein Login (302/401), gekommen ist {{ traefik.stdout }}."

• Prüf auf die richtige Antwort, nicht auf irgendeine. Mein Traefik-Dashboard und mein Wiki liegen hinter Single Sign-on, also müssen sie mit einer Umleitung zum Login (302) oder 401 antworten. Ein 200 hieße, dass sie plötzlich für alle offen sind. Die Prüfung erwischt einen kaputten Login, nicht nur einen kaputten Dienst.
• Plane Wartung ein. Mein nächtliches Nextcloud-Backup schaltet den Wartungsmodus ein, der mit 503 antwortet. Zwischen 02:55 und 04:30 Uhr ignoriert die Automation genau diesen Code für Nextcloud, und nur diesen.

6. Plattenplatz und der Host

Eine volle Platte ist der klassische Grund, warum ein ganzer Server auf einmal ausfällt: Datenbanken schreiben nicht mehr, Container stürzen ab, Logs, die das erklären würden, können nicht geschrieben werden. Mit den Platten-Sensoren des SSH-Add-ons ist das ein Trigger aus zwei Zeilen:

triggers:
  - trigger: numeric_state
    entity_id:
      - sensor.ssh_host_myserver_host_disk_use
      - sensor.ssh_host_myserver_host_disk_use_data
    above: 85
actions:
  - action: telegram_bot.send_message
    data:
      message: "⚠️ {{ trigger.to_state.attributes.friendly_name }} ist zu {{ trigger.to_state.state }} % belegt."

Bei 85 % habe ich Tage, nicht Minuten, um zu reagieren. Dieselben Sensoren stehen als Anzeigen auf dem Dashboard, neben CPU und Speicher.

7. Backups und Updates

• Backups: Ein Skript auf dem Host schreibt alle fünf Minuten den Zustand jedes Backup-Jobs in eine JSON-Datei. Das SSH-Add-on liest diese Datei und legt einen Sensor pro Job an, dazu einen Binärsensor „Backup-Problem“. Ist der zehn Minuten lang an (ein Job ist fehlgeschlagen, ein Snapshot ist älter als 26 Stunden, die Backup-Platte ist nicht eingehängt), bekomme ich eine Nachricht mit dem Grund. Die Details stehen in meinem Backup-Artikel.
• Updates: Eine Automation startet dreimal pro Woche um 04:00 Uhr mein Docker-Update-Skript per SSH (docker compose pull und up -d pro Stack). Der Container-Alarm oben ist das Sicherheitsnetz: Macht ein Update einen Container kaputt, weiß ich es vor dem Frühstück. Beim Reverse Proxy hält eine feste Hauptversion dieses Risiko klein (siehe meinen Traefik-Artikel).
• Versionswechsel: Für Zigbee2MQTT speichere ich zusätzlich die zuletzt bekannte Version in einem input_text-Helfer und schicke eine Nachricht, wenn sie sich ändert, mit der Erinnerung, die Release Notes zu lesen. Das habe ich eingebaut, nachdem ein Update das Verhalten einiger Geräte geändert hatte und ich es erst Tage später bemerkt habe.

8. Das Dashboard

Eine Ansicht „Server“ auf meinem Haupt-Dashboard zeigt die Host-Anzeigen (CPU, RAM, beide Platten), den Backup-Status und eine Kachel pro Container. Jede Kachel zeigt, ob der Container läuft, und ein Tipp auf ihr Symbol startet ihn neu:

type: tile
entity: switch.ssh_host_myserver_docker_vaultwarden
name: Vaultwarden
icon: mdi:restart
icon_tap_action:
  action: perform-action
  perform_action: button.press
  target:
    entity_id: button.ssh_host_myserver_docker_vaultwarden_restart

Das ist nicht für den täglichen Gebrauch gedacht. Es ist die Seite, die ich öffne, wenn eine Nachricht kommt, um auf einen Blick zu sehen, ob ein einzelner Container ausgefallen ist oder der ganze Host ein Problem hat, und um den offensichtlichen Kandidaten vom Handy aus neu zu starten.

Was ich gelernt habe

• Ein Ort für Alarme. Telegram lese ich sowieso. Ein eigenes Monitoring mit eigener App wäre noch etwas, das ich ignoriere.
• Prüf auch von außen. „Container läuft“ und „Dienst funktioniert für einen Besucher“ sind zwei verschiedene Fragen. Ein Container kann einwandfrei laufen, während sein Login kaputt ist oder der Proxy woandershin zeigt.
• Prüf die erwartete Antwort. Eine Login-Seite, die plötzlich 200 liefert, ist ein Sicherheitsproblem, kein Erfolg.
• Gib jedem Alarm eine kurze Verzögerung. Zwei Minuten für Container, zehn für Backups: Echte Probleme bleiben, Neustarts wecken dich nicht.
• Räum auf, wenn du einen Container entfernst. Gerät löschen, aus der Alarmliste und vom Dashboard nehmen. Tote Entitäten machen ein Dashboard, dem du nicht mehr traust.

Kurz gesagt

Problem: In einem Homelab sammeln sich Dinge, die man nicht neu herunterladen kann: Dokumente, Passwörter, Fotos, jahrelange Sensordaten, die Kopplung jedes Zigbee-Geräts. Eine kaputte Platte, ein schiefgegangenes Update oder ein Ransomware-Angriff, und alles ist weg.

Lösung: Nächtliche Snapshots jedes Dienstes auf eine eigene Platte (Datenbanken als Dumps, Dateien mit rsync-Hardlinks), eine dritte Kopie, die sich ein Laptop auf eine verschlüsselte SSD holt, eine Überwachung, die Alarm schlägt, wenn etwas fehlt, und ein getestetes Restore-Skript.

Getestet mit: etwa zehn Diensten in Docker (Nextcloud, Vaultwarden, Paperless-ngx, Authentik, BookStack, Zigbee2MQTT, Traefik, PostgreSQL für Home Assistant), zwei WordPress-Seiten bei einem Webhoster, Bash + rsync + systemd-Timern, Home Assistant für die Alarme

Backups sind der langweiligste Teil eines Homelabs, bis zu dem Tag, an dem man eins braucht. Ich habe meins Schritt für Schritt aufgebaut, meist nach „was wäre wenn…“-Momenten, und am Ende sind es einfache Bash-Skripte, rsync und systemd-Timer geworden: keine Backup-Software mit eigener Datenbank, die ich erst wiederherstellen müsste. Dieser Artikel zeigt das ganze Setup: was ich sichere, wie die Snapshots funktionieren, warum Datenbanken gedumpt statt kopiert werden, wie die dritte Kopie gegen einen gehackten Server geschützt ist, woran ich jede Nacht erkenne, dass es geklappt hat, und wie eine Wiederherstellung aussieht.

1. Drei Kopien, zwei Platten, eine davon außer Reichweite

Die klassische Regel heißt 3-2-1: drei Kopien deiner Daten, auf zwei verschiedenen Medien, eine davon außer Haus. So sieht meine Version aus, und hier hat sie ihre Grenzen:

Ehrlich gesagt steht die dritte Kopie im selben Haus. Gegen Feuer oder Einbruch hilft sie nicht; dafür müsste die SSD woanders liegen, oder eine verschlüsselte Cloud-Kopie wäre der nächste Schritt. Für alles andere haben diese drei Ebenen bisher jedes echte Problem abgedeckt, das ich hatte.

2. Was gesichert wird

Jeder Dienst hat sein eigenes kleines Skript und seine eigene Uhrzeit, sodass ein fehlschlagender Job die anderen nie blockiert und der schwere Nextcloud-Job zuletzt läuft:

Bewusst nicht gesichert: Logs, Caches, Warteschlangen, die Sperrliste von CrowdSec (die baut sich selbst neu auf) und die Live-Datenbankordner. Die sind unbrauchbar, solange die Datenbank läuft; die Dumps sind das Backup.

3. Snapshots mit rsync-Hardlinks

Jeder Lauf legt einen Ordner mit Datum an, etwa 2026-10-20_0030. Jeder dieser Ordner sieht aus wie eine vollständige Kopie: du kannst darin stöbern, einzelne Dateien herauskopieren oder alles wiederherstellen. Dateien, die sich seit der letzten Nacht nicht geändert haben, werden aber nicht noch einmal kopiert. Sie sind Hardlinks auf dieselbe Datei im vorherigen Snapshot und belegen keinen zusätzlichen Platz. Genau das macht die rsync-Option --link-dest:

/backup/paperless_backup/
├── 2026-10-19_0030/
│   ├── paperless-db.dump   Datenbank-Dump
│   ├── media/              alle Dokumente (größtenteils Hardlinks)
│   ├── data/               Suchindex, Klassifikator
│   ├── compose/            docker-compose.yml, .env
│   └── rsync.log
├── 2026-10-20_0030/
├── latest -> 2026-10-20_0030
└── backup-paperless.sh    das Skript kopiert sich selbst hierher

• Einen alten Snapshot zu löschen ist sicher. Eine Datei verschwindet erst von der Platte, wenn der letzte Snapshot gelöscht wird, der auf sie zeigt.
• Das Dateisystem muss Hardlinks können: ext4, XFS oder btrfs. Nicht exFAT oder NTFS – das typische Format einer neuen USB-Platte.
• Hardlinks sind keine zusätzlichen Kopien. Dreißig Snapshots eines unveränderten Dokuments sind trotzdem nur eine Datei auf der Platte. Stirbt dieser Sektor, sind alle dreißig betroffen. Dafür gibt es die dritte Kopie.
• Das Skript kopiert sich selbst neben die Snapshots, damit die Anleitung auf der Backup-Platte liegt, auch wenn der Server weg ist.

4. Datenbanken werden gedumpt, nie kopiert

Wer die Dateien einer laufenden Datenbank kopiert, bekommt ein Abbild eines bewegten Ziels: halb geschriebene Seiten, ein Write-Ahead-Log, das nicht dazu passt. Das lässt sich vielleicht wiederherstellen, vielleicht auch nicht. Ein Dump bittet die Datenbank selbst um einen konsistenten Export, während sie weiterläuft. Und jeder Dump wird direkt nach dem Schreiben geprüft:

Ein Dump, der seine Prüfung nicht besteht, stoppt den ganzen Job, und der Snapshot der Nacht wird nie zu latest (nächster Abschnitt). Ein kaputtes Backup ist schlimmer als keins, weil du es erst merkst, wenn du es brauchst.

5. Ein Backup-Skript, erklärt

Alle meine Skripte folgen demselben Muster. Hier das für Paperless, leicht gekürzt:

#!/usr/bin/env bash
set -Eeuo pipefail

PROJECT=/srv/docker/paperless          # Compose-Ordner
DEST=/backup/paperless_backup
KEEP_DAYS=30
STAMP=$(date +%F_%H%M)
SNAP=$DEST/$STAMP
WORK=$SNAP.partial

fail() { echo "ERROR: $*"; exit 1; }

# 1. nie die Systemplatte füllen, wenn die Backup-Platte fehlt
mountpoint -q /backup || fail "/backup is not mounted"

mkdir -p "$DEST" && chmod 700 "$DEST"
rm -rf "$DEST"/*.partial               # Reste eines fehlgeschlagenen Laufs
mkdir -p "$WORK"

LINK=()
[ -d "$DEST/latest" ] && LINK=(--link-dest="$DEST/latest/media")

# 2. Datenbank-Dump + Prüfung
cd "$PROJECT"
docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' > "$WORK/paperless-db.dump"
docker compose exec -T db pg_restore --list < "$WORK/paperless-db.dump" > /dev/null 
  || fail "dump check failed"

# 3. Dateien, unveränderte als Hardlinks auf den letzten Snapshot
rsync -aHAX --numeric-ids "${LINK[@]}" "$PROJECT/data/media/" "$WORK/media/"

# 4. erst jetzt wird der Snapshot echt
mv "$WORK" "$SNAP"
ln -sfn "$STAMP" "$DEST/latest"
cp -f "$0" "$DEST/"

# 5. Aufbewahrung
find "$DEST" -mindepth 1 -maxdepth 1 -type d -name '20??-??-??_????' 
  -mtime +"$KEEP_DAYS" -exec rm -rf {} +

• set -Eeuo pipefail: jeder fehlschlagende Befehl stoppt das Skript. Ein Backup-Skript, das nach einem Fehler weitermacht, erzeugt Backups, die gut aussehen und es nicht sind.
• mountpoint -q: ist die USB-Platte nicht eingehängt, ist /backup nur ein leerer Ordner auf der Systemplatte. Ohne diese Prüfung füllt die erste Nacht nach einem Plattenausfall deine System-SSD.
• Der .partial-Ordner: der Snapshot entsteht unter einem vorläufigen Namen und wird erst umbenannt, wenn alles geklappt hat. Ein fehlgeschlagener Lauf wird nie zu latest, also verlinkt der nächste Lauf weiter auf den letzten guten.
• rsync -aHAX --numeric-ids: behält Rechte, Hardlinks, ACLs, erweiterte Attribute und die numerischen Besitzer-IDs. Container laufen oft unter Benutzer-IDs, die es auf dem Host nicht gibt; mit Namen statt Nummern würde eine Wiederherstellung die Besitzer falsch setzen.
• Aufbewahrung nach Ordneralter: find -mtime +30 entfernt Snapshots, die älter als 30 Tage sind. Dank der Hardlinks ist das immer sicher.

6. Zeitplan mit systemd-Timern

Ich nutze systemd-Timer statt cron. Sie protokollieren jeden Lauf im Journal, holen Läufe nach, die verpasst wurden, während der Server aus war (Persistent=true), und ein Dienst kann warten, bis die Backup-Platte eingehängt ist:

# /etc/systemd/system/backup-paperless.service
[Unit]
Description=Paperless backup
RequiresMountsFor=/backup
After=docker.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup-paperless.sh

# /etc/systemd/system/backup-paperless.timer
[Unit]
Description=Nightly Paperless backup

[Timer]
OnCalendar=*-*-* 00:30
Persistent=true

[Install]
WantedBy=timers.target

Eingeschaltet wird er mit systemctl enable --now backup-paperless.timer. systemctl list-timers zeigt, wann jeder Job zuletzt lief und wann er als Nächstes läuft, und journalctl -u backup-paperless zeigt seine Ausgabe. Meine Jobs starten zwischen 23:30 und 03:00 Uhr, mindestens 15 Minuten auseinander, damit sie sich nie um die Platte streiten.

7. Dienste, die besondere Sorgfalt brauchen

• Nextcloud: der Job schaltet den Wartungsmodus ein, dumpt die Datenbank, kopiert die Dateien und schaltet ihn wieder aus. Sonst könnte jemand zwischen Dump und Dateikopie eine Datei hochladen, und beides passt nicht mehr zusammen. Die Kopie läuft mit einer Bandbreitenbegrenzung von rsync (--bwlimit), damit die Platten nicht ausgelastet sind, und um 03:00 Uhr, wenn niemand etwas hochlädt. In einer normalen Nacht sind das wenige Minuten Wartungsmodus.
• Zigbee2MQTT: sein Ordner enthält den Netzwerkschlüssel und die Datenbank aller gekoppelten Geräte. Ohne ihn muss jedes Gerät neu gekoppelt werden. Der Container wird für die wenigen Sekunden der Kopie pausiert (docker pause, nicht gestoppt), damit die Datenbankdatei konsistent ist.
• Authentik und BookStack: die Datenbank allein reicht nicht. Beide haben in ihrer .env einen geheimen Schlüssel, der Sitzungen signiert oder Daten verschlüsselt. Stell den Dump zusammen mit der .env aus derselben Nacht wieder her, sonst funktionieren Logins und verschlüsselte Felder nicht mehr.
• Der Reverse Proxy: die acme.json von Traefik enthält alle Zertifikate und den Let’s-Encrypt-Kontoschlüssel (siehe meinen Traefik-Artikel). Ohne sie fordert Traefik jedes Zertifikat neu an und kann in Ratenlimits laufen.
• Seiten beim Webhoster: der Server meldet sich mit einem SSH-Schlüssel an, holt den WordPress-Ordner als tar-Archiv und dumpt die Datenbank auf dem Host. Die Backups des Hosters sind ein Bonus, kein Plan.

8. Die dritte Kopie: geholt, nur lesend, verschlüsselt

Der naheliegende Weg zu einer zweiten Kopie: der Server schiebt sie irgendwohin. Das Problem: ist der Server gehackt oder von Ransomware befallen, hat der Angreifer denselben Zugriff und kann auch diese Kopie löschen oder verschlüsseln. Deshalb funktioniert meine dritte Kopie andersherum. Ein Laptop holt sich den neuesten Snapshot jedes Jobs auf eine verschlüsselte USB-SSD, und der Server hat keinen Weg dorthin:

Die rrsync-Einschränkung ist eine Zeile in der authorized_keys des Servers:

command="sudo rrsync -ro /backup",restrict ssh-ed25519 AAAA… offsite-pull

Der Job auf dem Laptop läuft stündlich, tut aber nur etwas, wenn es Sinn ergibt: höchstens einmal am Tag, nur am Netzteil, nie während der Server seine eigenen Backups macht (23:15–04:30 Uhr), und nur wenn die SSD angesteckt ist und der Server antwortet. Außerdem prüft er, was er kopiert:

• Stichproben: Dumps nicht leer, gzip-Archive lesbar, die Vaultwarden-Datenbank besteht ihre Integritätsprüfung, die Zertifikatsdatei ist nicht leer.
• Ransomware-Alarm: vor der Nextcloud-Kopie zählt ein Probelauf, wie viele Dateien sich geändert haben. Sind es mehr als 20 %, stimmt etwas gewaltig nicht (so sieht Massenverschlüsselung aus). Die Kopie wird behalten, aber alte Generationen werden nicht mehr gelöscht, bis ich es mir angesehen habe.
• Längerer Verlauf als auf dem Server: die neuesten 7 Kopien, dann eine pro Woche für 8 Wochen und eine pro Monat für 12 Monate. Nextcloud mit etwa 800 GB behält 10 Generationen.

9. Wissen, dass es geklappt hat

Ein Backup, das vor drei Wochen still und leise aufgehört hat, ist der häufigste Weg, Daten zu verlieren. Deshalb sammelt ein kleines Python-Skript auf dem Server alle fünf Minuten den Zustand jedes Jobs und schreibt ihn in eine JSON-Datei: letzter Lauf, Ergebnis, Alter des neuesten Snapshots, ob der Timer aktiv ist, ob die Backup-Platte eingehängt ist.

• Eine kleine Statusseite auf dem Server zeigt das als Tabelle.
• Home Assistant liest dieselbe Datei und legt pro Job einen Sensor an (ok, failed, stale, …). Hat ein Job zehn Minuten lang ein Problem, bekomme ich eine Push-Benachrichtigung und eine Telegram-Nachricht. „Stale“ heißt, dass der neueste Snapshot älter als 26 Stunden ist; das erwischt auch einen Timer, der einfach nie gelaufen ist.
• Abdeckungsprüfung: das Skript listet außerdem jeden laufenden Container auf und vergleicht ihn mit einer Liste abgedeckter Dienste. Ein neuer Container ohne Backup-Job erscheint als Warnung. Damit war die Lücke geschlossen, vor der ich am meisten Angst hatte: an einem Sonntagnachmittag einen Dienst hinzufügen und sein Backup vergessen.

Zur Abdeckungsliste gehört eine Hausregel: jeder neue Container bekommt seinen Backup-Job, seinen Wiederherstellungsschritt und seinen Eintrag in der Abdeckungsliste in derselben Änderung. „Später“ ist der Weg, auf dem Backups vergessen werden.

10. Wiederherstellen

Zuerst der einfache Weg: die meisten „ich habe etwas gelöscht“-Momente lassen sich in der App selbst lösen. Nextcloud hat gelöschte Dateien und Versionen, Paperless einen Papierkorb für 30 Tage. Erst wenn das nicht hilft, gehe ich an die Snapshots, und eine einzelne Datei ist nur eine Kopie aus dem richtigen Datumsordner.

Für den schlimmen Tag, wenn der Server weg ist oder mehrere Dienste kaputt sind, liegt ein interaktives Restore-Skript auf der Backup-Platte selbst:

1. Jobs wählen: einen, mehrere oder alle, in fester Reihenfolge: zuerst die Infrastruktur (Reverse Proxy, Zertifikate), dann Single Sign-on, dann die Datenbanken und Apps.
2. Snapshot wählen: den neuesten, ein Datum für alle oder pro Job.
3. Schritte pro Job wählen: Dateien, Datenbank, Container.
4. Probelauf: das Skript zeigt jeden Befehl, den es ausführen würde, und macht erst weiter, wenn ich RESTORE eintippe.

Es löscht nie etwas: Dateien, die es überschreibt, wandern in einen Ordner .pre-restore-<Zeit>, und jede Datenbank wird gedumpt, bevor sie ersetzt wird. Die Backup-Timer pausieren während der Wiederherstellung, damit kein Backup-Job gegen ein halb wiederhergestelltes System läuft.

Ein Restore-Skript, das du nie ausgeführt hast, ist eine Hoffnung, kein Plan. Meins hat einen Prüfstand: gefälschte docker-, systemctl– und sshd-Befehle und gefälschte Snapshots, damit es jedes Szenario durchspielen kann, ohne echte Daten anzufassen. Das sind 211 Prüfungen, und sie müssen nach jeder Änderung am Restore-Skript bestehen. Eine echte Wiederherstellung auf einer Ersatzmaschine ab und zu ersetzt das trotzdem nicht: das ist der einzige Beweis, der zählt.

Was ich gelernt habe

• Langweilige Werkzeuge gewinnen. rsync, Bash und systemd gibt es auch in zehn Jahren noch, und ich kann mit nichts als einer Shell wiederherstellen.
• Datenbanken dumpen und den Dump prüfen. Ein kopierter Datenbankordner ist ein Glücksspiel; ein ungeprüfter Dump eine Überraschung, die nur darauf wartet.
• Snapshots sind keine Kopien. Hardlinks geben dir Verlauf, keine Redundanz. Du brauchst trotzdem eine zweite Platte.
• Die Kopie, die einen Angriff überleben muss, holen statt schieben. Was der Server erreichen kann, kann auch ein Angreifer auf dem Server erreichen.
• Die Backups überwachen, nicht nur die Dienste. Der Alarm „seit 26 Stunden kein neuer Snapshot“ ist mehr wert als jede Funktion des Backups selbst.
• Geheimnisse gehören zu den Daten. Schlüssel und .env-Dateien aus derselben Nacht wie die Datenbank, sonst sieht die Wiederherstellung gut aus und nichts funktioniert.

Kurz gesagt

Problem: Sobald Port 80 und 443 offen sind, scannen Bots aus aller Welt deine Dienste, probieren Passwörter aus und suchen nach bekannten Sicherheitslücken. Traefik allein leitet all das weiter.

Lösung: Mehrere Schichten vor jedem Dienst: Geo-Blocking für Länder, aus denen du nie zugreifst, CrowdSec gegen bekannte Angreifer und Angriffsmuster, Single Sign-on vor Apps ohne eigenen guten Login, dazu ein paar Grundregeln für die Container.

Getestet mit: Traefik 3.7, GeoBlock-Plugin 0.3.8, CrowdSec 1.8 mit dem Traefik-Bouncer-Plugin 1.7 und AppSec, Authentik 2026.8, Docker Compose auf einem kleinen Heimserver

Das ist der zweite Teil meines Traefik-Setups. Der erste Teil erklärt die Grundlagen: Entrypoints, Router, Labels und Zertifikate. Hier geht es um die Frage, die Traefik selbst nicht beantwortet: Soll diese Anfrage überhaupt herein? Ein Reverse Proxy entscheidet, wohin eine Anfrage geht. Die Schichten in diesem Artikel entscheiden, ob.

Die Schichten im Überblick

Jede Anfrage an Port 443 durchläuft diese Prüfungen der Reihe nach. Jede ist billig, und jede hält eine andere Art von Besucher auf:

Keine Schicht ist perfekt. GeoBlock lässt sich mit einem VPN austricksen, CrowdSec kennt nicht jeden Angreifer, und jeder Login kann einen Fehler haben. Zusammen machen sie aus „jeder im Internet“ ein „wenige Leute, in wenigen Ländern, mit gültigem Login“.

1. Eine Zeile für alle Dienste

Man könnte Middlewares an jeden Router einzeln hängen. Ich hänge die zwei globalen stattdessen an den Entrypoint websecure, in der statischen Konfiguration von Traefik. So kann kein Dienst vergessen werden, auch keiner, den ich nächstes Jahr dazunehme:

    command:
      # ... die Konfiguration aus Teil 1 ...

      # Schutz für JEDE Seite auf 443: zuerst GeoBlock, dann CrowdSec, dann Security-Header (Schritt 5).
      # Beides schnell abschalten: Zeile auskommentieren und docker compose up -d
      - "--entrypoints.websecure.http.middlewares=geoblock@docker,crowdsec@docker,secheaders@docker"

      # Die zwei Plugins, beim Start von plugins.traefik.io geladen
      - "--experimental.plugins.geoblock.modulename=github.com/PascalMinder/geoblock"
      - "--experimental.plugins.geoblock.version=v0.3.8"
      - "--experimental.plugins.crowdsec.modulename=github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
      - "--experimental.plugins.crowdsec.version=v1.7.1"

• Die Reihenfolge zählt: GeoBlock läuft zuerst, weil es die billigste Prüfung ist. Anfragen aus gesperrten Ländern erreichen CrowdSec gar nicht erst, das hält dessen Logs und Arbeit klein.
• @docker heißt, die Middleware ist mit Docker-Labels definiert, hier am Traefik-Container selbst (nächste Abschnitte).
• Die Plugin-Versionen sind fest, aus demselben Grund wie das Traefik-Image in Teil 1: eine neue Plugin-Version kann Optionen ändern.
• Port 80 ist nicht abgedeckt, und das ist in Ordnung: Er antwortet nur mit einer Umleitung auf HTTPS, und dort greifen dann alle Prüfungen.

2. GeoBlock: nur die Länder, die du brauchst

Meine Dienste nutzt meine Familie, und wir alle sind in zwei europäischen Ländern. Es gibt keinen Grund, warum jemand aus anderen Ländern meine Login-Seiten erreichen sollte. GeoBlock schlägt das Land jeder Besucher-IP nach und lässt nur die erlaubten durch. Diese Labels kommen an den Traefik-Container:

    labels:
      # --- GeoBlock: nur die aufgeführten Länder erlauben (+ private/Heim-IPs) ---
      - "traefik.http.middlewares.geoblock.plugin.geoblock.countries[0]=DE"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.countries[1]=AT"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.allowLocalRequests=true"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.allowUnknownCountries=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.unknownCountryApiResponse=nil"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.blackListMode=false"

      # Ausnahmen: ein Dienst, der dich aus dem Ausland erreichen muss
      - "traefik.http.middlewares.geoblock.plugin.geoblock.allowedIPAddresses[0]=203.0.113.0/24"

      # Länderabfrage
      - "traefik.http.middlewares.geoblock.plugin.geoblock.api=https://get.geojs.io/v1/ip/country/{ip}"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.apiTimeoutMs=750"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.cacheSize=100"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.forceMonthlyUpdate=true"

      # Logging: nur abgelehnte Anfragen, in eine eigene Datei
      - "traefik.http.middlewares.geoblock.plugin.geoblock.silentStartUp=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.logLocalRequests=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.logAllowedRequests=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.logApiRequests=false"
      - "traefik.http.middlewares.geoblock.plugin.geoblock.logFilePath=/var/log/traefik/geoblock.log"

• countries: die erlaubten Länder als Zwei-Buchstaben-Codes. Meine sind andere; wähl deine eigenen. Mit blackListMode=false ist das eine Erlaubnisliste: alles, was nicht drinsteht, wird gesperrt. Andersherum (wenige Länder sperren, den Rest erlauben) schützt viel weniger.
• allowLocalRequests=true: private Adressen (dein Heimnetz) sind immer erlaubt. Ohne diese Zeile sperrst du dich zu Hause aus, sobald eine Anfrage mit lokaler Adresse ankommt.
• allowUnknownCountries=false: findet die Abfrage kein Land, wird die Anfrage gesperrt. Sicherer, um den Preis einer seltenen Fehlsperre.
• allowedIPAddresses: Ausnahmen für Dienste, die dich aus einem anderen Land aufrufen. Bei mir ist das der Connector eines KI-Assistenten zu Home Assistant, der aus dem veröffentlichten IP-Bereich des Anbieters in den USA kommt. Erlaube nur Bereiche, die der Anbieter offiziell veröffentlicht, nie einen geratenen.
• Abfrage und Cache: unbekannte IP-Adressen werden bei einem Online-Dienst nachgeschlagen (hier geojs.io), höchstens 750 ms lang. Die letzten 100 Ergebnisse bleiben im Cache, damit wiederkehrende Besucher keine neuen Abfragen auslösen.
• Log-Datei: jede gesperrte Anfrage landet in geoblock.log. Es ist erstaunlich lehrreich, sie nach einem Tag zu lesen: das meiste ist automatisiertes Scannen.

Let’s Encrypt funktioniert auch mit GeoBlock. Die TLS-Challenge aus Teil 1 beantwortet Traefik, bevor irgendeine Middleware läuft, deshalb werden die Prüfserver im Ausland nicht gesperrt.

3. CrowdSec: bekannte Angreifer und Angriffsmuster

CrowdSec macht zwei Dinge. Es liest das Access-Log von Traefik und merkt, wenn sich eine IP-Adresse wie ein Angreifer verhält (viele fehlgeschlagene Logins, Suche nach /wp-login.php auf einem Server ohne WordPress und so weiter). Und es teilt das mit einer Community-Liste, sodass du auch Adressen sperrst, die gestern jemand anderen angegriffen haben. Dazu arbeitet seine Komponente AppSec als Web Application Firewall (WAF): Sie prüft jede Anfrage gegen Regeln für typische Angriffe, bevor Traefik sie weiterleitet.

Es gibt zwei Teile: die CrowdSec-Engine (ein eigener Container) und einen Bouncer in Traefik, der die Engine zu jeder Anfrage befragt.

Die Engine

  crowdsec:
    image: crowdsecurity/crowdsec:v1.8.1
    container_name: crowdsec
    restart: unless-stopped
    environment:
      # Erkennungsregeln: Traefik-Log-Parser, typische Web-Angriffe, bekannte CVEs, AppSec (WAF)
      COLLECTIONS: "crowdsecurity/traefik crowdsecurity/base-http-scenarios crowdsecurity/http-cve crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules"
      # Registriert den Traefik-Bouncer mit dem Schlüssel aus .env
      BOUNCER_KEY_traefik: ${CROWDSEC_BOUNCER_KEY}
      TZ: Europe/Berlin
    volumes:
      - ./crowdsec/config:/etc/crowdsec
      - ./crowdsec/data:/var/lib/crowdsec/data
      - ./crowdsec/acquis.d:/etc/crowdsec/acquis.d:ro
      - ./traefik-logs:/var/log/traefik:ro
    networks:
      - proxy
    # Keine veröffentlichten Ports: Traefik erreicht es als crowdsec:8080 und crowdsec:7422

• Collections sind Regelpakete aus dem CrowdSec-Hub: ein Parser für das Log-Format von Traefik, Szenarien für typische Web-Angriffe und bekannte Sicherheitslücken (CVEs) sowie die AppSec-Regelsätze.
• BOUNCER_KEY_traefik registriert Traefik als Bouncer mit einem Schlüssel, den du selbst wählst. Erzeug einen und schreib ihn in die .env-Datei neben der Compose-Datei, nie in die Compose-Datei selbst: echo "CROWDSEC_BOUNCER_KEY=$(openssl rand -hex 32)" >> .env.
• Der Log-Ordner von Traefik ist nur lesend eingebunden, damit CrowdSec das Access-Log aus Teil 1 lesen kann.
• Keine veröffentlichten Ports: nur Traefik spricht mit CrowdSec, über das gemeinsame Netzwerk proxy.

Was CrowdSec liest, steht in crowdsec/acquis.d/traefik.yaml:

# 1. Traefik-Access-Log: Brute Force, Scans, bekannte Exploits
filenames:
  - /var/log/traefik/access.log
labels:
  type: traefik
---
# 2. AppSec (WAF): Traefik schickt jede Anfrage hierher, bevor es sie weitergibt
source: appsec
name: appsec
listen_addr: 0.0.0.0:7422
appsec_config: crowdsecurity/appsec-default
labels:
  type: appsec

Der Bouncer in Traefik

    labels:
      # --- CrowdSec-Bouncer ---
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.enabled=true"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecMode=stream"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecLapiScheme=http"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecLapiHost=crowdsec:8080"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecLapiKey=${CROWDSEC_BOUNCER_KEY}"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.updateIntervalSeconds=60"
      # AppSec (WAF)
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecAppsecEnabled=true"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecAppsecHost=crowdsec:7422"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecAppsecFailureBlock=true"
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.crowdsecAppsecUnreachableBlock=false"
      # das Heimnetz nie sperren
      - "traefik.http.middlewares.crowdsec.plugin.crowdsec.clientTrustedIPs[0]=192.168.10.0/24"

• crowdsecMode=stream: der Bouncer lädt alle 60 Sekunden die komplette Liste der gesperrten Adressen und prüft Anfragen lokal. Das ist schnell, und Traefik muss CrowdSec nicht bei jeder Anfrage fragen.
• crowdsecAppsecFailureBlock=true: kann AppSec über eine Anfrage nicht entscheiden (ein Fehler bei der Prüfung), wird sie gesperrt.
• crowdsecAppsecUnreachableBlock=false: ist der CrowdSec-Container nicht erreichbar, werden Anfragen durchgelassen. Das ist eine bewusste Abwägung: Während eines CrowdSec-Updates bleiben meine Dienste online, und GeoBlock filtert weiter. Wenn du lieber offline als ungeschützt bist, setz es auf true.
• clientTrustedIPs: dein Heimnetz wird nie gesperrt. Ohne diese Zeile kann ein Familienmitglied, das fünfmal das falsche Passwort eintippt, das ganze Haus aussperren.

Befehle für den Alltag

# welche Adressen sind gerade gesperrt, und warum?
docker exec crowdsec cscli decisions list

# was wurde zuletzt erkannt?
docker exec crowdsec cscli alerts list

# wird das Log gelesen, sprechen Bouncer und AppSec mit CrowdSec?
docker exec crowdsec cscli metrics

# eine Adresse entsperren (z. B. ein Freund, der gesperrt wurde)
docker exec crowdsec cscli decisions delete --ip 198.51.100.7

# eine Adresse von Hand für 24 Stunden sperren
docker exec crowdsec cscli decisions add --ip 198.51.100.7 --duration 24h

Das Access-Log und das GeoBlock-Log wachsen jeden Tag, deshalb rotiere ich sie mit logrotate auf dem Host (7 Tage, komprimiert). copytruncate lässt die Datei an ihrem Platz, sodass weder Traefik noch CrowdSec neu starten müssen:

# /etc/logrotate.d/traefik
/pfad/zu/traefik/traefik-logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
}

4. Single Sign-on vor Apps

Manche Apps haben keinen eigenen Login, oder nur einen schwachen: das Dashboard von Traefik, das Zigbee2MQTT-Frontend, kleine Admin-Werkzeuge. Für sie fragt Traefik vor jeder Anfrage meinen Identity Provider Authentik: Ist diese Person angemeldet und darf sie diese App nutzen? Wenn nicht, sieht sie die Login-Seite von Authentik, mit Zwei-Faktor-Anmeldung. Das nennt sich Forward Auth.

Die Middleware wird einmal definiert, mit Labels am Authentik-Server-Container:

    labels:
      # Pfad des eingebauten Outposts (nötig für Forward Auth auf anderen Domains)
      - traefik.http.routers.authentik-outpost.rule=HostRegexp(`.+`) && PathPrefix(`/outpost.goauthentik.io/`)
      - traefik.http.routers.authentik-outpost.priority=1000
      - traefik.http.routers.authentik-outpost.entrypoints=websecure
      - traefik.http.routers.authentik-outpost.tls=true
      - traefik.http.routers.authentik-outpost.service=authentik

      # Forward-Auth-Middleware für Apps OHNE eigenen Login
      - traefik.http.middlewares.authentik.forwardauth.address=http://authentik-server:9000/outpost.goauthentik.io/auth/traefik
      - traefik.http.middlewares.authentik.forwardauth.trustForwardHeader=true
      - traefik.http.middlewares.authentik.forwardauth.authResponseHeaders=X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid

• Der Outpost-Router fängt den Pfad /outpost.goauthentik.io/ auf jedem Hostnamen ab und schickt ihn an Authentik. Dorthin kommt die Login-Umleitung zurück. priority=1000 sorgt dafür, dass er gegen den Router der App gewinnt.
• forwardauth.address: diese Adresse fragt Traefik zu jeder Anfrage. Authentik antwortet mit „ja“ (die Anfrage geht weiter) oder mit einer Umleitung auf die Login-Seite.
• authResponseHeaders: nach erfolgreichem Login gibt Authentik Benutzername, Gruppen und E-Mail als Header an die App weiter. Apps, die sie verstehen, können den Benutzer automatisch anmelden.

Eine App zu schützen ist dann ein zusätzliches Label an ihrem Router, hier für das Traefik-Dashboard aus Teil 1:

      - "traefik.http.routers.traefik.middlewares=authentik@docker"

In Authentik braucht jede geschützte App einen Proxy Provider im Forward-Auth-Modus (einzelne Anwendung) und eine Anwendung, die an die erlaubten Benutzer oder Gruppen gebunden ist. Ohne das kennt Authentik den Hostnamen nicht und lehnt alle ab.

5. Security-Header für jeden Dienst

Security-Header sind kurze Anweisungen, die der Server mit jeder Seite an den Browser schickt. Viele Apps setzen einige davon, aber selten alle, und jede App macht es anders. Eine dritte Middleware am Entrypoint ergänzt die wichtigsten bei jedem Dienst und entfernt die Header, die Angreifern nur verraten, welche Software und Version du einsetzt. Diese Labels kommen an den Traefik-Container, und die Entrypoint-Zeile aus Schritt 1 bekommt einen dritten Eintrag: geoblock@docker,crowdsec@docker,secheaders@docker.

    labels:
      # --- Security-Header für jede Seite auf 443 ---
      # HSTS: Browser nutzen nur noch https, für 1 Jahr
      - "traefik.http.middlewares.secheaders.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.secheaders.headers.contentTypeNosniff=true"
      # Softwarenamen und Versionen verbergen (ein leerer Wert entfernt den Header)
      - "traefik.http.middlewares.secheaders.headers.customResponseHeaders.Server="
      - "traefik.http.middlewares.secheaders.headers.customResponseHeaders.X-Powered-By="

• HSTS (stsSeconds): nach dem ersten Besuch weigert sich der Browser ein Jahr lang, die Seite über reines HTTP zu öffnen, auch wenn ihn jemand in einem öffentlichen WLAN dorthin umleiten will. includeSubdomains und preload habe ich bewusst weggelassen: Sie binden auch jede andere Subdomain deiner Domain an HTTPS, und preload lässt sich nur sehr schwer rückgängig machen.
• contentTypeNosniff: der Browser vertraut dem angegebenen Dateityp und rät nicht. Das verhindert, dass ein hochgeladenes „Bild“ als Skript ausgeführt wird.
• Server und X-Powered-By entfernen: vorher haben meine Dienste jedem Dinge wie Server: nginx oder X-Powered-By: PHP/8.5 erzählt. Das macht nichts angreifbar, erspart einem Angreifer aber den ersten Schritt, Exploits für genau diese Version zu suchen.

Prüfen geht mit einem Befehl pro Dienst. Du solltest strict-transport-security und x-content-type-options sehen und keine server-Zeile:

curl -s -o /dev/null -D - https://app.example.com/ | grep -i -E "strict-transport|x-content-type|^server|x-powered"

6. Grundregeln für die Container

Ein paar kleine Einstellungen an den Containern selbst, die nichts kosten:

  traefik:
    image: traefik:v3.7
    security_opt:
      - no-new-privileges:true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # ...

• no-new-privileges: Prozesse im Container können sich später keine zusätzlichen Rechte verschaffen (zum Beispiel über ein setuid-Programm). Bricht je jemand in Traefik ein, macht das den nächsten Schritt schwerer.
• Docker-Socket nur lesend: Traefik muss Container-Informationen nur lesen. Aber Achtung: :ro schützt nur die Socket-Datei; die Docker-API dahinter nimmt trotzdem Befehle an. Strenger ist ein Socket-Proxy, ein kleiner Container, der nur die Lese-Anfragen durchlässt, die Traefik braucht. Für mein Monitoring-Portal nutze ich so einen schon, und Traefik soll auch noch umziehen.
• Keine veröffentlichten Ports bei keinem Dienst außer Traefik (80 und 443). Alles andere ist nur über Traefik erreichbar und damit über alle Schichten oben. Eine vergessene ports:-Zeile umgeht sie alle.
• exposedbydefault=false aus Teil 1 gehört auch hierher: nichts wird aus Versehen öffentlich.

7. Testen, ob es funktioniert

Trau keinem Sicherheits-Setup, das du nicht getestet hast. Diese Prüfungen dauern fünf Minuten. Mach die Angriffstests von außerhalb deines Heimnetzes (mobile Daten, nicht WLAN), weil dein Heimnetz auf jeder Erlaubnisliste steht:

# AppSec sollte typische Angriffs-Anfragen mit 403 sperren
curl -s -o /dev/null -w "%{http_code}n" "https://app.example.com/?id=1%27%20OR%20%271%27=%271"
curl -s -o /dev/null -w "%{http_code}n" "https://app.example.com/../../etc/passwd"
curl -s -o /dev/null -w "%{http_code}n" "https://app.example.com/.env"

# hat CrowdSec es gesehen?
docker exec crowdsec cscli alerts list | head

# GeoBlock: Anfragen aus anderen Ländern stehen hier
tail -n 5 traefik-logs/geoblock.log

# Forward Auth: ohne Login solltest du zu Authentik umgeleitet werden (302)
curl -s -o /dev/null -w "%{http_code} %{redirect_url}n" https://traefik.example.com/

Um GeoBlock aus einem anderen Land zu testen, nimm ein VPN mit Ausgang in einem gesperrten Land oder einen der vielen Online-Dienste, die eine Website „von einem anderen Standort“ prüfen. Du solltest ein 403 bekommen.

Was ich (noch) nicht mache

• Zentrale Frame- und Content-Richtlinien (X-Frame-Options, Content Security Policy): sie hängen zu sehr von der jeweiligen App ab, deshalb setzen die Apps sie selbst (siehe Schritt 5).
• Eigene TLS-Optionen: brauche ich nicht. Ich habe mit openssl s_client geprüft: Die Standardwerte von Traefik lehnen TLS 1.0 und 1.1 schon ab und akzeptieren nur 1.2 und 1.3.
• Rate Limiting: die ratelimit-Middleware von Traefik auf Login-Seiten. CrowdSec deckt das meiste ab, weil es Brute-Force-Versuche sperrt.
• Der Socket-Proxy für Traefik, wie oben erwähnt.

Was ich gelernt habe

• Middlewares am Entrypoint schlagen Middlewares pro Router: neue Dienste sind ab der ersten Sekunde geschützt, ohne dass ich an etwas denken muss.
• Erlaubnislisten schlagen Sperrlisten. Die zwei Länder aufzuzählen, die ich brauche, ist sicherer und einfacher als die hundert, die ich nicht brauche.
• Das Heimnetz immer ausnehmen, in GeoBlock und in CrowdSec. Sonst bist du selbst der Erste, der ausgesperrt wird.
• Entscheide, was passiert, wenn eine Schutzschicht ausfällt: alles sperren oder durchlassen. Beides ist vertretbar, aber es sollte eine Entscheidung sein, kein Standardwert, den du nie angesehen hast.
• Teste von außen. Vom eigenen Sofa aus sieht alles sicher aus, weil dein Heimnetz auf jeder Erlaubnisliste steht.

Kurz gesagt

Problem: Jeder selbst gehostete Dienst will seinen eigenen Port, sein eigenes Zertifikat und seinen eigenen Weg nach draußen. Spätestens ab dem dritten Dienst wird das unübersichtlich.

Lösung: Ein einziger Traefik-Container vor allem anderen. Er nimmt Anfragen auf Port 80 und 443 an, holt sich Let’s-Encrypt-Zertifikate selbst und schickt jede Anfrage an den richtigen Dienst, gesteuert über ein paar Labels in der jeweiligen docker-compose.yml.

Getestet mit: Traefik 3.7, Docker Compose auf einem kleinen Heimserver, Let’s Encrypt, etwa zehn Dienste (Docker-Container und eine Home-Assistant-VM)

Traefik ist die Haustür meines Homelabs. Jede Anfrage aus dem Internet kommt zuerst dort an, und Traefik entscheidet, welcher Dienst sie bekommt. In diesem Artikel erkläre ich meine Konfiguration Zeile für Zeile: wie Traefik eingerichtet ist, wie ein Container über Labels veröffentlicht wird, wie Dienste außerhalb von Docker dazukommen und wie die Zertifikate funktionieren. Die Absicherung (Geo-Blocking, CrowdSec, Single Sign-on vor den Diensten) lasse ich bewusst weg. Sie bekommt einen eigenen Artikel, weil sie auf allem hier aufbaut.

1. Wie Traefik denkt

Traefik hat vier Bausteine. Wenn die klar sind, ergibt jede Zeile der Konfiguration Sinn:

Außerdem gibt es zwei Arten von Konfiguration. Die statische Konfiguration wird einmal beim Start gelesen: Entrypoints, Zertifikatseinstellungen, wo die Routen herkommen. Die dynamische Konfiguration sind die Routen selbst. Traefik liest sie aus Docker-Labels und aus Dateien und übernimmt Änderungen ohne Neustart.

2. Bevor du anfängst

1. DNS: ein A-Record für jeden Hostnamen (zum Beispiel vault.example.com), der auf deine öffentliche IP-Adresse zeigt. Ein Wildcard-Eintrag geht auch.
2. Router: leite die Ports 80 und 443 von deinem Internet-Router auf den Docker-Host weiter. Mehr muss nicht offen sein.
3. Ein gemeinsames Docker-Netzwerk, in dem Traefik und alle veröffentlichten Container hängen:

docker network create proxy

4. Eine Datei für die Zertifikate. Traefik verweigert sie, wenn andere Benutzer sie lesen können:

mkdir -p traefik-data/dynamic
touch traefik-data/acme.json
chmod 600 traefik-data/acme.json

3. Der Traefik-Container

Die ganze statische Konfiguration steht bei mir im command-Abschnitt der Compose-Datei. Eine eigene traefik.yml funktioniert genauso gut; mir gefällt, alles an einer Stelle zu haben.

services:
  traefik:
    image: traefik:v3.7
    container_name: traefik
    restart: unless-stopped
    networks:
      - proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik-data/acme.json:/acme.json
      - ./traefik-data/dynamic:/dynamic:ro
      - ./traefik-logs:/var/log/traefik
    command:
      # Allgemein
      - "--global.checknewversion=false"
      - "--global.sendanonymoususage=false"
      - "--log.level=INFO"
      - "--accesslog=true"
      - "--accesslog.filepath=/var/log/traefik/access.log"
      - "--api.dashboard=true"

      # Woher die Routen kommen
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      - "--providers.file.directory=/dynamic"
      - "--providers.file.watch=true"

      # Ports
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"

      # Alles von http auf https umleiten
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"

      # Let's Encrypt
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=you@example.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/acme.json"

      # Kein Timeout für lange Uploads (Nextcloud)
      - "--entrypoints.web.transport.respondingTimeouts.readTimeout=0"
      - "--entrypoints.websecure.transport.respondingTimeouts.readTimeout=0"

networks:
  proxy:
    external: true

Was die Zeilen tun:

• Docker-Socket: Traefik beobachtet Docker, um zu sehen, welche Container starten und stoppen und welche Labels sie haben. Nur-Lesen reicht dafür. Wie man das weiter absichert, kommt im Artikel zur Absicherung.
• exposedbydefault=false: nur Container mit dem Label traefik.enable=true werden veröffentlicht. Ohne diese Zeile wäre jeder Container, den du startest, aus dem Internet erreichbar.
• providers.docker.network=proxy: Traefik spricht die Container über das gemeinsame Netzwerk proxy an. Das ist wichtig, wenn ein Container in mehreren Netzwerken hängt: sonst nimmt Traefik vielleicht eine Adresse, die es nicht erreicht.
• File-Provider: jede .yml-Datei in /dynamic wird als zusätzliche Route gelesen, und watch=true übernimmt Änderungen beim Speichern. So kommen Dienste außerhalb von Docker dazu (Schritt 5).
• Umleitung: eine Anfrage an http:// wird mit einer Umleitung auf https:// beantwortet. Kein Dienst braucht eine eigene Umleitung.
• Access-Log: eine Zeile pro Anfrage. Die erste Anlaufstelle, wenn etwas nicht ankommt, und später die Grundlage für die Angriffserkennung.
• readTimeout=0: der Standard-Timeout von Traefik hat große Nextcloud-Uploads abgebrochen. Null heißt: kein Limit. Wenn du keine großen Dateien hochlädst, lass die Zeilen weg.

Welches Versions-Tag du nehmen solltest

Der Teil nach dem Doppelpunkt in image: traefik:v3.7 ist das Tag. Es bestimmt, welche Traefik-Version Docker herunterlädt, und welche Version du nach dem nächsten docker compose pull bekommst. Traefik veröffentlicht dieselbe Version unter mehreren Tags:

Traefik nutzt semantische Versionierung: die erste Zahl (Hauptversion) darf deine Konfiguration brechen, die zweite (Nebenversion) bringt neue Funktionen, die dritte (Patch) behebt nur Fehler und Sicherheitslücken. Je sicherer das Tag, desto öfter musst du es von Hand anpassen.

Warum das gerade beim Reverse Proxy zählt: Wenn Traefik ausfällt, sind alle Dienste auf einmal offline, nicht nur einer. Und in vielen Homelabs laufen die Updates nachts automatisch. Mit latest kann eine neue Hauptversion um 4 Uhr alles lahmlegen, und du merkst es morgens, wenn nichts mehr lädt.

Meine Empfehlung: v3, wenn deine Updates automatisch laufen, oder v3.7, wenn du von Hand aktualisierst und die Release Notes sowieso liest. Traefik hängt direkt im Internet, also pinne keine exakte Version und vergiss sie dann. Sicherheitskorrekturen kommen nur mit neuen Patch-Versionen.

Aktualisieren und Zurückgehen ist jeweils eine Änderung in der Compose-Datei:

# welche Version läuft gerade?
docker exec traefik traefik version

# Update: Tag bei Bedarf ändern (z. B. v3.7 -> v3.8), dann
docker compose pull traefik
docker compose up -d traefik
docker logs traefik --since 2m    # nach Fehlern schauen

# etwas kaputt? altes Tag wieder eintragen und dieselben zwei Befehle erneut ausführen

Starte den Container mit docker compose up -d und prüfe docker logs traefik. Dort sollten keine Fehler stehen, nur eine Zeile, dass die Provider gestartet sind.

4. Einen Container mit Labels veröffentlichen

Hier spielt Traefik seine Stärke aus. Ein Dienst veröffentlicht keinen Port auf dem Host. Er hängt im Netzwerk proxy und beschreibt seine Route mit Labels. Als Beispiel mein Vaultwarden, gekürzt auf den Traefik-Teil:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.vaultwarden.rule=Host(`vault.example.com`)"
      - "traefik.http.routers.vaultwarden.entrypoints=websecure"
      - "traefik.http.routers.vaultwarden.tls.certresolver=letsencrypt"
      - "traefik.http.routers.vaultwarden.service=vaultwarden"
      - "traefik.http.services.vaultwarden.loadbalancer.server.port=80"

networks:
  proxy:
    external: true

• Router-Name (vaultwarden): frei wählbar, aber über alle Container eindeutig. Einen Block kopieren und vergessen, ihn umzubenennen, ist der häufigste Fehler; der zweite Container ersetzt dann stillschweigend den ersten.
• rule: welcher Hostname zu diesem Dienst gehört. Regeln lassen sich kombinieren, zum Beispiel Host(`example.com`) && PathPrefix(`/api`).
• entrypoints=websecure: nur HTTPS. Reines HTTP erreicht den Router nie, weil der Entrypoint vorher umleitet.
• tls.certresolver=letsencrypt: Traefik holt das Zertifikat für den Hostnamen bei der ersten Anfrage und erneuert es selbst.
• server.port: der Port im Container, nicht auf dem Host. Meist errät Traefik ihn aus dem Image, aber ausdrücklich angegeben vermeidet er Überraschungen bei Images mit mehreren Ports.

Nach docker compose up -d ist der Dienst unter seinem Namen online, mit gültigem Zertifikat. Kein Traefik-Neustart, keine Portweiterleitung, keine Zertifikatsverwaltung.

5. Dienste außerhalb von Docker

Mein Home Assistant läuft in einer virtuellen Maschine, nicht in Docker, und hat deshalb keine Labels. Für solche Dienste schreibe ich die Route als Datei in den Ordner dynamic:

# traefik-data/dynamic/homeassistant.yml
http:
  routers:
    homeassistant:
      rule: "Host(`home.example.com`)"
      entryPoints:
        - websecure
      service: homeassistant-service
      tls:
        certResolver: letsencrypt

  services:
    homeassistant-service:
      loadBalancer:
        servers:
          - url: "http://192.0.2.20:8123"

Die Adresse ist die lokale IP-Adresse der VM mit Port. Datei speichern, und die Route ist aktiv; im Log von Traefik steht, dass es die neue Konfiguration gelesen hat. Genauso funktioniert es mit einem NAS, der Weboberfläche eines Routers oder allem anderen in deinem Netz, das HTTP spricht.

Home Assistant muss außerdem wissen, dass es hinter einem Proxy steht, sonst lehnt es die Anfragen mit „400 Bad Request“ ab. In seiner configuration.yaml:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.0.2.10   # der Docker-Host, auf dem Traefik läuft

6. Zertifikate mit Let’s Encrypt

Ich nutze die TLS-Challenge: Let’s Encrypt verbindet sich auf Port 443, und Traefik beweist genau dort, dass es den Hostnamen kontrolliert. Die Vorteile: kein zusätzlicher Port, kein API-Schlüssel beim DNS-Anbieter, und es funktioniert für jeden Hostnamen, der auf deine IP-Adresse zeigt. Die Grenze: keine Wildcard-Zertifikate, dafür brauchst du die DNS-Challenge.

Alle Zertifikate und der Kontoschlüssel landen in acme.json. Sichere diese Datei. Ohne sie fordert Traefik nach einem Neuaufbau jedes Zertifikat neu an, und Let’s Encrypt hat Ratenlimits. Wie ich das ganze Homelab sichere, erkläre ich in einem eigenen Artikel.

7. Das Dashboard

Das Dashboard von Traefik zeigt alle Router, Services und Middlewares, die es kennt, und ob sie Fehler haben. Es ist der schnellste Weg herauszufinden, warum eine Route nicht funktioniert. Ich veröffentliche es wie jeden anderen Dienst, mit Labels am Traefik-Container selbst:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.traefik.rule=Host(`traefik.example.com`)"
      - "traefik.http.routers.traefik.entrypoints=websecure"
      - "traefik.http.routers.traefik.tls.certresolver=letsencrypt"
      - "traefik.http.routers.traefik.service=api@internal"

api@internal ist der eingebaute Service von Traefik für das Dashboard; einen Port braucht es nicht.

8. Wenn etwas nicht funktioniert

Zwei Befehle decken die meisten Fälle ab:

# Fehler beim Lesen der Routen oder beim Holen der Zertifikate
docker logs traefik 2>&1 | grep -i -E "error|acme"

# Ist die Anfrage bei Traefik angekommen, und was hat es geantwortet?
tail -f traefik-logs/access.log

Was ich gelernt habe

• Labels schlagen Konfigurationsdateien bei Containern: die Route steht direkt neben dem Dienst, zu dem sie gehört, und verschwindet mit ihm.
• exposedbydefault=false ist nicht optional. Veröffentlichen sollte immer eine bewusste Entscheidung pro Container sein.
• Ein gemeinsames Netzwerk und traefik.docker.network=proxy an jedem Dienst haben mir die meisten 502-Fehler erspart.
• Sichere acme.json zusammen mit den Compose-Dateien.
• Ein Reverse Proxy ist keine Firewall. Er entscheidet, wohin eine Anfrage geht, nicht ob sie herein darf. Darum geht es im nächsten Artikel: Geo-Blocking, CrowdSec und Single Sign-on vor den Routen von Traefik.

Kurz gesagt

Problem: Papier stapelt sich, Rechnungen kommen per E-Mail, als PDF und jetzt auch als XML, und das deutsche Recht erwartet, dass du alles bis zu zehn Jahre lang auffindbar und unverändert aufbewahrst.

Lösung: Ein selbst gehostetes Dokumentenarchiv (Paperless-ngx), ein Netzwerkscanner, ein paar klare tägliche Abläufe, eine schriftliche Verfahrensdokumentation und ein Aufbewahrungsplan nach den aktuellen deutschen Regeln.

Getestet mit: Paperless-ngx in Docker auf einem kleinen Heimserver, ein Netzwerkscanner mit Dokumenteneinzug, Nextcloud als Dateiablage, Rechtsstand Deutschland Oktober 2026

Kleine Betriebe und Homeoffices ertrinken in Papier: Briefe, Quittungen, Kontoauszüge, Verträge. Dazu kommen immer mehr Rechnungen per E-Mail, und seit 2025 muss jedes Unternehmen in Deutschland elektronische Rechnungen empfangen können. Ein guter Zeitpunkt, mit dem Abheften aufzuhören und ein richtiges papierloses Büro aufzubauen. Meins läuft in meinem Homelab, und die Beispiele unten stammen aus diesem Setup.

1. Was „papierlos“ bedeuten sollte

Bevor du einen Scanner kaufst, leg das Ziel fest. Für uns waren es vier Regeln:

1. Ein Archiv für alles: Gescanntes Papier, E-Mail-Anhänge und E-Rechnungen landen am selben Ort.
2. Digitale Originale bleiben Originale. Eine PDF- oder XML-Rechnung, die per E-Mail kam, wird genau so gespeichert, wie sie angekommen ist. Ausdrucken und wieder einscannen ist nicht erlaubt.
3. Alles ist durchsuchbar dank Texterkennung (OCR) und ein paar wenigen Tags.
4. Nichts geht verloren: automatische Backups, darunter eine Kopie außer Haus.

2. Das technische Setup

Die Bausteine sind günstig und größtenteils Open Source:

Ein minimaler Paperless-ngx-Stack sieht so aus. Passwörter und Schlüssel gehören in eine .env-Datei daneben, nie in die Compose-Datei:

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
  db:
    image: docker.io/library/postgres:17
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${DB_PASSWORD}
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on: [db, broker]
    ports:
      - "127.0.0.1:8010:8000"   # nur über Reverse Proxy / SSO
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBPASS: ${DB_PASSWORD}
      PAPERLESS_SECRET_KEY: ${SECRET_KEY}
      PAPERLESS_URL: https://paperless.example.com
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_OCR_LANGUAGE: deu+eng
      PAPERLESS_FILENAME_FORMAT: "{{ created_year }}/{{ correspondent }}/{{ created }} {{ title }}"

Ein paar Einstellungen sind wichtiger, als sie aussehen:

• OCR-Sprache: deu+eng erkennt deutsche Umlaute und englische Wörter im selben Dokument.
• Original und Archivversion: Paperless behält die Datei genau so, wie sie ankam, und erzeugt daneben ein durchsuchbares PDF/A. Für die Ordnungsmäßigkeit zählt das Original.
• Consume-Ordner: Scanner, E-Mail-Import und Menschen legen Dateien in einen Ordner. Paperless holt sie dort ab.
• Nicht im Internet: Der Port ist an den Server selbst gebunden und nur über einen Reverse Proxy mit Single Sign-on erreichbar. Ein Archiv voller Rechnungen, Verträge und Kontoauszüge ist eine Beute für Angreifer.

E-Rechnungen brauchen besondere Sorgfalt

Seit dem 1. Januar 2025 muss jedes Unternehmen in Deutschland elektronische Rechnungen von anderen inländischen Unternehmen empfangen können. Eine E-Rechnung ist eine strukturierte Datei: entweder eine XRechnung (reines XML) oder eine ZUGFeRD-Rechnung (ein PDF mit eingebettetem XML). Daraus folgen zwei Dinge:

• Das XML ist das rechtliche Original, nicht ein Ausdruck oder ein Screenshot. Speichere die Datei genau so, wie sie angekommen ist.
• Eine reine XML-Datei ist für Menschen nicht lesbar. Halte einen Viewer bereit (zum Beispiel einen kostenlosen XRechnung-Viewer) und speichere eine lesbare Ansicht neben dem Original, nie stattdessen.

Für das Ausstellen gibt es Übergangsfristen: Papier- und einfache PDF-Rechnungen sind noch bis Ende 2026 erlaubt, für Unternehmen mit einem Vorjahresumsatz bis 800.000 Euro bis Ende 2027. Danach müssen Rechnungen zwischen inländischen Unternehmen E-Rechnungen sein. Kleinbetragsrechnungen bis 250 Euro und Kleinunternehmer haben Ausnahmen; frag deine Steuerberatung, welche für dich gelten.

3. Sortieren: Tags, Korrespondenten und ein bisschen KI

Die Suche funktioniert nur, wenn Dokumente einheitlich sortiert sind. Paperless bietet vier Werkzeuge. Nutze sie für unterschiedliche Dinge:

Paperless lernt aus deiner Sortierung und schlägt für neue Dokumente Korrespondenten und Tags vor. Wir haben einen kleinen Klassifizierer dazugebaut, der ein Sprachmodell nach dem passenden Zielordner fragt. Wenn du das auch machst, achte auf den Datenschutz: Unser Klassifizierer schickt nur den ersten Teil des Textes, und er maskiert personenbezogene Daten vor dem Versand: Namen, Adressen, IBANs, Steuer- und Kundennummern und alle Geldbeträge. Dokumente, bei denen er unsicher ist, bekommen ein Tag to-review, statt automatisch einsortiert zu werden.

4. Abläufe für die Menschen, die damit arbeiten

Die Technik ist der einfache Teil. Das papierlose Büro funktioniert nur, wenn alle denselben Abläufen folgen. Diese Abläufe funktionieren gut für ein kleines Büro; pass sie an deine Situation an:

Eingehendes Papier (täglich)

1. Post öffnen, Heftklammern entfernen, alles in den Dokumenteneinzug legen.
2. Mit Duplex und 300 dpi scannen. Ein Dokument pro Scanauftrag, oder Trennblätter verwenden.
3. Das Ergebnis noch am selben Tag in Paperless prüfen: Ist jede Seite lesbar, ist der OCR-Text plausibel, hat die Sortierung funktioniert?
4. Das Papier in eine Kiste für den laufenden Monat legen. Dort bleibt es bis zur Monatsprüfung (siehe unten), nicht länger.

Rechnungen und Dokumente per E-Mail

• Nutze ein eigenes Postfach nur für Rechnungen und gib diese Adresse allen Lieferanten.
• Lass Paperless die Anhänge mit seinem eingebauten Mail-Import automatisch abholen und zur Prüfung markieren.
• Druck eine E-Mail-Rechnung nie aus. Die Datei ist das Original.

Belege unterwegs

Tanken, Parken, Büromaterial: Fotografier die Quittung noch am selben Tag mit dem Handy und lade sie hoch, zum Beispiel über eine Paperless-App oder einen geteilten Nextcloud-Ordner, den Paperless einliest. Leg den Papierbeleg trotzdem in die Monatskiste, denn Thermopapier verblasst und ein schlechtes Foto ist wertlos.

Monatlicher Ablauf

1. Alles mit dem Tag to-review abarbeiten.
2. Die Kontoauszüge des Monats mit den abgelegten Rechnungen vergleichen: Gibt es zu jeder Buchung einen Beleg?
3. Den Monat an die Steuerberatung übergeben (ein geteilter Ordner oder ein Export aller Dokumente mit for-tax-advisor).
4. Eine Stichprobe der gescannten Papiere mit den Originalen vergleichen, die Prüfung im Protokoll vermerken und das Papier dann vernichten. Die Ausnahmen aus Abschnitt 6 behältst du.

Rollen und Berechtigungen

Gib jeder Person einen eigenen Login. Geschäftsdokumente gehören der Inhaberin oder dem Inhaber; private Haushaltsdokumente können für die ganze Familie sichtbar sein. Niemand außer der Administration darf Dokumente löschen, und auch dann sollte das Löschen über einen Papierkorb mit Wartezeit laufen.

5. Ordnungsmäßigkeit: GoBD, Verfahrensdokumentation und Datenschutz

In Deutschland folgen digitale Buchführung und Archivierung den GoBD, den Grundsätzen der Finanzverwaltung zur ordnungsmäßigen Führung und Aufbewahrung von Büchern, Aufzeichnungen und Unterlagen in elektronischer Form. In der Praxis laufen sie auf ein paar Anforderungen hinaus:

Sei in einem Punkt ehrlich: Ein selbst gehostetes Paperless-ngx ist kein zertifiziertes „revisionssicheres“ Archiv. Die Anforderungen deckst du über die Art ab, wie du es betreibst: eingeschränkte Löschrechte, Protokollierung, Backups und ein dokumentiertes Verfahren. Besprich mit deiner Steuerberatung, ob das für deinen Betrieb ausreicht.

Die Verfahrensdokumentation

Dieses Dokument macht das Vernichten von Papier nach dem Scannen (ersetzendes Scannen) überhaupt erst möglich. Schreib es also bevor du das erste Original in den Schredder steckst. Es beschreibt in einfachen Worten:

• welche Dokumente gescannt werden, von wem, wann und mit welchem Gerät und welchen Einstellungen;
• wie der Scan auf Vollständigkeit und Lesbarkeit geprüft wird und wer prüft;
• wie E-Mails und E-Rechnungen empfangen, geprüft und archiviert werden;
• wann und wie Papieroriginale vernichtet werden und welche aufbewahrt werden;
• das System: Software, Versionen, Speicher, Zugriffsrechte, Backups und wie eine Wiederherstellung funktioniert;
• wer verantwortlich ist und wann das Dokument zuletzt geprüft wurde.

Prüf sie einmal im Jahr und jedes Mal, wenn sich etwas ändert, etwa ein neuer Scanner, eine neue Softwareversion oder eine neue Person in der Buchhaltung. Die Verfahrensdokumentation selbst musst du so lange aufbewahren wie die Dokumente, die sie beschreibt.

Datenschutz (DSGVO)

• Das Archiv enthält personenbezogene Daten von Kunden, Lieferanten und Familienmitgliedern. Beschränk den Zugriff auf die Personen, die ihn brauchen.
• Jeder externe Dienst, der Dokumente sieht (Cloud-Speicher, ein KI-Klassifizierer, ein OCR-Dienst), braucht einen Vertrag zur Auftragsverarbeitung, und personenbezogene Daten sollten maskiert werden, bevor sie das Haus verlassen.
• Aufbewahrungsfristen sind auch Löschfristen: Sobald ein Dokument steuer- und handelsrechtlich nicht mehr gebraucht wird, sollten die personenbezogenen Daten darin gelöscht werden.

6. Wie lange was aufbewahrt werden muss

Die Abgabenordnung (§ 147 AO) und das Handelsgesetzbuch (§ 257 HGB) legen die Fristen fest. Seit 2025 ist die Frist für Buchungsbelege kürzer als früher:

Drei Details, die oft falsch verstanden werden:

• Die Frist beginnt mit dem Ende des Kalenderjahres, in dem das Dokument entstanden ist oder empfangen wurde. Eine Rechnung vom März 2026 muss bis Ende 2034 aufbewahrt werden (8 Jahre ab dem 31. Dezember 2026).
• Offene Steuerfestsetzungen verlängern sie: Solange die Steuerfestsetzung für ein Jahr noch offen ist (zum Beispiel während eines Einspruchs oder einer Betriebsprüfung), dürfen die Unterlagen dafür nicht vernichtet werden, auch wenn die Frist abgelaufen ist.
• Manche Branchen weichen ab: Für Banken, Versicherungen und Wertpapierinstitute gelten andere Fristen. Prüf, ob dich das betrifft.

Manche Papieroriginale solltest du auch mit gutem Verfahren nach dem Scannen nie vernichten: notarielle Urkunden, Jahresabschlüsse und Eröffnungsbilanzen mit Originalunterschrift, Zollbelege und alles, bei dem das Original selbst rechtlichen Wert hat (zum Beispiel Urkunden oder Dokumente mit Siegel). Bewahr sie in einem Ordner auf und scanne sie nur zur Bequemlichkeit.

Eine einfache Lösung dafür in Paperless: ein benutzerdefiniertes Feld „Aufbewahren bis“ (ein Jahr) bei jedem Dokumenttyp mit Aufbewahrungsfrist und eine gespeicherte Ansicht, die alles auflistet, dessen Jahr abgelaufen ist. Einmal im Jahr entscheidest du, was gelöscht wird. Lass nichts automatisch löschen.

7. Einführungsplan

8. Checkliste

• Archiv nur mit Login erreichbar, am besten Single Sign-on, nicht offen im Internet
• Nächtliches Backup, Kopie außer Haus, Wiederherstellung mindestens einmal getestet
• Eigenes Rechnungspostfach mit automatischem Import
• E-Rechnungen als Original-XML bzw. ZUGFeRD-PDF gespeichert, Viewer vorhanden
• Schriftliche Ordner- und Tag-Liste
• Verfahrensdokumentation geschrieben und von der Steuerberatung geprüft
• Monatlicher Prüfablauf mit Scan-Kontrolle und Protokoll
• Aufbewahrungsfeld und jährliche Löschprüfung
• Kiste für Papieroriginale, die aufbewahrt werden müssen

Was ich gelernt habe

• Das Schwierige ist nicht die Software, sondern die Routine. Plane jeden Tag und jeden Monat eine feste Zeit dafür ein.
• Schreib die Verfahrensdokumentation früh. Sie zwingt dich, Dinge zu entscheiden, die du sonst offen lassen würdest.
• Maskiere personenbezogene Daten, bevor Dokumenttext das Haus verlässt, auch für „nur eine schnelle KI-Sortierung“.
• Prüf Eigentümer und Berechtigungen mit einem zweiten Benutzerkonto, bevor du startest. Viele „bei ihr funktioniert es nicht“-Probleme waren Berechtigungsprobleme.
• Löschen an einer Stelle sollte überall löschen. Wir gleichen den Paperless-Papierkorb mit der Nextcloud-Kopie ab, sonst leben alte Kopien weiter.

Kurz gesagt

Problem: Heizkörperthermostate messen die Temperatur direkt neben dem heißen Heizkörper, ein gemeinsamer Blueprint reagierte nicht mehr, und ein Update hat die Heizung unbemerkt lahmgelegt.

Lösung: Drei kleine Automationen pro Raum (Toggle, Target Sync, Calibration), ein echter Raumsensor als Messwert für jedes Ventil und ein paar Sicherheitsnetze, die melden, wenn etwas aus dem Ruder läuft.

Getestet mit: Home Assistant, Zigbee2MQTT 2.14, 12 Heizkörperventile SONOFF TRVZB, Zigbee-Temperatur- und Bewegungssensoren

Unser Haus hat neun beheizte Räume mit zwölf smarten Heizkörperventilen. Das Ziel war einfach: warm, wenn jemand im Raum ist, ein paar Grad weniger, wenn nicht, und keine Heizung bei offenem Fenster. Bis dahin hat es ein paar Umbauten gebraucht. Hier ist das Setup, das jetzt funktioniert, und die Probleme, auf die wir unterwegs gestoßen sind.

Die Bausteine pro Raum

Jeder Raum nutzt dieselben Helfer. Dadurch sind die Automationen fast identisch, und ein neuer Raum ist im Wesentlichen kopieren und umbenennen.

Dazu hat jeder Raum drei Automationen:

• Toggle folgt dem Hauptschalter und schaltet Ventil und Target Sync ein oder aus.
• Target Sync entscheidet zwischen Komfort und ECO und schreibt die Zieltemperatur ans Ventil.
• Calibration gibt die echte Raumtemperatur an das Ventil weiter.

Warum ich den Blueprint ersetzt habe

Am Anfang liefen alle Räume über einen gemeinsamen Heizungs-Blueprint. Das war bequem, bis es das nicht mehr war: Ende August reagierte er auf einige Eingaben einfach nicht mehr, weil eine interne Schutzbedingung fehlschlug. Ein Fehler in einem gemeinsamen Blueprint trifft alle Räume gleichzeitig, und die Logik lässt sich von außen schlecht untersuchen.

Ich habe ihn durch drei einfache Automationen pro Raum ersetzt. Das sind mehr Automationen (33 für das ganze Haus), aber jede ist kurz, macht genau eine Sache und ist im Trace gut zu verfolgen, wenn etwas schiefgeht.

1. Toggle

Geht der Hauptschalter an, wird das Ventil auf heat gesetzt, der Target Sync eingeschaltet und einmal ausgeführt, damit sofort die richtige Temperatur gilt. Geht er aus, wird zuerst der Target Sync abgeschaltet und dann das Ventil ausgeschaltet.

alias: Office - Heating - Toggle
triggers:
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "on"
    id: turned_on
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "off"
    id: turned_off
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: turned_on
        sequence:
          - action: climate.set_hvac_mode
            target:
              entity_id: climate.office_heating_valve
            data:
              hvac_mode: heat
          - action: automation.turn_on
            target:
              entity_id: automation.office_heating_target_sync
          - action: automation.trigger
            target:
              entity_id: automation.office_heating_target_sync
      - conditions:
          - condition: trigger
            id: turned_off
        sequence:
          - action: automation.turn_off
            target:
              entity_id: automation.office_heating_target_sync
          - action: climate.set_hvac_mode
            target:
              entity_id: climate.office_heating_valve
            data:
              hvac_mode: "off"
mode: single

2. Target Sync

Beim Target Sync unterscheiden sich die Räume. Im Büro folgt er einem Bewegungsmelder: Komfort nach zwei Minuten Bewegung, ECO nach zehn Minuten ohne. Die Verzögerungen verhindern, dass die Heizung hoch- und runterspringt, wenn jemand nur kurz durchläuft.

alias: Office - Heating - Target Sync
triggers:
  - trigger: state
    entity_id: binary_sensor.office_motion
    to: "on"
    for: { minutes: 2 }
  - trigger: state
    entity_id: binary_sensor.office_motion
    to: "off"
    for: { minutes: 10 }
  - trigger: state
    entity_id:
      - input_number.temperature_comfort_office
      - input_number.temperature_eco_office
  - trigger: state
    entity_id: input_boolean.heating_office_on
    to: "on"
conditions:
  - condition: state
    entity_id: input_boolean.heating_office_on
    state: "on"
actions:
  - if:
      - condition: state
        entity_id: binary_sensor.office_motion
        state: "on"
    then:
      - action: climate.set_temperature
        target:
          entity_id: climate.office_heating_valve
        data:
          temperature: "{{ states('input_number.temperature_comfort_office') | float }}"
    else:
      - action: climate.set_temperature
        target:
          entity_id: climate.office_heating_valve
        data:
          temperature: "{{ states('input_number.temperature_eco_office') | float }}"
mode: restart

Andere Räume nutzen andere Signale nach demselben Muster:

• Nur Zeitplan (Küche, Schlafzimmer, Bad): Komfort innerhalb des Zeitplans, ECO außerhalb.
• Zeitplan und Anwesenheit (Räume, die einer Person gehören): Komfort nur, wenn der Zeitplan aktiv ist und diese Person zu Hause ist.
• Ein Gerät als Anwesenheit: Im Gaming-Raum ist der AV-Receiver das beste Zeichen, dass jemand da ist. Receiver an heißt Komfort, Receiver aus heißt abgesenkte Temperatur.

3. Calibration: der wichtigste Teil

Ein Heizkörperthermostat misst die Temperatur dort, wo es sitzt: direkt neben dem heißen Heizkörper. Es hält den Raum also für warm, lange bevor er es ist, und schließt zu früh.

Das SONOFF TRVZB kann stattdessen eine externe Temperatur verwenden. In Zigbee2MQTT gibt es dafür zwei Entitäten:

• ein Select „Temperature sensor“: local_temperature (der eigene Sensor) oder remote_temperature (ein externer Wert)
• eine Number „External temperature input“, die den externen Wert empfängt

Die Calibration-Automation kopiert den Wert eines echten Raumsensors in diesen Eingang, sobald die Messung zwei Minuten stabil ist. Außerdem prüft sie das Select, denn nach einem Neuverbinden oder Batteriewechsel fällt das Ventil manchmal auf seinen eigenen Sensor zurück.

alias: Office - Climate - Calibration
triggers:
  - trigger: state
    entity_id: sensor.office_temperature
    for: { minutes: 2 }
  - trigger: state
    entity_id: select.office_heating_valve_temperature_sensor_select
    not_to:
      - remote_temperature
      - remote_source_offline
      - unavailable
      - unknown
conditions:
  - condition: numeric_state
    entity_id: sensor.office_temperature
    above: 0
actions:
  # das Ventil wieder auf den externen Sensor stellen, falls es zurückgefallen ist
  - if:
      - condition: not
        conditions:
          - condition: state
            entity_id: select.office_heating_valve_temperature_sensor_select
            state:
              - remote_temperature
              - remote_source_offline
    then:
      - action: select.select_option
        target:
          entity_id: select.office_heating_valve_temperature_sensor_select
        data:
          option: remote_temperature
        continue_on_error: true
  # die echte Raumtemperatur an das Ventil geben
  - action: number.set_value
    target:
      entity_id: number.office_heating_valve_external_temperature_input
    data:
      value: "{{ states('sensor.office_temperature') | float }}"
mode: single

Die Bedingung above: 0 verhindert, dass ein Sensor, der 0 oder gar nichts meldet, das Haus herunterkühlt. Mit der Calibration erreicht der Raum endlich die Temperatur, die das Dashboard anzeigt.

4. Keine Heizung bei offener Tür

Das Wohnzimmer hat eine Terrassentür und zwei Fenster, und die Heizung lief weiter, wenn sie offen waren. Die Pause-Automation schaltet die drei Ventile aus, wenn eine Tür oder ein Fenster eine Minute offen ist, und schaltet sie wieder ein, wenn alle wieder geschlossen sind.

Das wichtige Detail: Sie fasst den Hauptschalter nicht an. Stattdessen setzt sie ein eigenes Flag (input_boolean.heating_living_room_paused). Toggle und Target Sync lassen die Ventile in Ruhe, solange das Flag an ist. Weil das Flag ein Helfer ist und kein Warten innerhalb der Automation, übersteht es auch einen Neustart von Home Assistant. Ein Start-Trigger stellt die Heizung wieder her, falls alles geschlossen wurde, während Home Assistant nicht lief.

triggers:
  - trigger: state
    entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
    to: "on"
    for: { minutes: 1 }
    id: opened
  - trigger: state
    entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
    from: "on"
    to: "off"
    id: closed
  - trigger: homeassistant
    event: start
    id: ha_start
actions:
  - choose:
      - conditions:   # geöffnet, während die Heizung an ist -> pausieren
          - condition: trigger
            id: opened
          - condition: state
            entity_id: input_boolean.heating_living_room_on
            state: "on"
        sequence:
          - action: input_boolean.turn_on
            target: { entity_id: input_boolean.heating_living_room_paused }
          - action: climate.set_hvac_mode
            target: { entity_id: [climate.living_room_heating_1, climate.living_room_heating_2, climate.living_room_heating_3] }
            data: { hvac_mode: "off" }
      - conditions:   # alles zu und von uns pausiert -> fortsetzen
          - condition: trigger
            id: [closed, ha_start]
          - condition: state
            entity_id: [binary_sensor.terrace_door, binary_sensor.living_room_window_1, binary_sensor.living_room_window_2]
            state: "off"
          - condition: state
            entity_id: input_boolean.heating_living_room_paused
            state: "on"
        sequence:
          - action: input_boolean.turn_off
            target: { entity_id: input_boolean.heating_living_room_paused }
          - if:
              - condition: state
                entity_id: input_boolean.heating_living_room_on
                state: "on"
            then:
              - action: climate.set_hvac_mode
                target: { entity_id: [climate.living_room_heating_1, climate.living_room_heating_2, climate.living_room_heating_3] }
                data: { hvac_mode: heat }
              - action: automation.trigger
                target: { entity_id: automation.living_room_heating_target_sync }
mode: queued

5. Sicherheitsnetze

Automationen scheitern leise. Diese drei sorgen dafür, dass ich es mitbekomme:

• Kindersicherung erzwingen: Nach einem Batteriewechsel oder Neu-Anlernen kann die Kindersicherung eines Ventils aus sein, und dann kann jeder am Rädchen drehen. Ist eine der zwölf Sperren 10 Sekunden lang aus, oder startet Home Assistant, werden alle Sperren wieder eingeschaltet.
• Warnung bei falscher Zieltemperatur: 10 Minuten nachdem sich die Zieltemperatur eines Ventils oder ein Komfort-/ECO-Wert geändert hat, prüft ein Template jedes Ventil. Passt eine Zieltemperatur weder zum ECO- noch zum Komfortwert ihres Raums (Toleranz 0,25 °C), bekomme ich eine Telegram-Nachricht. Räume mit ausgeschalteter Heizung, ausgeschaltete Ventile und das pausierte Wohnzimmer werden übersprungen. So fällt ein Target Sync auf, der das Ventil nicht erreicht hat.
• Warnung bei neuer Zigbee2MQTT-Version: eine Nachricht, sobald Zigbee2MQTT in einer neuen Version läuft. Den Grund liest du im nächsten Abschnitt.

Der Kern der Prüfung, vereinfacht auf ein Ventil:

{% set target  = state_attr('climate.office_heating_valve', 'temperature') | float %}
{% set eco     = states('input_number.temperature_eco_office') | float %}
{% set comfort = states('input_number.temperature_comfort_office') | float %}
{{ (target - eco) | abs > 0.25 and (target - comfort) | abs > 0.25 }}

Die Probleme, die wir hatten

Was ich gelernt habe

• Kleine, langweilige Automationen pro Raum schlagen einen cleveren gemeinsamen Blueprint. Sie sind leichter zu lesen, zu testen und zu reparieren.
• Ein Heizkörperthermostat ohne externen Sensor heizt auf die falsche Temperatur. Ihm einen echten Raumsensor zu geben, ist die zusätzliche Automation wert.
• Nutze ein Flag als Helfer statt eines Wartens für alles, was einen Neustart überstehen muss.
• Jede Automation, die still scheitern kann, braucht eine Warnung, die das Ergebnis prüft, nicht nur den Auslöser.

Kurz gesagt

Problem: WordPress war der letzte Dienst, der noch ein eigenes Passwort wollte.

Lösung: Ein OAuth2/OpenID-Provider in Authentik plus das Plugin OpenID Connect Generic in WordPress, mit allen Werten unten aufgelistet.

Getestet mit: WordPress 7.1, Authentik 2026.8, OpenID Connect Generic 3.11

Ich nutze Authentik als zentrale Anmeldung für meine selbst gehosteten Dienste. Dieser Blog soll genauso funktionieren: ein Klick auf den Login-Button, Passkey, fertig. Die normale WordPress-Anmeldung bleibt als Rückfallebene erhalten, falls Authentik einmal nicht erreichbar ist.

In den Beispielen läuft Authentik unter https://auth.example.com, der Blog unter https://blog.example.com, und der Slug der Authentik-Anwendung ist blog. Ersetze diese Werte durch deine eigenen.

So funktioniert die Anmeldung

1. Du klickst auf der WordPress-Anmeldeseite auf den Login-Button.
2. WordPress leitet dich zu Authentik weiter, wo du dich anmeldest, zum Beispiel mit einem Passkey.
3. Authentik schickt dich mit einem Einmal-Code zurück zu WordPress.
4. WordPress tauscht den Code im Hintergrund gegen Tokens, liest Benutzername und E-Mail-Adresse und meldet dich als passenden WordPress-Benutzer an.

1. Authentik: Provider anlegen

Im Authentik-Adminbereich unter Applications → Providers → Create den Typ OAuth2/OpenID Provider wählen. Das sind meine Einstellungen:

Zum Vergleich derselbe Provider, über die API angelegt:

curl -X POST https://auth.example.com/api/v3/providers/oauth2/ 
  -H "Authorization: Bearer $AUTHENTIK_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Provider for Blog",
    "client_type": "confidential",
    "authorization_flow": "<UUID von default-provider-authorization-implicit-consent>",
    "invalidation_flow": "<UUID von default-provider-invalidation-flow>",
    "property_mappings": ["<openid-UUID>", "<email-UUID>", "<profile-UUID>"],
    "signing_key": "<UUID des Signatur-Zertifikats>",
    "sub_mode": "hashed_user_id",
    "include_claims_in_id_token": true,
    "grant_types": ["authorization_code", "refresh_token"],
    "redirect_uris": [{
      "matching_mode": "strict",
      "url": "https://blog.example.com/wp-admin/admin-ajax.php?action=openid-connect-authorize"
    }]
  }'

2. Authentik: Anwendung anlegen

Unter Applications → Applications → Create:

Danach die Anwendung öffnen, unter Policy / Group / User Bindings die Benutzer oder die Gruppe binden, die sich bei WordPress anmelden dürfen. Ohne Binding kann jeder Authentik-Benutzer die Anwendung nutzen.

Alle Endpunkte stehen im Discovery-Dokument der Anwendung. Ruf es einmal auf, um zu prüfen, dass alles passt:

curl -s https://auth.example.com/application/o/blog/.well-known/openid-configuration

3. WordPress: Plugin installieren

Installiere und aktiviere OpenID Connect Generic (von daggerhart) aus dem Plugin-Verzeichnis. Die Einstellungen findest du unter Einstellungen → OpenID Connect Client. Sobald das Plugin aktiv ist, zeigt die Anmeldeseite einen Button. Er funktioniert erst, wenn die Einstellungen unten gespeichert sind.

4. WordPress: alle Plugin-Einstellungen

Nur die JWKS-URI, die End-Session-URL und der Issuer enthalten den Slug der Anwendung. Die Endpunkte für authorize, token und userinfo sind in Authentik für alle Anwendungen gleich.

Wie bestehende Benutzer zugeordnet werden

Mit Link Existing Users sucht das Plugin einen WordPress-Benutzer, dessen Benutzername dem Wert des Identity Keys entspricht, hier also dem Authentik-Benutzernamen (preferred_username). Bei der ersten Anmeldung werden die beiden Konten verknüpft, danach bleibt die Verknüpfung fest. Verwende in WordPress und Authentik denselben Benutzernamen. Solange Create user if does not exist aus ist, bekommt niemand ein neues WordPress-Konto, nur weil er einen Authentik-Zugang hat.

Optional: das Secret aus der Datenbank heraushalten

Statt die Werte auf der Einstellungsseite einzutragen, kannst du sie in der wp-config.php definieren. Das Plugin verwendet dann diese Werte und zeigt die Felder schreibgeschützt an:

define( 'OIDC_CLIENT_ID', 'deine-client-id' );
define( 'OIDC_CLIENT_SECRET', 'dein-client-secret' );
define( 'OIDC_CLIENT_SCOPE', 'openid email profile' );
define( 'OIDC_ENDPOINT_LOGIN_URL', 'https://auth.example.com/application/o/authorize/' );
define( 'OIDC_ENDPOINT_USERINFO_URL', 'https://auth.example.com/application/o/userinfo/' );
define( 'OIDC_ENDPOINT_TOKEN_URL', 'https://auth.example.com/application/o/token/' );
define( 'OIDC_ENDPOINT_LOGOUT_URL', 'https://auth.example.com/application/o/blog/end-session/' );

5. Testen

Bevor du auf den Button klickst, teste die Anfrage in der Kommandozeile. Ein funktionierender Provider leitet zum Authentik-Login weiter:

curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}n" 
  "https://auth.example.com/application/o/authorize/?response_type=code&scope=openid%20email%20profile&client_id=DEINE_CLIENT_ID&state=test&redirect_uri=https%3A%2F%2Fblog.example.com%2Fwp-admin%2Fadmin-ajax.php%3Faction%3Dopenid-connect-authorize"

# gut:    302 -> https://auth.example.com/if/flow/default-authentication-flow/?...
# falsch: 302 -> https://blog.example.com/...?error=invalid_request&...

Wenn das passt: aus WordPress abmelden, auf den Login-Button klicken und mit Authentik anmelden. Du solltest als dein bestehender Benutzer im Dashboard landen.

Fehlersuche

Was ich gelernt habe

• Die Authentik-Oberfläche setzt Standardwerte, die die API nicht setzt.
• Das Serverlog nennt den wahren Grund, wenn der Browser nur einen allgemeinen Fehler zeigt.
• Behalte die lokale WordPress-Anmeldung als Rückfallebene. Wenn der Identity Provider ausfällt, willst du trotzdem auf deine eigene Seite kommen.