Paperless-ngx: Scanner, Einrichtung, Backup

Der Schuhkarton mit Briefen unterm Schreibtisch ist auch eine Datenbank, nur mit grauenhafter Suche. Paperless-ngx macht daraus ein durchsuchbares Archiv, wenn du Scanner, Ordner und Backup in der richtigen Reihenfolge planst.

Kurz gesagt

Wie richtest du Paperless-ngx zu Hause ein? Starte es mit Docker Compose, binde einen Ordner des Hosts als Eingangsordner des Containers ein und lass jeden Scanner, der Dateien in einen Netzwerkordner speichern kann, seine PDFs dort ablegen. Die Marke des Scanners ist Paperless egal; es beobachtet einen Ordner [13]. Drei Entscheidungen wiegen schwerer als die Software. Erstens der Scanner: Achte auf beidseitiges Scannen in einem Durchgang, einen Einzugsschacht und ein Netzwerkziel (SMB ab Version 2, FTP oder SFTP). Zweitens die OCR-Sprache: Der Standard ist Englisch, also setze für deutsche Briefe deu+eng [2]. Drittens das Backup: Nutze den eingebauten document_exporter, kopiere dessen Ausgabe außer Haus und probe die Wiederherstellung auf einem zweiten Rechner, denn ein Export lässt sich nur in dieselbe Version und in eine leere Installation importieren [3].

So funktioniert’s

1. Was du aufbaust. Paperless besteht aus einem Consumer, der einen Ordner beobachtet, und einem Webserver für die Oberfläche [5]. Mit der offiziellen PostgreSQL-Compose-Datei bekommst du drei Container: einen Valkey-Broker, PostgreSQL 18 und den Paperless-Webserver, der auch den Consumer enthält und auf Port 8000 lauscht [10]. Die Doku empfiehlt PostgreSQL für neue Installationen [1]. Sie beschreibt außerdem ein Skript, das die Einrichtung interaktiv erledigt, und rät, es vor dem Pipen in eine Shell zu lesen [1]. Paperless läuft nur unter Linux [1]. Eine Mindestausstattung für RAM oder CPU haben wir in der Setup-Doku nicht gefunden, deshalb gilt sie als unbelegt. Die Doku sagt aber, dass es auf einem Raspberry Pi läuft, mit Tuning-Hinweisen wie OCR nur der ersten Seite [1].
2. Version und Image-Tag. Das neueste Release, das wir am 25. Okt. 2026 gefunden haben, ist v3.3.4 vom 22. Okt. 2026, ein Sicherheits-Wartungsrelease [9]. Version 3 bringt Breaking Changes. Du kannst nur von 2.20.15 aus upgraden, PAPERLESS_SECRET_KEY ist jetzt Pflicht, die Consumer-Einstellungen wurden umbenannt, und Duplikate werden standardmäßig nicht mehr abgelehnt [4]. Die offiziellen Compose-Dateien nutzen image: ...:latest [10]. Die Doku beschreibt das Festnageln auf eine Release-Serie [3]. Eine Feature-Anfrage in den Diskussionen des Projekts stellt fest, dass es Minor- und Patch-Tags gibt, aber keine Major-Tags wie 3, und ein Maintainer antwortet, nur Feature-Release-Tags anzubieten sei Absicht [12]. Wir nageln auf eine volle Version wie 3.3.4 fest. Die Tag-Liste der Registry konnten wir nicht lesen, also bestätige mit einem einmaligen docker pull ghcr.io/paperless-ngx/paperless-ngx:3.3.4, dass der Tag existiert.
3. Scanner-Typen, allgemein. Vier Arten funktionieren. (a) Ein Einzugsscanner für den Schreibtisch mit Touchscreen, der in einen Netzwerkordner speichert. (b) Ein Multifunktionsdrucker mit Einzug und Scan-to-Folder. (c) Ein Scanner, der nur über einen Computer arbeitet; das Paperless-Wiki führt ein solches Modell als nur per USB nutzbar, es braucht also einen PC in der Kette [13]. (d) Eine Handy-App, die per FTP, SMB, WebDAV oder API hochlädt; das Wiki listet mehrere [13]. Unsere Einschätzung: Ein Einzugsscanner mit eigenem Netzwerkziel macht am wenigsten Reibung, denn das Papier geht hinein und die Datei kommt an, ohne dass ein Computer dazwischen sitzt.
4. Kriterien statt Testsieger. Prüfe diese Punkte im Datenblatt, nicht auf der Verpackung. Beidseitiges Scannen in einem Durchgang; kann dein Scanner nur eine Seite, kann Paperless zwei Durchgänge zusammenführen (erst die ungeraden Seiten, dann die umgekehrten geraden), wenn du sie in einen Unterordner double-sided legst, doch die Funktion ist standardmäßig aus und den Ordner musst du selbst anlegen [6]. Die Kapazität des Einzugs. Ein Netzwerkziel, das du nutzen kannst: Die Tabelle im Wiki hat Spalten für FTP, SFTP, NFS, SMB, SMTP, WebDAV und API-Upload [13]. Die SMB-Version, die das Gerät spricht. Wie das Gerät Dateien benennt und mehrseitige PDFs baut. Die OCR übernimmt Paperless selbst, du brauchst also keinen Scanner, der durchsuchbare PDFs erzeugt [2].
5. Zwei Beispiele mit Herstellerangaben, keine Empfehlungen. Brothers US-Seite zum ADS-1700W nennt beidseitiges Scannen, einen Einzug für 20 Seiten, bis zu 25 Seiten (50 Bilder) pro Minute und Scannen per FTP und in einen Netzwerkordner, formuliert als „Network Folder (CIFS - Windows only)“ [14]. Die Support-Seite beschreibt ein Netzwerkprofil mit Ordnerpfad, Benutzername und Passwort, einer Option für beidseitiges Scannen, einer Option zum Überspringen leerer Seiten und dem Hinweis, dass die Uhr des Geräts gestellt sein muss [15]. Epsons Benutzerhandbuch zum ES-C380W sagt, dass er in einen Netzwerkordner (SMB), per FTP/FTPS oder per WebDAV scannt und dass du den freigegebenen Ordner vorher anlegen musst [16]. Das US-Datenblatt führt einen Duplexscanner mit Einzug für 20 Blatt in einem Durchgang [17]. Keine der abgerufenen Quellen nennt die SMB-Version. Frage also beim Hersteller nach oder teste mit deiner Freigabe, bevor du das Gerät behältst. Das Paperless-Wiki führt beide Modelle unter den Empfehlungen seiner Nutzer, das ist ein Erfahrungsbericht, kein Test [13]. Wir haben keinen der beiden Scanner benutzt. Prüfe das regionale Datenblatt, denn das sind US-Seiten.
6. Die SMBv1-Falle. Das Wiki vermerkt, dass ältere Canon-Modelle nur auf SMBv1-Freigaben scannen können, die moderne Systeme und NAS-Geräte standardmäßig abschalten, und schlägt einen kleinen SMB1-Proxy vor, statt SMBv1 auf dem Hauptspeicher einzuschalten [13]. Samba hat SMB1 seit 4.11.0 standardmäßig aus, und die Release Notes sagen, dass Microsoft SMB1-Unterstützung in neueren Versionen nicht mehr installiert [18]. Braucht ein Scanner SMB1, wähle einen anderen Scanner oder kapsele den Umweg. Schwäche nicht den Server, auf dem deine Dokumente liegen.
7. Weitere Scan-to-Folder-Fallen. Laut Wiki schließen manche Canon-Multifunktionsgeräte die Datei nach jeder Seite und öffnen sie neu; das Wiki rät, die Polling-Werte anzupassen, mit 180 Sekunden als Startwert wegen der Drei-Minuten-Zeitüberschreitung des Geräts [13]. Dieser Rat stammt aus der Zeit vor Paperless v3, das die Verzögerungs-Einstellungen des Consumers umbenannt hat [4]; die aktuellen Namen findest du auf der Konfigurationsseite [2]. Manche Scanner brauchen für SMB eine bestimmte Firmware- oder Softwareversion; das Wiki nennt ein ScanSnap-Modell mit Mindest-Firmware [13]. Liegt der Eingangsordner selbst auf NFS oder SMB, funktionieren die nativen Dateibenachrichtigungen möglicherweise nicht, und du musst PAPERLESS_CONSUMER_POLLING_INTERVAL auf eine positive Zahl von Sekunden setzen [1][2][7].
8. Der Eingangsordner. Behandle ihn wie einen Posteingang. Dateien, die du dort ablegst, werden in Paperless neu angelegt und aus dem Ordner entfernt [5][8]. Für Scanner, die Dateien pushen, schlägt die Doku einen FTP-Server oder eine Samba-Freigabe auf dem Host vor [5]. Binde ./consume in der Compose-Datei als Bind Mount an einen Host-Ordner und setze USERMAP_UID und USERMAP_GID auf deinen Host-Benutzer, damit beide Seiten schreiben können [1][11]. Mit PAPERLESS_CONSUMER_RECURSIVE=true liest Paperless auch Unterordner, und PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true macht aus Ordnernamen Tags [2]. Seit v3 wird ein Duplikat trotzdem übernommen und markiert, außer du setzt PAPERLESS_CONSUMER_DELETE_DUPLICATES=true [4][5].
9. OCR-Sprachen. Paperless nutzt Tesseract über OCRmyPDF. PAPERLESS_OCR_LANGUAGE nimmt dreibuchstabige Codes, kann Sprachen wie deu+eng kombinieren und steht standardmäßig auf eng. Mehrere Sprachen kosten mehr CPU-Zeit [2]. Der Container bringt Englisch, Deutsch, Italienisch, Spanisch und Französisch mit; weitere brauchen PAPERLESS_OCR_LANGUAGES, das in Rootless-Containern nicht funktioniert [1][2][11]. Der Datumsparser nutzt ein anderes Format mit zweibuchstabigen Codes wie de+en und leitet seine Sprachen aus der OCR-Einstellung ab, wenn du ihn leer lässt [2]. Der OCR-Modus steht standardmäßig auf auto und überspringt OCR, wo ein Dokument schon eingebetteten Text hat. redo führt die OCR erneut aus, wenn die Textebene des Scanners schlecht ist [2].
10. Halte es aus dem Internet heraus. Unsere Empfehlung lautet: nur LAN oder VPN, keine Portweiterleitung. Die Beispiel-Umgebungsdatei sagt, dass PAPERLESS_URL nötig ist, wenn du Paperless auf einer öffentlichen Domain erreichbar machst, und erwähnt einen Reverse Proxy [11]; der Reverse-Proxy-Guide unter „Passt dazu“ erklärt den Aufbau. Die Doku rät zu einem eigenen Alltagskonto statt der Arbeit als Superuser [1].
11. Was der Exporter tut. document_exporter schreibt deine Dokumente, Vorschaubilder und eine manifest.json mit dem Datenbankinhalt in einen Ordner und aktualisiert einen vorhandenen Export schrittweise [3]. Im Compose-Setup ist das Ziel ../export der Host-Ordner ./export [3][10]. Nützliche Optionen: -d entfernt auch Dateien gelöschter Dokumente, -z schreibt ein Zip, --data-only exportiert nur die Datenbank, und --passphrase verschlüsselt bestimmte Felder, mit der Warnung, dass ein verlorenes Passwort den Export unimportierbar macht [3]. API-Tokens werden nicht exportiert [3]. Die Doku rät, Backups zu machen, während Paperless nichts verarbeitet [3]. Im Cronjob nimmst du docker compose exec -T webserver document_exporter ../export [3].
12. Was der Exporter nicht tut. Ein Export lässt sich nur in dieselbe Paperless-Version importieren [3]. Der Importer verlangt eine völlig leere Installation [3]. Die Alternative sind Sicherungen der Docker-Volumes: Die Doku nennt paperless_media, paperless_data und paperless_pgdata [3]. Unsere Einschätzung: Mach den Export zum Hauptbackup und kopiere den Export-Ordner mit einem Werkzeug, das Versionen und Verschlüsselung kann; unser Guide zu restic und Borg unter „Passt dazu“ behandelt das. Eine Kopie neben dem Server ist eine Kopie. Warum du mehr brauchst, erklärt der 3-2-1-Guide.
13. Aufbewahrung ist nicht unser Thema. Die empfohlene Arbeitsweise von Paperless behält ein Papieroriginal nur für Dokumente, die du in physischer Form brauchst, etwa Verträge und Zertifikate, und nummeriert sie mit einer Archivseriennummer [5]. Welche Dokumente du wegwerfen darfst und wie lange du welche aufbewahren musst, ist eine Rechts- und Steuerfrage. Frag eine Steuerberatung oder die zuständige Stelle. Wir machen dazu keine Aussage.

Ein Homelab-Beispiel

Das ist ein allgemeines Setup für deinen eigenen Linux-Server, kein Bericht über unseren. Zu Paperless-ngx oder Scannern im Bytearium-Homelab machen wir keine Aussage. Angenommen ist ein Ordner /srv/paperless auf dem Host.

Hole die drei Dateien des Releases v3.3.4, die die Doku verlangt [1]:

mkdir -p /srv/paperless/consume /srv/paperless/export && cd /srv/paperless
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/v3.3.4/docker/compose/docker-compose.postgres.yml
curl -fsSLo docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/v3.3.4/docker/compose/docker-compose.env
curl -fsSLo .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/v3.3.4/docker/compose/.env

Ändere in docker-compose.yml die Zeile image: ghcr.io/paperless-ngx/paperless-ngx:latest in image: ghcr.io/paperless-ngx/paperless-ngx:3.3.4 [10]. Setze in docker-compose.env mindestens:

USERMAP_UID=1000
USERMAP_GID=1000
PAPERLESS_SECRET_KEY=<Ausgabe von: python3 -c "import secrets; print(secrets.token_urlsafe(64))">
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
PAPERLESS_CONSUMER_RECURSIVE=true

Den Schlüssel-Befehl liefert der Kommentar der Env-Datei [11]. Führe dann docker compose pull und docker compose up -d aus. Öffne http://<Server>:8000 aus deinem Netz und lege auf Nachfrage den Superuser an [1].

Lass den Scanner nach /srv/paperless/consume schreiben, zum Beispiel über eine Samba-Freigabe auf dem Host, die der Scanner erreicht. Richte am Scanner ein Profil ein: PDF, beidseitig an, leere Seiten überspringen an und der Freigabepfad mit einem eigenen Benutzer, der nur dort schreiben darf. Scanne drei Probebriefe und prüfe Textsuche, OCR-Sprache und die Daten, die Paperless erkennt.

Backup, als nächtlicher Job auf dem Host:

cd /srv/paperless && docker compose exec -T webserver document_exporter ../export --no-progress-bar

Kopiere /srv/paperless/export danach auf eine zweite Platte und außer Haus, mit restic oder Borg. Bewahre docker-compose.env (sie enthält den geheimen Schlüssel) und ein etwaiges Export-Passwort an einem Ort auf, der weder der Server noch dasselbe Backup-Repository ist.

Probe die Wiederherstellung: Lege auf einem zweiten Rechner denselben Ordner an, nimm denselben Image-Tag, starte mit docker compose up -d, kopiere den Export-Ordner nach ./export und führe docker compose exec webserver document_importer ../export aus [3]. Suche nach drei Dokumenten, die du kennst, und öffne sie. Erzeuge danach neue API-Tokens, denn Exporte enthalten sie nicht [3].

Prüfliste

• Prüfe im Datenblatt, ob der Scanner in einem Durchgang beidseitig scannt, wie viele Blatt der Einzug fasst und ob er ein Netzwerkziel bietet, das du nutzen kannst.
• Frage beim Hersteller nach oder teste, welche SMB-Version der Scanner spricht, und schalte SMB1 nie auf dem Rechner ein, der deine Dokumente hält.
• Setze PAPERLESS_OCR_LANGUAGE auf deu+eng oder deine eigene Mischung und setze PAPERLESS_SECRET_KEY vor dem ersten Start.
• Nagle den Image-Tag auf eine volle Version fest und bestätige ihn mit einem einzigen docker pull.
• Binde ./consume als Bind Mount ein, setze USERMAP_UID und USERMAP_GID und aktiviere Polling, wenn der Ordner auf einer Netzfreigabe liegt.
• Halte Paperless nur aus dem LAN oder per VPN erreichbar.
• Führe document_exporter nach Zeitplan aus und kopiere den Export mit Versionen und Verschlüsselung außer Haus.
• Bewahre geheimen Schlüssel und Export-Passwort getrennt von Server und Backup-Repository auf.
• Spiele den Export in eine leere zweite Installation derselben Version zurück und notiere Datum und Ergebnis.
• Frage eine Steuerberatung, wie lange du welche Dokumente aufbewahren musst, bevor du Papier wegwirfst.