Setting Up Paperless-ngx on Unraid

In this post, I’ll guide you through the installation of Paperless-ngx on your Unraid system. Paperless-ngx is an essential document management system that helps users easily manage and automate the storage, organization, and retrieval of scanned documents, PDFs, and more. This is especially useful for automating the handling of invoices, bills, and important paperwork.

Paperless-ngx offers several advantages, such as OCR (Optical Character Recognition) to convert scanned documents into searchable PDFs, tagging for easy categorization, and email integration for automated document processing. With these features, it’s a great tool for both personal and professional document management. You can read more about Paperless-ngx and how I’ve personally integrated it with my home setup in the following posts:

Requirements

Although you’re more than welcome to just read this post for general knowledge, check out my recommendations for what you need to have, in order to be able to fully use the provided information.

Familiarity with terms like "array" and "pool" for better understanding.
Knowing your way around a windows file system, creating folders, copying files, etc.
An Unraid system that is up and running, with at least one array. An added pool (previously called Cache in older versions) is optional but highly recommended.

Do you have what’s needed?

What Are Unraid Apps?

On Unraid, applications are typically installed as Docker containers. Docker enables these apps to run in isolated environments, keeping them separate from the main operating system. This isolation offers benefits such as enhanced security, ease of migration, and flexibility in managing resources.

For Paperless-ngx, using Docker ensures that the app is contained within its own environment, with access restricted only to the folders you explicitly define. This isolation boosts security by preventing the app from interacting with other parts of your system, while also reducing the risk of conflicts with other applications.

Step 1: Installing Redis

Before you install Paperless-ngx, you’ll need to install Redis. Redis is a type of database that is used by Paperless-ngx to store your system settings, document metadata, and for caching, which helps speed up operations and ensure the app runs smoothly.

To install Redis, go to the Apps section in Unraid, search for "Redis", and sort by number of downloads to find the most popular version. Install the top result, and there are no specific settings to configure. Just take note of the port it uses (default: 6379), and don't change this unless necessary.

Step 2: Installing Paperless-ngx

Now that Redis is installed, you can proceed with the Paperless-ngx installation. In the Unraid Apps section, search for "Paperless-ngx." Make sure you install "Paperless-ngx" and not the older versions like "Paperless" or "Paperless-ng."

Once installed, you’ll be prompted to configure Paperless-ngx settings. There are a few essential steps here:

Folder Setup: You’ll need to define where Paperless-ngx can store its files. There are three primary folders:
- Data: For all your PDF and document data.
- Media: To store additional media files.
- Consume: Any file placed in this folder will be automatically processed by Paperless-ngx and then removed.
I recommend storing these as subfolders under a paperless-ngx folder inside your appdata directory on the cache pool.
Redis Configuration: You’ll need to link Paperless-ngx to Redis. Under the PAPERLESS_REDIS option, enter the address for Redis in this format: redis://[your_unraid_ip]:6379. Replace [your_unraid_ip] with the IP address of your Unraid server.
Filename Format: To keep your files organized, I suggest using a structured format like {added_year}/{tag_list}/{title}. This setup ensures your documents will be stored in folders such as \2024\Electricity\filename.pdf.
Auto Login (Optional): If Paperless-ngx is only accessible within your home network and you want to avoid logging in every time, you can set up auto-login. Add another "path, port, or variable", select Variable, with the name PAPERLESS_AUTO_LOGIN_USERNAME and set the value to root.
OCR Settings: If you receive documents with digital signatures (specific to some providers, in my case electricity bills for some reason) that prevent OCR, you can bypass these signatures. Add the variable PAPERLESS_OCR_USER_ARGS with the value {"invalidate_digital_signatures": true}. It doesn't hurt to add this setting even if you have no idea what this is, it won't do any harm.
Additional OCR Languages: By default, Paperless-ngx supports OCR in several languages (English, German, Italian, Spanish and French). If you need additional languages, add the variable PAPERLESS_OCR_LANGUAGES (Notice it's in plural) and enter a three-letter language code (available from here).

Starting Paperless-ngx

To ensure that both Paperless-ngx and Redis start automatically whenever Unraid boots up, it’s a good idea to toggle the "Auto Start" setting to "On" for both containers (from the Docker section in Unraid). This way, you won’t have to worry about manually starting the services after every reboot, allowing Paperless-ngx to run continuously without interruption.

To access the Paperless-ngx WebUI, you have two options. You can either go to the Docker tab in Unraid, click on the icon for Paperless-ngx, and select "WebUI", or you can directly browse to http://192.168.1.69:8000/dashboard (make sure to replace 192.168.1.69 with your own Unraid server’s IP address).

Recommended Settings and Tweaks

Once Paperless-ngx is running, here are some additional tweaks and settings to enhance your document management:

Tags: Add tags for better organization. My tags categorize documents by sender or type (e.g., "electricity", "banking", "school"). Additionally, Create a special "Inbox" tag and check the "inbox tag" option. This tag will automatically be assigned to new documents until you review them.
Document Types: Set up document types for more precise categorization, such as "receipts", "bills", and "agreements".
PDF Viewer: Under Settings > General, enable the "Use PDF viewer provided by the browser" option. This allows you to view and print documents directly from the browser without downloading them.
OCR Language: Add any additional languages you configured during setup under Configuration > OCR Settings > Language.

Email Integration

In the Mail section of Paperless-ngx, I highly recommend setting up an email account to automate document ingestion. By adding your email address (either your standard email address or a new one you'll create for this purpose), Paperless-ngx can monitor incoming messages and automatically process attachments that match certain rules you define. This feature is particularly useful for bills or statements sent directly to your inbox. For example, you can create a rule that triggers when an email with the subject "water bill" arrives and contains an attachment named "bill*" (using wildcards like * to generalize file names). You can set it to automatically tag this document with "Water" and categorize it under the "Bills" document type. You can also instruct the system to perform an action on the email after processing, such as marking it as read or archiving it. This prevents duplicate processing and ensures that only unread emails get scanned. For seamless operation, I recommend enabling an action like "Mark as read, don't process read mails", which makes managing email automation much more efficient. This way, you won’t even receive a Gmail notification for this email, but you can still be notified through integrations such as Home Assistant notifications when documents are added to Paperless-ngx. This setup is ideal for organizing bills, statements, and other recurring documents without the need for manual intervention.

Conclusion

You’re now set up to use Paperless-ngx on your Unraid system! You can easily scan, upload, and process documents into a well-organized digital repository. You can add documents through the consume folder, email, or other methods. Plus, with integrations like Home Assistant, the possibilities for automation are vast.

If you have any questions or encounter any issues during installation, feel free to comment below. I’ll be happy to assist!

Support this website by checking out smart home devices on AliExpress. From Zigbee to Wi-Fi gadgets, clicking the links below helps me continue writing these posts. Thank you!