Deployn

How to Install Paperless-NGX on Synology NAS with Docker

Learn how to install Paperless-ngx on your Synology NAS the document management system using Docker.

How to Install Paperless-NGX on Synology NAS with Docker-heroimage

CAUTION

Please note that this blog post was originally written in German and has been translated for your convenience. Although every effort has been made to ensure accuracy, there may be translation errors. I apologize for any discrepancies or misunderstandings that may result from the translation and I am grateful for any corrections in the comments or via email.

Introduction to Paperless-ngx Document Management

Paperless-NGX is an open-source document management system (DMS) designed to reduce paper consumption in offices and work environments by enabling electronic document management. It allows users to organize, manage, and access documents from any device and offers features such as Optical Character Recognition (OCR) to make documents digitally searchable. Implementing Paperless-ngx can help reduce paper consumption and enhance efficiency in the work environment.

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.

Getting Started

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.

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.

Set up group for Docker

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

Set up new user

Add this user to the Docker group.

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.

Enable SSH service

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. Turn off SSH service

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.

New Directory

The Docker group needs access rights to the folder.

Group Access Management

The Docker user as well.

User Access Right

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

Paperless Directory

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

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.

Change the permissions on this folder to ensure the Docker user, network scanner, and actual user account receive the necessary permissions.

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

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 on your Synology NAS

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 6.2 and PostgreSQL 14 for the past few weeks (instead of 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.

New Stack

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.

Insert Compose File into Stack

version: "3.6"

networks:
    internal:
        external: false

services:
    broker:
        container_name: paperless-redis
        image: redis:6.2
        # If you prefer to use version 6.0
        # image: redis:6.0
        networks:
            - internal
        volumes:
            # Enter the correct path here
            - /volume1/paperless/redis:/redis
        #  - /volume2/paperless/redis:/redis
        restart: unless-stopped

    db:
        container_name: paperless-db
        image: postgres:14
        # 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

    webserver:
        container_name: paperless
        image: ghcr.io/paperless-ngx/paperless-ngx:latest
        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/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"

    db-backup:
        container_name: paperless-db-backup
        # Possibly adjust the image to match the one above
        image: postgres:14
        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

    # Omit this part if you do not want conversion of Office documents, emails.
    gotenberg:
        container_name: paperless-gotenberg
        image: gotenberg/gotenberg:7
        restart: unless-stopped
        environment:
            CHROMIUM_DISABLE_ROUTES: 1
        command:
            - "gotenberg"
            - "--chromium-disable-javascript=true"
            - "--chromium-allow-list=file:///tmp/.*"
        networks:
            - internal

    tika:
        container_name: paperless-tika
        image: apache/tika:2.3.0
        restart: unless-stopped
        networks:
            - internal

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.

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.

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

New User

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

Selecting Container

Then click on Console.

Console

Now enter python3 manage.py createsuperuser as a command.

Create New User

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

Paperless-ng Image Update

Postgres:14, Redis:6.2, and Gotenberg/Gotenberg:7 can also be updated. Postgres:14 means that the latest image of Postgres with a 14 at the beginning should be used. This can be 14.0 but also 14.1.2 (if it exists).

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 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!

FAQs

What is NGX in Paperless?

NGX stands for Next Generation X. Paperless-NGX is the successor to Paperless-ng which itself is a fork of the original project.

Can I install Paperless-NGX on my Synology NAS?

Yes, you can install Paperless-NGX on your Synology NAS using Docker.

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

Docker Compose is a tool for defining and running multi-container Docker applications. It helps in setting up and configuring the Paperless-NGX environment.

How do I install Paperless-NGX using Docker?

You can install Paperless-NGX using Docker by deploying it through Docker Compose (in this case a Portainer Stack).

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

Portainer is a lightweight management UI that allows you to easily manage your different Docker environments. It can help in managing the Paperless-NGX Docker instance by deploying a stack with multiple containers.

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

You can login to the Paperless-NGX instance by accessing it through your web browser using the specified port and login credentials.

Where can I find the Paperless-NGX Docker image?

You can find the Paperless-NGX Docker image on the official Paperless-NGX GitHub repository.

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

You can consume PDF, PNG, JPEG, TIFF, and GIF documents with Paperless-NGX. Additionally, you can also consume emails and office documents such as *.docx, *.doc, *.odt, *.ppt, *.pptx, *.odp, *.xls, *.xlsx, and *.ods when using Tika/Gotenberg.

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

If you have a question that is not answered here, please feel free to ask it in the comments section below. Don't forget to add some information about your setup (e.g., Synology NAS model, Paperless Version) and the error message or log output if applicable.


This website uses cookies. These are necessary for the functionality of the website. You can find more information in the privacy policy