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:
- Introduction to Paperless-ngx
- Top Unraid Apps for Productivity and Management
- Getting Alerts in Home Assistant for Paperless-ngx Inbox Items
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.
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.
paperless-ngx
folder inside yourappdata
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 namePAPERLESS_AUTO_LOGIN_USERNAME
and set the value toroot
. - 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!