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.
|
||||
@@ -0,0 +1,41 @@
|
||||
#!/bin/bash
|
||||
# scan-to-paperless — scan from network scanner via sane-airscan → Paperless consume folder
|
||||
# Usage: scan-to-paperless [name] [--flatbed] [--gray] [--150dpi]
|
||||
#
|
||||
# Requires: sane-airscan, sane-utils
|
||||
# The consume folder must be writeable by the user running this script.
|
||||
|
||||
set -e
|
||||
|
||||
DEVICE="airscan:e0:Brother MFC-J5855DW"
|
||||
CONSUME="/mnt/seagate8tb/paperless/consume"
|
||||
MODE="Color"
|
||||
RES="300"
|
||||
SOURCE="ADF"
|
||||
|
||||
NAME=""
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--flatbed) SOURCE="Flatbed" ;;
|
||||
--gray) MODE="Gray" ;;
|
||||
--150dpi) RES="150" ;;
|
||||
*) NAME="$1" ;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
SCAN_OPTS="--mode $MODE --resolution $RES"
|
||||
if [ "$SOURCE" = "ADF" ]; then
|
||||
SCAN_OPTS="$SCAN_OPTS --source ADF --batch-count=1"
|
||||
fi
|
||||
|
||||
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
|
||||
FILENAME="${NAME:-scan}_${TIMESTAMP}.pdf"
|
||||
OUTFILE="$CONSUME/$FILENAME"
|
||||
|
||||
echo "📄 Scanning ($SOURCE, $MODE, ${RES}dpi) → $FILENAME"
|
||||
scanimage --device "$DEVICE" $SCAN_OPTS --format pdf -o "$OUTFILE"
|
||||
|
||||
SIZE=$(du -h "$OUTFILE" | cut -f1)
|
||||
echo "✅ Done — $SIZE saved to Paperless"
|
||||
echo " File: $FILENAME"
|
||||
Reference in New Issue
Block a user