Paperless-NGX installieren: Voraussetzungen, Betriebsmodelle und der Weg zur lauffähigen Installation

Paperless-NGX ist kein „Klick-und-fertig“-Tool, sondern eine Plattform, die bewusst auf Flexibilität und Selbstbetrieb setzt. Bevor man sich mit Details wie Ordnerstrukturen oder Automatisierung beschäftigt, lohnt es sich daher, einen Schritt zurückzugehen und zu klären:

• Welche Voraussetzungen bringt Paperless mit?
• In welchen Umgebungen kann es betrieben werden?
• Welche Schritte kommen bei einer Installation realistisch auf einen zu?

Gerade auf einer Synology-NAS lässt sich Paperless-NGX jedoch vergleichsweise unkompliziert betreiben. Mit der integrierten Container-App (Container Manager) und einem grundlegenden Verständnis von Docker-Containern kann eine lauffähige Basisinstallation in überschaubarer Zeit umgesetzt werden. Eine einfache Konfiguration reicht aus, um Dokumente zu importieren, zu verarbeiten und durchsuchbar abzulegen.

Diese Grundinstallation ist oft der Einstiegspunkt: Ausgehend von einer funktionierenden Minimal-Konfiguration lässt sich Paperless schrittweise erweitern – etwa durch feinere Workflows, zusätzliche Automatisierung oder optimierte Speicheranbindungen. Die Unterstützung durch KI-Systeme wie ChatGPT kann dabei helfen, Konfigurationsdateien besser zu verstehen, Optionen gezielt auszubauen und typische Stolpersteine zu vermeiden. Neben dem funktionalen Ergebnis nimmt man dabei zwangsläufig auch technisches Verständnis und praktische Learnings mit.

Dieser Artikel soll genau diese Orientierung liefern – ohne direkt in Spezialthemen wie NFS, Performance-Tuning oder Feinoptimierungen einzusteigen.

---

Weitere Artikel zu Paperless-ngx

• Was Paperless-NGX im Alltag wirklich leistet
• Paperless-NGX auf Synology: NFS-Mounts, saubere Drive-Integration und ein stabiles Docker-Setup
• Paperless-NGX Troubleshooting – typische Stolperfallen und schnelle Checks

---

Was braucht man grundsätzlich für Paperless-NGX?

Paperless-NGX ist eine serverseitige Anwendung und benötigt eine Linux-basierte Laufzeitumgebung. Konkret heißt das:

• ein Linux-System (physisch oder virtuell)
• ausreichend Speicherplatz für Dokumente
• Docker oder Docker Compose (empfohlen)
• grundlegendes Verständnis für Container, Volumes und Netzwerk

Die Hardwareanforderungen sind dabei überraschend moderat. Paperless wird produktiv betrieben auf:

• klassischen Linux-Servern (VM oder Bare Metal)
• NAS-Systemen mit Docker-Unterstützung
• Mini-PCs
• sogar auf einem Raspberry Pi, sofern man realistische Erwartungen an Performance und OCR-Durchsatz hat

Entscheidend ist weniger die CPU-Leistung als:

• ausreichend RAM
• stabiler Storage
• saubere Einbindung der Datenverzeichnisse

---

Mögliche Betriebsmodelle

Bevor man sich für einen Installationsweg entscheidet, sollte man sich über das Betriebsmodell klar werden.

1. Selbstbetrieb auf eigener Hardware

Das ist der klassische Ansatz:

• volle Kontrolle über Daten
• maximale Flexibilität
• etwas mehr technischer Aufwand

Typische Umgebungen:

• Linux-Server
• NAS mit Docker (z. B. Synology)
• Mini-Server oder Raspberry Pi

---

2. Betrieb auf einem NAS (z. B. Synology)

Ein NAS bietet sich an, wenn:

• ohnehin Speicher für Dokumente vorhanden ist
• Docker unterstützt wird
• das System ohnehin 24/7 läuft

Ich selbst betreibe Paperless-NGX auf einer Synology NAS in Containern. Das ist technisch gut machbar, erfordert aber ein sauberes Setup und ein paar bewusste Architekturentscheidungen.

---

3. Gehostete Paperless-Angebote

Es gibt inzwischen auch Anbieter, die Paperless-NGX als gehosteten Dienst anbieten. Vorteile:

• kein eigener Serverbetrieb
• schnelle Inbetriebnahme

Nachteile:

• laufende Kosten
• Abhängigkeit vom Anbieter
• sensible Dokumente liegen extern

Für manche Szenarien ist das eine valide Option, für andere bewusst nicht.

Hier eine Aufstellung von gehosteten Paperless-Angebote:

Anbieter	Kurzbeschreibung	Preismodell
paperless-hosting.de	Spezialisierter deutscher Anbieter für Paperless-NGX-Hosting, Fokus auf einfache Inbetriebnahme und DSGVO-konforme Serverstandorte.	Monatliche Pauschalen, meist gestaffelt nach Speicherplatz und Nutzeranzahl
cloudshift.de	Paperless-NGX als vollständig verwalteter SaaS-Dienst, inkl. Wartung, Backups und optionalem Support.	Monatliches Abo, Business-Tarife mit SLA
elest.io	Internationaler Managed-Service-Anbieter für Open-Source-Software, schnelle Bereitstellung, technisch flexibel.	Pay-as-you-go, abhängig von Ressourcen (CPU, RAM, Storage)
peaknetworks.de	Deutsches Cloud- und App-Hosting, ISO-zertifizierte Rechenzentren, Fokus auf Skalierbarkeit.	Monatliche Hosting-Pakete, abhängig von Leistung und Speicher
paperless-cloud.com	Paperless-NGX als Managed SaaS-Lösung mit Hosting in Deutschland, optional individualisierbar.	Monatliche Abos, meist nutzer- oder speicherbasiert
bitbetter.de	Managed Paperless-NGX inkl. Hosting, Wartung und Support, stärker auf professionelle Nutzung ausgelegt.	Feste Monatspreise, Einstieg meist ab mittlerem zweistelligen Bereich

Gehostete Angebote eignen sich vor allem für Nutzer, die keinen eigenen Server betreiben möchten und bereit sind, Kontrolle und Datenhaltung gegen Komfort zu tauschen.

---

Entscheidung für Docker als Installationsbasis

Unabhängig vom gewählten Host-System hat sich Docker als de-facto-Standard für Paperless-NGX etabliert. Docker bringt:

• reproduzierbare Setups
• saubere Trennung von Anwendung und Daten
• einfache Updates
• klare Abhängigkeiten (Datenbank, Redis, Webservice)

Gerade auf Systemen wie einer Synology NAS ist Docker der sauberste Weg, Paperless dauerhaft wartbar zu betreiben.

---

Welche Komponenten gehören zu einer Paperless-Installation?

Eine vollständige Paperless-NGX-Installation besteht nicht nur aus „einem Container“. Typischerweise gehören dazu:

• Paperless-NGX Web-/Worker-Container
• PostgreSQL (Datenbank)
• Redis (Task-Queue)
• persistente Volumes für:
  • Scan-Inbox (Consume)
  • Ablage (Media)
  • optional Export

Diese Trennung ist wichtig, um:

• Daten unabhängig vom Container zu sichern
• Updates gefahrlos durchführen zu können
• spätere Migrationen zu ermöglichen

---

Die realen Schritte zur Installation (aus der Praxis)

Aus meiner Erfahrung lässt sich der Weg zu einer funktionierenden Installation grob in folgende Schritte gliedern:

1. Grundumgebung vorbereiten

• Docker / Docker Compose installieren oder aktivieren
• sicherstellen, dass Container automatisch starten dürfen
• festen Speicherort für Paperless-Daten definieren

---

2. Verzeichnisstruktur planen

Noch bevor der erste Container startet, sollte klar sein:

• wo neue Dokumente eingehen
• wo abgelegte Dokumente liegen
• welche Ordner später ggf. extern erreichbar sein sollen

Eine saubere Struktur spart später enorm Zeit und Frust.

---

3. Docker-Compose-Datei erstellen (Beispiel-Compose-Datei)

In diesem Schritt werden:

• Container definiert
• Abhängigkeiten festgelegt
• Umgebungsvariablen gesetzt
• Volumes gemountet

Hier entscheidet sich, ob das Setup später wartbar bleibt oder nicht. Das folgende Beispiel ist bewusst „minimal“, aber praxistauglich. Es verwendet lokale Pfade als Volumes (keine NFS-Details). Pfade und Ports lassen sich an die eigene Umgebung anpassen.

version: "3.8"

services:
  broker:
    image: redis:7-alpine
    container_name: paperless-redis
    restart: unless-stopped

    # Redis wird ausschließlich intern genutzt.
    # Paperless erreicht den Dienst über den Servicenamen "broker".
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 10

    logging:
      options:
        max-size: "10m"
        max-file: "3"

  db:
    image: postgres:15-alpine
    container_name: paperless-db
    restart: unless-stopped

    # Datenbank-Zugangsdaten werden vollständig aus der .env gelesen.
    # Keine Zugangsdaten direkt in dieser Datei hinterlegen.
    environment:
      POSTGRES_DB: ${PAPERLESS_DB_NAME}
      POSTGRES_USER: ${PAPERLESS_DB_USER}
      POSTGRES_PASSWORD: ${PAPERLESS_DB_PASSWORD}

    # Persistente Speicherung der Datenbank
    volumes:
      - db-data:/var/lib/postgresql/data

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${PAPERLESS_DB_USER} -d ${PAPERLESS_DB_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 10

    logging:
      options:
        max-size: "10m"
        max-file: "3"

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped

    depends_on:
      db:
        condition: service_healthy
      broker:
        condition: service_healthy

    ports:
      # Weboberfläche erreichbar unter http://<NAS-IP>:8000
      - "8000:8000"

    environment:
      # Interne Anbindung an Redis
      PAPERLESS_REDIS: redis://broker:6379

      # Datenbank-Verbindung
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: ${PAPERLESS_DB_NAME}
      PAPERLESS_DBUSER: ${PAPERLESS_DB_USER}
      PAPERLESS_DBPASS: ${PAPERLESS_DB_PASSWORD}

      # Zeitzone und OCR-Sprachen
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_OCR_LANGUAGE: deu+eng

      # Kryptografischer Secret Key
      # Wird bewusst aus der .env gelesen.
      # Hinweise zur Generierung stehen in der .env-Datei.
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}

      # Optional: Admin-Account beim ersten Start anlegen
      PAPERLESS_ADMIN_USER: ${PAPERLESS_ADMIN_USER}
      PAPERLESS_ADMIN_PASSWORD: ${PAPERLESS_ADMIN_PASSWORD}
      PAPERLESS_ADMIN_MAIL: ${PAPERLESS_ADMIN_MAIL}

      # UID/GID-Mapping für saubere Dateirechte auf der Synology
      USERMAP_UID: ${PAPERLESS_UID}
      USERMAP_GID: ${PAPERLESS_GID}

      # Rekursive Verarbeitung der Inbox
      PAPERLESS_CONSUMER_RECURSIVE: "true"

      # Unterordner der Inbox werden als Tags interpretiert
      PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS: "true"

      # Duplikate automatisch entfernen
      PAPERLESS_CONSUMER_DELETE_DUPLICATES: "true"

      # Synology-spezifische Metadaten ignorieren
      PAPERLESS_CONSUMER_IGNORE_PATTERNS: '["@eaDir/*"]'

      # Archivmodus: Dokumente werden in die Ablage verschoben
      PAPERLESS_ARCHIVE_MODE: "move"

      # Eigener Papierkorb für gelöschte Dokumente
      # Ohne diese Einstellung werden Dokumente sofort endgültig gelöscht.
      PAPERLESS_TRASH_DIR: /usr/src/paperless/trash

    volumes:
      # Interne Paperless-Daten (Index, Konfiguration)
      - paperless-data:/usr/src/paperless/data

      # Medienverzeichnis
      - paperless-media:/usr/src/paperless/media

      # Paperless Inbox
      # Empfohlener freigegebener Ordner auf der Synology
      - "/volume1/Paperless Inbox:/usr/src/paperless/consume"

      # Paperless Ablage – Archiv
      # Statisches Archiv, nicht über Synology Drive teilen
      - "/volume1/Paperless Ablage/Archiv:/usr/src/paperless/media/documents/archive"

      # Optionaler Export-Ordner
      - "/volume1/Paperless Ablage/Export:/usr/src/paperless/export"

      # Papierkorb
      - "/volume1/Paperless Ablage/Trash:/usr/src/paperless/trash"

    logging:
      options:
        max-size: "50m"
        max-file: "5"

volumes:
  # Docker-Volumes für interne Daten
  db-data:
  paperless-data:
  paperless-media:
Code-Sprache: YAML (yaml)

Hinweise zur Praxis:

• Die ./data/... Pfade können genauso gut auf einen festen Speicherort zeigen (z. B. /volume1/docker/paperless/... auf einer Synology).
• USERMAP_UID/GID sollten zur eigenen Umgebung passen; wichtig ist vor allem Konsistenz.
• PAPERLESS_OCR_LANGUAGE ist sinnvoll, wenn deutschsprachige Dokumente dominieren.

# ------------------------------
# Datenbank-Konfiguration
# ------------------------------

# Name der Paperless-Datenbank
PAPERLESS_DB_NAME=paperlessdb

# Datenbank-User
# Nicht "paperless" verwenden, sondern einen eigenen Namen wählen.
PAPERLESS_DB_USER=pl_user

# Datenbank-Passwort
# Empfehlung: mindestens 24 Zeichen, zufällig generiert.
PAPERLESS_DB_PASSWORD=change-me-to-a-long-random-password

# ------------------------------
# Paperless Secret Key
# ------------------------------

# Pflichtfeld.
# Wird für Sessions, Tokens und kryptografische Signaturen verwendet.
#
# Empfehlung:
# - mindestens 50 Zeichen, besser 64 oder mehr
# - vollständig zufällig
# - keine Wörter oder Passphrasen
#
# Geeignete Generierung im Terminal:
#   openssl rand -base64 48
#
PAPERLESS_SECRET_KEY=generate-your-own-secret-key

# ------------------------------
# Optional: Admin-Benutzer
# ------------------------------

# Wird nur beim ersten Start verwendet.
# Danach erfolgt die Benutzerverwaltung über die Weboberfläche.
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=change-me-too
PAPERLESS_ADMIN_MAIL=admin@example.tld

# ------------------------------
# Synology UID / GID
# ------------------------------

# Muss zu den Besitzrechten der gemounteten Ordner passen.
# Typische Werte sind 1000:1000, können aber abweichen.
PAPERLESS_UID=1000
PAPERLESS_GID=1000
Code-Sprache: Extended Backus-Naur Form (ebnf)

---

4. Erster Start und Grundkonfiguration

Nach dem ersten Start geht es darum:

• Paperless initial zu konfigurieren
• Benutzer anzulegen
• grundlegende Einstellungen (Sprache, OCR, Zeitzone) zu prüfen

In diesem Schritt zeigt sich meist schnell, ob:

• Volumes korrekt eingebunden sind
• Rechte passen
• Container sauber miteinander kommunizieren

---

5. Erste Dokumente testen

Bevor man das System produktiv nutzt, empfiehlt es sich:

• ein paar Testdokumente einzuspielen
• OCR-Erkennung zu prüfen
• Klassifizierung zu beobachten
• Ablagepfade zu kontrollieren

Hier lassen sich viele spätere Probleme früh erkennen.

---

Themen, die bewusst ausgelagert sind

Einige Aspekte verdienen aus meiner Sicht eigene Artikel und werden hier bewusst nur angerissen:

• NFS vs. SMB und saubere Mounts
• Synology Drive Integration
• Sicherheits- und Backup-Strategien
• Automatisierungsregeln im Detail

---

Fazit

Paperless-NGX lässt sich auf sehr unterschiedlichen Plattformen betreiben – vom Raspberry Pi bis zum NAS oder Server. Entscheidend ist weniger die Hardware als ein durchdachtes Setup. Wer sich vor der Installation:

• über das Betriebsmodell klar wird
• die Komponenten versteht
• die Schritte realistisch einschätzt

vermeidet viele der typischen Stolperfallen. Die eigentliche Stärke von Paperless zeigt sich erst später im Alltag – aber eine saubere Installation ist die Voraussetzung dafür.