initial commit
This commit is contained in:
ray
@@ -0,0 +1,159 @@
|
||||
---
|
||||
name: paperless-ingestion
|
||||
description: "Get documents into Paperless-ngx — network scanner setup (sane-airscan, FTP, SMB), email ingestion, mobile share-sheet, and PDF optimization."
|
||||
version: 1.0.0
|
||||
author: ray
|
||||
platforms: [linux]
|
||||
created_by: "agent"
|
||||
metadata:
|
||||
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
|
||||
|
||||
```bash
|
||||
sudo apt install -y sane-airscan sane-utils
|
||||
```
|
||||
|
||||
### Discover scanner
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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`):
|
||||
|
||||
```ini
|
||||
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`:
|
||||
|
||||
```ini
|
||||
[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.
|
||||
Reference in New Issue
Block a user