saneless

SANE scanner to paperless-ngx bridge. Web UI and CLI for triggering scans, assembling multi-page PDFs, and ingesting documents into paperless-ngx with metadata -- all from any device on the local network.

---

Getting Started

New to saneless? Start here. Get from installation to your first scan in minutes.

• Which setup do I have? -- Find which of the three deployment shapes is yours, and what it needs, before you install.
• Quick Start -- Five-minute path from install to your first document in paperless-ngx.
• First CLI Scan -- Step-by-step CLI tutorial: install, configure, scan, verify.
• First Web UI Scan -- Walk through the web interface to scan a document.

How-To Guides

Step-by-step instructions for specific tasks. Each guide solves one problem and assumes you already have saneless running.

• Install on Bare Metal -- Install saneless directly on a Linux host with system SANE headers.
• Deploy with Docker Compose -- Run saneless as a container alongside paperless-ngx.
• Configure Scan Profiles -- Create profiles for different scan types (color, grayscale, high-res).
• Set Up ADF Duplex Scanning -- Scan double-sided documents with an automatic document feeder.
• Scan a Multi-Page Document -- Build one PDF from several scans, on the flatbed or by hand-feeding the feeder.
• Scanner Host Discovery (Containers) -- Connect a containerized saneless instance to a remote scanner.
• Use the CLI for Scripting -- Automate scans with shell scripts and JSON output.
• Troubleshoot a Failed Scan -- Find out why a scan failed, where its pages went, and what to do next.

Reference

Technical details: CLI, configuration, API, Docker. Look up exact option names, defaults, and behaviors.

• CLI Commands -- All commands, flags, and exit codes.
• Configuration (TOML) -- Every configuration key, its type, default, and description.
• Environment Variables -- Override any config value via environment variables.
• Web API -- HTTP endpoints for scanning, status, and health checks.
• Docker -- Image tags, volumes, environment variables, and health checks.

Explanation

Background and design decisions. Understand why saneless works the way it does.

• Architecture Overview -- How the scanner, pipeline, worker, and web layer fit together.
• Empty Page Detection -- How saneless detects and removes blank pages from every scan.
• Consume Directory Fallback -- How file-based ingestion works when the paperless-ngx API is unavailable.

Changelog

Changelog -- What each release added, changed and fixed.