Installing Paperless-NGX: Requirements, Deployment Models and the Path to a Working Installation

Paperless-NGX is not a “click and you’re done” tool, but a platform deliberately designed for flexibility and self-hosting. Before dealing with details such as folder structures or automation, it is therefore worth taking a step back and clarifying:

• What requirements does Paperless have?
• In which environments can it be operated?
• What steps does a realistic installation involve?

On a Synology NAS, however, Paperless-NGX can be operated comparatively easily. With the integrated container application (Container Manager) and a basic understanding of Docker containers, a working basic installation can be implemented in a manageable amount of time. A simple configuration is enough to import, process and store documents in a searchable form.

This basic installation is often the starting point. Once a minimal configuration is working, Paperless can be extended step by step – for example with more refined workflows, additional automation or optimised storage connections. Support from AI systems such as ChatGPT can help you understand configuration files, expand options selectively and avoid typical pitfalls. Alongside the functional result, you inevitably gain technical knowledge as well.

This article is intended to provide exactly that orientation – without immediately diving into specialist topics such as NFS, performance tuning or fine optimisation.

More Articles About Paperless-ngx

• What Paperless-NGX Really Delivers in Everyday Use
• Paperless-NGX on Synology: NFS Mounts, Clean Drive Integration and a Stable Docker Setup
• Paperless-NGX Troubleshooting – Common Pitfalls and Quick Checks

What Do You Fundamentally Need for Paperless-NGX?

Paperless-NGX is a server-side application and requires a Linux-based runtime environment. Specifically, that means:

• a Linux system (physical or virtual)
• sufficient storage space for documents
• Docker or Docker Compose (recommended)
• a basic understanding of containers, volumes and networking

The hardware requirements are surprisingly moderate. Paperless is used productively on:

• conventional Linux servers (VM or bare metal)
• NAS systems with Docker support
• mini PCs
• even a Raspberry Pi, provided you have realistic expectations regarding performance and OCR throughput

What matters more than CPU performance is:

• sufficient RAM
• reliable storage
• clean integration of the data directories

Possible Deployment Models

Before choosing an installation path, you should be clear about the deployment model.

1. Self-Hosting on Your Own Hardware

This is the classic approach:

• full control over your data
• maximum flexibility
• slightly more technical effort

Typical environments:

• Linux server
• NAS with Docker (e.g. Synology)
• mini server or Raspberry Pi

2. Running on a NAS (e.g. Synology)

A NAS is a good choice when:

• storage for documents is already available
• Docker is supported
• the system already runs 24/7

I run Paperless-NGX myself on a Synology NAS in containers. This works well technically, but requires a clean setup and a few deliberate architectural decisions.

3. Hosted Paperless Services

There are now providers offering Paperless-NGX as a hosted service. Advantages:

• no need to operate your own server
• quick deployment

Disadvantages:

• ongoing costs
• dependency on the provider
• sensitive documents are stored externally

For some scenarios this is a valid option; for others it is deliberately not.

Here is an overview of hosted Paperless services:

Hosted services are particularly suitable for users who do not want to operate their own server and are prepared to trade some control over infrastructure and data storage for convenience.

Choosing Docker as the Installation Basis

Regardless of the chosen host system, Docker has become the de facto standard for Paperless-NGX. Docker provides:

• reproducible setups
• clean separation of application and data
• easy updates
• clear dependencies (database, Redis, web service)

Especially on systems such as a Synology NAS, Docker is the cleanest way to keep Paperless maintainable over the long term.

Which Components Belong to a Paperless Installation?

A complete Paperless-NGX installation consists of more than “one container”. It typically includes:

• Paperless-NGX web/worker container
• PostgreSQL (database)
• Redis (task queue)
• persistent volumes for:
  • scan inbox (Consume)
  • archive (Media)
  • optional export

This separation is important in order to:

• back up data independently of the container
• perform updates safely
• enable future migrations

The Actual Installation Steps (From Practice)

Based on my experience, the path to a working installation can be roughly divided into the following steps:

1. Prepare the Basic Environment

• install or enable Docker / Docker Compose
• ensure containers are allowed to start automatically
• define a fixed storage location for Paperless data

2. Plan the Directory Structure

Even before the first container starts, you should know:

• where new documents arrive
• where archived documents are stored
• which folders may later need to be accessible externally

A clean structure saves a great deal of time and frustration later.

3. Create the Docker Compose File (Example Compose File)

In this step:

• containers are defined
• dependencies are specified
• environment variables are set
• volumes are mounted

This is where it is decided whether the setup will remain maintainable later. The following example is deliberately “minimal”, but practical. It uses local paths as volumes (without NFS details). Paths and ports can be adapted to your own environment.

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

Practical notes:

• The ./data/... paths can just as easily point to a fixed storage location (for example /volume1/docker/paperless/... on a Synology).
• USERMAP_UID/GID should match your own environment; consistency is what matters most.
• PAPERLESS_OCR_LANGUAGE is useful when German-language documents predominate.

# ------------------------------
# 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 language: Extended Backus-Naur Form (ebnf)

4. First Start and Basic Configuration

After the first start, the tasks are to:

• configure Paperless initially
• create users
• check basic settings (language, OCR, time zone)

At this stage it usually becomes clear quickly whether:

• volumes are mounted correctly
• permissions are correct
• containers communicate cleanly with one another

5. Test the First Documents

Before using the system productively, it is advisable to:

• import a few test documents
• check OCR recognition
• observe classification
• verify archive paths

This allows many later problems to be identified early.

Topics Deliberately Covered Elsewhere

In my view, some aspects deserve their own articles and are therefore only touched on here:

• NFS vs. SMB and clean mounts
• Synology Drive integration
• Security and backup strategies
• Automation rules in detail

Conclusion

Paperless-NGX can be operated on a wide range of platforms – from a Raspberry Pi to a NAS or server. What matters less than the hardware is a well-designed setup. Anyone who, before installation:

• clarifies the deployment model
• understands the components
• assesses the steps realistically

will avoid many of the typical pitfalls. The real strength of Paperless only becomes apparent later in everyday use – but a clean installation is the prerequisite.