---

📜 Star this repo to keep your docs in line and your chaos in check.

─── ⛧ ───

💀 Got rogue PDFs or rebellious receipts? Cast them into the fire and Enter 🔥HADES🔥.

---

Paperless-ngx 🗃️🤖

Paperless-ngx transforms your mountains of paper clutter into a sleek, searchable, digital archive. Deploy it on your Synology NAS and enjoy the magic of AI-powered document management. No more hunting for receipts like a pirate searching for treasure! 🏴‍☠️📄

---

Overview 📝

This repository adapts the guides from Lixandru Marius Bogdan to create a complete all-in-one deployment for Paperless-ngx and Paperless-AI. It allows you to deploy all services seamlessly onto a Synology NAS using Container Manager or Portainer.

• 📖 Paperless-ngx Setup
• 🤖 Paperless-ngx AI Setup
• 🖥️ Portainer Guide

Alternatively, you can use my 🐳 Docker Compose deployment for Portainer to deploy and manage Portainer on your NAS before setting up this project.

This setup supports:

• OCR-Powered Search 🔍 - Scan, search, and retrieve documents with ease.
• AI-Powered Categorization 🤖 - Let Paperless-ngx AI auto-sort and tag your documents.
• Office File Support 📑 - Convert and manage .docx, .pdf, and other formats.
• Synology NAS Friendly 🏠 - Deploy with DSM Container Manager or Portainer.

---

Configuring IPAM and Network Firewall 🌍

This project uses Docker IPAM (IP Address Management) to manage container networking. To ensure smooth communication, you may need to configure your firewall to allow access based on the defined subnet.

IPAM Configuration

You can configure the following settings in your .env file:

# Define the subnet range for the network
COMPOSE_NETWORK_SUBNET="${COMPOSE_NETWORK_SUBNET:-172.24.0.0/16}"

# Define the IP range for containers
COMPOSE_NETWORK_IP_RANGE="${COMPOSE_NETWORK_IP_RANGE:-172.24.5.0/24}"

# Define the network gateway
COMPOSE_NETWORK_GATEWAY="${COMPOSE_NETWORK_GATEWAY:-172.24.5.254}"

Updating Firewall Settings on Synology NAS 🔥

To allow communication for this Docker network, update the Synology Firewall settings:

1. Open Control Panel → Security (under Connectivity).
2. Navigate to the Firewall tab → Click Edit Rules.
3. Click Create to add a new rule:
   • Ports: Select All
   • Source IP: Select Specific IP
   • Click Select → Choose Subnet
   • Enter 172.24.0.0 for IP Address and 255.255.0.0 for Subnet mask/Prefix length
   • Action: Select Allow
4. Click OK to apply the changes.

This ensures that containers using this Docker network can communicate without restrictions.

For more details, check the Docker Compose IPAM documentation.

---

Deployment 🚀

This guide walks you through deploying Paperless-ngx using DSM Container Manager (recommended for Synology NAS). You can also use Portainer if you prefer a different UI.

1. Folders Are Pre-Created 📂

No need to manually create folders—this project automatically sets them up in the config directory:

config/
├── paperless-ai/
├── paperless-ngx/
│   ├── consume/
│   ├── data/
│   ├── db/
│   ├── export/
│   ├── media/
│   ├── redis/
│   ├── trash/

2. Copy and Edit the Environment File 📜

A sample environment file is already included! Simply copy it and update the values as needed:

cp example.env .env
vim .env  # Edit with your settings

3. Deploy Using DSM Container Manager 🏠

1. Open DSM Container Manager.
2. Navigate to Projects → Click Create.
3. Select Import YAML and browse to the docker-compose.yml file in the project root.
4. Click Next → Review settings → Click Apply.

4. Alternative Deployment with Portainer 🖥️

If you prefer Portainer, follow these steps:

1. Go to Stacks in Portainer.
2. Click Add Stack → Name it paperless.
3. Browse to the docker-compose.yml file in the project root.
4. Click Deploy the Stack.

5. Access the Web Interfaces 🌐

Once deployed, open your browser and access the service:

• Paperless-ngx: https://paperlessngx.yourname.synology.me

Log in with your admin credentials and start managing documents! 🏆

---

Docker Compose Configuration 🐳

The full docker-compose.yml file is included in the project root. Check it out if you want to tweak or customize your deployment.

📄 View docker-compose.yml

---

Troubleshooting 🛠️

Paperless-ngx can't connect to Redis? ❌

• Ensure your firewall rules allow access to the subnet defined in COMPOSE_NETWORK_SUBNET.
• Make sure your .env file has the correct PAPERLESS_REDIS value.
• Run docker logs paperless to check for errors.
• Try restarting the stack with docker compose down && docker compose up -d.

Redis Memory Overcommit Warning ⚠️

If you see the following warning in Redis logs:

WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail under low memory condition. Being disabled, it can also cause failures without low memory condition, see https://github.com/jemalloc/jemalloc/issues/1328.

This means that Linux memory overcommit is disabled, which can cause Redis to fail under low memory conditions. To fix this, update your system configuration:

sudo vim /etc/sysctl.conf

Add these lines to make the changes persistent:

vm.overcommit_memory = 1

Then apply the changes:

sudo sysctl vm.overcommit_memory=1

Or reboot your NAS for the changes to take effect.

Redis TCP Backlog Warning ⚠️

If you see this warning:

WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128.

This means the system's TCP connection backlog is too low, which could cause Redis to drop connections under high load. To fix it:

sudo vim /etc/sysctl.conf

Add this line:

net.core.somaxconn = 65535

Then apply the changes:

sudo sysctl net.core.somaxconn=65535

Or reboot your NAS for the changes to take effect.

Can't access the web interfaces? 🌍

• Ensure the correct NAS IP and port are used.
• Run docker ps to check if all containers are running.

---

Conclusion 🎉

Congratulations! 🎊 You've set up Paperless-ngx, and Paperless-AI on your Synology NAS. Now you can manage documents efficiently using AI models. 🚀🗃️🤖

For more advanced configurations, check out the official Paperless-ngx documentation and Paperless-AI documentation.