Paperless-ngx mit Docker: papierloses Büro mit OCR
Paperless-ngx als Docker-Stack mit PostgreSQL, Tika und Gotenberg betreiben: deutsche OCR, Consume-Ordner, automatische Zuordnung, Reverse-Proxy sowie Backup und Wiederherstellung per Exporter, getestet mit Version 3.3.1.
Geprüft am 14.10.2026 · für Paperless-ngx 3.3.1
WerbelinksMit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu
Paperless-ngx ist ein quelloffenes Dokumentenmanagement-System für das papierlose Büro. Gescannte Rechnungen, Verträge und Briefe landen in einem Eingangsordner, Paperless-ngx erkennt den Text per OCR (Texterkennung), macht ihn durchsuchbar und ordnet Tags, Korrespondenten und Dokumenttypen zu. Diese Anleitung richtet den offiziellen Docker-Stack mit PostgreSQL, Tika und Gotenberg ein, stellt die OCR auf Deutsch und sichert die Daten mit dem Exporter. Alle Schritte liefen im Test mit Paperless-ngx 3.3.1.
Voraussetzungen
- Server: Linux mit Docker Engine und Compose-Plugin, zum Beispiel Debian 12 oder Ubuntu 24.04. Die Images gibt es für amd64 und arm64.
- CPU und RAM: 2 Kerne und 4 GB RAM. Im Test belegte der Stack nach einem OCR-Lauf rund 950 MB, davon Paperless-ngx etwa 730 MB und Tika 170 MB. Mehr Kerne beschleunigen die OCR, eine GPU ist nicht nötig.
- Speicher: rund 3 GB für die Images, dazu je Dokument Original, Archiv-PDF und Vorschaubild. Planen Sie mindestens das Doppelte Ihres Papierarchivs als PDF.
- Netz: Port 8000 im LAN. Für Zugriff von außen eine Domain und einen Reverse-Proxy mit HTTPS.
Schritt 1: Projektordner anlegen und Vorlagen laden
Paperless-ngx stellt mehrere Compose-Vorlagen bereit. Die Variante mit PostgreSQL, Tika und Gotenberg verarbeitet zusätzlich Office-Dateien und E-Mails, deshalb nutzt diese Anleitung sie. Laden Sie die drei Dateien in einen eigenen Ordner:
sudo mkdir -p /opt/paperless
sudo chown $USER: /opt/paperless
cd /opt/paperless
BASE=https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose
curl -fsSL -o docker-compose.yml $BASE/docker-compose.postgres-tika.yml
curl -fsSL -O $BASE/docker-compose.env
curl -fsSL -O $BASE/.env
mkdir -p consume exportDie Datei .env enthält nur COMPOSE_PROJECT_NAME=paperless und legt damit den Projektnamen fest. Das offizielle Installationsskript install-paperless-ngx.sh erledigt dasselbe interaktiv; der manuelle Weg zeigt Ihnen aber genau, was eingerichtet wird.
Verifizieren: ls -A /opt/paperless zeigt .env, docker-compose.env, docker-compose.yml, consume und export.
Schritt 2: docker-compose.yml prüfen und anpassen
Die Vorlage startet fünf Dienste. Nur der Webserver veröffentlicht einen Port, alle anderen sprechen intern im Compose-Netz miteinander:
| Dienst | Image (Vorlage, Stand 14.10.2026) | Aufgabe |
|---|---|---|
| webserver | ghcr.io/paperless-ngx/paperless-ngx:latest | Weboberfläche, OCR, Verarbeitung, Port 8000 |
| db | postgres:18 | Datenbank, Volume pgdata unter /var/lib/postgresql |
| broker | valkey/valkey:9-alpine | Aufgabenwarteschlange (Redis-kompatibel) |
| tika | apache/tika:3.3.1.0 | Textextraktion aus Office-Dateien |
| gotenberg | gotenberg/gotenberg:8.37 | Umwandlung von Office und E-Mail nach PDF |
Zwei Änderungen empfehlen sich. Erstens schreiben Sie die Paperless-Version fest, denn latest zieht beim nächsten pull auch eine neue Hauptversion. Zweitens ersetzen Sie das Vorlagen-Passwort paperless der Datenbank. Die geänderten Zeilen:
db:
image: docker.io/library/postgres:18
environment:
POSTGRES_DB: paperless
POSTGRES_USER: paperless
POSTGRES_PASSWORD: ${DB_PASSWORD}
webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:3.3.1
environment:
PAPERLESS_DBPASS: ${DB_PASSWORD}
# übrige Zeilen der Vorlage unverändertDas Passwort tragen Sie in die Datei .env ein, Compose setzt es an beiden Stellen ein:
echo "DB_PASSWORD=$(openssl rand -hex 16)" >> .envVerifizieren: docker compose config | grep -E "image:|POSTGRES_PASSWORD|PAPERLESS_DBPASS" zeigt das feste Tag 3.3.1 und zweimal dasselbe zufällige Passwort.
Schritt 3: docker-compose.env für deutschen Betrieb einstellen
Die Datei docker-compose.env steuert Paperless-ngx selbst. PAPERLESS_SECRET_KEY ist Pflicht; in der Vorlage steht dort change-me. Erzeugen Sie einen eigenen Schlüssel:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"
id -u; id -gTragen Sie die Werte so ein (Kommentarzeichen entfernen):
USERMAP_UID=1000
USERMAP_GID=1000
PAPERLESS_SECRET_KEY=IHR-ERZEUGTER-SCHLÜSSEL
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu
# nur bei Zugriff über eine Domain:
# PAPERLESS_URL=https://paperless.example.dePAPERLESS_OCR_LANGUAGE erwartet den Tesseract-Code deu, nicht de. Das Image bringt Englisch, Deutsch, Italienisch, Spanisch und Französisch mit; weitere Sprachen ergänzen Sie mit PAPERLESS_OCR_LANGUAGES. USERMAP_UID und USERMAP_GID sorgen dafür, dass Dateien in consume und export Ihrem Benutzer gehören.
Verifizieren: grep -E "^(PAPERLESS_SECRET_KEY|PAPERLESS_OCR_LANGUAGE)" docker-compose.env zeigt deu und einen langen eigenen Schlüssel statt change-me.
Schritt 4: Stack starten und Administrator anlegen
docker compose pull
docker compose up -d
docker compose psBeim ersten Start legt Paperless-ngx das Datenbankschema an. Im Test war der Webserver nach gut einer Minute healthy. Legen Sie dann den Administrator an:
docker compose run --rm webserver createsuperuserMelden Sie sich anschließend unter http://SERVER-IP:8000 an. Die Oberfläche folgt der Browsersprache und erscheint damit auf Deutsch.
Verifizieren: docker compose ps zeigt fünf Dienste mit Up, den Webserver mit (healthy), und curl -I http://127.0.0.1:8000/accounts/login/ liefert HTTP/1.1 200 OK. Unten links in der Seitenleiste steht „Paperless-ngx v3.3.1“.
Schritt 5: Dokumente über den Consume-Ordner importieren
Alles, was im Ordner consume landet, liest Paperless-ngx ein, erkennt den Text und entfernt die Datei danach aus dem Ordner:
cp ~/scans/rechnung-2026-1014.pdf /opt/paperless/consume/In der Praxis befüllt ein Netzwerkscanner den Ordner per SMB-Freigabe, oder Paperless-ngx ruft Anhänge aus einem Postfach ab (Verwaltung, E-Mail). Einzelne Dateien ziehen Sie auch direkt in die Weboberfläche. Im Test war eine einseitige PDF-Rechnung nach weniger als einer Minute importiert.
Verifizieren: Die Datei ist aus consume verschwunden, unter „Dokumente“ erscheint sie mit Vorschaubild, und der Reiter „Inhalt“ der Detailansicht zeigt den erkannten Text mit korrekten Umlauten.
Schritt 6: Tags, Korrespondenten und automatische Zuordnung
Tags, Korrespondenten, Dokumenttypen und Speicherpfade haben je ein Zuordnungsverfahren:
- Automatisch: ein lernendes Modell, das aus Ihren bereits sortierten Dokumenten lernt. Es braucht dafür einige korrekt zugeordnete Dokumente je Kategorie.
- Exakt, Regulärer Ausdruck, Ungenau: feste Regeln über eine genaue Wortfolge, ein Muster oder eine unscharfe Teilübereinstimmung.
- Alle Wörter, Irgendein Wort: mehrere Begriffe müssen alle oder mindestens einer vorkommen.
Legen Sie für Ihre wichtigsten Absender zuerst feste Regeln an, etwa Korrespondent „Musterfirma GmbH“ mit dem Begriff Musterfirma. Für komplexere Abläufe (Tag setzen, Speicherpfad wählen, Benachrichtigung) gibt es unter „Arbeitsabläufe“ regelbasierte Workflows.
Verifizieren: Ein neu importiertes Dokument mit dem Regelbegriff im Text bekommt den Korrespondenten oder Tag ohne Ihr Zutun.
Schritt 7: Zugriff über Reverse-Proxy und HTTPS
Port 8000 gehört nicht ungeschützt ins Internet. Für Zugriff über eine Domain setzen Sie PAPERLESS_URL=https://paperless.example.de in docker-compose.env, binden den Port nur an localhost und schalten einen Proxy davor:
ports:
- "127.0.0.1:8000:8000"server {
listen 443 ssl;
server_name paperless.example.de;
# ssl_certificate und ssl_certificate_key eintragen
client_max_body_size 100M;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}client_max_body_size erlaubt Uploads großer PDFs über die Weboberfläche. Danach docker compose up -d ausführen. Der Test lief über einen HTTPS-Proxy mit gesetztem PAPERLESS_URL; Anmeldung und Bedienung funktionierten ohne CSRF-Fehler. Mehr zu Nginx: Nginx als Reverse-Proxy mit TLS einrichten.
Verifizieren: curl -I https://paperless.example.de/accounts/login/ liefert 200, die Anmeldung im Browser klappt ohne „CSRF verification failed“, und ss -tlnp | grep 8000 zeigt nur 127.0.0.1:8000.
Schritt 8: Backup mit dem Exporter und Wiederherstellung
Ein reiner Datenbank-Dump reicht nicht, denn die Dokumente liegen im Volume media. Der document_exporter schreibt Datenbankinhalt, Einstellungen, Originale, Archiv-PDFs und Vorschaubilder in den Ordner export. -c vergleicht Prüfsummen, -d entfernt im Export Dateien, die es in Paperless-ngx nicht mehr gibt:
cd /opt/paperless
docker compose exec -T webserver document_exporter ../export -c -d --no-progress-bar
ls exportIm Test enthielt export danach manifest.json, metadata.json sowie Original, Archiv-PDF und Vorschaubild der Rechnung. Kopieren Sie den Ordner regelmäßig auf ein anderes System, etwa per rsync in einem nächtlichen Cronjob. API-Tokens sind nicht im Export enthalten.
Wiederhergestellt wird in eine leere Instanz derselben Paperless-Version, denn der Export bildet das Datenbankschema genau ab. Im Test wurden alle Volumes gelöscht, der Stack neu gestartet und der Export eingespielt:
docker compose down -v
docker compose up -d
docker compose exec -T webserver document_importer ../export --no-progress-barDanach waren die Rechnung samt erkanntem Text, Volltextsuche und Benutzer admin wieder vorhanden. down -v löscht alle Daten; verwenden Sie das nur für eine Testinstanz oder einen echten Neuaufbau. Zur Prüfroutine: Backup-Restore-Test als feste Routine etablieren.
Verifizieren: Nach dem Import zeigt „Dokumente“ dieselbe Anzahl wie vorher, eine Suche nach einem Wort aus dem Dokumenttext findet es, und die Datei lässt sich herunterladen.
Schritt 9: Updates einspielen
Lesen Sie vor jedem Update die Release Notes und erstellen Sie einen Export wie in Schritt 8. Dann ändern Sie das Tag in docker-compose.yml, etwa von 3.3.1 auf die nächste Version, und starten neu:
docker compose down
docker compose pull
docker compose up -d
docker compose logs --tail 50 webserverDatenbankmigrationen laufen beim Start automatisch. Lassen Sie das PostgreSQL-Tag fest auf 18: Eine neue PostgreSQL-Hauptversion lässt sich nicht einfach per pull einspielen, die Daten müssen per Dump oder pg_upgrade migriert werden. Bestandsinstallationen mit Version 2 lesen vor dem Wechsel auf Version 3 die offizielle Migrationsanleitung.
Verifizieren: docker compose ps zeigt den Webserver wieder als (healthy), und die Versionsnummer unten links in der Seitenleiste ist gestiegen.
Typische Fehler
- Webserver startet nicht, Log nennt den Secret Key:
PAPERLESS_SECRET_KEYfehlt oder steht noch aufchange-me. - OCR liefert wenig oder falschen Text:
PAPERLESS_OCR_LANGUAGE=deuprüfen, nichtde. Schlechte Scans mit mindestens 300 dpi wiederholen. - Dateien bleiben in consume liegen: Rechte stimmen nicht.
USERMAP_UIDundUSERMAP_GIDauf Ihren Benutzer setzen,docker compose logs webserverprüfen. - Office-Dateien werden abgelehnt: Tika oder Gotenberg läuft nicht, oder es wurde die Vorlage ohne Tika genutzt.
- „CSRF verification failed“ hinter dem Proxy:
PAPERLESS_URLfehlt oder weicht von der aufgerufenen Adresse ab. - Datenbank startet nach Image-Wechsel nicht: Das PostgreSQL-Tag wurde auf eine neue Hauptversion geändert. Zurück auf das alte Tag und regulär migrieren.
Häufige Fragen
Reicht SQLite statt PostgreSQL?
Für Einzelpersonen mit wenigen tausend Dokumenten ja, dafür gibt es eine eigene Vorlage. Für mehrere Benutzer und größere Archive ist PostgreSQL die robustere Wahl.
Ist Paperless-ngx revisionssicher im Sinne der GoBD?
Nicht von sich aus. Paperless-ngx speichert die Originale unverändert, bringt aber keine Verfahrensdokumentation und keine unveränderbare Ablage mit. Klären Sie den Einsatz für steuerrelevante Belege mit Ihrer Steuerberatung.
Wie viel Speicher brauche ich?
Je Dokument liegen Original, Archiv-PDF und Vorschaubild ab. Als grobe Planung reicht die doppelte Größe Ihrer gescannten PDFs plus Platz für den Export.
Wie kommen Scans automatisch in Paperless-ngx?
Über den Ordner consume: Geben Sie ihn per SMB frei und stellen Sie am Scanner „Scan to Folder“ darauf ein, oder lassen Sie Paperless-ngx ein Postfach abrufen.
Fazit
Mit der offiziellen Vorlage steht Paperless-ngx in rund einer Viertelstunde. Entscheidend sind ein eigener Secret Key, die OCR-Sprache deu, ein festes Versions-Tag und ein regelmäßiger Export, dessen Wiederherstellung Sie einmal ausprobiert haben. Für Zugriff von außen gehört ein Reverse-Proxy mit HTTPS davor.
