Ein Sonntag im Homelab: Paperless-ngx, Pi-hole, Reverse Proxy & Co.
-
Andy -
22. November 2026 um 16:20 -
49 Mal gelesen -
12 Antworten
- Paperless-ngx startet nicht mehr: :latest ist jetzt v3
- Doppelseitig scannen mit einem einseitigen Scanner
- Backup: Die Datenbank liegt nicht da, wo man denkt
- Schöne Adressen mit echtem HTTPS, ohne etwas ins Internet zu stellen
- Home Assistant hinter dem Proxy: Die YAML wird ignoriert
- Pi-hole: weniger Listen, mehr Überblick, eigener Resolver
- Was ich mitnehme
Paperless-ngx startet nicht mehr: :latest ist jetzt v3
Der Grund war ein einziges Wort in der Compose-Datei: image: ghcr.io/paperless-ngx/paperless-ngx:latest. Hinter latest steckt inzwischen Paperless-ngx v3, und dieses Update bringt Breaking Changes mit sich, die eine v2-Konfiguration am Start hindern. Die wichtigsten laut Migrationsanleitung:
- PAPERLESS_SECRET_KEY ist Pflicht. In der Standard-Compose-Datei ist er auskommentiert.
- PAPERLESS_DBENGINE muss gesetzt werden (bei PostgreSQL: postgresql). Die Datenbank wird nicht mehr aus PAPERLESS_DBHOST abgeleitet.
- Upgrade nur über v2.20.15. Ältere Versionen können nicht direkt auf v3 springen.
- PAPERLESS_CONSUMER_POLLING gibt es nicht mehr, das Intervall heißt jetzt nur noch PAPERLESS_CONSUMER_POLLING_INTERVAL.
- Duplikate werden nicht mehr automatisch abgelehnt. Wer das will, setzt PAPERLESS_CONSUMER_DELETE_DUPLICATES=true.
So kommt ihr sauber auf v3:
- Im Portainer-Editor des bestehenden Stacks das Image auf paperless-ngx:2.20.15 setzen und mit „Update the stack“ neu deployen. Wichtig: nicht über „Add stack“ einen neuen Stack anlegen, sonst gibt es Namenskonflikte, und mit einem anderen Stack-Namen landet ihr bei einer leeren Datenbank.
- Warten, bis Paperless auf 2.20.15 sauber läuft.
- Dann das Image auf eine konkrete v3-Version setzen, z. B. 3.5.1, die neuen Variablen ergänzen und erneut deployen.
Achtung: Ein Tag :3 gibt es nicht, die Versionsnummer muss vollständig angegeben werden. Beim ersten Start mit v3 laufen die Datenbank-Migrationen, und der Suchindex wird mit der neuen Suchmaschine Tantivy neu aufgebaut. Nach dem Wechsel des Secret Keys müsst ihr euch einmal neu anmelden.
Doppelseitig scannen mit einem einseitigen Scanner
Mein Brother-Scanner zieht Blätter nur einseitig ein. Paperless kann aber zwei einseitige Scans automatisch zu einem doppelseitigen Dokument zusammenfügen. Dafür braucht es zwei Variablen und einen Unterordner:
PAPERLESS_CONSUMER_ENABLE_COLLATE_DOUBLE_SIDED: 1
PAPERLESS_CONSUMER_COLLATE_DOUBLE_SIDED_SUBDIR_NAME: doppelseitig
PAPERLESS_CONSUMER_RECURSIVE: 1
Der Ordner consume/doppelseitig muss existieren, Paperless legt ihn nicht selbst an. Beim Ordnernamen darauf achten, nur den Namen einzutragen, ohne ./ davor.
Der Ablauf laut Dokumentation:
- Stapel einlegen und die Vorderseiten scannen, z. B. Seiten 1, 3 und 5. Der Scan landet im Ordner doppelseitig.
- Stapel umdrehen, ohne die Blätter neu zu sortieren, und die Rückseiten scannen. Die kommen rückwärts heraus: 6, 4, 2.
- Paperless dreht den zweiten Scan um, fügt beide zu den Seiten 1 bis 6 zusammen und verarbeitet das Ergebnis ganz normal.
Der erste Scan wartet bis zu 30 Minuten auf den zweiten. Leere Seiten am Ende darf man weglassen, leere Seiten in der Mitte nicht.
Mein Stolperstein: Der Scanner hatte zwei Profile, eines für consume und eines für consume/doppelseitig. Am Gerät war aus Gewohnheit das falsche ausgewählt, also kamen zwei getrennte Dokumente an. Im Paperless-Log sieht man sofort, in welchem Ordner eine Datei gefunden wurde. Gibt es dort die Meldung „Got scan with odd numbered pages“, hat es geklappt.
Backup: Die Datenbank liegt nicht da, wo man denkt
Meine Dokumente liegen per NFS auf der Synology. Die PostgreSQL-Datenbank mit allen Tags, Korrespondenten und Zuordnungen lag aber als Docker-Volume lokal auf dem Raspberry Pi. Wäre dessen SD-Karte ausgefallen, wären alle Metadaten weg gewesen.
Die Lösung ist ein kleines Skript, das jede Nacht per Cron läuft und zwei Dinge aufs NAS schreibt:
# 1) Datenbank-Dump zuerst, läuft auch, wenn der Export scheitert
docker exec paperless-db-1 pg_dump -U paperless -Fc paperless \
> /mnt/paperless/export/db/paperless_$(date +%F).dump
# 2) Vollständiger Paperless-Export (Dokumente + Metadaten)
docker exec paperless-webserver-1 document_exporter ../export/paperless -d -c
Der Export geht bewusst in einen eigenen Unterordner. Die Option -d löscht nämlich alles im Zielordner, was nicht zum aktuellen Export gehört, also auch daneben liegende Datenbank-Dumps. Weil der Export ein Spiegel ist, lohnen sich zusätzlich Snapshots oder Hyper Backup auf der Synology.
Wichtig für den Ernstfall: Ein Export lässt sich nur in eine komplett leere Installation mit derselben Paperless-Version importieren. Ein weiterer Grund, die Version fest anzugeben.
Der Export hat sofort Probleme aufgedeckt. Er brach bei zwei Dokumenten ab, deren Dateien auf dem NAS fehlten. Der Befehl docker exec paperless-webserver-1 document_sanity_checker zeigt solche Probleme vollständig an. Bei mir kamen 97 verwaiste Dateien aus einer alten Installation dazu, teils in Ordnern mit dem Namen PAPERLESS_FILENAME_FORMAT=2025/..., weil die Variable damals falsch eingetragen war. Die habe ich in einen Quarantäne-Ordner verschoben und die Originale erneut in den Consume-Ordner kopiert. Mit aktivierter Duplikat-Erkennung verwirft Paperless alles, was es schon kennt, und importiert nur, was wirklich fehlte.
Schöne Adressen mit echtem HTTPS, ohne etwas ins Internet zu stellen
Statt 192.168.178.20:8010 rufe ich Paperless jetzt unter https://paperless.home.meinedomain.de auf, ohne Zertifikatswarnung. Dasselbe gilt für Portainer, Pi-hole, Home Assistant, evcc und beide NAS. Von außen erreichbar ist trotzdem nichts.
So greift das ineinander:
- Pi-hole beantwortet im Heimnetz alle Namen unter home.meinedomain.de mit der IP des Raspberry Pi. Dafür reicht eine einzige Zeile unter Settings → All settings → Miscellaneous → misc.dnsmasq_lines: address=/home.meinedomain.de/192.168.178.20
- Nginx Proxy Manager läuft als Container auf dem Pi, hört auf die Ports 80 und 443 und leitet jeden Namen an den passenden Dienst weiter.
- Ein Wildcard-Zertifikat für *.home.meinedomain.de von Let's Encrypt deckt alle Dienste ab.
Der Trick ist die DNS-Challenge. Let's Encrypt prüft dabei nicht, ob der Server erreichbar ist, sondern ob man die Domain kontrolliert. Nginx Proxy Manager legt dazu über die API des DNS-Anbieters kurz einen TXT-Eintrag an und löscht ihn danach wieder. Am Router wird kein Port geöffnet, im öffentlichen DNS steht kein Eintrag. Für all-inkl.com bringt Nginx Proxy Manager seit Version 2.13.6 ein eigenes Plugin mit, es braucht nur die KAS-Zugangsdaten.
Zwei Stolpersteine:
- Mit *.home.meinedomain.de und home.meinedomain.de im selben Zertifikat schlug die Ausstellung fehl („Could not find TXT record“). Nur mit dem Wildcard-Eintrag klappte es sofort. Den zweiten Namen braucht man ohnehin nicht.
- ssh pi@evcc.home.meinedomain.de landet beim Proxy-Pi, nicht beim evcc-Pi. Alle Namen zeigen ja auf den Proxy. Für SSH also weiter die IP nutzen oder einen Alias in ~/.ssh/config anlegen.
Unterwegs funktionieren die Adressen über WireGuard, wenn das VPN den Pi-hole als DNS-Server verteilt.
Home Assistant hinter dem Proxy: Die YAML wird ignoriert
Home Assistant antwortete über den Proxy zunächst nur mit „400: Bad Request“. Das ist normal, solange man den Proxy nicht erlaubt hat. Der klassische Weg ist ein http:-Block in der configuration.yaml mit use_x_forwarded_for: trueund der IP des Proxys unter trusted_proxies.
Genau das hatte ich eingetragen, die Konfigurationsprüfung war grün, nach dem Neustart kam trotzdem weiter der Fehler. Im Log stand: „A request from a reverse proxy was received from 192.168.178.20, but your HTTP integration is not set-up for reverse proxies“.
Die Erklärung: Seit Home Assistant 2026.8 wird die HTTP-Integration in der Oberfläche konfiguriert. Die alten YAML-Einstellungen werden einmalig übernommen, spätere Änderungen an der Datei greifen nicht mehr. Andere Nutzer berichten dasselbe.
Die Lösung: Einstellungen → System → Netzwerk → HTTP-Server → Reverse-Proxy, dort „X-Forwarded-For vertrauen“ einschalten und die IP des Proxys als vertrauenswürdigen Proxy eintragen. Beim Speichern startet Home Assistant neu, danach klappt es sofort. Den http:-Block in der YAML kann man anschließend löschen.
Pi-hole: weniger Listen, mehr Überblick, eigener Resolver
Blocklisten ausmisten. Bei mir liefen StevenBlack, OISD Big und HaGeZi Pro parallel. Das ist doppelt und dreifach gemoppelt: HaGeZi bezieht OISD und StevenBlack bereits als Quellen mit ein. Jetzt laufen nur noch zwei Listen:
StevenBlack und OISD sind nur deaktiviert, nicht gelöscht. So lassen sie sich jederzeit wieder einschalten.
Gerätenamen statt IP-Adressen. Mit „Conditional Forwarding“ fragt Pi-hole die Fritzbox, welches Gerät hinter welcher IP steckt. Im Query Log stehen dann Namen wie „iPhone.fritz.box“. In Pi-hole v6 findet sich das unter Settings → DNS → Conditional forwarding als kleine Tabelle. Bleibt dort die Spalte „Domain“ leer, gibt es die Fehlermeldung „contains two commas following each other“. Mit fritz.box als Domain ist der Eintrag vollständig: true,192.168.178.0/24,192.168.178.1,fritz.box
Eigener DNS-Resolver mit Unbound. Statt alle Anfragen an Quad9 oder Google weiterzugeben, fragt jetzt ein Unbound-Container die zuständigen DNS-Server selbst ab und prüft DNSSEC. Ich nutze das Multi-Arch-Image klutchell/unbound, das auch auf dem Raspberry Pi läuft. In Pi-hole wird dann als einziger Upstream-Server 192.168.178.20#5335 eingetragen.
Stolperfalle: Das aktuelle Image lauscht im Container auf Port 53, nicht auf 5053, wie es in älteren Anleitungen steht. Die richtige Zuordnung ist also 5335:53. Testen lässt sich Unbound vor der Umstellung mit dig @192.168.178.20 -p 5335 heise.de. Erst wenn dort status: NOERROR mit einer IP-Adresse erscheint, sollte man Pi-hole umstellen. Sonst hat das ganze Heimnetz kein DNS mehr.
Was ich mitnehme
- Keine :latest-Tags für wichtige Container. Feste Versionen wie paperless-ngx:3.5.1 oder nginx-proxy-manager:2.17.0 verhindern, dass ein harmloser Neustart zur Migration wird. Updates spiele ich jetzt bewusst ein, nach einem Blick in die Release Notes.
- Backups erst testen, dann vertrauen. Der erste Export-Lauf hat zwei kaputte Dokumente und 97 verwaiste Dateien aufgedeckt, von denen ich nichts wusste.
- SD-Karten sind die Schwachstelle. Alle meine Raspberry Pis laufen noch von SD-Karte. Home Assistant sichert sich zwar täglich aufs NAS, der Umzug auf SSDs steht trotzdem als Nächstes an. Dann folgen InfluxDB und Grafana für die Langzeitauswertung der PV-Daten.
- Logs lesen spart Zeit. Ob Paperless, Home Assistant oder Pi-hole: Die eigentliche Ursache stand jedes Mal im Log, oft wörtlich.
Wie sieht euer Homelab aus? Nutzt ihr Paperless-ngx schon mit v3, oder setzt ihr auf andere Lösungen? Schreibt es in die Kommentare.
Ich werde jetzt erstmal zig Terminal- und Browser-Fenster und -Tabs schließen und dann mal ab auf die Couch. Es ist Sonntag. Cheers!
Artikelbild mit Hilfe von KI erstellt.
Quellen
- GitHub: Breaking Changes, Upgrade-Pfad über 2.20.15, neue Variablen
- docs.paperless-ngx.com: Alle Umgebungsvariablen, u. a. für doppelseitiges Scannen
- docs.paperless-ngx.com: Ablauf beim Zusammenführen einseitiger Scans
- docs.paperless-ngx.com: Export, Import und Sanity-Checker
- GitHub: All-Inkl-DNS-Plugin seit Version 2.13.6
- Home Assistant: Reverse-Proxy-Einstellungen seit 2026.8 in der Oberfläche
- Home Assistant: Erfahrungsbericht anderer Nutzer zum gleichen Problem
- GitHub: Listenstufen und Threat-Intelligence-Listen
- edwardangert-github-io.pages.dev: Unterschiede zwischen HaGeZi und OISD
- GitHub: Docker-Image und Standard-Port
Über den Autor
Ich habe generation i mit ins Leben gerufen, um Technik mit Verstand zu begleiten.
Apple-Fan? Definitiv. Aber immer mit dem kritischen Blick eines Gründers, dem Substanz wichtiger ist als jeder Hype.
Ich sorge für den richtigen Rhythmus zwischen Innovation und echtem Nutzen.
Antworten 12