1. Dashboard
  2. Artikel
  3. Forum
  4. Shop
  • Anmelden
  • Registrieren
  • Suche
Gedankenwelt
  • Alles
  • Gedankenwelt
  • Artikel
  • Seiten
  • Forum
  • Erweiterte Suche
  1. generation i
  2. Artikel
  3. Gedankenwelt

Ein Sonntag im Homelab: Paperless-ngx, Pi-hole, Reverse Proxy & Co.

  • Andy
  • 22. November 2026 um 16:20
  • 49 Mal gelesen
  • 12 Antworten
Eigentlich wollte ich nur herausfinden, warum Paperless-ngx nicht mehr startet. Am Abend lief mein Homelab dann auf Paperless v3, mit nächtlichem Backup, echten HTTPS-Zertifikaten für alle Dienste und einem Pi-hole mit eigenem DNS-Resolver. Hier ist, was ich dabei gelernt habe, mit den Stolperfallen, die euch hoffentlich erspart bleiben.

Die Ausgangslage: Ein Raspberry Pi mit Docker und Portainer, darauf Paperless-ngx und Pi-hole. Dazu eine Synology als Datenablage, ein zweiter Raspberry Pi mit Home Assistant OS und einer für evcc für die Wallbox. Alles läuft im Heimnetz, nichts ist von außen erreichbar.
Inhaltsverzeichnis [VerbergenAnzeigen]
  1. Paperless-ngx startet nicht mehr: :latest ist jetzt v3
  2. Doppelseitig scannen mit einem einseitigen Scanner
  3. Backup: Die Datenbank liegt nicht da, wo man denkt
  4. Schöne Adressen mit echtem HTTPS, ohne etwas ins Internet zu stellen
  5. Home Assistant hinter dem Proxy: Die YAML wird ignoriert
  6. Pi-hole: weniger Listen, mehr Überblick, eigener Resolver
  7. 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:

  1. 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.
  2. Warten, bis Paperless auf 2.20.15 sauber läuft.
  3. 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:

Code
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:

  1. Stapel einlegen und die Vorderseiten scannen, z. B. Seiten 1, 3 und 5. Der Scan landet im Ordner doppelseitig.
  2. Stapel umdrehen, ohne die Blätter neu zu sortieren, und die Rückseiten scannen. Die kommen rückwärts heraus: 6, 4, 2.
  3. 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:

Code
# 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:

  1. 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
  2. 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.
  3. 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:

ListeZweckEinträge (Nov. 2026)
HaGeZi ProWerbung, Tracker, Telemetrieca. 284.000
HaGeZi Threat Intelligence (medium)Phishing, Malware, Betrugca. 413.000

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.

Diskutiere mit uns im Forum! 12 Antworten, zuletzt: 22. November 2026 um 19:15

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.

Andy Team

Vorheriger Artikel Ein Jahr generation i: 365 Tage Apple, Smart Home und ziemlich viel Café

Antworten 12

access
22. November 2026 um 16:57

Ich würde mich sehr für Paperless ngx interessieren, allerdings ist meine Frau noch gerne Analog unterwegs. Hat das auch OCR drin?

Andy
22. November 2026 um 16:58
Zitat von access

Hat das auch OCR drin?

Ja.

Das wird eines meiner nächsten Aufgaben sein: Meine Frau von Paperless-ngx überzeugen und sie die Dokumente mal scannen lassen, die ankommen usw. ... Aber irgendwann muss man ja mal anfangen damit.

Ich sende z.B. Rechnungen, die per Mail ankommen, direkt an Paperless-ngx weiter.

carsten_h
22. November 2026 um 17:05
Zitat

ssh pi@evcc.home.meinedomain.de landet beim Proxy-Pi, nicht beim evcc-Pi. Alle Namen zeigen ja auf den Proxy

Das habe ich so geregelt, daß ich eine Domain mit Adressen von außen habe:

*.abc.aussen.de, die von der Fritz!Box mit der dynamischen externen IP, meines Netzes versorgt wird.

Für reine interne Adressen habe ich noch die Domain:

*.abc.innen.de, die einmalig mit der internen IP meines Reverse-Proxies (zoraxy) versorgt wurde.

Für beides gibt es Wildcard-Zertifikate von Let‘s Encrypt und den Rest erledigt der Reverse-Proxy.

Andy
22. November 2026 um 17:11

Das „von außen“ benötige ich ja eigentlich nicht - da ich, sobald das WLAN verlassen wird, per WireGuard wieder „daheim“ bin?

carsten_h
22. November 2026 um 17:27

Ja, aber dann hast Du in der Konfiguration etwas falsch, wenn Du mit „evcc.home.meinedomain.de“ auf dem Reverse-Proxy landest. Der Reverse-Proxy sollte das dann in die interne IP deines Gerätes ändern.

Andy
22. November 2026 um 17:29

Ich hab das ehrlicherweise nicht getestet. War bisher nur im WLAN ohne VPN.


WLAN aus, VPN WireGuard aktiviert sich - evcc.home.meinedomain.de bringt mich zu evcc.

carsten_h
22. November 2026 um 17:37

Dann verstehe ich den Teil im Artikel mit dem zweiten Stolperstein aber nicht.
Es sollte auch im lokalen Netz genauso funktionieren.

Webmark
22. November 2026 um 17:38

Ich habe dieses Thema nur oberflächlich durchgelesen, denn ehrlich gesagt habe ich absolut keine Ahnung um was es bei "Paperless-ngx, Pi-hole, Reverse Proxy & Co." geht.

Könnt ihr mir mit einem kurzen Statement auf die Sprünge helfen?

Andy
22. November 2026 um 17:44
Zitat von carsten_h

Dann verstehe ich den Teil im Artikel mit dem zweiten Stolperstein aber nicht.

Du meinst das:

  • 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.

?

Hier lande ich nicht auf dem Raspberry, auf dem evcc läuft.

Zitat von Webmark

Könnt ihr mir mit einem kurzen Statement auf die Sprünge helfen?

  • Paperless-ngx ist eine Dokumentenverwaltung, die man zuhause laufen hat.
  • Pi-Hole ein Werbeblocker
  • Reverse Proxy ist etwas aufwändiger zu erklären. Hilft Wikipedia?
Webmark
22. November 2026 um 18:02

Danke, nun weiß ich zumindest grundsätzlich um was es hier eigentlich geht.

Kategorien

  1. News über Apple 21
  2. News 74
  3. Sonstige News 24
  4. Shortnews 10
  5. Gerüchte 15
  6. Gedankenwelt 54
  7. KI / LLM 5
  8. Android 2
  9. iOS-Apps 1
  10. Smarthome 19
  11. Netzwerk 2
  12. CarPlay 1
  13. Apple TV / tvOS 1
  14. Hardware 8
  15. iCloud 1
  16. Mac-Hardware 10
  17. macOS 2
  18. iPad 2
  19. iPhone 3
  20. iOS 3
  21. Café 5
  22. 3D-Druck 4
  23. Filter zurücksetzen
Diskutiere mit uns im Forum! 12 Antworten, zuletzt: 22. November 2026 um 19:15
  1. generation i
  2. Artikel
  3. Gedankenwelt
  1. Forenregeln
  2. Datenschutzerklärung
  3. Netiquette
  4. Kontakt
  5. Impressum
  6. Credits
Community-Software: WoltLab Suite™ 6.2.9