Rechnungen, Verträge, Behördenpost, Garantiebelege: Wer Papier nur ablegt, sucht später ewig. Paperless-ngx löst das Problem, indem es jedes Dokument einscannt, per OCR volltextdurchsuchbar macht und automatisch verschlagwortet. In dieser Anleitung baust du Paperless-ngx als sauberen Docker-Compose-Stack auf einem Debian- oder Ubuntu-Server auf: mit PostgreSQL als Datenbank, Redis als Task-Broker und Tesseract-OCR mit deutschem Sprachpaket. Am Ende hast du einen Eingangsordner, in den du Scans legst, und ein durchsuchbares Web-Archiv deiner Dokumente.

Was ist Paperless-ngx und warum lohnt es sich?

Paperless-ngx ist ein quelloffenes Dokumentenmanagement-System (DMS), das aus eingescannten PDFs, Bildern und Office-Dateien ein durchsuchbares, getaggtes Archiv erzeugt. Es ist die aktiv gepflegte Weiterentwicklung der eingestellten Projekte Paperless und Paperless-ng und wird von einer großen Community betreut.

Der Kern-Workflow ist denkbar einfach: Du legst eine Datei in den Consume-Ordner (oder lädst sie über die Weboberfläche hoch), und Paperless-ngx erkennt automatisch den Text per OCR, erzeugt ein durchsuchbares PDF/A, liest Datum und Korrespondent aus und schlägt passende Tags vor. Über selbst definierte Regeln lassen sich Dokumente automatisch sortieren: Alles von deiner Krankenkasse bekommt das Tag Gesundheit, jede Datei mit "Rechnung" im Text landet im passenden Dokumenttyp.

Für deutsche Dokumente ist entscheidend, dass die OCR die richtige Sprache nutzt. Tesseract bringt im offiziellen Image bereits viele Sprachpakete mit, deutsche Texte erkennst du über die Variable PAPERLESS_OCR_LANGUAGE=deu sauber inklusive Umlauten.

Architektur des Stacks

Paperless-ngx ist kein einzelner Container, sondern besteht aus mehreren Diensten, die zusammenarbeiten:

webserver (ghcr.io/paperless-ngx/paperless-ngx) – die eigentliche Anwendung mit Weboberfläche, OCR und Aufgaben-Worker. Erreichbar auf Port 8000.
db (postgres:16) – PostgreSQL als Datenbank. Robuster als die mitgelieferte SQLite, klar empfohlen für den Dauerbetrieb.
broker (redis:7) – Redis als Nachrichten-Broker für die Hintergrund-Tasks (OCR, Indexierung).
gotenberg (optional) – wandelt Office-Dokumente und E-Mails in PDF um, bevor sie verarbeitet werden.
tika (optional) – Apache Tika extrahiert Inhalte und Metadaten aus diesen Office-Formaten.

Gotenberg und Tika brauchst du nur, wenn du Word-, Excel- oder E-Mail-Dateien verarbeiten willst. Für reine PDF- und Bild-Scans kannst du sie weglassen. In dieser Anleitung nehmen wir sie mit auf, da sie nur wenig Ressourcen kosten und den Funktionsumfang deutlich erweitern.

Voraussetzungen

Ein Server mit Debian 12 oder Ubuntu 22.04/24.04 (physisch, VM oder LXC). Auch ein anderer Linux-Host mit Docker funktioniert.
Docker Engine und das Compose-Plugin installiert. Prüfen mit docker --version und docker compose version.
Mindestens 2 GB RAM, besser 4 GB – OCR ist rechenintensiv, vor allem bei mehrseitigen Scans.
Etwas freier Speicherplatz für Datenbank, Originaldateien und die archivierten PDF/A-Versionen.
Port 8000 auf dem Host frei (oder ein alternativer Host-Port).
Ein Konto mit sudo-Rechten und einen Terminal-Zugang per SSH.

Falls Docker noch fehlt, installierst du es am schnellsten über das offizielle Skript und fügst deinen Benutzer der Gruppe docker hinzu:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# danach einmal ab- und wieder anmelden

Schritt 1: Projektordner und Volumes anlegen

Lege ein Verzeichnis für den Stack an. Wir nutzen bind-mounts unter /opt/paperless, damit du Konfiguration und Daten an einem Ort hast.

sudo mkdir -p /opt/paperless
sudo chown $USER:$USER /opt/paperless
cd /opt/paperless
mkdir -p data media consume export pgdata redisdata

Die Ordner haben feste Aufgaben:

consume – dein Eingangsordner. Alles, was hier landet, wird automatisch verarbeitet.
media – die fertig verarbeiteten Dokumente (Original plus archiviertes PDF/A).
data – Index, Klassifikator und interne Daten von Paperless.
export – Zielordner für manuelle Exporte und Backups des Dokumentenbestands.
pgdata / redisdata – persistente Daten von Datenbank und Broker.

Schritt 2: Umgebungsvariablen in der .env festlegen

Zwei Werte musst du selbst setzen: einen geheimen Schlüssel und die Zugangsdaten für den ersten Admin. Erzeuge zuerst einen zufälligen SECRET_KEY:

openssl rand -base64 48

Lege dann im Projektordner eine Datei .env an und trage deine Werte ein. Ersetze den Beispiel-Schlüssel und das Passwort durch eigene, sichere Werte:

PAPERLESS_SECRET_KEY=hier-deinen-generierten-schluessel-einsetzen
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=BitteSofortAendern!
PAPERLESS_OCR_LANGUAGE=deu
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_URL=http://192.168.1.50:8000
POSTGRES_PASSWORD=einSicheresDbPasswort

Hinweise dazu:

PAPERLESS_ADMIN_USER und PAPERLESS_ADMIN_PASSWORD erzeugen beim ersten Start automatisch einen Superuser. Das Passwort solltest du nach dem ersten Login dennoch in der Weboberfläche ändern.
PAPERLESS_URL setzt du auf die Adresse, unter der du Paperless erreichst – die LAN-IP des Servers oder später deine Domain hinter einem Reverse Proxy. Sie ist wichtig, damit Login und Sicherheitsprüfungen funktionieren.
PAPERLESS_OCR_LANGUAGE=deu aktiviert die deutsche Texterkennung. Mehrere Sprachen gibst du mit + an, etwa deu+eng für gemischte Dokumente.

Schritt 3: docker-compose.yml erstellen

Lege im Projektordner die Datei docker-compose.yml mit folgendem Inhalt an. Sie orientiert sich am offiziellen Beispiel aus der Paperless-ngx-Doku und nutzt deine .env für die Geheimnisse:

services:
  broker:
    image: redis:7
    restart: unless-stopped
    volumes:
      - ./redisdata:/data

  db:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: ${POSTGRES_PASSWORD}
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}
      PAPERLESS_OCR_LANGUAGE: ${PAPERLESS_OCR_LANGUAGE}
      PAPERLESS_TIME_ZONE: ${PAPERLESS_TIME_ZONE}
      PAPERLESS_URL: ${PAPERLESS_URL}
      PAPERLESS_ADMIN_USER: ${PAPERLESS_ADMIN_USER}
      PAPERLESS_ADMIN_PASSWORD: ${PAPERLESS_ADMIN_PASSWORD}

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:latest
    restart: unless-stopped

Achte beim Einfügen auf die Einrückung – YAML ist empfindlich gegenüber Tabs und falschen Leerzeichen. Verwende ausschließlich Leerzeichen.

Schritt 4: Stack starten

Starte alle Container im Hintergrund:

docker compose up -d

Beim ersten Start lädt Docker die Images herunter und Paperless richtet die Datenbank ein. Das kann ein paar Minuten dauern. Den Fortschritt beobachtest du mit:

docker compose logs -f webserver

Sobald in den Logs der laufende Webserver erscheint, ist die Anwendung bereit. Mit Strg+C beendest du nur die Log-Ausgabe, die Container laufen weiter.

Schritt 5: Ersten Admin anlegen (falls nötig)

Hast du in der .env bereits PAPERLESS_ADMIN_USER und PAPERLESS_ADMIN_PASSWORD gesetzt, wurde der Superuser automatisch erstellt – diesen Schritt kannst du überspringen. Möchtest du den Admin lieber manuell anlegen oder ein weiteres Admin-Konto erstellen, geht das so:

docker compose run --rm webserver createsuperuser

Du wirst nach Benutzername, optionaler E-Mail-Adresse und Passwort gefragt. Danach steht das Konto für den Login bereit.

Schritt 6: Weboberfläche öffnen und einloggen

Rufe im Browser die Adresse deines Servers mit Port 8000 auf, zum Beispiel:

http://192.168.1.50:8000

Melde dich mit den Admin-Zugangsdaten an. Du landest im Dashboard von Paperless-ngx. Falls du das Passwort über die .env gesetzt hast, ändere es jetzt über das Benutzermenü oben rechts – die Variable bleibt sonst im Klartext in der Datei stehen.

Schritt 7: Erstes Dokument verarbeiten lassen

Jetzt der eigentliche Test. Kopiere eine PDF-Datei oder einen Scan in den Consume-Ordner auf dem Server:

cp ~/rechnung-beispiel.pdf /opt/paperless/consume/

Paperless erkennt die neue Datei automatisch, startet die OCR und legt das Dokument an. Nach wenigen Sekunden bis Minuten (je nach Seitenzahl und CPU) erscheint es in der Weboberfläche unter Dokumente. Klicke es an: Du siehst das archivierte PDF, den erkannten Volltext und die ausgelesenen Metadaten. Über die Suchleiste findest du das Dokument jetzt anhand beliebiger Wörter aus dem Text.

Tipp für den Alltag: Statt Dateien per SSH zu kopieren, gibst du den Consume-Ordner per Samba/NFS im Netzwerk frei oder lädst Scans direkt über den Upload-Button der Weboberfläche hoch. Viele Netzwerk-Scanner können automatisch in einen Netzwerkordner scannen – ideal für den papierlosen Workflow.

Schritt 8: Tags, Korrespondenten und Automatik einrichten

Damit Paperless sortiert statt nur ablegt, lohnt sich etwas Vorarbeit unter Einstellungen:

Korrespondenten anlegen (z. B. Krankenkasse, Vermieter, Finanzamt). Paperless lernt mit der Zeit, welche Dokumente zu wem gehören.
Dokumenttypen definieren (Rechnung, Vertrag, Bescheid).
Tags mit Übereinstimmungs-Algorithmus versehen: Setzt du bei einem Tag das Match auf "automatisch", taggt Paperless künftig passende Dokumente von selbst.

Nach einigen manuell zugeordneten Dokumenten greift der Klassifikator und übernimmt die Zuordnung zunehmend selbstständig.

Updates und Wartung

Für ein Update lädst du die neuen Images und startest die Container neu. Aus dem Projektordner heraus:

cd /opt/paperless
docker compose pull
docker compose up -d

Datenbank-Migrationen führt Paperless beim Start automatisch aus. Für den produktiven Betrieb solltest du das Image-Tag pinnen, statt :latest zu nutzen – so kontrollierst du selbst, wann ein größeres Update kommt. Vor jedem Major-Update lohnt ein Blick in die Release Notes auf GitHub, gelegentlich gibt es Breaking Changes. Nicht mehr benötigte alte Images räumst du mit docker image prune auf.

Backup

Sicherbar sind zwei Wege. Am einfachsten ist der eingebaute Export, der den kompletten Dokumentenbestand samt Metadaten in den export-Ordner schreibt:

docker compose exec webserver document_exporter ../export

Zusätzlich solltest du die Volume-Ordner sichern. Für ein konsistentes Backup der Datenbank stoppst du den Stack kurz und sicherst dann die Ordner data, media, pgdata und deine .env:

docker compose stop
tar czf paperless-backup-$(date +%F).tar.gz data media pgdata .env docker-compose.yml
docker compose start

Nimm diese Sicherung in deine reguläre Backup-Routine auf – etwa über ein zweites NAS, eine externe Platte oder ein Cloud-Backup nach der 3-2-1-Regel. Der consume-Ordner muss nicht gesichert werden, er ist nur ein Durchlauf.

Troubleshooting

OCR erkennt Umlaute falsch: Prüfe, ob PAPERLESS_OCR_LANGUAGE=deu gesetzt ist und du den webserver-Container danach neu gestartet hast.
Dokumente bleiben im Consume-Ordner liegen: Schau in docker compose logs -f webserver. Häufig fehlen Schreibrechte auf die Volume-Ordner oder der Redis-Broker ist nicht erreichbar.
Container startet nicht, "permission denied" auf pgdata: Stelle sicher, dass die Ordner deinem Benutzer gehören und Docker darauf schreiben darf.
Office-Dateien werden nicht verarbeitet: Vergewissere dich, dass die Container gotenberg und tika laufen (docker compose ps) und die Tika-Variablen im webserver gesetzt sind.
OCR sehr langsam: Bei wenig RAM kommt der Worker ins Schwitzen. Mehr RAM oder das Begrenzen paralleler Tasks hilft.

Fazit

Mit diesem Compose-Stack hast du Paperless-ngx als vollwertiges Dokumentenmanagement aufgesetzt: PostgreSQL und Redis im Rücken, Tesseract für saubere deutsche OCR und optional Gotenberg plus Tika für Office-Dateien. Der Consume-Ordner macht das System alltagstauglich – einmal eingerichtet, scannst du nur noch in den Ordner, den Rest erledigt Paperless. Wer den Dienst von außen erreichbar machen will, stellt ihm einen Reverse Proxy mit HTTPS voran und passt PAPERLESS_URL entsprechend an. Damit ist der Weg zum papierlosen Büro frei.

Weitere Anleitungen in den Kategorien Docker und Linux.

Quellen: Paperless-ngx Dokumentation, Paperless-ngx auf GitHub