hermes-config/skills/self-hosting/paperless-ingestion/SKILL.md

name, description, version, author, platforms, created_by, metadata

name	description	version	author	platforms	created_by	metadata
paperless-ingestion	Get documents into Paperless-ngx — network scanner setup (sane-airscan, FTP, SMB), email ingestion, mobile share-sheet, and PDF optimization.	1.0.0	ray	linux	agent	hermes tags self-hosting paperless scanning documents

Paperless-ngx Ingestion

This skill absorbs the former scan-to-paperless skill (v1.0.0). All content — sane-airscan driverless scanning, Samba guest share, vsftpd setup, and the scripts/scan-to-paperless.sh scan script — is now consolidated here.

Multiple paths to get physical and digital documents into Paperless-ngx so they're OCR'd, classified, tagged, and searchable.

Quick Reference

Method	Best for	Needs
sane-airscan (direct)	Network scanner, locked web UI	sane-airscan package
Scan to FTP	Printer scan-to-FTP button	vsftpd, printer web UI access
Scan to SMB	Printer scan-to-network button	Samba share, printer web UI access
Email ingestion	Forwarding receipts/invoices	Paperless email config
Mobile share-sheet	Snapping receipts on phone	Paperless PWA or third-party app
Manual upload	One-off files	Web UI drag-and-drop

sane-airscan (Network Scanner → Paperless)

When to use: The printer is on the network but its web admin is locked (forgotten password, locked-down firmware). sane-airscan uses eSCL/AirScan — a driverless protocol supported by most modern network scanners and MFPs (Brother, HP, Canon, Epson, Xerox). No Brother drivers, no web UI, no printer password needed.

Install

sudo apt install -y sane-airscan sane-utils

Discover scanner

scanimage -L
# device `escl:http://192.168.50.219:80' is a Brother MFC-J5855DW platen,adf scanner
# device `airscan:e0:Brother MFC-J5855DW' is a eSCL Brother MFC-J5855DW ip=192.168.50.219

Either device alias works. Prefer the airscan:e0:... form — it's more stable across IP changes.

One-shot scan

scanimage --device "airscan:e0:Brother MFC-J5855DW" \
  --mode Color --resolution 300 --format pdf \
  -o /path/to/paperless/consume/document.pdf

Reusable scan script

Install at /usr/local/bin/scan-to-paperless (see scripts/scan-to-paperless.sh). Usage:

scan-to-paperless                  # ADF, color 300dpi → consume folder
scan-to-paperless invoice          # names it "invoice_20250614_172310.pdf"
scan-to-paperless --flatbed        # use flatbed instead of document feeder
scan-to-paperless --gray           # black & white
scan-to-paperless --150dpi         # low resolution (smaller file)
scan-to-paperless receipt --flatbed --gray --150dpi

Permissions

The user running scanimage needs write access to the Paperless consume folder:

# Option A: ACL for a specific user
sudo setfacl -m u:USERNAME:rwx /path/to/paperless/consume

# Option B: Group-based
sudo usermod -a -G paperless USERNAME
sudo chmod 775 /path/to/paperless/consume

Scan to FTP

When to use: The printer web UI IS accessible and the printer supports scan-to-FTP. Set up a lightweight FTP server that drops files into the Paperless consume folder.

Server setup

sudo apt install -y vsftpd
sudo useradd -m -d /path/to/paperless/consume -s /usr/sbin/nologin paperscan
echo "/usr/sbin/nologin" | sudo tee -a /etc/shells

Minimal vsftpd config (/etc/vsftpd.conf):

listen=YES
anonymous_enable=NO
local_enable=YES
write_enable=YES
chroot_local_user=YES
allow_writeable_chroot=YES
userlist_enable=YES
userlist_file=/etc/vsftpd.userlist
userlist_deny=NO
pasv_enable=YES
pasv_min_port=40000
pasv_max_port=40005
pasv_address=192.168.50.98

Userlist: /etc/vsftpd.userlist contains paperscan.

Printer configuration

In the printer's web UI → Scan → Scan to FTP:

• Host: server IP
• Username: paperscan
• Password: (set during user creation)
• Directory: / (chrooted to consume folder)

Scan to SMB

When to use: Printer supports scan-to-network but not FTP, or Samba already running.

Add to /etc/samba/smb.conf:

[scans]
   path = /mnt/seagate8tb/paperless/consume
   browseable = yes
   read only = no
   guest ok = yes
   force user = paperscan
   create mask = 0644

Reload: sudo systemctl reload smbd

On the printer: \\192.168.50.98\scans, no username/password (guest access).

Email Ingestion

Paperless can consume documents sent to a dedicated email address. See Paperless docs for mail rule configuration. Useful for forwarding receipts, invoices, and any document you receive digitally.

Mobile Share-Sheet

The Paperless web UI works as a PWA — "Add to Home Screen" on phone. Once added, any app's Share menu can send directly to Paperless. Third-party apps (Paperless Mobile for Android, Paperparrot/SwiftPaperless for iOS) offer smoother scanning workflows.

Pitfalls

• Brother scan profiles require web UI: On newer Brother MFPs (MFC-J5xxx series), scan-to-FTP/Network profiles can only be created via the web-based management interface, not the touchscreen. If the web admin password is lost, use sane-airscan instead — it bypasses the printer's scan profiles entirely.
• Brother HTTPS form-based auth: Modern Brother MFPs require HTTPS login to the web admin (HTTP redirects to an HTTPS login page). The password field uses form-based auth (<form method="post"> with <input type="password" name="Bc2a">), not HTTP Basic auth — curl -u and sshpass will both fail. Default passwords like initpass, access, admin no longer work on recent firmware; each device has a unique password on a sticker. The sticker password is often the Wi-Fi password, not the admin password. If locked out, skip the web UI entirely and use sane-airscan.
• ADF empty causes error: When the ADF is empty, scanimage exits with an error. Use --flatbed or wrap in a script that falls back.
• Consume folder permissions: Files dropped in the consume folder must be readable by the Paperless container. Use force user in Samba, chroot + matching UID in FTP, or ACLs for direct scans.
• FTP passive ports: If the printer can't connect via FTP, check that passive port range (40000-40005) is not firewalled.
• Consume folder watched, not polled: Paperless uses inotify on the consume folder. Large files or network filesystems may have delayed detection.