feat(docs): add built-in help section with How-To guides embedded in app

- Add MkDocs Material docs build stage to Dockerfile and Dockerfile.local - Mount pre-built docs as static files at /help/ in FastAPI (app/main.py) - Add app/views/help.py with /help → /help/ permanent redirect route - Register help router in app/views/__init__.py - Add Help nav link to base.html (public + app nav, desktop + mobile) - Create how-to guides: HP printer, ScanSnap, watched folder, email ingestion, mobile scanning - Update mkdocs.yml with How-To Guides section and Material theme palette - Add optional docs service (squidfunk/mkdocs-material) to docker-compose.yaml with docs profile - Add mkdocs-material to requirements-dev.txt - Add /docs_build to .gitignore - Add tests for help view (8 tests, 100% coverage on help.py) Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
2026-03-07 20:33:10 +00:00
parent 6ebf66275c
commit 46b2f17acc
17 changed files with 1225 additions and 0 deletions
@@ -0,0 +1,154 @@
+# How to Set Up Automatic Document Ingestion via Email
+
+Many devices (scanners, printers, fax services, and apps) can send documents as email attachments. This guide explains how to automatically route those attachments into DocuElevate.
+
+---
+
+## Overview
+
+The Email Ingestion workflow works like this:
+
+```
+Scanner/Device → Email (SMTP) → Monitored Mailbox → DocuElevate API → Processing & Storage
+```
+
+DocuElevate periodically checks a designated email inbox, downloads PDF/image attachments, and processes them through the standard document pipeline.
+
+---
+
+## Prerequisites
+
+- An email account dedicated to document ingestion (e.g., `scan@yourdomain.com`)
+- IMAP access enabled for that account
+- DocuElevate running with the Celery worker active
+
+---
+
+## Configuration
+
+Add the following to your DocuElevate `.env` file:
+
+```env
+# Email ingestion settings
+EMAIL_INGESTION_ENABLED=true
+EMAIL_INGESTION_IMAP_HOST=mail.yourdomain.com
+EMAIL_INGESTION_IMAP_PORT=993
+EMAIL_INGESTION_IMAP_SSL=true
+EMAIL_INGESTION_USERNAME=scan@yourdomain.com
+EMAIL_INGESTION_PASSWORD=your-email-password
+EMAIL_INGESTION_FOLDER=INBOX
+EMAIL_INGESTION_INTERVAL=60           # Check every 60 seconds
+EMAIL_INGESTION_MARK_SEEN=true        # Mark emails as read after processing
+EMAIL_INGESTION_ALLOWED_SENDERS=      # Comma-separated allowlist (empty = allow all)
+```
+
+Restart DocuElevate after saving the configuration:
+
+```bash
+docker compose restart api worker
+```
+
+---
+
+## Supported File Types
+
+DocuElevate will process the following attachment types from emails:
+
+| Type | Extension | Notes |
+|------|-----------|-------|
+| PDF | `.pdf` | Native support; OCR applied if not searchable |
+| JPEG/PNG | `.jpg`, `.jpeg`, `.png` | Converted to PDF before processing |
+| TIFF | `.tif`, `.tiff` | Common format from older scanners/fax |
+| Multi-page TIFF | `.tif` | Full multi-page support |
+
+---
+
+## Setting Up Your Scanner/Device
+
+### HP Printers – Scan to Email
+
+See the detailed guide: [HP Enterprise Printer Setup](./HPPrinterSetup.md#option-a-scan-to-email--docuelevate-api-upload)
+
+### Fujitsu ScanSnap – Send by Email
+
+See the detailed guide: [ScanSnap Setup](./SnapScanSetup.md#method-3-scan-to-email--docuelevate)
+
+### iOS/Android Scanning Apps
+
+Most mobile scanning apps (Adobe Scan, Microsoft Lens, SwiftScan) can email scans:
+
+1. Scan your document.
+2. Use the app's **Share** or **Send** function.
+3. Select **Email** and enter `scan@yourdomain.com`.
+4. DocuElevate will pick up the attachment within the configured interval.
+
+### Fax-to-Email Services
+
+Services like eFax, RingCentral Fax, or Twilio Fax can forward incoming faxes as email attachments. Configure them to send to `scan@yourdomain.com`.
+
+---
+
+## Security Considerations
+
+> **Important:** Only process emails from trusted sources to avoid ingesting malicious documents.
+
+Use the `EMAIL_INGESTION_ALLOWED_SENDERS` setting to restrict which email addresses can submit documents:
+
+```env
+EMAIL_INGESTION_ALLOWED_SENDERS=scanner@office.com,printer@office.com,fax@office.com
+```
+
+DocuElevate will silently skip emails from addresses not in the allowlist.
+
+Additionally:
+
+- Use a **dedicated email account** solely for document ingestion
+- Enable **app-specific passwords** (Gmail, Outlook) instead of your main account password
+- Store credentials in environment variables, never in config files committed to version control
+
+---
+
+## Monitoring
+
+Check the DocuElevate worker logs to verify email ingestion is running:
+
+```bash
+docker logs document_worker --follow
+```
+
+You should see log entries like:
+
+```
+INFO  Email ingestion: checking inbox scan@yourdomain.com
+INFO  Email ingestion: found 3 new messages
+INFO  Email ingestion: processing attachment invoice-2024.pdf from printer@office.com
+INFO  Email ingestion: queued document ID 142 for processing
+```
+
+---
+
+## Troubleshooting
+
+**No emails are being processed?**
+→ Verify IMAP credentials and that IMAP is enabled on your mail server.  
+→ Check firewall rules: port 993 (SSL) or 143 (plain) must be open from DocuElevate to the mail server.
+
+**Gmail not working?**
+→ Enable "App Passwords" in your Google Account security settings.  
+→ Use the App Password (not your main Google password) for `EMAIL_INGESTION_PASSWORD`.
+
+**Attachments processed but files are empty?**
+→ Some email clients send inline images instead of attachments. Check the raw email source.
+
+**Emails keep getting re-processed?**
+→ Set `EMAIL_INGESTION_MARK_SEEN=true` to mark emails as read after processing.  
+→ Alternatively, configure a separate ingestion folder and move/delete emails after processing.
+
+---
+
+## Related Documentation
+
+- [HP Enterprise Printer Setup](./HPPrinterSetup.md)
+- [ScanSnap Setup](./SnapScanSetup.md)
+- [Configuration Guide](../ConfigurationGuide.md)
+- [Notifications Setup](../NotificationsSetup.md)