Paperless-ngx ist ein quelloffenes Dokumentenmanagement-System (DMS) für das papierlose Büro. Du wirfst gescannte Belege, Rechnungen und Verträge in einen Ordner, und Paperless-ngx erledigt den Rest: Es erkennt den Text per OCR, macht ihn volltextdurchsuchbar, ordnet automatisch Tags, Korrespondenten und Dokumenttypen zu und legt alles versioniert ab. Diese Anleitung zeigt dir, wie du Paperless-ngx auf einem Linux-Server (Debian 12 oder Ubuntu 24.04) per Docker Compose betreibst – mit OCR auf Deutsch, Office-Unterstützung über Tika und Gotenberg, sauberen Volumes und einem konsistenten Backup. Zielgruppe sind Admins im Mittelstand und ambitionierte Heimserver-Nutzer.

Kurzfassung: Vorlage holen, docker-compose.env mit PAPERLESS_OCR_LANGUAGE=deu anpassen, Stack starten, Superuser anlegen.

docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser

Danach ist die Web-UI unter http://SERVER-IP:8000 erreichbar. Dokumente landen im ./consume-Ordner und werden automatisch verarbeitet.

Voraussetzungen

Paperless-ngx ist ein reines CPU-Workload – eine GPU ist nicht nötig. Eine Mehrkern-CPU beschleunigt die OCR-Verarbeitung, mehr ist hier aber nicht zwingend. Nur die optionale lokale KI der v3.0-Beta wäre potenziell rechenintensiver; für den Produktivbetrieb bleibst du ohnehin bei der Stable-Version.

Server: Linux mit Docker und Docker Compose (Debian 12 oder Ubuntu 24.04). Mehr brauchst du an Software nicht.
RAM: Richtwert ~2 GB, mehr für parallele OCR und Tika empfohlen.
CPU: Mehrkern beschleunigt OCR spürbar, keine GPU erforderlich.
Storage: skaliert mit der Dokumentmenge – pro Dokument fallen Original, Archiv-PDF und Thumbnail an. Plane großzügig.
Optional: eine Domain plus Reverse-Proxy (nginx/Traefik) und HTTPS, falls du Paperless-ngx aus dem Internet erreichbar machen willst.

Falls Docker auf dem Server noch fehlt oder du mit dem Compose-Konzept noch nicht vertraut bist, lies vorab unsere Grundlagen zu Docker Compose und Stacks.

Schritt 1: Verzeichnis und Compose-Vorlage anlegen

Paperless-ngx wird offiziell per Docker Compose betrieben. Du kannst das interaktive Install-Skript nutzen oder – transparenter – die Vorlagen direkt aus dem Repo holen. Wir holen die Variante mit PostgreSQL plus Tika und Gotenberg, weil nur diese auch Office-Dateien (docx/xlsx) und E-Mail-Anhänge verarbeitet.

Lege zuerst ein Projektverzeichnis an und wechsle hinein:

mkdir -p /opt/paperless
cd /opt/paperless

Wer es schnell und geführt mag, nutzt das offizielle interaktive Install-Skript. Es legt Verzeichnis, Compose-Files, .env und Superuser an:

bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Für volle Kontrolle empfehlen wir das manuelle Setup. Hol dir die passende Vorlage und benenne sie um:

curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres-tika.yml
mv docker-compose.postgres-tika.yml docker-compose.yml
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env

Schritt 2: compose.yaml verstehen und anpassen

Die folgende docker-compose.yml entspricht der offiziellen Postgres-plus-Tika-Vorlage und ist copy-paste-fertig. Der Stack besteht aus fünf Services: webserver (Paperless-ngx selbst), broker (Redis), db (PostgreSQL) sowie gotenberg (Office nach PDF) und tika (Volltextextraktion). Nur Port 8000 wird nach außen gemappt; Redis, Postgres, Gotenberg und Tika kommunizieren ausschließlich intern im Compose-Netz.

services:
  broker:
    image: docker.io/library/redis:8
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: BITTE-AENDERN

  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
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBPASS: BITTE-AENDERN
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000

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

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

volumes:
  data:
  media:
  pgdata:
  redisdata:

Ein paar Punkte zum Verständnis:

Image-Tag: ghcr.io/paperless-ngx/paperless-ngx:latest zeigt aktuell auf die Stable-Version v2.20.15. Die v3.0 mit lokaler KI gibt es nur als Tag beta – für Produktion nicht versehentlich darauf wechseln.
Volumes: Die benannten Volumes data, media, pgdata und redisdata sorgen für Persistenz. Besonders wichtig ist media – dort liegen Originale, Archiv-PDFs und Thumbnails.
Bind-Mounts: ./consume ist dein Eingangsordner, ./export das Ziel für Backups. Den lokalen Pfad vor dem Doppelpunkt wählst du frei.
Passwörter: Ersetze beide BITTE-AENDERN durch ein eigenes, identisches Passwort. Auch wenn die DB nicht nach außen exponiert ist, solltest du das Default paperless bewusst ersetzen.

Schritt 3: docker-compose.env für deutschen Betrieb konfigurieren

Die zentrale Konfiguration steckt in docker-compose.env. Für deutschsprachige Dokumente sind zwei Werte entscheidend. Achtung: PAPERLESS_OCR_LANGUAGE erwartet einen Tesseract-Sprachcode (deu), nicht den ISO-Kurzcode de – ein falscher Code führt zu fehlerhafter oder fehlender OCR.

PAPERLESS_OCR_LANGUAGE=deu
PAPERLESS_TIME_ZONE=Europe/Berlin

# Damit der consume-/export-Ordner dem Host-Benutzer gehoert
# (sonst Rechteprobleme). Mit `id -u` und `id -g` ermitteln:
USERMAP_UID=1000
USERMAP_GID=1000

# Nur fuer oeffentlichen Zugriff / Reverse-Proxy noetig:
# PAPERLESS_URL=https://DEINE-DOMAIN.de
# PAPERLESS_SECRET_KEY=DEINE-LANGE-ZUFALLSKETTE

Das offizielle Image bringt die Sprachpakete eng, deu, ita, spa und fra bereits mit. Brauchst du weitere Sprachen, installierst du sie über PAPERLESS_OCR_LANGUAGES nach (Leerzeichen-getrennte Tesseract-Codes).

Schritt 4: Stack starten und Superuser anlegen

Jetzt ziehst du die Images und startest den Stack im Hintergrund:

docker compose pull
docker compose up -d

Beim ersten Start initialisiert Paperless-ngx die Datenbank – das dauert einen Moment. Den Fortschritt siehst du in den Logs:

docker compose logs -f webserver
docker compose ps

Lege anschließend den ersten Administrator an. Interaktiv fragt der Befehl nach Benutzername, optionaler E-Mail und Passwort (mindestens 8 Zeichen):

docker compose run --rm webserver createsuperuser

Für automatisierte Deployments kannst du den Superuser auch nicht-interaktiv per ENV in docker-compose.env anlegen lassen. Das legt den User beim Start an, ändert aber kein bestehendes Passwort und überschreibt vorhandene User nicht:

PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=DEIN-SICHERES-PASSWORT

Ruf nun die Web-UI im Browser auf: http://SERVER-IP:8000 beziehungsweise lokal http://127.0.0.1:8000. Melde dich mit deinem Superuser an.

Schritt 5: Dokumente importieren über den Consume-Ordner

Das Herzstück ist der Consume-Ordner. Alles, was du in ./consume (im Container /usr/src/paperless/consume) ablegst, wird automatisch erkannt, per OCR verarbeitet und in die Bibliothek übernommen. Du kannst Dateien einfach hineinkopieren:

cp ~/scans/rechnung-2026.pdf /opt/paperless/consume/

In der Praxis bestückst du diesen Ordner meist automatisch:

Netzwerkscanner: Scan-to-Folder direkt in das Consume-Verzeichnis (z. B. per SMB/NFS-Freigabe darauf).
E-Mail-Abruf: Paperless-ngx kann Postfächer abrufen und Anhänge importieren (in der Web-UI unter den Mail-Einstellungen konfigurierbar).
Manueller Upload: direkt über die Web-UI per Drag-and-drop.

Nach der Verarbeitung findest du die Dokumente volltextdurchsuchbar in der Oberfläche. Office-Dateien und E-Mails funktionieren nur, weil Tika und Gotenberg laufen und PAPERLESS_TIKA_ENABLED=1 gesetzt ist – deshalb haben wir bewusst die Tika-Variante gewählt.

Schritt 6: Tags, Korrespondenten und automatisches Matching

Damit aus dem Dokumentenstapel ein durchsuchbares Archiv wird, nutzt du Tags, Korrespondenten, Dokumenttypen und Speicherpfade. Jedes dieser Objekte kann ein Matching-Verfahren bekommen, das eingehende Dokumente automatisch zuordnet:

Auto: ein neuronales Netz, das aus bereits korrekt zugeordneten Dokumenten lernt. Es berücksichtigt nur Dokumente ohne Inbox-Tag und trainiert standardmäßig stündlich neu.
Literal / Regular Expression / Fuzzy: regelbasierte Zuordnung über Begriffe, reguläre Ausdrücke oder unscharfen Abgleich.
All / Any: mehrere Begriffe müssen alle bzw. mindestens einer zutreffen.

Wichtig direkt nach dem Setup: Das Auto-Matching kann anfangs noch nichts zuordnen, weil es noch keine Trainingsdaten gibt. Tagge deine ersten Dokumente daher manuell und entferne das Inbox-Tag, sobald sie korrekt sortiert sind. Nach dem nächsten Trainingslauf greift die automatische Zuordnung dann zunehmend.

Schritt 7: Reverse-Proxy und HTTPS

Port 8000 gehört nicht ungeschützt ins Internet. Für externen Zugriff stellst du einen Reverse-Proxy mit HTTPS davor und setzt in docker-compose.env die öffentliche Adresse. Ohne korrektes PAPERLESS_URL kommt es hinter dem Proxy sonst zu Login- und CSRF-Fehlern. Für öffentliche Deployments solltest du außerdem unbedingt einen PAPERLESS_SECRET_KEY setzen:

PAPERLESS_URL=https://paperless.DEINE-DOMAIN.de
PAPERLESS_SECRET_KEY=DEINE-LANGE-ZUFALLSKETTE

Ein minimaler nginx-Reverse-Proxy auf den lokalen Port 8000 sieht so aus:

server {
    listen 443 ssl;
    server_name paperless.DEINE-DOMAIN.de;

    # ssl_certificate / ssl_certificate_key hier eintragen

    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;
    }
}

Schritt 8: Updates einspielen

Der Update-Workflow ist denkbar einfach: neue Images ziehen, Stack neu hochfahren, alte Images aufräumen:

docker compose pull
docker compose up -d
docker image prune

Zwei Stolperfallen: Mit dem Tag latest kann ein docker compose pull jederzeit ein Major-Update ziehen – vorher Changelog lesen und Backup machen, oder gleich einen konkreten Versions-Tag pinnen. Und: Ein Postgres-Major-Upgrade (etwa postgres:17 auf 18) lässt sich nicht einfach in-place durchführen; die Daten müssen migriert werden. Pinne den Postgres-Tag daher bewusst und zieh ihn nicht blind hoch.

Schritt 9: Backup

Ein konsistentes Backup besteht aus drei Teilen: der PostgreSQL-Datenbank, den Dokumentdateien (media: Originale, Archiv, Thumbnails) und den Metadaten (Tags, Korrespondenten, Matching-Regeln). Ein reiner Volume- oder DB-Dump allein ist unvollständig.

Empfohlen ist der document_exporter: Er schreibt alles in ein portables Format inklusive manifest.json – ideal für Migration und Restore. Das Flag -c exportiert nur per Checksumme geänderte Dateien, -d entfernt im Export gelöschte Dateien:

# Dokumente + Metadaten als portabler Export in den ./export-Ordner
docker compose exec -T webserver document_exporter ../export -c -d

Zusätzlich kannst du einen klassischen PostgreSQL-Dump ziehen (der db-Service heißt im Compose db):

docker compose exec -T db pg_dump -U paperless paperless > paperless-db.sql

Den Export spielst du bei Bedarf so wieder ein:

docker compose exec -T webserver document_importer ../export

Sichere den Inhalt von ./export anschließend regelmäßig auf ein externes Ziel (z. B. per rsync oder Backup-Tool).

Troubleshooting

OCR liefert keinen oder schlechten Text: Prüfe, ob PAPERLESS_OCR_LANGUAGE=deu (Tesseract-Code) gesetzt ist – nicht de. Für weitere Sprachen PAPERLESS_OCR_LANGUAGES ergänzen.
Office-Dokumente/E-Mails werden nicht verarbeitet: Du nutzt vermutlich die schlanke Variante. Verwende das Tika-Compose-File und setze PAPERLESS_TIKA_ENABLED=1.
Dateien im consume-Ordner werden nicht eingelesen oder gehören root: USERMAP_UID/USERMAP_GID auf den Host-Benutzer setzen (per id -u / id -g ermitteln) und Container neu starten.
Login- oder CSRF-Fehler hinter dem Reverse-Proxy: PAPERLESS_URL auf die externe Domain setzen und den Proxy korrekt durchreichen.
Auto-Matching ordnet nichts zu: Das ist direkt nach dem Setup normal. Erst manuell taggen, Inbox-Tag entfernen und den nächsten Trainingslauf abwarten (Default stündlich).
Versehentlich auf v3.0 gewechselt: Der Tag beta ist nicht für Produktion gedacht. Für Stable bleibst du bei latest.

Häufige Fragen

Brauche ich eine GPU für Paperless-ngx?

Nein. Paperless-ngx ist ein reines CPU-Workload und braucht keine GPU. Eine Mehrkern-CPU beschleunigt die OCR, mehr ist nicht erforderlich. Nur die optionale lokale KI der v3.0-Beta wäre rechenintensiver – im Produktivbetrieb mit der Stable-Version spielt das keine Rolle.

Welche Version soll ich verwenden, latest oder beta?

Für Produktion nimmst du latest (aktuell v2.20.15). Der Tag beta liefert v3.0 mit lokaler KI, neuer Volltextsuche und Dokument-Versionen, ist aber noch Beta. Wechsle nicht versehentlich darauf.

Wie bekomme ich Scans automatisch nach Paperless-ngx?

Über den Consume-Ordner. Richte Scan-to-Folder deines Netzwerkscanners auf das gemountete ./consume-Verzeichnis (z. B. per SMB-Freigabe) oder lass Paperless-ngx ein Postfach abrufen. Alles, was im Ordner landet, wird automatisch importiert und per OCR verarbeitet.

Reicht ein einfacher Datenbank-Dump als Backup?

Nein. Ein konsistentes Backup braucht DB, media-Dateien und Metadaten. Nutze den document_exporter mit -c -d – er schreibt alles inklusive manifest.json in ein portables Format. Den PostgreSQL-Dump kannst du zusätzlich ziehen.

Kann ich Paperless-ngx aus dem Internet erreichbar machen?

Ja, aber nicht direkt über Port 8000. Setze einen Reverse-Proxy mit HTTPS davor, trage PAPERLESS_URL mit deiner Domain ein und vergib einen PAPERLESS_SECRET_KEY. Sonst drohen Sicherheits- und CSRF-Probleme.

Wie viel RAM und Speicher brauche ich?

Als Richtwert etwa 2 GB RAM, mehr für parallele OCR und Tika. Der Speicherbedarf skaliert mit der Dokumentmenge, da pro Dokument Original, Archiv-PDF und Thumbnail abgelegt werden – plane großzügig.

Fazit

Mit Docker Compose hast du Paperless-ngx in rund einer halben Stunde produktiv am Laufen: OCR auf Deutsch, Volltextsuche, automatische Verschlagwortung und ein sauberes, portables Backup. Die wichtigsten Stellschrauben sind die Tika-Variante für Office-Dateien, der korrekte Tesseract-Sprachcode deu, passende USERMAP-IDs und ein Reverse-Proxy mit HTTPS für externen Zugriff. Bleibe für die Produktion beim Tag latest, pinne deinen Postgres-Tag bewusst und mach vor jedem Update ein Backup – dann ist dein papierloses Büro stabil und wartungsarm.

Weiterführende Anleitungen und Quellen

Weiterführende Anleitungen aus unserem Wissensbereich:

Quellen: