Paperless-NGX on Synology: NFS Mounts, Clean Drive Integration and a Stable Docker Setup

When running Paperless-NGX on a Synology NAS, stability and everyday usability depend not only on the container itself, but above all on how storage is integrated.
Especially when Docker, automated document processing and optional Synology Drive integration come together, it quickly becomes apparent whether a setup will remain maintainable in the long term – or create unnecessary problems.

In this article, I describe how we integrated Paperless-NGX cleanly using NFS shares, why this decision makes technical sense and how it led to a deliberately reduced but practical Drive integration.

More Articles About Paperless-ngx

• What Paperless-NGX Really Delivers in Everyday Use
• Installing Paperless-NGX: Requirements, Deployment Models and the Path to a Working Installation
• Paperless-NGX Troubleshooting – Common Pitfalls and Quick Checks

Why NFS Instead of SMB? – Considering Synology Drive and the Overall Architecture

Synology provides very convenient standard file access through SMB, particularly in combination with Synology Drive. For conventional file storage or shared working directories, this is generally more than sufficient.

When Docker, Paperless-NGX and Synology Drive are combined, however, SMB quickly reaches architectural limits. The decisive issue is less Paperless itself than the role of Synology Drive as an additional actor in the filesystem.

Architectural principle: clear responsibilities

This setup consists of three clearly separated layers:

1. Docker container
   • contains application logic only
   • no persistent data inside the container itself
2. Mounted directories (Consume, Media, Export)
   • form the persistent data layer
   • must be monitored reliably by Paperless (file events)
3. Synology Drive (optional, selective)
   • accesses individual directories
   • generates additional filesystem events

For this interaction to remain stable, the filesystem needs to:

• correctly represent Linux filesystem semantics
• reliably propagate file events
• allow clean UID/GID mapping

Why SMB is problematic here

SMB introduces several difficulties in this architecture:

• Inotify events are not reliably propagated to the container
• additional metadata and locks created by Drive can lead to unexpected behaviour
• file permissions are abstracted rather than represented unambiguously
• multiple “instances” working on the filesystem at the same time increase complexity

Especially for the consume folder, which is monitored continuously, this can result in documents being processed late or not at all.

Why NFS is the better choice here

NFS fits much more cleanly into this architecture:

• native Linux semantics without protocol translation
• reliable Inotify events for Paperless
• unambiguous POSIX permissions (UID/GID)
• clear separation between application (container) and data (host)

Synology Drive can still be used – but selectively and in a controlled manner, for example only for the Scan_Inbox.

Conclusion of this architectural decision

Using NFS here is not an end in itself, but a deliberate architectural decision in order to:

• run Paperless reliably
• enable Drive integration without compromising file events
• keep responsibilities clearly separated

The container remains stateless, the data resides on the host, and Synology Drive is used where it makes functional sense – rather than indiscriminately everywhere.

Target Directory Structure

The storage structure was deliberately divided into three logically separate areas:

• Scan_Inbox – inbox for new documents
• Archive – final, structured archive
• Export – optional export path

This separation simplifies not only configuration, but also maintenance, troubleshooting and future extensions.

Create the Folder Structure (Synology via SSH)

The two shared folders “Paperless Inbox” and “Paperless Archive” should already have been created through the DSM interface. The following SSH configuration only adds the required subfolders.

sudo -i

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

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

This creates a clear logical separation:

New documents arrive in the Paperless Inbox, while archived and exported documents are organised clearly in the Paperless Archive. This makes later maintenance, permission management and backups much easier to understand – particularly on a Synology running multiple services for multiple users.

Set POSIX Permissions Correctly (UID/GID + setgid)

For this example, a neutral UID/GID of 1000:1000 is assumed (typical for many 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 language: Bash (bash)

The setgid bit ensures that newly created files automatically retain the correct group – an important consideration with mixed access from Docker, Drive, scanners and mobile uploads.

POSIX permissions are applied only to the “Paperless Inbox”, because this area is actively monitored and modified by Paperless-ngx. The “Paperless Archive” is used solely as the destination for archive and export data and is not integrated as a Synology Team Drive, avoiding unnecessary metadata and filesystem events.

Avoid DSM Metadata

To avoid unnecessary scans and side effects, Synology DSM-specific folders such as @eaDir or #recycle should not be used in these directories.

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

Docker: Mount NFS as a Volume

The NFS shares are not mounted by DSM “somewhere” directly, but are integrated cleanly as Docker volumes.

Complete docker-compose.yml with NFS Mount

In this variant, only the Paperless Inbox is connected via NFS. The reason is that this folder is actively monitored and sees frequent file changes, for example from scanners or uploads from multiple sources. A clearly separated, externally connected consume directory is therefore appropriate.

The Paperless Archive containing the archive, export and trash directories, by contrast, remains a conventional bind mount directly on the Synology’s local filesystem. Paperless therefore accesses the data directly without a network protocol, while users can continue to access the same shared folders normally via SMB. The type of Docker mount has no effect on whether those shares are accessible to users.

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 language: YAML (yaml)

Changed Lines Highlighted in the YAML

Compared with the original YAML, only two sections are changed or added. These are highlighted in colour in the YAML above.

1. Line 120: Change the inbox to an NFS volume (instead of a bind mount), line 120:

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

2. Lines 146 to 151: New NFS volume for the 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 language: YAML (yaml)

Increase Inotify Limits (Recommended)

Paperless-ngx relies on Inotify to detect new documents immediately. With larger document collections, nested folder structures or NFS mounts, the default limits of many Linux distributions may not be sufficient.

When these limits are reached, Paperless may stop responding reliably to new files – often without a clear error message. Increasing the Inotify limits is therefore recommended for stable and scalable installations.

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 language: Bash (bash)

Synology Drive: Deliberately Limited Integration

A central principle of this setup is the deliberate restriction of Drive integration.

Scan_Inbox via Drive: Practical and Sufficient

The Scan_Inbox is additionally integrated into Synology Drive.
This enables:

• mobile scans (for example via the iOS Files app)
• uploads while away from home
• immediate processing by Paperless

For everyday use, this is the most important use case.

Export Share: Optional

An export share is technically possible, but usually unnecessary in day-to-day operation.
Exports are more of an exception and provide no real additional value through Drive.

Archive: Deliberately a Static Repository

The final archive is a quiet, structured repository:

• no regular user access
• no editing via Drive
• viewing, searching and use take place entirely through Paperless

The actual document viewer is Paperless itself – not the filesystem.

Conclusion

By combining:

• NFS instead of SMB
• a clear directory structure
• a clean Docker setup
• targeted rather than maximum Drive integration

you get a Paperless system that runs reliably, remains maintainable and works well in everyday use. In particular, recognising that not every share needs to be synchronised contributes significantly to the stability and reliability of the system.