Paperless-NGX auf Synology: NFS-Mounts, saubere Drive-Integration und ein stabiles Docker-Setup

Beim Betrieb von Paperless-NGX auf einer Synology NAS entscheidet nicht nur der Container selbst über Stabilität und Alltagstauglichkeit, sondern vor allem die Art, wie Speicher eingebunden wird.
Gerade im Zusammenspiel mit Docker, automatischer Dokumentenverarbeitung und optionaler Synology-Drive-Integration zeigt sich schnell, ob ein Setup langfristig wartbar ist – oder ob man sich unnötige Probleme einhandelt.

Im folgenden Artikel beschreibe ich, wie wir Paperless-NGX über NFS-Freigaben sauber eingebunden haben, warum diese Entscheidung technisch sinnvoll ist und wie daraus eine bewusst reduzierte, aber praxistaugliche Drive-Integration entstanden ist.

---

Weitere Artikel zu Paperless-ngx

• Was Paperless-NGX im Alltag wirklich leistet
• Paperless-NGX installieren: Voraussetzungen, Betriebsmodelle und der Weg zur lauffähigen Installation
• Paperless-NGX Troubleshooting – typische Stolperfallen und schnelle Checks

---

Warum NFS statt SMB? – mit Blick auf Synology Drive und die Gesamtarchitektur

Synology bietet mit SMB einen sehr komfortablen Standardzugriff, insbesondere in Kombination mit Synology Drive. Für klassische Dateiablagen oder gemeinsame Arbeitsverzeichnisse ist das in der Regel vollkommen ausreichend.

Im Zusammenspiel von Docker, Paperless-NGX und Synology Drive zeigt sich jedoch schnell, dass SMB architektonisch an seine Grenzen stößt. Der entscheidende Punkt ist dabei weniger Paperless selbst, sondern die Rolle von Synology Drive als zusätzlicher Akteur im Dateisystem.

Architekturgedanke: klare Verantwortlichkeiten

In diesem Setup gibt es drei klar getrennte Ebenen:

1. Docker-Container
   • enthält ausschließlich Applikationslogik
   • keine dauerhaften Daten im Container selbst
2. Gemountete Verzeichnisse (Consume, Media, Export)
   • sind der persistente Datenlayer
   • müssen zuverlässig von Paperless überwacht werden (File-Events)
3. Synology Drive (optional, selektiv)
   • greift auf einzelne dieser Verzeichnisse zu
   • erzeugt zusätzliche Dateisystem-Ereignisse

Damit dieses Zusammenspiel stabil funktioniert, braucht es ein Dateisystem, das:

• Linux-Dateisystem-Semantik korrekt abbildet
• File-Events zuverlässig weiterreicht
• sauberes UID/GID-Mapping erlaubt

Warum SMB hier problematisch ist

Über SMB entstehen in dieser Architektur mehrere Schwierigkeiten:

• Inotify-Events werden nicht zuverlässig an den Container weitergereicht
• zusätzliche Metadaten und Locks durch Drive können zu unerwartetem Verhalten führen
• Dateirechte werden abstrahiert, nicht eindeutig abgebildet
• mehrere „Instanzen“, die gleichzeitig am Dateisystem arbeiten, erhöhen die Komplexität

Gerade beim Consume-Ordner, der permanent überwacht wird, kann das dazu führen, dass Dokumente verspätet oder gar nicht verarbeitet werden.

Warum NFS hier die bessere Wahl ist

NFS fügt sich deutlich sauberer in diese Architektur ein:

• native Linux-Semantik ohne Protokoll-Übersetzung
• zuverlässige Inotify-Events für Paperless
• eindeutige POSIX-Rechte (UID/GID)
• klare Trennung zwischen Applikation (Container) und Daten (Host)

Synology Drive kann dabei weiterhin genutzt werden – aber gezielt und kontrolliert, zum Beispiel ausschließlich für die Scan_Inbox.

Fazit dieses Architekturentscheids

Der Einsatz von NFS ist hier kein Selbstzweck, sondern eine bewusste Architekturentscheidung, um:

• Paperless stabil zu betreiben
• Drive-Integration zu ermöglichen, ohne File-Events zu gefährden
• Verantwortlichkeiten sauber zu trennen

Der Container bleibt zustandslos, die Daten liegen auf dem Host, und Synology Drive wird dort eingesetzt, wo es fachlich Sinn ergibt – nicht pauschal überall.

Zielstruktur der Verzeichnisse

Die Ablage wurde bewusst in drei logisch getrennte Bereiche aufgeteilt:

• Scan_Inbox – Eingang für neue Dokumente
• Ablage – finales, strukturiertes Archiv
• Export – optionaler Exportpfad

Diese Trennung erleichtert nicht nur die Konfiguration, sondern auch Wartung, Fehlersuche und spätere Erweiterungen.

---

Ordnerstruktur anlegen (Synology per SSH)

Die beiden Freigegebenen Ordner „Paperless Inbox“ und „Paperless Ablage“ sollten bereits über die DSM-Oberfläche angelegt sein. Die folgende SSH-Konfiguration ergänzt lediglich die erforderlichen Unterordner.

sudo -i

INBOX="/volume1/Paperless Inbox"
ABLAGE="/volume1/Paperless Ablage"

mkdir -p \
  "$INBOX/Scan_Inbox" \
  "$ABLAGE/Archiv" \
  "$ABLAGE/Export"
Code-Sprache: Bash (bash)

Damit ist die Struktur logisch getrennt:

Neue Dokumente landen in der Paperless Inbox, während archivierte und exportierte Dokumente klar in der Paperless Ablage organisiert sind. Das macht die spätere Wartung, Rechtevergabe und Datensicherung deutlich übersichtlicher – besonders auf einer Synology mit mehreren Diensten und Benutzern.

---

POSIX-Rechte sauber setzen (UID/GID + setgid)

Für dieses Beispiel wird von einer neutralen UID/GID 1000:1000 ausgegangen (typisch für viele Linux-Setups).

sudo -i

INBOX="/volume1/Paperless Inbox"

chown -R 1000:1000 "$INBOX"

# setgid auf Verzeichnissen, damit Gruppenrechte sauber vererbt werden
find "$INBOX" -type d -exec chmod 2770 {} \;

# Dateien les- und schreibbar für Owner & Group
find "$INBOX" -type f -exec chmod 660 {} \;
Code-Sprache: Bash (bash)

Das gesetzte setgid-Bit sorgt dafür, dass neu erzeugte Dateien automatisch die richtige Gruppe behalten – ein wichtiger Punkt bei gemischten Zugriffen (Docker, Drive, Scanner, mobile Uploads).

POSIX-Rechte werden ausschließlich auf der „Paperless Inbox“ gesetzt, da dieser Bereich aktiv von Paperless-ngx überwacht und verändert wird. Die „Paperless Ablage“ dient ausschließlich als Ziel für Archiv- und Exportdaten und ist nicht als Synology Team Drive eingebunden, um unnötige Metadaten und Dateisystem-Ereignisse zu vermeiden.

---

DSM-Metadaten vermeiden

Um unnötige Scans und Seiteneffekte zu vermeiden, sollten Synology DSM-spezifische Ordner wie @eaDir oder #recycle in diesen Verzeichnissen nicht verwendet werden.

sudo -i
BASE="/Paperless Inbox"
find "$BASE" -type d \( -name "@eaDir" -o -name "#recycle" \) -prune
Code-Sprache: Bash (bash)

---

Docker: NFS als Volume einbinden

Die NFS-Freigaben werden nicht direkt von DSM „irgendwohin“ gemountet, sondern sauber als Docker-Volumes eingebunden.

Vollständige docker-compose.yml mit NFS Mount

In dieser Variante wird ausschließlich die Paperless Inbox per NFS eingebunden. Der Hintergrund ist, dass dieser Ordner aktiv überwacht wird und häufige Dateiänderungen auftreten, etwa durch Scanner oder Uploads von mehreren Quellen. Für diesen Zweck ist ein klar abgegrenztes, extern angebundenes Consume-Verzeichnis sinnvoll.

Die Paperless Ablage mit Archiv, Export und Papierkorb bleibt hingegen als klassischer Bind-Mount direkt auf das lokale Dateisystem der Synology eingebunden. Dadurch greift Paperless ohne Netzwerkprotokoll direkt auf die Daten zu, während Benutzer parallel weiterhin ganz normal über SMB auf dieselben freigegebenen Ordner zugreifen können. Die Art des Docker-Mounts hat dabei keinen Einfluss auf die Erreichbarkeit der Freigaben für Benutzer.

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
      # Consume-Verzeichnis als dedizierter Unterordner via NFS
      - 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:

  # NFS-Volume für die Inbox (Synology als NFS-Server)
  paperless-inbox:
    driver: local
    driver_opts:
      type: "nfs"
      o: "addr=192.168.1.10,nolock,soft,rw,nfsvers=4"
      device: ":/volume1/Paperless Inbox/Scan_Inbox"
  #Die IP-Adresse addr= entspricht der Synology-IP im lokalen Netz.
Code-Sprache: YAML (yaml)

Geänderte und im YAML markierte Zeilen

Bezogen auf die ursprüngliche YAML werden nur zwei Stellen geändert, bzw. ergänzt. Diese sind in der yaml oben farblich hervorgehoben.

1. Zeile 120: Umstellung der Inbox auf ein NFS-Volume (statt Bind-Mount) Zeile 120:

- paperless-inbox:/usr/src/paperless/consumeCode-Sprache: YAML (yaml)

2. Zeilen 146 bis 151: Neues NFS-Volume für die Inbox

paperless-inbox:
driver: local
driver_opts:
type: "nfs"
o: "addr=192.168.1.10,nolock,soft,rw,nfsvers=4"
device: ":/volume1/Paperless Inbox/Scan_Inbox"Code-Sprache: YAML (yaml)

---

Inotify-Limits erhöhen (empfohlen)

Paperless-ngx verlässt sich auf inotify, um neue Dokumente sofort zu erkennen. Bei größeren Dokumentenbeständen, verschachtelten Ordnerstrukturen oder NFS-Mounts reichen die Standard-Limits vieler Linux-Distributionen nicht aus.

Werden die Limits erreicht, reagiert Paperless nicht mehr zuverlässig auf neue Dateien – oft ohne klare Fehlermeldung. Das Erhöhen der inotify-Limits ist daher eine empfohlene Maßnahme für stabile und skalierbare Installationen.

sudo -i
cat >/etc/sysctl.d/99-paperless.conf <<'EOF'
fs.inotify.max_user_watches=524288
fs.inotify.max_user_instances=1024
EOF

sysctl --system
Code-Sprache: Bash (bash)

---

Synology Drive: bewusst reduziert eingesetzt

Ein zentraler Punkt dieses Setups ist die bewusste Einschränkung der Drive-Integration.

Scan_Inbox über Drive: praxisnah und ausreichend

Die Scan_Inbox wird zusätzlich in Synology Drive eingebunden.
Das ermöglicht:

• mobile Scans (z. B. über die iOS Dateien-App)
• Uploads von unterwegs
• sofortige Verarbeitung durch Paperless

Für den Alltag ist dies der wichtigste Anwendungsfall.

---

Export-Freigabe: optional

Die Export-Freigabe ist technisch möglich, im täglichen Betrieb jedoch meist nicht erforderlich.
Exporte sind eher Ausnahmefälle und bringen über Drive keinen echten Mehrwert.

---

Ablage: bewusst ein statisches Archiv

Die finale Ablage ist ein ruhiges, strukturiertes Archiv:

• keine regelmäßigen Benutzerzugriffe
• keine Bearbeitung über Drive
• Anzeige, Suche und Nutzung erfolgen vollständig über Paperless

Der eigentliche Dokumenten-Viewer ist Paperless selbst – nicht das Dateisystem.

---

Fazit

Durch die Kombination aus:

• NFS statt SMB
• klarer Verzeichnisstruktur
• sauberem Docker-Setup
• gezielter (nicht maximaler) Drive-Integration

entsteht ein Paperless-System, das stabil läuft, wartbar bleibt und im Alltag überzeugt. Gerade die Erkenntnis, dass nicht jede Freigabe synchronisiert werden muss, trägt wesentlich zur Ruhe und Zuverlässigkeit des Systems bei.