gitea-admin/gh-christianlouis-docuelevate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #503 from christianlouis/copilot/add-help-forum-and-blog

Browse Source 
feat(help): embed MkDocs documentation site at /help/ with How-To guides
This commit is contained in:
Christian Krakau-Louis
2026-03-07 21:58:16 +01:00
committed by GitHub
parent 3a1ecaf63a 63905842fd
commit f53574dc33
17 changed files with 1259 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/HowToGuides.md
+80
View File
@@ -0,0 +1,80 @@
# How-To Guides
Welcome to the DocuElevate How-To Guides. These step-by-step articles help you connect common scanners, printers, and mobile devices to DocuElevate for automatic document ingestion and processing.
---
## Document Ingestion Guides
Choose the method that matches your hardware or workflow:
### 🖨️ Scanners & Printers
| Guide | Description |
|-------|-------------|
| [HP Enterprise Printer Setup](howto/HPPrinterSetup.md) | Configure HP MFPs for automatic scan-to-DocuElevate via email, network folder, or WebDAV |
| [Fujitsu ScanSnap Setup](howto/SnapScanSetup.md) | Set up ScanSnap iX1600/iX1500/iX500 to send scans directly to DocuElevate |
| [Watched Folder Setup](howto/WatchedFolderSetup.md) | Monitor a local or network folder and automatically ingest any files dropped into it |
### 📧 Email & Cloud
| Guide | Description |
|-------|-------------|
| [Email Ingestion](howto/EmailIngestion.md) | Route documents sent as email attachments into DocuElevate automatically |
| [Mobile Scanning](howto/MobileScanning.md) | Use iOS/Android apps to capture and upload documents from your phone |
---
## Quick Comparison: Which Method Is Right for You?
| Method | Best For | Setup Complexity |
|--------|----------|-----------------|
| **Web Upload** | Occasional one-off uploads | ⭐ Very Easy |
| **Watched Folder** | Any scanner that saves to a folder | ⭐⭐ Easy |
| **Email Ingestion** | Scanners with Scan-to-Email, fax services | ⭐⭐ Easy |
| **HP Printer (SMB)** | HP Enterprise MFPs on a corporate network | ⭐⭐⭐ Medium |
| **ScanSnap + Cloud** | Home/office ScanSnap via Dropbox/Drive | ⭐⭐ Easy |
| **Mobile App** | On-the-go document capture | ⭐ Very Easy |
| **API Integration** | Custom workflows, developer integrations | ⭐⭐⭐⭐ Advanced |
---
## General Configuration Tips
### Enable OCR for Searchable PDFs
DocuElevate applies OCR (Optical Character Recognition) to scanned documents, making them fully searchable. Configure the OCR engine in your `.env`:
```env
OCR_ENABLED=true
OCR_ENGINE=tesseract # or: azure, google
OCR_LANGUAGE=eng # ISO 639-2 language code
```
### Set Up Automatic Cloud Backup
After processing, DocuElevate can store documents in your preferred cloud storage. Configure in Settings or `.env`:
```env
DEFAULT_STORAGE_TARGET=dropbox # or: gdrive, onedrive, s3, nextcloud
```
### Configure Notifications
Get notified when documents are processed:
```env
NOTIFICATION_ENABLED=true
NOTIFICATION_EMAIL=you@example.com
```
See [Notifications Setup](NotificationsSetup.md) for webhook, Slack, and other integrations.
---
## Need Help?
- Browse the full [Documentation](UserGuide.md)
- Check [Troubleshooting](Troubleshooting.md) for common issues
- View [Configuration Reference](ConfigurationGuide.md) for all settings
- Explore the [API Reference](API.md) for programmatic access
docs/howto/EmailIngestion.md
+156
View File
@@ -0,0 +1,156 @@
# 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
# Use an app-specific password (Gmail, Outlook) – NOT your main account password.
# See the Security Considerations section below for details.
EMAIL_INGESTION_PASSWORD=your-app-specific-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)
docs/howto/HPPrinterSetup.md
+217
View File
@@ -0,0 +1,217 @@
# How to Set Up Automatic Document Ingestion with an HP Enterprise Printer
This guide explains how to configure an HP Enterprise printer/MFP (Multi-Function Printer) to automatically send scanned documents to DocuElevate for processing and storage.
---
## Prerequisites
- An HP Enterprise printer or MFP with **Scan to Email** or **Scan to Network Folder** capability
- DocuElevate running and accessible on your network
- Admin access to the HP printer's Embedded Web Server (EWS)
- (Optional) An SMTP server or a configured email address for Scan to Email
---
## Option A: Scan to Email → DocuElevate API Upload
HP Enterprise printers can send scanned documents as email attachments. You can set up a dedicated inbox that forwards documents to DocuElevate via the REST API.
### Step 1: Configure Scan to Email on the Printer
1. Open a browser and navigate to the printer's IP address (e.g., `http://192.168.1.100`) to access the **Embedded Web Server (EWS)**.
2. Go to **Scan** → **Scan to E-mail**.
3. Enable **Scan to E-mail** and configure your SMTP server settings.
4. Create a **Quick Set** (shortcut) for the destination:
- **From:** `scanner@yourdomain.com`
- **To:** `docuelevate-inbox@yourdomain.com` (the receiving address you'll configure)
- **File Type:** PDF
- **Resolution:** 200–300 DPI (recommended)
- **Color Mode:** Grayscale or Black & White for text documents
### Step 2: Set Up an Email-to-DocuElevate Bridge
Use a lightweight tool like [imapfilter](https://github.com/lefcha/imapfilter) or a simple Python script (see below) to poll the inbox and upload attachments to DocuElevate via its REST API.
**Example Python script (`email_to_docuelevate.py`):**
```python
import imaplib
import email
import os
import sys
import requests
IMAP_HOST = "mail.yourdomain.com"
IMAP_USER = "docuelevate-inbox@yourdomain.com"
# Use an app-specific password (Gmail/Outlook), NOT your main account password.
# Store credentials as environment variables – never hardcode them.
IMAP_PASS = os.environ.get("IMAP_PASS")
DOCUELEVATE_URL = "http://your-docuelevate-host:8000"
API_KEY = os.environ.get("DOCUELEVATE_API_KEY")
if not IMAP_PASS:
sys.exit("Error: IMAP_PASS environment variable is not set.")
if not API_KEY:
sys.exit("Error: DOCUELEVATE_API_KEY environment variable is not set.")
def fetch_and_upload():
mail = imaplib.IMAP4_SSL(IMAP_HOST)
mail.login(IMAP_USER, IMAP_PASS)
mail.select("INBOX")
_, msg_ids = mail.search(None, "UNSEEN")
for msg_id in msg_ids[0].split():
_, msg_data = mail.fetch(msg_id, "(RFC822)")
msg = email.message_from_bytes(msg_data[0][1])
for part in msg.walk():
if part.get_content_maintype() == "multipart":
continue
if part.get("Content-Disposition") is None:
continue
filename = part.get_filename()
if filename and filename.lower().endswith(".pdf"):
payload = part.get_payload(decode=True)
files = {"file": (filename, payload, "application/pdf")}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.post(
f"{DOCUELEVATE_URL}/api/upload",
files=files,
headers=headers
)
print(f"Uploaded {filename}: {resp.status_code}")
mail.store(msg_id, "+FLAGS", "\\Seen")
mail.logout()
if __name__ == "__main__":
fetch_and_upload()
```
Run this script via a cron job every few minutes:
```bash
*/5 * * * * /usr/bin/python3 /opt/email_to_docuelevate.py >> /var/log/docuelevate_import.log 2>&1
```
---
## Option B: Scan to Network Folder (SMB/CIFS)
HP Enterprise printers can scan directly to a network folder. You can configure a watched folder that DocuElevate monitors for new files.
### Step 1: Set Up a Shared Network Folder
On your DocuElevate server (or any reachable server), create a shared folder:
```bash
# Create the shared folder
mkdir -p /srv/scanner-inbox
# Create a dedicated Samba user for the printer
sudo useradd -M -s /sbin/nologin scanner
sudo smbpasswd -a scanner # set a password for the printer to authenticate with
# Install Samba
sudo apt-get install samba
# Add to /etc/samba/smb.conf:
[scanner-inbox]
path = /srv/scanner-inbox
writable = yes
guest ok = no
valid users = scanner
create mask = 0660
directory mask = 0770
```
> **Security note:** Use a dedicated user (`scanner`) with a strong password instead of `guest ok = yes`. This prevents unauthorised devices on your network from depositing files.
Restart Samba: `sudo systemctl restart smbd`
### Step 2: Configure the HP Printer for Scan to Network Folder
1. Open the printer's **Embedded Web Server (EWS)**.
2. Go to **Scan** → **Scan to Network Folder**.
3. Click **Add** to create a new Quick Set:
- **UNC Path:** `\\192.168.1.200\scanner-inbox` (replace with your server's IP)
- **Username:** `scanner` (the Samba user created above)
- **Password:** the password set with `smbpasswd`
- **File Type:** PDF (Searchable PDF if available)
- **Resolution:** 200–300 DPI
4. Test the connection from the EWS interface.
### Step 3: Configure DocuElevate to Watch the Folder
In your DocuElevate `.env` configuration:
```env
# Enable folder watching
WATCH_FOLDER_ENABLED=true
WATCH_FOLDER_PATH=/srv/scanner-inbox
WATCH_FOLDER_INTERVAL=30 # seconds between checks
```
DocuElevate's Celery worker will automatically detect and process new files placed in the watched folder.
---
## Option C: Scan to FTP/WebDAV
DocuElevate supports FTP and WebDAV as upload targets. HP printers can send scanned documents directly.
### WebDAV Configuration
1. In the EWS, go to **Scan** → **Save to SharePoint** or **Save to Network Folder**.
2. Some HP models support WebDAV directly — configure the WebDAV URL to point to DocuElevate's WebDAV endpoint (if enabled):
- **URL:** `http://your-docuelevate-host:8000/webdav/inbox/`
- **Username/Password:** Your DocuElevate credentials
### FTP Configuration
1. Ensure an FTP server is running alongside DocuElevate (or configure one in docker-compose).
2. In the EWS, configure **Scan to FTP**:
- **FTP Server:** `192.168.1.200`
- **Port:** `21`
- **Remote Path:** `/scanner-inbox/`
3. DocuElevate's watch folder will pick up the FTP-delivered files.
---
## Recommended Scanner Quick Set Settings
| Setting | Recommended Value |
|---------|------------------|
| File Type | PDF (Searchable PDF / PDF/A if available) |
| Resolution | 200–300 DPI |
| Color Mode | Auto Detect or Grayscale |
| Sides | Auto Detect (2-sided) |
| Original Size | Auto Detect |
| Orientation | Auto Detect |
---
## Troubleshooting
**Printer can't connect to the network folder?**
→ Verify the IP address and that the Samba/SMB service is running. Check firewall rules (port 445/TCP).
**Scanned PDFs aren't being processed?**
→ Check DocuElevate's Celery worker logs: `docker logs document_worker --follow`
**Email attachments not arriving?**
→ Verify SMTP settings on the printer. Check spam filters on the receiving mailbox.
**Poor OCR quality?**
→ Increase scan resolution to 300 DPI and use Grayscale mode for text documents.
---
## Related Documentation
- [DocuElevate Configuration Guide](../ConfigurationGuide.md)
- [Storage Architecture](../StorageArchitecture.md)
- [Troubleshooting](../Troubleshooting.md)
docs/howto/MobileScanning.md
+152
View File
@@ -0,0 +1,152 @@
# How to Scan Documents from Your Phone or Tablet
DocuElevate works seamlessly with mobile scanning apps. This guide covers the best ways to capture documents with your phone or tablet and get them into DocuElevate automatically.
---
## Option 1: DocuElevate Web Upload (Simplest)
The easiest way is to use DocuElevate's built-in web interface directly from your mobile browser.
1. Open your phone's browser and navigate to your DocuElevate instance (e.g., `http://your-docuelevate-host:8000`).
2. Tap **Upload** in the top navigation.
3. Tap **Choose File** — your phone will open the camera or file picker.
4. Select **Camera** to capture a photo of the document, or pick an existing file.
5. Tap **Upload** — DocuElevate will process the image and convert it to a searchable PDF.
> **Tip:** Use good lighting and hold the phone steady for better OCR quality.
---
## Option 2: DocuElevate Browser Extension
The **DocuElevate Browser Extension** for Chrome/Firefox allows one-tap uploading from your mobile browser.
See the [Browser Extension guide](../BrowserExtension.md) for installation and setup instructions.
---
## Option 3: Mobile Scanning Apps
These apps provide superior document capture (auto perspective correction, multi-page, etc.) and can send directly to DocuElevate.
### Microsoft Lens (iOS / Android)
Microsoft Lens is free and integrates with OneDrive, which DocuElevate supports natively.
1. Install **Microsoft Lens** from the App Store or Google Play.
2. Scan your document.
3. Save to **OneDrive** in a folder you've connected to DocuElevate.
4. DocuElevate will automatically process new files in your OneDrive folder.
### Adobe Scan (iOS / Android)
Adobe Scan produces high-quality searchable PDFs.
1. Install **Adobe Scan** from the App Store or Google Play.
2. Scan your document.
3. Tap **Share** → **Save to Files** (iOS) or **Share** (Android).
4. Choose to save to your connected cloud storage (Dropbox, Google Drive) monitored by DocuElevate.
**Or use email ingestion:**
1. Tap **Share** → **Email**.
2. Send to your DocuElevate ingestion email address.
3. See [Email Ingestion Setup](./EmailIngestion.md) for configuration.
### SwiftScan (iOS)
SwiftScan (formerly Scanbot) offers excellent auto-capture and document enhancement.
1. Install **SwiftScan** from the App Store.
2. Scan your document.
3. Configure the **Auto-Upload** feature:
- Go to **Settings** → **Cloud Services**.
- Connect Dropbox, Google Drive, or OneDrive.
- Set the upload folder to your DocuElevate-monitored folder.
4. Every scan is automatically uploaded and processed by DocuElevate.
### CamScanner (iOS / Android)
1. Install **CamScanner**.
2. Configure **Auto Backup** to Dropbox or Google Drive.
3. Point DocuElevate at the same cloud folder.
---
## Option 4: iOS Shortcuts Automation
On iPhone/iPad, you can create an **iOS Shortcut** that scans a document and uploads it directly to DocuElevate's API.
### Creating the Shortcut
1. Open the **Shortcuts** app on your iPhone.
2. Tap **+** to create a new shortcut.
3. Add the following actions:
- **Scan Document** — opens the camera for scanning
- **Get Contents of URL** — configures the API call:
- **URL:** `http://your-docuelevate-host:8000/api/upload`
- **Method:** POST
- **Headers:** `Authorization: Bearer YOUR_API_KEY`
- **Request Body:** Form data with `file` = Scanned Document
4. Name the shortcut "Send to DocuElevate".
5. Add it to your home screen for one-tap scanning.
```
Shortcut flow:
┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐
│ Scan Document│ → │ Select pages │ → │ POST to DocuElevate │
│ (Camera) │ │ & crop │ │ /api/upload │
└─────────────┘ └──────────────┘ └──────────────────────┘
```
---
## Option 5: Android Automation with Tasker
On Android, **Tasker** can automate document upload when files appear in a specific folder.
1. Install **Tasker** from Google Play.
2. Create a **Profile** triggered by **File Created** in your scanner app's output folder.
3. Add a **Task** that calls DocuElevate's upload API using the **HTTP Request** action.
---
## Recommended Mobile Scanning Settings
For best results with DocuElevate's OCR engine:
| Setting | Recommended Value |
|---------|------------------|
| Output Format | PDF |
| Resolution/Quality | High (equivalent to 300 DPI) |
| Color Mode | Auto (greyscale for text, color for mixed) |
| Perspective Correction | On (auto-straighten) |
| Filter | Document / Black & White for text |
| Multi-page | Combine into single PDF |
---
## Troubleshooting
**Upload fails from mobile browser?**
→ Check that DocuElevate is accessible from your phone's network (same WiFi, or publicly reachable).
→ Verify your session is still logged in.
**OCR quality is poor?**
→ Ensure good lighting, no shadows on the document.
→ Use your scanning app's auto-enhance or document filter.
→ Increase resolution to "High" or "Best" in the app settings.
**Files synced to cloud but not processed?**
→ Check DocuElevate's cloud storage connection in Settings.
→ View worker logs: `docker logs document_worker --tail 50`
---
## Related Documentation
- [Email Ingestion Setup](./EmailIngestion.md)
- [HP Enterprise Printer Setup](./HPPrinterSetup.md)
- [ScanSnap Setup](./SnapScanSetup.md)
- [Browser Extension](../BrowserExtension.md)
- [API Reference](../API.md)
docs/howto/SnapScanSetup.md
+192
View File
@@ -0,0 +1,192 @@
# How to Set Up Fujitsu ScanSnap to Automatically Send Documents to DocuElevate
This guide walks you through configuring a Fujitsu ScanSnap scanner to automatically upload scanned documents to DocuElevate for AI-powered processing and storage.
---
## Supported ScanSnap Models
This guide applies to the following ScanSnap models:
- **iX1600 / iX1500 / iX1400** – Wi-Fi and USB, ScanSnap Home software
- **iX500 / iX100** – USB/Wi-Fi, ScanSnap Manager software
- **S1300i / S1100i** – USB, ScanSnap Manager software
> **Note:** ScanSnap Home (for newer models) and ScanSnap Manager (for older models) differ in their profile/job configuration interface. Both methods are covered below.
---
## Method 1: Scan to Folder → DocuElevate Watched Folder
This is the simplest method and works with all ScanSnap models.
### Step 1: Configure DocuElevate's Watched Folder
Add the following to your DocuElevate `.env` file and restart the service:
```env
WATCH_FOLDER_ENABLED=true
WATCH_FOLDER_PATH=/srv/scan-inbox
WATCH_FOLDER_INTERVAL=10
```
Create the directory and set permissions:
```bash
mkdir -p /srv/scan-inbox
chmod 777 /srv/scan-inbox
```
If running DocuElevate in Docker, mount this folder into the container in your `docker-compose.yaml`:
```yaml
services:
api:
volumes:
- /srv/scan-inbox:/srv/scan-inbox
worker:
volumes:
- /srv/scan-inbox:/srv/scan-inbox
```
### Step 2: Configure ScanSnap Home (iX1600/iX1500/iX1400)
1. Open **ScanSnap Home** on your computer.
2. Click **+** to create a new profile.
3. Select **Save to folder** as the action.
4. Configure the profile:
- **Folder:** `/srv/scan-inbox` (or a local folder that syncs to it)
- **File format:** PDF
- **Image quality:** Normal or Better
- **Color mode:** Auto
- **Scanning side:** Both sides (auto)
5. Enable **Convert to searchable PDF** if your ScanSnap and ScanSnap Home version support it.
6. Name the profile "DocuElevate" and save.
Now, pressing the scan button while this profile is active will send the scanned PDF directly to the watched folder.
### Step 3: Configure ScanSnap Manager (older models)
1. Right-click the ScanSnap Manager icon in the system tray.
2. Select **Scan Button Settings**.
3. Choose the **Save** tab.
4. Set **Image saving folder** to `/srv/scan-inbox` (or use a shared network path).
5. Under **File format**, select **PDF**.
6. Click **OK** to save.
---
## Method 2: Scan to Cloud Storage → DocuElevate Sync
If you already use Dropbox, Google Drive, or OneDrive with ScanSnap, you can leverage those integrations to feed documents into DocuElevate.
### Using Dropbox
1. In ScanSnap Home, create a profile with action **Save to Dropbox**.
2. Set the destination folder to `ScanSnap/` (or any folder).
3. In DocuElevate settings, configure Dropbox as your storage provider and point DocuElevate to monitor/pull from that folder.
4. DocuElevate will process new documents as they appear in Dropbox.
### Using Google Drive
1. Create a ScanSnap profile that saves to **Google Drive** under a dedicated folder (e.g., `ScanSnap/Inbox`).
2. Configure DocuElevate's Google Drive integration to use that folder as a source/destination.
---
## Method 3: Scan to Email → DocuElevate
ScanSnap can send scanned documents as email attachments. Pair this with the email-to-DocuElevate bridge described in the [HP Printer Guide](./HPPrinterSetup.md#option-a-scan-to-email--docuelevate-api-upload) for automatic ingestion.
1. In ScanSnap Home, create a profile with action **Send by E-mail**.
2. Configure the recipient address as your DocuElevate-monitored mailbox.
3. Set file format to **PDF**.
4. The email bridge script will pick up the attachment and upload it to DocuElevate.
---
## Method 4: ScanSnap Cloud (iX1600 / ScanSnap Home 3.x+)
The ScanSnap iX1600 supports **ScanSnap Cloud**, which can send directly to cloud services.
1. Open the **ScanSnap Home** app or use the printer's touchscreen.
2. Configure a **ScanSnap Cloud** profile that saves to **Google Drive** or **Dropbox**.
3. Point DocuElevate to monitor that cloud folder.
---
## Recommended Scan Settings
| Setting | Recommended Value |
|---------|------------------|
| File Format | PDF (Searchable PDF if available) |
| Image Quality | Normal (200 DPI) for text, Better (300 DPI) for photos |
| Color Mode | Auto (detects black/white vs color) |
| Scanning Side | Both Sides (Auto) |
| Compression | Medium |
| Rotate | Auto |
| Remove blank pages | Yes |
| Correct skewed scans | Yes |
---
## Automating with ScanSnap Home Profiles
You can create multiple profiles in ScanSnap Home for different document types:
| Profile | Settings | Notes |
|---------|----------|-------|
| **Documents** | B&W, 200 DPI, PDF | For invoices, letters, contracts |
| **Photos** | Color, 300 DPI, PDF | For photo documents |
| **Receipts** | B&W, 200 DPI, PDF, Remove blank pages | For expense reports |
| **Business Cards** | Color, 300 DPI, JPEG | May require separate OCR |
Each profile can be assigned to the scanner's shortcut button (on models with a touchscreen).
---
## Setting Up One-Button Scanning
On the **ScanSnap iX1600** with its touchscreen:
1. Tap the profile name (e.g., "DocuElevate") on the scanner's display.
2. The scanner will use that profile for the next scan.
3. Press the physical **Scan** button.
4. The document is scanned and automatically delivered to DocuElevate's watched folder.
On models without a touchscreen:
1. Set the "DocuElevate" profile as the **default profile** in ScanSnap Manager/Home.
2. Press the **Scan** button — the document goes directly to DocuElevate.
---
## Troubleshooting
**Files appear in the folder but DocuElevate doesn't process them?**
→ Check that `WATCH_FOLDER_ENABLED=true` in your `.env` and that the worker can read the folder:
```bash
docker logs document_worker --tail 50
```
**ScanSnap can't find the network folder?**
→ Ensure the folder is shared over SMB/CIFS (Windows share). See the [HP Printer Setup guide](./HPPrinterSetup.md#step-1-set-up-a-shared-network-folder) for Samba configuration.
**Scanned PDFs have poor text recognition?**
→ Increase scan resolution to 300 DPI. Enable "Convert to searchable PDF" in ScanSnap Home if available.
**Files are processed twice (duplicates)?**
→ Enable duplicate detection in DocuElevate settings. Check [Troubleshooting](../Troubleshooting.md) for deduplication options.
**ScanSnap doesn't appear in ScanSnap Home after network change?**
→ Re-run the ScanSnap network setup wizard. Ensure the scanner and your computer are on the same Wi-Fi network/subnet.
---
## Related Documentation
- [HP Enterprise Printer Setup](./HPPrinterSetup.md)
- [DocuElevate Configuration Guide](../ConfigurationGuide.md)
- [Dropbox Setup](../DropboxSetup.md)
- [Google Drive Setup](../GoogleDriveSetup.md)
- [Troubleshooting](../Troubleshooting.md)
docs/howto/WatchedFolderSetup.md
+234
View File
@@ -0,0 +1,234 @@
# How to Set Up a Watched Folder for Automatic Document Ingestion
The **Watched Folder** feature allows DocuElevate to automatically detect and process documents placed in a specific local directory. Any scanner, application, or script that saves files to that folder will have its output automatically ingested.
---
## Overview
```
Scanner / Any App → Drop files in folder → DocuElevate watches for new files → Process & Store
```
This is one of the simplest ingestion methods and works with virtually any scanner, OCR app, or document workflow tool.
---
## Configuration
Add these settings to your `.env` file:
```env
WATCH_FOLDER_ENABLED=true
WATCH_FOLDER_PATH=/srv/docuelevate/watch
WATCH_FOLDER_INTERVAL=30 # Polling interval in seconds
WATCH_FOLDER_RECURSIVE=false # Watch subdirectories too
WATCH_FOLDER_DELETE_AFTER=true # Delete originals after successful processing
WATCH_FOLDER_EXTENSIONS=pdf,jpg,jpeg,png,tiff,tif
```
**Restart** the services after editing:
```bash
docker compose restart api worker
```
---
## Docker Setup
When running DocuElevate with Docker Compose, mount the watch folder into both the `api` and `worker` containers:
```yaml
# docker-compose.yaml
services:
api:
volumes:
- /srv/docuelevate/watch:/srv/docuelevate/watch
- /var/docparse/workdir:/workdir
worker:
volumes:
- /srv/docuelevate/watch:/srv/docuelevate/watch
- /var/docparse/workdir:/workdir
```
Create the folder and set permissions:
```bash
sudo mkdir -p /srv/docuelevate/watch
# Create a dedicated group for scanner/upload access
sudo groupadd scanner-upload
# Set group ownership and restrict access to owner + group only
sudo chown root:scanner-upload /srv/docuelevate/watch
sudo chmod 770 /srv/docuelevate/watch
# Add the user running DocuElevate (e.g., www-data or your deploy user) to the group
sudo usermod -aG scanner-upload www-data
```
> **Security note:** Avoid `chmod 777` (world-writable). Use group-based access control so only authorised processes can write to the watched folder.
---
## Multiple Watch Folders
If you have multiple scanners or document sources, you can organize them by subfolder:
```
/srv/docuelevate/watch/
├── reception/ ← Front desk scanner
├── accounting/ ← Finance team scanner
├── hr/ ← HR department
└── general/ ← General purpose
```
Enable recursive watching:
```env
WATCH_FOLDER_RECURSIVE=true
```
DocuElevate will monitor all subdirectories and tag documents with the subfolder name for easy filtering.
---
## Using with Network Scanners
### Windows / Samba Share
Share the watch folder over the network so scanners and Windows PCs can drop files directly:
> **Security note:** The example below uses a dedicated Samba user (`scanner`) for authentication. Using `guest ok = yes` (no password) is convenient but allows any device on the network to write files — avoid it in multi-tenant or internet-exposed environments.
```bash
# Install Samba
sudo apt-get install samba -y
# Create a dedicated Samba user for scanner devices
sudo useradd -M -s /sbin/nologin scanner
sudo smbpasswd -a scanner # set a password
# Add to /etc/samba/smb.conf
[DocuElevate-Inbox]
comment = DocuElevate Document Inbox
path = /srv/docuelevate/watch
browsable = yes
guest ok = no
valid users = scanner
read only = no
create mask = 0660
directory mask = 0770
force group = scanner-upload
```
Restart Samba:
```bash
sudo systemctl restart smbd nmbd
```
Windows access: `\\your-server-ip\DocuElevate-Inbox`
### NFS Share (Linux)
```bash
# Add to /etc/exports
/srv/docuelevate/watch 192.168.1.0/24(rw,sync,no_subtree_check)
# Apply changes
sudo exportfs -ra
```
### FTP Server (for older devices)
Many older scanners only support FTP. Run a simple FTP server alongside DocuElevate:
```yaml
# Add to docker-compose.yaml
services:
ftp:
image: garethflowers/ftp-server
container_name: docuelevate_ftp
environment:
- FTP_USER=scanner
- FTP_PASS=changeme
ports:
- "21:21"
- "20:20"
- "21100-21110:21100-21110"
volumes:
- /srv/docuelevate/watch:/home/scanner
```
Configure your scanner's FTP settings to use this server. Files will land in the watched folder.
---
## Supported File Types
| Format | Extension | Notes |
|--------|-----------|-------|
| PDF | `.pdf` | OCR applied if not already searchable |
| JPEG | `.jpg`, `.jpeg` | Converted to PDF |
| PNG | `.png` | Converted to PDF |
| TIFF | `.tif`, `.tiff` | Supports multi-page TIFF |
| HEIC | `.heic` | iPhone photos (converted) |
---
## Monitoring
Check that the watched folder is active:
```bash
# View worker logs
docker logs document_worker --follow
# Expected output:
# INFO Watch folder monitor: watching /srv/docuelevate/watch (interval: 30s)
# INFO Watch folder: found new file invoice.pdf
# INFO Watch folder: queued document ID 156 for processing
```
You can also view processing status in the DocuElevate web interface under **Queue Monitor**.
---
## Troubleshooting
**Files are dropped but not picked up?**
- Verify `WATCH_FOLDER_ENABLED=true` in `.env`
- Check that `WATCH_FOLDER_PATH` matches the mounted path in docker-compose
- Look at worker logs: `docker logs document_worker --tail 100`
**Permission denied errors?**
```bash
# Preferred: use group-based ACL for targeted access
sudo setfacl -m g:scanner-upload:rwx /srv/docuelevate/watch
sudo setfacl -d -m g:scanner-upload:rwx /srv/docuelevate/watch
# If you need a quick fix and understand the risk, restrict to owner+group:
sudo chown -R root:scanner-upload /srv/docuelevate/watch
sudo chmod -R 770 /srv/docuelevate/watch
```
**Files processed but not deleted?**
- Set `WATCH_FOLDER_DELETE_AFTER=true`
- If you want to keep originals, set to `false` and manage cleanup separately
**File appears partially uploaded?**
- Large files may arrive before the scanner finishes writing them
- Increase `WATCH_FOLDER_INTERVAL` to give time for files to be fully written
- DocuElevate uses file-lock detection to avoid processing incomplete files
---
## Related Documentation
- [HP Enterprise Printer Setup](./HPPrinterSetup.md)
- [ScanSnap Setup](./SnapScanSetup.md)
- [Email Ingestion](./EmailIngestion.md)
- [Configuration Guide](../ConfigurationGuide.md)
- [Deployment Guide](../DeploymentGuide.md)