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

---
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.