How to Install Paperless-NGX on Synology NAS with Docker

Installing Paperless-NGX on your Synology NAS using Docker is a great way to run this powerful open-source document management system on your home server. This step-by-step guide walks you through the process of setting up Paperless-NGX in a Docker container, making it easy to digitize, organize and search all your important documents.

Introduction to Paperless-ngx Document Management

Paperless-NGX is an open-source document management system that helps reduce paper clutter by digitizing and organizing your documents. It offers powerful features like OCR (Optical Character Recognition) to make your scanned documents searchable, and a web-based interface to access your documents from anywhere.

Running Paperless-NGX in a Docker container on your Synology NAS is a convenient way to set up your own self-hosted document archive. Docker simplifies the installation process and keeps Paperless-NGX isolated from the rest of your system for better security and easier maintenance.

Glossary: Key Terms and Technologies

Installation of Paperless-ngx on your Synology NAS using Docker

I previously published a guide for installing on a Linux server in the blog. However, due to some clutter and the recent release of the first official version of Paperless-NGX as the successor to Paperless-ng, I have moved the relevant part for installing on a Synology NAS to this blog post. Here, I will walk you through the process of installing Paperless-ngx using Docker on a Synology NAS.

Prerequisites

Before installing Paperless-NGX on your Synology NAS, ensure that you have the following prerequisites in place:

To begin, you will need a Synology NAS. I personally use a Synology DS220+(Amazon Affiliate-Link) with additional 8 GB RAM(Amazon Affiliate-Link). While this much RAM is not essential, at least 1 GB is recommended. However, for processing many documents with OCR and uploading and converting Docx documents with Tika and Gotenberg, it is better to have 2 GB.

You will also need Docker from the package center and Portainer installed as described here on the Synology NAS. We want to install Paperless in a Docker container. Portainer simplifies the installation and container management by providing a graphical interface. I won’t explore other options (Compose via SSH or execution via task scheduler, etc.) here.

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 is installed and the NAS has an x64 CPU. However, the preparation, such as creating shared folders, may differ slightly.

(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 to allow access to Paperless via a specified domain name. The proxy server can also enable external access if desired.

(Optional) An email address that can be scanned by Paperless is also optional for automatically archiving attachments from emails. 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) 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) Storage for backups. 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) Android smartphone. There are two apps Paperless and Paperless Share, which make it easier to handle Paperless with an Android smartphone.

System Resources

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

Preparing for Installation of Paperless-ngx on your Synology NAS

Creating New User and Group

For security reasons, you may not want to use your administrator account to start the Paperless container. In this case, create a “docker” group.

Then create a new user. You can create a “paperless” user to assign rights more precisely.

Add this user to the Docker group.

You need to find out the ID of the newly created user and the “docker” group. To do this, temporarily enable SSH and connect to the NAS via any terminal.

ssh adminusername@{nas-ip-address}

First, I want to find out the UserID of the user docker.

id docker

You should see something like:

uid=1010(docker) gid=100(users) groups=100(users),65555(docker)

In this case, note down 1010 as UserID and 65555 as GroupID.

exit

Also, turn off SSH again.

Setting Up New Folders

Create a new shared folder without enabling data checksum.

Synology writes the following about enabling data checksum:

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

I’m leaving out the checksum check, even though it won’t be a database receiving many write operations in this case.

The Docker group needs access rights to the folder.

The Docker user as well.

Six subfolders will be created in the paperless folder: data, db, db-backup, export, media, and redis.

Additionally, create the folder in the home directory for automatic document extraction by Paperless.

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.

Change the permissions on this folder to ensure the Docker user, network scanner, and actual user account receive the necessary 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

It is important to ensure that the containers being created can communicate with each other. If a restrictive firewall is set up, it is recommended to either allow the full internal IP range right away or to check which IP addresses are used by the containers after installation. Otherwise, the containers are not able to communicate with each other, so the paperless container cannot find the database container.

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 Redis broker. Redis is responsible for bringing tasks from the web server to the task scheduler.

I have been using Paperless-ngx with Redis 7.0 and PostgreSQL 16 for the past few weeks (instead of the origin 6.0 and 13). It ran stable and without any problems. Therefore, this time, I am using these newer versions. 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.

We can access Portainer and start with the installation.

New Stack (Docker-Compose)

Under Stacks, a new stack can now be added.

If this menu item is missing, you should make sure to select the local environment and run Portainer with the image portainer/portainer-ce instead of portainer/portainer.

You can proceed with creating a new stack in Portainer using a Docker Compose file.

networks:
    internal:
        external: false

services:
    broker:
        container_name: paperless-redis
        image: redis:7
        # If you prefer to use version 6.0
        # image: redis:6.0
        networks:
            - internal
        volumes:
            # Enter the correct path here
            - /volume1/paperless/redis:/data
        #  - /volume2/paperless/redis:/data
        restart: unless-stopped
        user: "1010:65555" # UserID and GroupID for the docker user
        sysctls:
            - net.core.somaxconn=511
        cap_add:
            - SYS_RESOURCE
        deploy:
            resources:
                limits:
                    memory: 256M
        healthcheck:
            test: ["CMD", "redis-cli", "ping"]
            interval: 30s
            timeout: 5s
            retries: 3

    db:
        container_name: paperless-db
        image: postgres:16
        # If you prefer to use version 13 of PostgreSQL
        # image: postgres:13
        # 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/data
        #  - /volume2/paperless/db:/var/lib/postgresql/data
        environment:
            POSTGRES_DB: paperless
            POSTGRES_USER: paperless
            # Use a different password here
            POSTGRES_PASSWORD: xzdN19DTd3CxWOuXP6eSyfhB19HRAx
        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:2.9
        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: xzdN19DTd3CxWOuXP6eSyfhB19HRAx # This is the password from above
            USERMAP_UID: 1010 # UserID for the docker user
            USERMAP_GID: 65555 # GroupID for the docker user
            PAPERLESS_OCR_LANGUAGES: eng deu
            # Enter a random key here if you want to make Paperless accessible from outside.
            PAPERLESS_SECRET_KEY: C3Q2dLkVPqZWDKTXgkHwWhJ6jk8XqAbeDmDZjCxvb3c2jXl6pTGQXqJFqEkS9umFmXrk4WmzT8rlwjqWan6A2G54Q5IgraBv96CS
            # 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
            PAPERLESS_OCR_LANGUAGE: deu
            # 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
            # Set the following line if you are using a proxy server.
            PAPERLESS_URL: "https://paperless.domain.de"
        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:16
        volumes:
            # Enter the correct path here
            - /volume1/paperless/db-backup:/dump
            - /etc/localtime:/etc/localtime:ro
        environment:
            PGHOST: db
            PGDATABASE: paperless
            PGUSER: paperless
            PGPASSWORD: xzdN19DTd3CxWOuXP6eSyfhB19HRAx # 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
        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:2.9.2.1
        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. The PAPERLESS_SECRET_KEY also needs to be changed. You can comment or delete the line if you do not plan to operate Paperless publicly. The key can be random.

The User ID (UID) and Group ID (GID) should be changed (otherwise, access rights to the folders are not guaranteed).

For PAPERLESS_FILENAME_FORMAT, you have the following variables available:

- { 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.

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

In the Stack they should be marked as healthy or running (for those without a healthcheck).

Generator

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.

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”.

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:

{
    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
}

New User

Finally, we need a user account in Paperless. To do this, I click on the paperless container in Portainer.

Then click on Console.

Now enter python3 manage.py createsuperuser as a command.

Next I will be asked for a username, password, and email address.

Now it should be possible to log in to Paperless. If you have not set up a proxy host, Paperless is accessible under the NAS IP address, including the selected port (8010).

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

In the settings, you can also turn on the PDF web viewer. At least under Chrome, it has worked reliably so far.

Updating the Paperless-ngx on your Synology NAS container

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.7” in Portainer’s Image Menu.

Postgres:16, Redis:7, and Gotenberg/Gotenberg:8 can also be updated. Postgres:16 means that the latest image of Postgres with a 16 at the beginning should be used. This can be 16.0 but also 16.1.2 (if it exists). Don’t update the major version of Postgres (e.g. Postgres:17) without migration.

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.

Here, you can create three tasks.

This will automatically sync these folders with the set service.

Document Exporter

Paperless-ngx also has a document exporter with which all stored documents can be exported and imported into another Paperless.

The procedure is roughly as follows:

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.

The setup is now complete. If you have any questions or suggestions for improvement, feel free to share them in the comments. I would also be interested to know how you archive your documents. Happy archiving!