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 bauen Sie 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 haben Sie einen Eingangsordner, in den Sie Scans legen, und ein durchsuchbares Web-Archiv Ihrer 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: Sie legen eine Datei in den Consume-Ordner (oder laden 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 Ihrer 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 erkennen Sie ü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 brauchen Sie nur, wenn Sie Word-, Excel- oder E-Mail-Dateien verarbeiten wollen. Für reine PDF- und Bild-Scans können Sie sie weglassen. In dieser Anleitung sind sie enthalten, 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, installieren Sie es am schnellsten über das offizielle Skript und fügen Ihren 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

Legen Sie ein Verzeichnis für den Stack an. Die Anleitung nutzt Bind-Mounts unter /opt/paperless, damit Konfiguration und Daten an einem Ort liegen.

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: Ihr 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 müssen Sie selbst setzen: einen geheimen Schlüssel und die Zugangsdaten für den ersten Admin. Erzeugen Sie zuerst einen zufälligen SECRET_KEY:

openssl rand -base64 48

Legen Sie dann im Projektordner eine Datei .env an und tragen Sie Ihre Werte ein. Ersetzen Sie den Beispiel-Schlüssel und das Passwort durch eigene, sichere Werte:

PAPERLESS_SECRET_KEY=hier-den-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 sollten Sie nach dem ersten Login dennoch in der Weboberfläche ändern.
PAPERLESS_URL setzen Sie auf die Adresse, unter der Sie Paperless erreichen: die LAN-IP des Servers oder später Ihre Domain hinter einem Reverse Proxy. Sie ist wichtig, damit Login und Sicherheitsprüfungen funktionieren.
PAPERLESS_OCR_LANGUAGE=deu aktiviert die deutsche Texterkennung. Mehrere Sprachen geben Sie mit + an, etwa deu+eng für gemischte Dokumente.

Schritt 3: docker-compose.yml erstellen

Legen Sie im Projektordner die Datei docker-compose.yml mit folgendem Inhalt an. Sie orientiert sich am offiziellen Beispiel aus der Paperless-ngx-Doku und nutzt Ihre .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_DBENGINE: postgresql
      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

Wichtig seit Paperless-ngx 3.0: PAPERLESS_DBENGINE: postgresql muss ausdrücklich gesetzt sein. Früher hat Paperless PostgreSQL schon an PAPERLESS_DBHOST erkannt, ohne die neue Variable arbeitet es mit SQLite und die PostgreSQL-Datenbank bleibt ungenutzt.

Achten Sie beim Einfügen auf die Einrückung: YAML ist empfindlich gegenüber Tabs und falschen Leerzeichen. Verwenden Sie ausschließlich Leerzeichen.

Schritt 4: Stack starten

Starten Sie 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 beobachten Sie mit:

docker compose logs -f webserver

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

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

Haben Sie in der .env bereits PAPERLESS_ADMIN_USER und PAPERLESS_ADMIN_PASSWORD gesetzt, wurde der Superuser automatisch erstellt; diesen Schritt können Sie überspringen. Möchten Sie den Admin lieber manuell anlegen oder ein weiteres Admin-Konto erstellen, geht das so:

docker compose run --rm webserver createsuperuser

Sie werden 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

Rufen Sie im Browser die Adresse Ihres Servers mit Port 8000 auf, zum Beispiel:

http://192.168.1.50:8000

Melden Sie sich mit den Admin-Zugangsdaten an. Sie landen im Dashboard von Paperless-ngx. Falls Sie das Passwort über die .env gesetzt haben, ändern Sie es jetzt über das Benutzermenü oben rechts, denn die Variable bleibt sonst im Klartext in der Datei stehen.

Schritt 7: Erstes Dokument verarbeiten lassen

Jetzt der eigentliche Test. Kopieren Sie 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. Klicken Sie es an: Sie sehen das archivierte PDF, den erkannten Volltext und die ausgelesenen Metadaten. Über die Suchleiste finden Sie das Dokument jetzt anhand beliebiger Wörter aus dem Text.

Tipp für den Alltag: Statt Dateien per SSH zu kopieren, geben Sie den Consume-Ordner per Samba/NFS im Netzwerk frei oder laden 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: Setzen Sie 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 laden Sie die neuen Images und starten 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 sollten Sie das Image-Tag pinnen, statt :latest zu nutzen; so kontrollieren Sie 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äumen Sie mit docker image prune auf.

Bestehende Installation auf Version 3 aktualisieren: Der Sprung auf 3.x ist nur von Version 2.20.15 aus vorgesehen. Laufen Sie auf einer älteren 2.x, aktualisieren Sie zuerst auf ghcr.io/paperless-ngx/paperless-ngx:2.20.15 und erst danach auf 3.x. Vor dem Update ergänzen Sie PAPERLESS_DBENGINE: postgresql im webserver-Dienst, sonst startet Paperless mit einer leeren SQLite-Datenbank. Weitere Änderungen laut Migrationsleitfaden: PAPERLESS_SECRET_KEY ist jetzt Pflicht, doppelte Dokumente werden standardmäßig nicht mehr abgewiesen (wieder aktivierbar mit PAPERLESS_CONSUMER_DELETE_DUPLICATES=true), die Variablen PAPERLESS_OCR_MODE=skip und PAPERLESS_OCR_SKIP_ARCHIVE_FILE wurden durch PAPERLESS_OCR_MODE=auto und PAPERLESS_ARCHIVE_FILE_GENERATION ersetzt, und der Suchindex wird beim ersten Start automatisch neu aufgebaut. Eine Dokumentenverschlüsselung aus paperless-ng müssen Sie vorher mit decrypt_documents aufheben.

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 sollten Sie die Volume-Ordner sichern. Für ein konsistentes Backup der Datenbank stoppen Sie den Stack kurz und sichern dann die Ordner data, media, pgdata und Ihre .env:

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

Nehmen Sie diese Sicherung in Ihre 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üfen Sie, ob PAPERLESS_OCR_LANGUAGE=deu gesetzt ist und Sie den webserver-Container danach neu gestartet haben.
Dokumente bleiben im Consume-Ordner liegen: Prüfen Sie 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: Stellen Sie sicher, dass die Ordner Ihrem Benutzer gehören und Docker darauf schreiben darf.
Office-Dateien werden nicht verarbeitet: Vergewissern Sie sich, 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 haben Sie 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, scannen Sie 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, Migrationsleitfaden v3