Deployn

Install Paperless-ngx 3 on a Synology NAS with Docker and Portainer

Install Paperless-ngx 3 on a Synology NAS with Docker Compose in Portainer, including PostgreSQL, Valkey and Tika, folder permissions and a scanner inbox.

Install Paperless-ngx 3 on a Synology NAS with Docker and Portainer hero image
Contents

Paperless-NGX is a powerful, open-source document management system (DMS) designed to help you digitize, organize, and easily search through your important documents. By installing it on a Synology NAS using Docker, you can create a reliable, self-hosted solution protected by the robust features of Docker containers.

This step-by-step guide explains every part of the installation process, including essential prerequisites, creating user accounts, setting up folders, configuring Docker Compose (often managed via Synology Container Manager or Portainer), and more. By the end, you’ll be ready to take advantage of Paperless-NGX’s efficient OCR capabilities, document upload automation, intuitive web interface, and backup options — all on your Synology NAS.

Why Choose Paperless-NGX on Your Synology NAS?

Paperless-NGX is the successor to Paperless-ng, itself a fork of the original Paperless project. It helps to declutter your home or office by providing a centralized repository for digitized documents. Key features include:

  • OCR (Optical Character Recognition) for searching scanned documents
  • A polished web-based interface accessible from any modern browser
  • Optional integration with Tika and Gotenberg to process emails and Office documents
  • Compatibility with common containerization platforms like Docker

Running Paperless-NGX with Docker on a Synology NAS is an excellent way to manage your documents effectively. Docker isolates Paperless-NGX from the rest of your system for improved security and smoother maintenance.

Glossary: Key Terms and Technologies

Term Description
ARM CPU Processor architecture used by some Synology NAS devices.
Caddy An alternative reverse proxy server.
Cloud Sync A Synology service for synchronizing data with cloud storage providers.
Docker A containerization platform for installing and running Paperless-NGX.
Gotenberg A tool for converting documents to PDF.
IMAP Email retrieval protocol, used to optionally fetch and archive email attachments.
Nginx Proxy Manager A reverse proxy solution that can allow access to Paperless-NGX from beyond your network.
OCR (Optical Character Recognition) A technology to identify and extract text from scanned or image-based documents.
Paperless-ng An earlier version of Paperless-NGX.
Paperless-NGX The open-source document management system you will install.
Portainer A user-friendly UI for managing Docker containers.
PostgreSQL Database system for storing Paperless-NGX data (recommended for multiple users).
Valkey An in-memory data store used by Paperless-NGX as a task/message broker.
SMTP The standard protocol for sending emails.
SQLite An alternative embedded database option for Paperless-NGX.
Synology NAS A Network Attached Storage device that can host applications, including Docker containers.

Installation of Paperless-ngx on your Synology NAS using Docker

This guide focuses on installing Paperless-NGX on Synology NAS using Docker. If you’re interested in a Linux server setup, check out my previous guide or my Youtube video. Since Paperless-NGX is now the official successor to Paperless-ng, I’ve moved NAS-specific instructions to this post for clarity and convenience.

Prerequisites for Paperless-NGX Installation

Before getting started, make sure you have the following:

  • A Synology NAS. I use the Synology DS220+ (Amazon affiliate link) with additional 8 GB RAM (Amazon affiliate link). While not strictly necessary, having at least 1 GB RAM is recommended. For heavier workloads, plan on 2 GB or more.

  • Container Manager installed from the Synology Package Center (called Docker up to DSM 7.1). It lets you paste a Compose file into the DSM interface and start it.

  • (Optional) Portainer works as well. The steps for it are included as a second variant below.

  • (Optional) Additionally, you may consider setting up a Nginx Proxy Manager either in the network or installed on the Synology NAS itself in combination with a DNS-Server if you want a customized domain name or remote access.

  • (Optional) An email inbox for fetching attachments automatically via IMAP. Of course, you can also use your own mail server for this purpose. Attachments are loaded, and the email can be automatically moved or deleted.

  • (Optional) A network scanner. I use a Xerox 6515DNI (Amazon affiliate link), which can either send a scan to the email mentioned above address or directly store the file in the NAS (if it doesn’t currently have trouble finding it). This saves the step of manual uploading. If you only want a scanner and not a printer, I recommend the Brother ADS-1700W (Amazon affiliate link).

  • (Optional) A backup strategy, e.g., external storage or cloud services via Synology Cloud Sync. Services such as Google Drive, Microsoft OneDrive, or other WebDAV storage options can be utilized for backup purposes. Of course, something simple like an external hard drive can also be used for backup. Remember, however, that RAID is not a backup.

  • (Optional) An Android smartphone. Useful apps include Paperless and Paperless Share, which make it easier to handle Paperless with an Android smartphone.

Please note that the instructions in this guide specifically apply to Synology NAS, but the document management system Paperless-NGX can also run on NAS from other manufacturers such as QNAP or ASUSTOR, especially if Portainer or Docker support is available and the NAS has an x64 CPU. However, the preparation, such as creating shared folders, may differ slightly.

Resource Usage

After I started the containers, I can see the following memory usage in the Container Manager:

Service RAM
Gotenberg 42 MB
Paperless 904 MB
Postgres 90 MB
Postgres-Backup 20 MB
Valkey 20 MB
Tika 234 MB

Preparing Your Synology NAS for Installation

Creating New User and Group for Docker

For security, it’s best practice not to run Paperless-NGX under your NAS administrator account.

In Synology DSM, create a new user group named “docker.”

Set up user group for Docker in Synology DSM

Create a new user, for example “paperless,” and add it to the “docker” group.

Set up new ‘paperless’ user in Synology DSM

Add ‘paperless’ user to the Docker Group

To find the user ID and the group ID of the “docker” group you do not need SSH. A one-time task in the Task Scheduler does it.

Open the Control Panel and then the Task Scheduler.

Control Panel with Task Scheduler

Click Create and choose Triggered Task → User-defined script. On the “General” tab enter a name (for example find-id), select root as the user and untick “Enabled”. This way the task only runs when you start it yourself.

Create task: name, user root, not enabled

On the “Task Settings” tab, enter this line under “User-defined script”:

Terminalbash
id docker

Enter the script

Confirm with OK. DSM warns about root rights and asks for your password. It does that for every root script. Then select the task, click Run, and afterwards Action → View Result. You will see something like this:

Task result with user ID and group ID

Terminalbash
uid=1027(docker) gid=100(users) groups=100(users),65536(docker)

In this example, note down 1027 as the UserID (after uid=) and 65536 as the GroupID (the number in front of (docker) after groups=). Your numbers will differ. You can delete the task afterwards.

Setting Up New Folders

Create a new shared folder for Paperless-NGX (e.g., “paperless”). Turn OFF data checksum for better performance (Synology recommends against enabling checksums for databases or services with frequent writes).

To ensure the quality of services, we recommend not enabling data checksum if the shared folder is used for the following services:

  • Hosting databases or virtual machines
  • Storing video recordings from Surveillance Station
  • Running services that require small or random write operations

Create a shared folder: enter the name, turn off the recycle bin

Enter the name paperless in the wizard. You do not need the recycle bin here. Confirm all further pages with Next until the folder is created. The only important point is that the data checksum stays off.

Data checksum stays off

Set permissions so that both the “docker” group and the new “paperless” user have full read/write access.

Group Access Management

User Access Right

Within the “paperless” folder, create six subfolders: data, db, db-backup, export, media, and valkey.

Paperless Directory

Create an “Inbox” folder in your user’s home directory for automatic document consumption: /volume1/homes/username/Paperless-Inbox

Paperless Inbox

Alternatively, you can consider creating a user account on the DiskStation for the network scanner and creating the Inbox folder in that user’s home directory. This way, the scanner does not need access to the main account, yet it is still possible to scan to this folder. Or you can create an additional shared folder if manual file placement is desired.

Give appropriate permissions to your new Paperless user, the network scanner (if used), or any other accounts needing write access.

Paperless Inbox Permissions

With this, I have prepared everything necessary.

Patrick has pointed out to me that the Inbox folder does not behave correctly as long as Synology Drive is in use.

Currently, the Synology Drive server cannot detect file changes in a folder attached to a Docker container. Synology Drive Server, Client, and ShareSync cannot synchronize files with Docker-attached folders. The limitation is mentioned here and here. There is currently no way to make it work properly. Unfortunately, no binary program could also be triggered for this case. Instead, files must be deleted directly from the host system rather than from the container.

Firewall Configuration

If you use a restrictive firewall on your NAS, ensure container-to-container communication is allowed. Double-check IP addresses assigned by Docker for your containers and update firewall settings accordingly, or allow the entire internal IP range.

Installing Paperless-ngx with Docker Compose

Paperless supports PostgreSQL and SQLite for data storage, but using PostgreSQL is recommended due to its capabilities in handling multiple simultaneous operations. The installation involves setting up Paperless-ngx with a PostgreSQL database along with a broker. I use Valkey for that, a Redis-compatible fork. It brings tasks from the web server to the task scheduler.

The stack in this guide uses Paperless-ngx 3.4, Valkey 9 and PostgreSQL 18. Additionally, I am starting a container that automatically creates a database dump for backup every week. Furthermore, Tika/Gotenberg, to process not only PDFs but also office documents (such as “.docx”, “.doc”, “.odt”, “.ppt”, “.pptx”, “.odp”, “.xls”, “.xlsx”, and “.ods”).

Since version 1.11.0 of Paperless, not only are attachments of emails processed but also the text of the email itself can be archived with Gotenberg.

The Compose File

The file below starts all containers at once. I marked the places you need to change in the comments. Adjust the file before you paste it.

yaml
networks:
    internal:
        external: false

services:
    broker:
        container_name: paperless-valkey
        image: valkey/valkey:9
        networks:
            - internal
        volumes:
            # Change to your correct path(s)
            - /volume1/paperless/valkey:/data
            # - /volume2/paperless/valkey:/data
        restart: unless-stopped
        user: "1027:65536" # Your Paperless user/group IDs
        sysctls:
            - net.core.somaxconn=511
        cap_add:
            - SYS_RESOURCE
        deploy:
            resources:
                limits:
                    memory: 256M
        healthcheck:
            test: ["CMD", "valkey-cli", "ping"]
            interval: 30s
            timeout: 5s
            retries: 3

    db:
        container_name: paperless-db
        image: postgres:18
        # Do not simply upgrade or downgrade, as the database will not load anymore.
        networks:
            - internal
        restart: unless-stopped
        volumes:
            # Enter the correct path here
            - /volume1/paperless/db:/var/lib/postgresql
        #  - /volume2/paperless/db:/var/lib/postgresql
        environment:
            POSTGRES_DB: paperless
            POSTGRES_USER: paperless
            POSTGRES_PASSWORD: your-database-password # Replace with your password
        deploy:
            resources:
                limits:
                    memory: 512M
        healthcheck:
            test: ["CMD", "pg_isready", "-U", "paperless"]
            interval: 30s
            timeout: 5s
            retries: 3
        logging:
            driver: "json-file"
            options:
                max-size: "10m"
                max-file: "5"

    webserver:
        container_name: paperless
        image: ghcr.io/paperless-ngx/paperless-ngx:3.4
        networks:
            # If the Proxy Manager is on the Synology, then the network from it should also be entered here, instead of opening a port.
            - internal
        restart: unless-stopped
        depends_on:
            - db
            - broker
        ports:
            # Delete this part if the Proxy Manager is on the Synology.
            # Otherwise, select a port here that is free.
            - 8010:8000
            # - 8011:8000
            # - 8012:8000
        healthcheck:
            test: ["CMD", "curl", "-f", "http://localhost:8000"]
            interval: 30s
            timeout: 10s
            retries: 5
        volumes:
            # Enter the correct paths here
            - /volume1/paperless/data:/usr/src/paperless/data
            - /volume1/paperless/media:/usr/src/paperless/media
            - /volume1/paperless/export:/usr/src/paperless/export
            - /volume1/homes/username/Paperless-Inbox:/usr/src/paperless/consume
        environment:
            PAPERLESS_REDIS: redis://broker:6379
            PAPERLESS_DBHOST: db
            PAPERLESS_DBPASS: your-database-password # This is the password from above
            USERMAP_UID: 1027 # UserID for the docker user
            USERMAP_GID: 65536 # GroupID for the docker user
            PAPERLESS_OCR_LANGUAGE: deu+eng
            # Required: enter your own long random key here. Paperless does not start without it.
            PAPERLESS_SECRET_KEY: a-long-random-key
            # Enter your own domain behind localhost here if you are using a proxy host, otherwise delete this environment variable.
            PAPERLESS_ALLOWED_HOSTS: "localhost,paperless.domain.de"
            PAPERLESS_TIME_ZONE: Europe/Berlin
            # Adjust here if you want a different folder structure
            PAPERLESS_FILENAME_FORMAT: "{created_year}/{correspondent}/{title}"
            # Omit the next three lines if you do not want to use Tika/Gotenberg.
            PAPERLESS_TIKA_ENABLED: 1
            PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000/ #or http://gotenberg:3000/forms/libreoffice/convert#
            PAPERLESS_TIKA_ENDPOINT: http://tika:9998
            PAPERLESS_URL: "https://paperless.domain.de" # Remove or adjust if not using a proxy
        deploy:
            resources:
                limits:
                    memory: 2048M
        logging:
            driver: "json-file"
            options:
                max-size: "10m"
                max-file: "5"

    db-backup:
        container_name: paperless-db-backup
        # Possibly adjust the image to match the one above
        image: postgres:18
        volumes:
            # Enter the correct path here
            - /volume1/paperless/db-backup:/dump
            - /etc/localtime:/etc/localtime:ro
        environment:
            PGHOST: db
            PGDATABASE: paperless
            PGUSER: paperless
            PGPASSWORD: your-database-password # This is the password from above
            BACKUP_NUM_KEEP: 10
            BACKUP_FREQUENCY: 7d # Every 7 days, can be adjusted
        entrypoint: |
            bash -c 'bash -s <<EOF
            trap "break;exit" SIGHUP SIGINT SIGTERM
            sleep 2m
            while /bin/true; do
              pg_dump -Fc > /dump/dump_\`date +%d-%m-%Y"_"%H_%M_%S\`.psql
              (ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.psql)|sort|uniq -u|xargs rm -- {}
              sleep $$BACKUP_FREQUENCY
            done
            EOF'
        networks:
            - internal
        deploy:
            resources:
                limits:
                    memory: 256M

    # Omit this part if you do not want conversion of Office documents, emails.
    gotenberg:
        container_name: paperless-gotenberg
        image: gotenberg/gotenberg:8.38
        restart: unless-stopped
        environment:
            CHROMIUM_DISABLE_ROUTES: 1
        command:
            - "gotenberg"
            - "--chromium-disable-javascript=true"
            - "--chromium-allow-list=file:///tmp/.*"
        networks:
            - internal
        deploy:
            resources:
                limits:
                    memory: 512M
        healthcheck:
            test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
            interval: 30s
            timeout: 5s
            retries: 3

    tika:
        container_name: paperless-tika
        image: apache/tika:3.3.1.0
        restart: unless-stopped
        networks:
            - internal
        deploy:
            resources:
                limits:
                    memory: 512M

In the comments, I have indicated the parts that need adjustment. The paths to the directories should be changed. In particular, the path to the Paperless-Inbox will be different.

You can modify the images. I do not recommend to use latest as the image tag. Instead, use a specific version. This way, you can be sure that the image will not change unexpectedly. You can look here for the newest Paperless image tags. If you use 2.7 as the image tag, you will get the latest version of Paperless-ngx 2.7 (2.7.0 or 2.7.1).

The database password needs to be changed in three places.

PAPERLESS_ALLOWED_HOSTS should be removed if you do not want to access Paperless via a proxy host. Otherwise, it ensures that only the Synology NAS has access and devices accessing Paperless through the registered domain.

You must always set PAPERLESS_SECRET_KEY. Paperless-ngx 3 does not start otherwise and stops with the message PAPERLESS_SECRET_KEY is not set or is the default 'change-me' value. The key is any long text of letters and digits, I recommend at least 32 characters. You do not need to remember it, but do not change it later, or all logged-in users get signed out.

Enter the numbers from the Task Scheduler at user: (Valkey) and at USERMAP_UID and USERMAP_GID (Paperless). Without them the containers lack access rights to the folders.

For PAPERLESS_FILENAME_FORMAT, you have the following variables available:

yml
- { asn }: The archival serial number of the document
- { correspondent }
- { document_type }
- { tag_list }: All tags separated by a comma
- { title }: Name of the document
- { created }
- { created_year }
- { created_month }: Month (1–12)
- { created_day }: Day (1–31)
- { added }: Time when the document was added to Paperless
- { added_year }
- { added_month }
- { added_day }

The files will be stored in the media folder according to the chosen schema. With the format chosen in the example above, my 2020 tax assessment would be stored in the directory “/media/documents/originals/2021/tax-office” (or similar). However, if I used {created}_{title}instead, it would not be stored in a subfolder, but the name of the file would have the prefix with the creation date (e.g., 20211217_nameofthefile.pdf). It is crucial to avoid touching this structure manually! If you want to change it afterwards, you must run the document_renamer command in the Paperless container.

You can omit the part with Tika and Gotenberg if you have limited system resources. Then PDF documents, PNG images, JPEG, TIFF and GIF images can still be processed.

Further configuration options can be found in the documentation.

Variant A: Project in Container Manager

Open Container Manager from the main menu, click Project on the left and then Create.

Container Manager without projects

  1. Enter paperless as the Project name.

    Create project dialog

  2. Click Set Path next to Path. Select the shared folder paperless, click Create folder, create a subfolder compose and select it. Container Manager stores the Compose file there. Do not use data, db or the inbox, or the file ends up between your documents.

    Choose the project folder

  3. Set Source to Create docker-compose.yml. Copy the adjusted code from the section “The Compose File”, click into the text field and paste it with Ctrl+V (Cmd+V on a Mac). Red notes below the field point to errors in the text, for example a shifted indentation.

    Pasted Compose file

  4. Click Next. Leave the “Web Portal” page empty and click Next again. In the summary, keep “Start the project after it is created” ticked and click Done.

    Summary

  5. A terminal window opens in which DSM downloads the images. The first time this is several hundred megabytes and can take a few minutes. It is finished when Exit Code: 0 appears at the bottom. Then click Close.

    Terminal while the project starts

  6. In the project paperless, open the Container tab. All containers should show a green dot. On the first start Paperless sets up the database, so the page is unreachable for about a minute and the Paperless container shows high CPU load.

    All containers are running

If a container does not run or restarts all the time, the section “If something does not start” below helps.

Variant B: Stack in Portainer

Open Portainer.

Select “Stacks” from the menu.

Click “Add Stack.”

In “Web editor,” paste the Docker Compose file shown below.

New Stack

If “Add Stack” is missing, ensure you’re in the local environment and running the portainer/portainer-ce image instead of portainer/portainer.

Below is an example Compose file. Adjust folder paths, passwords, user/group IDs, and any optional variables to suit your needs.

Insert Compose File into Stack

Click “Deploy the stack” and wait while the images are downloaded. In Portainer, confirm all containers show either “healthy” or “running.”

The deployment may take some time if all images need to be downloaded. After waiting a bit, all containers should be started.

Container Healthcheck

Generator

Docker Compose Generator

Adjust the values on the left, the finished docker-compose.yml builds up on the right. The preview updates with every input.

General

Paths on the NAS, reachability and credentials.

Warning

Password and secret key still use the example values. Replace them with “New” before starting.

Versions

Fixed tags instead of latest, so an update stays a decision.

Services and permissions

UID and GID of the NAS user who owns the folders.

Filename format

Controls how Paperless stores files in the archive. Reorder with the arrows, pick a separator per component.

  1. 1Created year
  2. 2Correspondent
  3. 3Title

More components

Format{{created_year}}/{{correspondent}}/{{title}}
Example2024/Acme Corp/Q4 Report.pdf
docker-compose.yml5 services
1# docker-compose.yml — Paperless-ngx on the NAS2networks:3  paperless_network:4    name: paperless_network5    external: false6 7services:8  broker:9    container_name: paperless-valkey10    image: valkey/valkey:911    restart: unless-stopped12    networks:13      - paperless_network14    volumes:15      - /volume1/paperless/valkey:/data16    user: "1010:65555"17 18  db:19    container_name: paperless-db20    image: postgres:1821    restart: unless-stopped22    networks:23      - paperless_network24    volumes:25      - /volume1/paperless/db:/var/lib/postgresql26    environment:27      POSTGRES_DB: paperless28      POSTGRES_USER: paperless29      POSTGRES_PASSWORD: "changeMeIamAPassword"30 31  webserver:32    container_name: paperless33    image: ghcr.io/paperless-ngx/paperless-ngx:3.434    restart: unless-stopped35    depends_on:36      - db37      - broker38      - gotenberg39      - tika40    networks:41      - paperless_network42    ports:43      - 8010:800044    volumes:45      - /volume1/paperless/data:/usr/src/paperless/data46      - /volume1/paperless/media:/usr/src/paperless/media47      - /volume1/paperless/export:/usr/src/paperless/export48      - /volume1/homes/user/Paperless-Inbox:/usr/src/paperless/consume   # adjust this49    environment:50      PAPERLESS_REDIS: redis://broker:637951      PAPERLESS_DBHOST: db52      PAPERLESS_DBPASS: "changeMeIamAPassword"53      USERMAP_UID: 101054      USERMAP_GID: 6555555      PAPERLESS_SECRET_KEY: "changeMeIamASecretKey"56      PAPERLESS_TIME_ZONE: Europe/Berlin57      PAPERLESS_OCR_LANGUAGE: deu+eng58      PAPERLESS_FILENAME_FORMAT: "{{created_year}}/{{correspondent}}/{{title}}"59      PAPERLESS_URL: "https://paperless.domain.com"60      PAPERLESS_ALLOWED_HOSTS: "localhost,paperless.domain.com"61      PAPERLESS_TIKA_ENABLED: 162      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000/63      PAPERLESS_TIKA_ENDPOINT: http://tika:999864 65  gotenberg:66    container_name: paperless-gotenberg67    image: gotenberg/gotenberg:8.3868    restart: unless-stopped69    networks:70      - paperless_network71    environment:72      CHROMIUM_DISABLE_ROUTES: 173    command:74      - "gotenberg"75      - "--chromium-disable-javascript=true"76      - "--chromium-allow-list=file:///tmp/.*"77 78  tika:79    container_name: paperless-tika80    image: apache/tika:3.3.1.081    restart: unless-stopped82    networks:83      - paperless_network

Nginx Proxy

In the meantime, you can set up a proxy host for Paperless. Here, I enter my Synology NAS address and the chosen port number. Additionally, I can limit access to local by using an access list.

Proxy Host

If the Nginx Proxy Manager is on the NAS and the web server is in the same Docker network, you can enter the containername of the web server here as well as port 8000.

After obtaining an SSL certificate for the proxy host, I added a few additional settings in “Custom Nginx Configuration”.

Custom Nginx Configuration

client_max_body_size 20M;
proxy_redirect off;

This ensures that larger files (20 MB) can also be loaded via Paperless’ web interface.

Caddy Proxy

Alternatively, when using an external device, you have many options instead of Nginx Proxy Manager. For example, you can use Caddy as a reverse proxy. Here is an example of a Caddyfile:

caddy
{
    acme_ca https://acme-v02.api.letsencrypt.org/directory
    email   mail@domain.com
}

paperless.example.com {
    @blocked not remote_ip private_ranges
    respond @blocked 403
    reverse_proxy 192.168.1.123:8010
}

First Start and User Account

Open Paperless in your browser: http://{NAS-IP-address}:8010 (the port is in the Compose file under ports). With a proxy host, use your domain instead.

On the first visit, Paperless-ngx 3.4 shows a registration page. The first account gets administrator rights. Enter a username, a password and optionally an email address, then click Register.

Registering the first user

After that you are signed in and see the start page.

Paperless-ngx start page

Alternative: Create the Account on the Console

If Paperless shows no registration page, an account already exists, or you prefer a command, use the console of the Paperless container. Here with Portainer:

In Portainer, select the “paperless” container (your Paperless-NGX service).

Selecting Container

Click “Console.”

Console

Run python3 manage.py createsuperuser as a command.

Create New User

Provide a username, email address, and password when prompted.

If Something Does Not Start

If Container Manager shows a container in grey or restarting all the time, check the log first: Container → double-click the container → Log tab. The important lines are usually at the top. I ran into two errors with this stack.

Paperless does not start and the log mentions PAPERLESS_SECRET_KEY. The key is missing in the Compose file, see above.

Error message about the missing secret key

Valkey does not start and the log says directory '/data' is not writable by current user (999). Then the user: line with your user ID and group ID is missing for Valkey, or the docker user has no write permission on the valkey folder.

Error message about the Valkey folder

Do not change the configuration while a container keeps restarting. Stop the project first (open the project, Stop). Then edit the text on the YAML Configuration tab, click Save and choose Create and start project. The tab is read-only while the project runs.

If the project hangs anyway (Stop and Clean do nothing), you can remove the containers and the network with a Task Scheduler task. Create it like the user ID task above, with user root and not enabled, and enter this script:

Terminalbash
docker rm -f $(docker ps -aq --filter name=paperless)
docker network rm paperless_internal

The filter matches every container whose name contains paperless. Check in the container list first that only containers of this stack have such a name. Your documents and settings stay in place because they live in the folders outside the containers.

Archiving with Paperless-ngx on your Synology NAS

Streamline Filing with Paperless

Seamlessly archive your documents by simply dragging and dropping files into Paperless’ web interface. Alternatively, use the designated Paperless Inbox folder, or send emails directly if your admin settings are configured.

If Tika and Gotenberg are set up, it should also be possible to upload a *.docx document, among others. If there are errors, it could be, for example, because the Synology DiskStation has an ARM CPU. In this case, different images are needed.

Enhance Document Retrieval with Metadata

Effortlessly locate documents later by editing their metadata post-upload.

  • Title: The title of the document

  • Archive Serial Number: Particularly important for documents also filed in hard copy. You can write a number on them before scanning them and then place them in a folder. This makes it possible to find the physical receipt later with Paperless.

  • Correspondent: Identify the creator or recipient; broader categories work well too. This means that if I receive an invoice from Netcup (Affiliate Link) , Netcup is the correspondent. Sometimes I have thought about grouping a few correspondents together. For example, the tax office, trade office, etc., could be grouped under “State Authority”.

  • Document Type: Here, I would enter the document type, such as invoice, report, manual, contract, miscellaneous, etc. I put documents into Miscellaneous until I think a type occurs more frequently, and it would make sense to separate them. The insurance policy would then be found under contract. Correspondence with the insurance, I would put it under Miscellaneous or Notification as long as it does not change the agreement.

  • Tags: Here, you can enter several filters for the document. For example, the document’s recipient, what subject the paper has and possibly also which year it concerns. Probably important are also such tags as “Tax”, if it affects taxes or “Work”, if the documents have to do with work (so both employment contracts as well as payroll or a simple letter). Everything that has to do with my business gets the tag Business. Sometimes, I also have year numbers as a tag when, for example, I receive a document in 2022 that refers to 2021; then it gets the label 2021.

With this, I am pretty satisfied so far. In the end, everyone has to decide for themselves. Fortunately, OCR also helps you find the information you are looking for.

PDF Viewer

Paperless-NGX includes an optional built-in PDF viewer. Enable it in the Paperless-NGX settings for convenient browser-based file previews.

Keeping Paperless-NGX Updated

Finally, it’s important to keep your Paperless instance or other containers updated by regularly checking for the latest versions and performing necessary updates. The latest version of Paperless can be found here.

The currently installed version can be seen at the bottom left in the Paperless-ngx UI. Before updating, I recommend creating a backup. The other containers can also be updated.

Simply re-pull the image “ghcr.io/paperless-ngx/paperless-ngx:latest” or “ghcr.io/paperless-ngx/paperless-ngx:2.14” in Portainer’s Image Menu.

Paperless-ng Image Update

Valkey and Gotenberg can also be updated. Never change the Postgres major version in the tag alone (for example from 18 to 19), because the database will not load without a migration. How to migrate is covered in this post.

Image Update

If a new image exists, the original gets the tag <none>.

Now, all you have to do is restart the stack once by selecting Stack, pressing “Stop this stack”, and then “Start this stack”.

Update: Nowadays, it’s even faster if you navigate in Portainer to the Stack Editor of Paperless and press the button “Update the stack”. Then you can select the option “Re-pull image and redeploy”.

Backing up Paperless

For a backup, the folders db-backup (database), media (archived PDF documents), and data (settings) need to be secured. This can be done manually. But you could also use Cloud Sync from the Package Center.

Cloud Sync

Here, you can create three tasks.

Cloud Sync Task

This will automatically sync these folders with the set service.

Document Exporter

Paperless-NGX makes it easy to move your documents between Paperless instances:

Step 1: Create a new export folder in Synology’s Paperless directory, for example, named export.

Step 2: Use Portainer to run the document_exporter ../export command in the Paperless container.

Step 3: Verify the export folder for your files after some minutes.

Step 4: Set up a new Paperless instance.

Step 5: Copy the entire export folder to the new Paperless directory.

Step 6: Run document_importer ../export via Portainer in the new setup.

Step 7: Confirm the import success.

Frequently asked questions

What is NGX in Paperless?

NGX stands for Next Generation X. Paperless-NGX is the successor to Paperless-ng, originally a fork of Paperless.

Can I install Paperless-NGX on my Synology NAS?

Yes, you can install Paperless-NGX on a Synology NAS by using Docker, Portainer, and a Docker Compose file.

What is Docker Compose and how is it related to Paperless-NGX?

Docker Compose is a tool that defines and runs multi-container Docker applications. It simplifies configuring Paperless-NGX with services like PostgreSQL, Valkey, and optional tools like Gotenberg and Tika.

How do I install Paperless-NGX using Docker?

Use a Docker Compose file (e.g., through Portainer 'Stacks') to deploy containers for Paperless, PostgreSQL, Valkey, and optionally Tika/Gotenberg.

What is Portainer and how does it help with managing Docker?

Portainer is a lightweight management UI that simplifies the deployment and administration of Docker containers through a browser-based interface.

How do I login to the Paperless-NGX instance on my Synology NAS?

Access your NAS IP address and mapped port in a web browser (e.g., `http://192.168.1.123:8010`), then use the superuser credentials you created.

Where can I find the Paperless-NGX Docker image?

Paperless-NGX maintains Docker images on GitHub Container Registry. You can find version tags at the Paperless-NGX GitHub repository.

What are the document types that I can consume with Paperless-NGX?

By default, it supports PDF, PNG, JPEG, TIFF, and GIF. With Tika/Gotenberg, it can also handle *.docx, *.doc, *.odt, *.ppt, *.pptx, *.odp, *.xls, *.xlsx, *.ods, and email attachments.

I have a question that is not answered here. What should I do?

Feel free to leave a comment below or reach out via email. Include details about your Synology model, Paperless version, error messages, or logs for assistance.

Conclusion

Paperless-NGX offers an efficient, self-hosted solution for digitizing and managing your documents. By installing it on a Synology NAS with Docker and Portainer, you can maintain tight control over your data and automate tedious tasks like scanning, file conversion, and metadata organization.

If you have tips or questions about your setup — from security and performance optimizations to backup strategies — please share them in the comments below. Happy archiving!

As an Amazon Associate I earn from qualifying purchases.

Share
XRedditEmail
Back to all posts

Changelog

  1. Stack updated to Paperless-ngx 3.4, Tika 3.3.1.0 and Gotenberg 8.38, Redis replaced with Valkey, sample password and key replaced with placeholders, PostgreSQL migration note added. Installation now also covers Container Manager instead of Portainer only, user ID without SSH via Task Scheduler, PAPERLESS_SECRET_KEY marked as required, first user created on the registration page, troubleshooting added, screenshots added.

More from this series

Comments