paperless-ngx installieren

Was paperless-ngx ist

paperless-ngx ist ein quelloffenes Dokumentenmanagement-System, das du auf einem eigenen Rechner betreibst. Es nimmt eingescannte Dokumente entgegen, jagt sie durch eine Texterkennung, versucht Absender, Dokumenttyp und Schlagworte automatisch zuzuordnen, und stellt dir eine durchsuchbare Weboberfläche darüber bereit. Es ist der Nachfolger des nicht mehr gepflegten „Paperless“ beziehungsweise „paperless-ng“ und wird von einer aktiven Gemeinschaft entwickelt.

Das System besteht aus mehreren Bausteinen, die gemeinsam laufen: der Webserver mit der Oberfläche, eine Datenbank, ein Zwischenspeicher (Redis) für die Aufgabenverwaltung und — wenn du auch Office-Dateien einlesen willst — zusätzlich Tika und Gotenberg. Genau deshalb wird es als Container-Verbund ausgeliefert: Docker startet alle Teile in der richtigen Reihenfolge.

Die Software selbst kostet nichts. Was sie kostet, sind Hardware, Strom und deine Zeit für den Betrieb — was das konkret bedeutet, rechnet unser Ratgeber zum DMS ohne Server vor.

Was du brauchst

• Einen Rechner, der durchläuft. Ein NAS, ein Mini-PC, ein Raspberry Pi oder ein gemieteter virtueller Server. Windows scheidet für eine Installation ohne Docker aus — paperless-ngx läuft direkt nur auf Linux.
• Docker und Docker Compose. Auf einem NAS heißt das je nach Hersteller Container Manager (Synology) oder Container Station (QNAP).
• Arbeitsspeicher: mindestens 2 GB, angenehm ab 4 GB. Im Leerlauf braucht der Verbund einige hundert Megabyte; bei der Texterkennung steigt der Bedarf deutlich und ein Prozessorkern wird voll ausgelastet.
• Speicherplatz für deine Dokumente plus etwa den gleichen Betrag noch einmal, wenn du die durchsuchbaren Archivfassungen erzeugen lässt.
• Grundkenntnisse auf der Kommandozeile. Du solltest dich in einer SSH-Sitzung zurechtfinden, eine Textdatei bearbeiten und Dateirechte nachschlagen können.

Weg 1: Das Installationsskript (der schnellste Weg)

Das Projekt stellt ein interaktives Skript bereit. Es stellt ein paar Fragen, legt danach die nötigen Dateien an, lädt die Abbilder herunter, startet die Container und legt dein Administratorkonto an. Für die meisten Erstinstallationen ist das der richtige Weg.

bash -c "$(curl --location --silent --show-error \
  https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Das Skript fragt unter anderem nach dem Port, den Verzeichnissen für Dokumente und Einwurf, der Datenbank, der OCR-Sprache und deinen Zugangsdaten. Wenn dir unwohl dabei ist, ein Skript direkt aus dem Netz in eine Shell zu leiten: sieh es dir vorher an — das empfiehlt das Projekt selbst.

Danach erreichst du paperless-ngx unter http://127.0.0.1:8000 beziehungsweise unter der IP-Adresse deines Servers und dem gewählten Port.

Weg 2: Docker Compose von Hand

Wer genau wissen will, was läuft — und wer später Anpassungen vornehmen möchte —, richtet den Verbund selbst ein. Das ist nicht schwer, es sind fünf Schritte.

1. Die passende Compose-Datei herunterladen

   Im Projektverzeichnis docker/compose liegen mehrere Varianten. Lade genau eine davon und speichere sie in einem eigenen Ordner als docker-compose.yml. Dazu gehören außerdem die Dateien docker-compose.env und .env.

   ← Seitlich scrollen — erste Spalte bleibt stehen →

   Welche Compose-Variante?

   Datei	Wofür
   docker-compose.postgres.yml	Die Empfehlung für neue Installationen.
   docker-compose.postgres-tika.yml	Wie oben, zusätzlich mit Unterstützung für Office-Dokumente.
   docker-compose.sqlite.yml	Sparsam — die Wahl für Raspberry Pi und schwache NAS.
   docker-compose.sqlite-tika.yml	Sparsam, mit Office-Unterstützung.
   docker-compose.mariadb.yml docker-compose.mariadb-tika.yml	Wenn du MariaDB ohnehin schon betreibst.
   docker-compose.portainer.yml	Für die Einrichtung über Portainer — auf NAS-Systemen verbreitet.

   „Tika“ oder nicht? Die Varianten mit -tika starten zwei zusätzliche Container, die Word-, Excel- und ähnliche Dateien lesbar machen. Sie kosten spürbar Arbeitsspeicher. Wenn du fast nur PDFs und Scans hast, lass sie weg.

2. Die Ordner festlegen

   In der docker-compose.yml stehen die Einhängepunkte für den Einwurfordner (consume), die Dokumente (media) und die Daten. Ersetze den Teil vor dem Doppelpunkt durch einen echten Pfad auf deinem Server:

   docker-compose.ymlyaml

   # vorher
         - ./consume:/usr/src/paperless/consume
   
   # nachher — dein eigener Ordner, z. B. eine NAS-Freigabe
         - /volume1/dokumente/einwurf:/usr/src/paperless/consume

   Wenn Port 8000 bei dir schon belegt ist, ändere ihn hier ebenfalls — links steht der Port auf dem Server, rechts der im Container:

   docker-compose.ymlyaml

       ports:
         - 8010:8000

3. Die Konfiguration anpassen

   Öffne docker-compose.env und setze mindestens die vier Werte aus dem nächsten Abschnitt — vor allem den geheimen Schlüssel, die OCR-Sprache und die Benutzerkennung.

4. Abbilder laden

   im Ordner mit der docker-compose.ymlbash

   docker compose pull

5. Starten

   im Ordner mit der docker-compose.ymlbash

   docker compose up -d

   Der erste Start dauert einen Moment, weil die Datenbank angelegt wird. Danach rufst du http://<server-ip>:8000 auf — beim ersten Aufruf wirst du aufgefordert, dein Administratorkonto anzulegen.

   Läuft etwas nicht, zeigt docker compose logs -f mit, was die Container melden.

Die wichtigsten Einstellungen

paperless-ngx kennt sehr viele Konfigurationswerte. Diese hier entscheiden darüber, ob die Installation im Alltag taugt:

# Pflicht: ein eigener geheimer Schlüssel — niemals den Standardwert lassen.
# Erzeugen mit:  python3 -c "import secrets; print(secrets.token_urlsafe(64))"
PAPERLESS_SECRET_KEY=hier-deinen-erzeugten-schluessel-einsetzen

# Die Sprache, in der deine Dokumente verfasst sind. Für deutsche Post: deu.
# Mehrsprachig geht auch:  deu+eng
PAPERLESS_OCR_LANGUAGE=deu

# Ohne das stimmen alle Zeitangaben und geplanten Aufgaben nicht.
PAPERLESS_TIME_ZONE=Europe/Berlin

# Damit Container und Server dieselben Dateirechte verwenden.
# Werte ermitteln mit:  id -u   und   id -g
USERMAP_UID=1000
USERMAP_GID=1000

# Nur nötig, wenn paperless über einen Reverse Proxy oder eine eigene Adresse
# erreichbar sein soll. Ohne diesen Wert scheitert die Anmeldung an der
# CSRF-Prüfung — einer der häufigsten Fehler überhaupt.
PAPERLESS_URL=https://paperless.meine-domain.de

Zur OCR-Sprache: Der Container bringt Englisch, Deutsch, Italienisch, Spanisch und Französisch mit. Brauchst du eine weitere Sprache, wird sie über PAPERLESS_OCR_LANGUAGES zusätzlich installiert — das ist ein anderer Wert als PAPERLESS_OCR_LANGUAGE, was regelmäßig verwechselt wird.

Auf dem NAS

Auf einem NAS gelten dieselben Schritte, nur läuft die Bedienung über die Container-Oberfläche des Herstellers: Container Manager bei Synology (dort als Compose-Projekt), Container Station bei QNAP, die Docker-App bei UGREEN, oder Portainer, das auf vielen Systemen nachrüstbar ist.

Drei Punkte, die auf einem NAS anders sind als auf einem Linux-Server:

• Die Benutzerkennung. USERMAP_UID und USERMAP_GID müssen zu dem NAS-Benutzer passen, dem die Freigabe gehört — sonst kann der Container den Einwurfordner nicht lesen oder du kommst über die Netzwerkfreigabe nicht mehr an die importierten Dateien.
• Der Arbeitsspeicher. Das NAS-Betriebssystem, die Indizierung der Fotos und die Freigabedienste belegen bereits einen Teil. Bleibt zu wenig übrig, wird der Container mitten in der Texterkennung beendet.
• Die Platten schlafen nicht mehr. Der Verbund schreibt laufend — der Ruhezustand entfällt praktisch, der Stromverbrauch steigt.

Raspberry Pi und schwache Hardware

paperless-ngx läuft auf einem Raspberry Pi. Es ist dann nicht schnell, aber benutzbar — vorausgesetzt, du drehst ein paar Stellschrauben zurück. Diese Empfehlungen stammen aus der offiziellen Dokumentation:

• SQLite statt PostgreSQL — spart einen kompletten Datenbankdienst.
• PAPERLESS_WEBSERVER_WORKERS=1 — ein Arbeitsprozess statt mehrerer.
• PAPERLESS_TASK_WORKERS und PAPERLESS_THREADS_PER_WORKER herunterdrehen, damit noch Rechenleistung für alles andere bleibt.
• PAPERLESS_ENABLE_NLTK=false — schaltet die aufwendigere Sprachverarbeitung ab.
• PAPERLESS_OCR_PAGES=1 — erkennt nur die erste Seite. Für das Wiederfinden reicht das meist.
• PAPERLESS_OCR_CLEAN=none — schnellere Erkennung bei leicht schlechterem Ergebnis.
• PAPERLESS_ARCHIVE_FILE_GENERATION=never — spart Platz und Rechenzeit, dafür entfällt die PDF/A-Ansicht im Browser.
• Wenn dein Scanner selbst OCR beherrscht: lass ihn das machen. PAPERLESS_OCR_MODE bleibt auf auto, dann überspringt paperless bereits erkannte Seiten.

Die ersten Schritte nach der Installation

1. Stammdaten anlegen

   Lege zuerst Korrespondenten (Absender), Dokumenttypen und Tags an, die zu deinem Papierkram passen — Stadtwerke, Krankenkasse, Versicherung, Rechnung, Vertrag, Steuer. Die automatische Zuordnung braucht diese Begriffe als Grundlage.

2. Erste Dokumente einwerfen

   Alles, was du in den Einwurfordner legst, wird automatisch eingelesen. Alternativ ziehst du Dateien direkt in die Weboberfläche.

3. Zuordnung korrigieren — und zwar geduldig

   paperless-ngx lernt aus deinen Korrekturen. Die ersten Dokumente ordnest du überwiegend selbst zu; ab einigen Dutzend pro Kategorie wird die automatische Erkennung brauchbar. Wer nach zehn Dokumenten aufgibt, hat den Lerneffekt nie gesehen.

4. Ein normales Benutzerkonto anlegen

   Das Projekt empfiehlt, für den Alltag ein Konto ohne Administratorrechte zu verwenden — der Superuser sieht und darf alles.

5. Das Backup einrichten — sofort, nicht später

   Ein Archiv ohne Sicherung ist ein Risiko, kein Archiv. Wie das geht, steht gleich im nächsten Abschnitt.

Betrieb: Updates, Backup, Zugriff

Updates

docker compose pull
docker compose up -d

Vor jedem größeren Versionssprung lohnt ein Blick in die Veröffentlichungshinweise des Projekts — und ein Backup davor ist Pflicht, nicht Kür.

Backup

Ein Dateisystem-Schnappschuss allein reicht nicht: Er erwischt die Datenbank möglicherweise mitten im Schreiben. paperless-ngx bringt deshalb einen eigenen Export mit, der Dokumente und Metadaten in eine wiederherstellbare Form schreibt:

docker compose exec webserver document_exporter ../export

Dieses Exportverzeichnis sicherst du dann wie jeden anderen wichtigen Ordner — inklusive einer Kopie außer Haus. Und: Ein Backup, das nie zurückgespielt wurde, ist eine Vermutung. Probiere die Wiederherstellung einmal aus, solange nichts kaputt ist.

Zugriff von unterwegs

Öffne keinen Port am Router auf die Weboberfläche. Nutze stattdessen ein VPN in dein Heimnetz, ein Overlay-Netz wie Tailscale oder ZeroTier, oder einen Reverse Proxy mit vorgeschalteter Anmeldung und Zwei-Faktor-Schutz. Ein aus dem Internet erreichbares Dokumentenarchiv ist ein lohnendes Ziel.

Typische Fehler und ihre Ursache

← Seitlich scrollen — erste Spalte bleibt stehen →

Wenn dir das alles zu viel ist

Wir haben diese Anleitung geschrieben, damit sie funktioniert — paperless-ngx ist ein gutes Stück Software, und wer sie betreiben will, soll das gut hinbekommen.

Aber es gibt einen Punkt, an dem viele hängenbleiben, und der liegt nicht bei der Installation, sondern danach. Die Installation ist ein Abend. Der Betrieb ist dauerhaft: Container aktualisieren, Backups prüfen, Sicherheitsmeldungen verfolgen, den Fernzugriff abdichten — und dabei sicherstellen, dass das Familienarchiv nicht an der einen Person hängt, die als Einzige versteht, wie es läuft.

Wenn du diese Anleitung liest und denkst „eigentlich will ich nur, dass mein Papierkram sortiert ist“ — dann ist PaperPeace vielleicht das Richtige für dich.

• Kein Server, keine Container, keine Updates. Eine App auf iPhone, iPad und Mac. Installieren, Speicherort wählen, fertig.
• Erkennung auf dem Gerät. Texterkennung, Dokumenttyp, Korrespondent und Tags werden lokal ermittelt. Nichts wird zur Analyse hochgeladen — auch nicht zu uns.
• Du bestimmst den Speicherort. Lokal, iCloud Drive, ein geteilter Ordner für die Familie, Dropbox, Google Drive, OneDrive oder dein NAS per SMB.
• Offline nutzbar. Die Bibliothek liegt auf dem Gerät — kein Netz heißt nicht: kein Dokument.
• Offenes Format. PDFs bleiben PDFs, die Metadaten liegen als lesbares Markdown daneben. Ein Backup ist eine Ordner-Sicherung, ein Wechsel ist ein Kopiervorgang.

Ehrlich bleibt: PaperPeace gibt es nur für Apple-Geräte, und Freigabe-Workflows oder revisionssichere Archivierung nach GoBD bietet es nicht. Wenn Windows- und Android-Geräte gleichberechtigt mitmachen sollen, ist paperless-ngx die bessere Wahl — dann hilft dir die Anleitung oben weiter.

Von paperless-ngx zu PaperPeace umziehen

Wenn du paperless-ngx bereits betreibst und wechseln möchtest, musst du nicht bei null anfangen. PaperPeace holt deine Dokumente direkt vom laufenden Server — samt der Ordnungsarbeit, die du bereits hineingesteckt hast.

1. In paperless-ngx einen API-Token erzeugen

   Melde dich an der Weboberfläche an, klicke oben rechts auf dein Profilsymbol und wähle „Mein Profil“. Unter API Auth Token erzeugst du über die Schaltfläche daneben einen Token und kopierst ihn.

2. Server-Adresse und Token in PaperPeace eintragen

   Du brauchst die Adresse, unter der du paperless erreichst (etwa http://192.168.1.50:8000), und den eben erzeugten Token. PaperPeace prüft die Verbindung, bevor es loslegt.

3. Den Import laufen lassen

   PaperPeace lädt jedes Dokument herunter und legt es in deiner Bibliothek ab. Bei großen Archiven dauert das seine Zeit — der Lauf lässt sich unterbrechen und später fortsetzen, ohne dass etwas doppelt landet.

Was dabei übernommen wird

• Das Dokument selbst — bevorzugt die durchsuchbare Archivfassung, sonst die Originaldatei.
• Titel, Korrespondent, Dokumenttyp und Tags — die Tags einschließlich ihrer Farben.
• Beide Daten: das Datum auf dem Dokument und der Zeitpunkt, zu dem du es damals abgelegt hast. Deine Ablage-Historie bleibt damit erhalten und wird nicht auf den Importzeitpunkt plattgedrückt.
• Notizen und eigene Felder (Custom Fields) sowie die Archiv-Seriennummer.

Was nicht übernommen wird

• Benutzerkonten, Gruppen und Berechtigungen — PaperPeace kennt kein Rechtesystem im Server-Sinn.
• Workflows, Verarbeitungsregeln, gespeicherte Ansichten und Speicherpfade.
• Mail-Regeln. PaperPeace hat einen eigenen E-Mail-Import, den du neu einrichtest.

Unabhängig davon lassen sich auch ganze Ordner samt Unterordnern und ZIP-Archive importieren — damit ist der Umzug aus so gut wie jedem anderen System gangbar, auch wenn es keine direkte Anbindung gibt.

Häufige Fragen