Laurent Brand home
← Portfolio homelab
Browse homelab topics

Homelab / Technical documentation

From the scanner to searchable documents.

A tested scanning and OCR path, with the manual ingestion boundary made explicit.

Jump to a section

The workflow that was actually tested

  1. Epson network scannerAirScan / SANE capture
  2. scanservjsProduces a PDF in its output directory
  3. Manual transferCopy a test PDF to Paperless consume
  4. Paperless-ngxIngestion, OCR and classification
Activity diagram · recovered 31 October workflow, S12. Manual transfer is a human step, not an implemented unattended bridge.

The reported scanner was an Epson ET-2875 / ET-2870-series device. A 150 DPI test produced a 1700 × 2340 PNG of about 1.5 MB. scanservjs then produced PDFs under /var/lib/scanservjs/output. Paperless ingestion and OCR were reported successful.

Evidence: S12.

Separate responsibilities and persistent state

The running-inventory evidence supports scanservjs and a Paperless stack with a webserver, PostgreSQL and a Valkey broker. The scanner interface creates files; Paperless consumes them and manages searchable records. The database and document files are different persistent resources.

A tested manual copy does not establish a watched output folder, automated script or shared consume mount. Later reachability questions also mean the scanner UI’s long-term endpoint should not be inferred from an old test port.

Export-inspected · 7 November inventory: a later local export maps the same host consume directory into scanservjs at /paperless-consume and into Paperless at /usr/src/paperless/consume. The scanservjs mount is writable. Its normal output directory is a separate mount source. This establishes shared-directory access, not a working automatic transfer from that output directory.

Illustrative · sanitized view of the shared-directory relationship · L05
services:
  scanservjs:
    volumes:
      - <CONSUME_HOST_DIRECTORY>:/paperless-consume
  paperless:
    volumes:
      - <CONSUME_HOST_DIRECTORY>:/usr/src/paperless/consume

Evidence: S05 · S12 · L05.

Validate with a synthetic document

  1. Use a test sheet containing invented text, not a personal document or an academic record.
  2. Confirm scanner detection and the output file in scanservjs. Confirm the expected page count and readable image before ingestion.
  3. Use the approved manual transfer into the actual consume directory; keep a separate test copy. Do not guess a host path from a container-internal path.
  4. In Paperless, confirm ingestion, search for the synthetic text and review classification. Successful OCR of one batch is not a statement about every document.
Illustrative · sanitized copy step · writes only a synthetic test file
cp -- "<SYNTHETIC_SCAN.pdf>" "<ACTUAL_CONSUME_DIRECTORY>/synthetic-scan.pdf"

No scans, document counts, employer contents, real classifications or screenshots of records are included in this documentation.

Diagnose by the last successful stage

Scroll within the table to see all columns.

Failure boundary and next check
SymptomNext check
Scanner absentCheck SANE/AirScan discovery in the scanner runtime, before investigating Paperless.
PDF exists but no importConfirm the manual copy destination and the actual consume mount; do not assume an automatic handoff.
Import succeeds but text search failsInspect OCR completion/status for the synthetic document; ingestion alone is not OCR success.
Classification differsReview the resulting metadata; do not describe historical automatic classification as a universal rule.