fix: merge main branch and renumber migration 027→037
Resolve 3 merge conflicts and renumber the automation_hooks migration to follow main's migration chain (036_add_document_translation_fields). Conflicts resolved: - app/api/__init__.py: add automation_router alongside main's new routers - app/utils/settings_service.py: add automation_hooks_enabled alongside compliance_enabled - tests/conftest.py: add AutomationHook alongside AuditLog/ComplianceTemplate imports Migration renumbered: - 027_add_automation_hooks → 037_add_automation_hooks - down_revision: 026_add_scheduled_jobs → 036_add_document_translation_fields Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
+342
@@ -1960,6 +1960,160 @@ Pass no `pipeline_id` query parameter (or omit it) to clear the assignment.
|
||||
```
|
||||
|
||||
|
||||
## Routing Rules
|
||||
|
||||
Routing rules let you conditionally assign documents to different pipelines
|
||||
based on file properties such as type, size, filename, or AI-extracted
|
||||
metadata. Rules are evaluated in **position order** (lowest first); the first
|
||||
rule that matches wins. If no rule matches, the system falls back to the
|
||||
owner's (or global) default pipeline.
|
||||
|
||||
### Supported operators and fields
|
||||
|
||||
```bash
|
||||
GET /api/routing-rules/operators
|
||||
```
|
||||
|
||||
Returns the catalogue of valid operators and built-in fields so UIs can
|
||||
populate dropdowns without hard-coding values.
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
{
|
||||
"operators": ["contains", "equals", "gt", "gte", "lt", "lte", "not_contains", "not_equals", "regex"],
|
||||
"builtin_fields": ["category", "document_type", "file_type", "filename", "size"],
|
||||
"metadata_prefix": "metadata."
|
||||
}
|
||||
```
|
||||
|
||||
> **Tip:** For AI metadata fields use the `metadata.` prefix, e.g.
|
||||
> `metadata.sender`, `metadata.amount`.
|
||||
|
||||
### List routing rules
|
||||
|
||||
```bash
|
||||
GET /api/routing-rules
|
||||
```
|
||||
|
||||
Returns the current user's rules **plus** any system-wide rules
|
||||
(`owner_id = null`), ordered by position.
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"owner_id": "alice",
|
||||
"name": "Route invoices",
|
||||
"position": 0,
|
||||
"field": "document_type",
|
||||
"operator": "equals",
|
||||
"value": "Invoice",
|
||||
"target_pipeline_id": 3,
|
||||
"is_active": true,
|
||||
"created_at": "2026-03-09T12:00:00+00:00",
|
||||
"updated_at": "2026-03-09T12:00:00+00:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Create routing rule
|
||||
|
||||
```bash
|
||||
POST /api/routing-rules
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Route invoices",
|
||||
"field": "document_type",
|
||||
"operator": "equals",
|
||||
"value": "Invoice",
|
||||
"target_pipeline_id": 3
|
||||
}
|
||||
```
|
||||
|
||||
Optional fields: `position` (auto-assigned if omitted), `is_active` (default `true`).
|
||||
|
||||
**Response (201 Created):** The created rule object.
|
||||
|
||||
### Get routing rule
|
||||
|
||||
```bash
|
||||
GET /api/routing-rules/{rule_id}
|
||||
```
|
||||
|
||||
**Response (200):** A single rule object.
|
||||
|
||||
### Update routing rule
|
||||
|
||||
```bash
|
||||
PUT /api/routing-rules/{rule_id}
|
||||
Content-Type: application/json
|
||||
|
||||
{ "name": "Renamed rule", "operator": "contains", "is_active": false }
|
||||
```
|
||||
|
||||
Only the supplied fields are updated.
|
||||
|
||||
**Response (200):** The updated rule object.
|
||||
|
||||
### Delete routing rule
|
||||
|
||||
```bash
|
||||
DELETE /api/routing-rules/{rule_id}
|
||||
```
|
||||
|
||||
Returns **204 No Content**.
|
||||
|
||||
### Reorder routing rules
|
||||
|
||||
```bash
|
||||
PUT /api/routing-rules/reorder
|
||||
Content-Type: application/json
|
||||
|
||||
{ "rule_ids": [3, 1, 2] }
|
||||
```
|
||||
|
||||
Provide the complete ordered list of your rule IDs. Positions are reassigned
|
||||
0, 1, 2, … in the given order.
|
||||
|
||||
### Evaluate rules (dry run)
|
||||
|
||||
```bash
|
||||
POST /api/routing-rules/evaluate
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"file_type": "application/pdf",
|
||||
"filename": "invoice_2024.pdf",
|
||||
"size": 204800,
|
||||
"document_type": "Invoice",
|
||||
"metadata": { "sender": "Acme Corp" }
|
||||
}
|
||||
```
|
||||
|
||||
Tests which rule (if any) would match the given properties **without**
|
||||
actually routing a document.
|
||||
|
||||
**Response (200) – match found:**
|
||||
```json
|
||||
{
|
||||
"matched": true,
|
||||
"rule": { "id": 1, "name": "Route invoices", "..." : "..." },
|
||||
"target_pipeline": { "id": 3, "name": "Invoice Pipeline", "is_active": true }
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200) – no match:**
|
||||
```json
|
||||
{
|
||||
"matched": false,
|
||||
"rule": null,
|
||||
"target_pipeline": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## API Tokens
|
||||
|
||||
Personal API tokens allow programmatic access to the DocuElevate API without
|
||||
@@ -2215,3 +2369,191 @@ Automation hook deliveries follow the same retry policy as regular webhooks: up
|
||||
## Further Assistance
|
||||
|
||||
For additional help with the API, please contact our support team or refer to the [Development Guide](../CONTRIBUTING.md).
|
||||
|
||||
## Mobile App API
|
||||
|
||||
The mobile API provides endpoints used by the native iOS and Android app. All endpoints require authentication (Bearer token or active session cookie).
|
||||
|
||||
For full mobile app documentation see [MobileApp.md](./MobileApp.md).
|
||||
|
||||
### POST /api/mobile/generate-token
|
||||
|
||||
Exchange an active web session for a long-lived API token scoped to the mobile app.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{ "device_name": "John's iPhone" }
|
||||
```
|
||||
|
||||
**Response (201 Created):**
|
||||
```json
|
||||
{
|
||||
"token": "de_AbCdEfGhIjKl...",
|
||||
"token_id": 42,
|
||||
"name": "Mobile App – John's iPhone",
|
||||
"created_at": "2026-03-10T09:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
> The `token` is shown **once only**.
|
||||
|
||||
### POST /api/mobile/register-device
|
||||
|
||||
Register an Expo push token to receive push notifications.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"push_token": "ExponentPushToken[xxxxxx]",
|
||||
"device_name": "John's iPhone",
|
||||
"platform": "ios"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (201 Created):** Device record with `id`, `platform`, `is_active`, `created_at`.
|
||||
|
||||
### GET /api/mobile/devices
|
||||
|
||||
List all registered push-notification devices for the current user.
|
||||
|
||||
**Response (200 OK):** Array of device records.
|
||||
|
||||
### DELETE /api/mobile/devices/{device_id}
|
||||
|
||||
Deactivate a push-notification device. The device will no longer receive push notifications.
|
||||
|
||||
**Response (204 No Content)**
|
||||
|
||||
### GET /api/mobile/whoami
|
||||
|
||||
Return basic profile information for the authenticated user.
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"owner_id": "john@example.com",
|
||||
"display_name": "John Doe",
|
||||
"email": "john@example.com",
|
||||
"avatar_url": "https://www.gravatar.com/avatar/...",
|
||||
"is_admin": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GraphQL API
|
||||
|
||||
DocuElevate exposes a GraphQL API at `/graphql` alongside the REST API. It
|
||||
supports flexible queries with field selection, making it ideal for dashboards
|
||||
and integrations that only need a subset of the available data.
|
||||
|
||||
### Endpoint
|
||||
|
||||
| Method | URL | Description |
|
||||
|--------|-----|-------------|
|
||||
| `POST` | `/graphql` | Execute a GraphQL query or mutation |
|
||||
| `GET` | `/graphql` | Open the GraphiQL interactive playground |
|
||||
|
||||
### Authentication
|
||||
|
||||
The GraphQL endpoint honours the same authentication rules as the REST API:
|
||||
|
||||
- **`AUTH_ENABLED=False`** (default, single-user mode): all queries are
|
||||
allowed without credentials.
|
||||
- **`AUTH_ENABLED=True`** (multi-user mode): a valid session cookie **or**
|
||||
an `Authorization: Bearer <token>` API token is required. Admin-only
|
||||
queries (settings, users) additionally require the `is_admin` flag.
|
||||
|
||||
### Available Queries
|
||||
|
||||
| Field | Returns | Notes |
|
||||
|-------|---------|-------|
|
||||
| `documents(ownerId, limit, offset)` | `[DocumentType]` | Paginated list of documents |
|
||||
| `document(id)` | `DocumentType` | Single document by primary key |
|
||||
| `pipelines(ownerId, limit, offset)` | `[PipelineType]` | Paginated list of pipelines with steps |
|
||||
| `pipeline(id)` | `PipelineType` | Single pipeline by primary key |
|
||||
| `settings(limit, offset)` | `[SettingType]` | Non-sensitive app settings (**admin only**) |
|
||||
| `users(limit, offset)` | `[UserType]` | User profiles (**admin only**) |
|
||||
| `user(userId)` | `UserType` | Single user profile (**admin only**) |
|
||||
|
||||
> **Note:** Sensitive configuration keys (API secrets, passwords, tokens) are
|
||||
> automatically excluded from the `settings` query regardless of the caller's
|
||||
> privilege level.
|
||||
|
||||
### GraphiQL Playground
|
||||
|
||||
Navigate to `http://<your-instance>/graphql` in a browser to open the
|
||||
interactive GraphiQL IDE, which provides schema documentation, auto-complete,
|
||||
and the ability to run queries directly.
|
||||
|
||||
### Example Queries
|
||||
|
||||
**List recent documents:**
|
||||
```graphql
|
||||
{
|
||||
documents(limit: 5) {
|
||||
id
|
||||
originalFilename
|
||||
mimeType
|
||||
fileSize
|
||||
documentTitle
|
||||
createdAt
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fetch a pipeline with its steps:**
|
||||
```graphql
|
||||
{
|
||||
pipeline(id: 1) {
|
||||
id
|
||||
name
|
||||
description
|
||||
isDefault
|
||||
isActive
|
||||
steps {
|
||||
position
|
||||
stepType
|
||||
label
|
||||
enabled
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**List application settings (admin only):**
|
||||
```graphql
|
||||
{
|
||||
settings {
|
||||
key
|
||||
value
|
||||
updatedAt
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**List user profiles (admin only):**
|
||||
```graphql
|
||||
{
|
||||
users(limit: 10) {
|
||||
userId
|
||||
displayName
|
||||
subscriptionTier
|
||||
isBlocked
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Using variables:**
|
||||
```graphql
|
||||
query GetDocument($id: Int!) {
|
||||
document(id: $id) {
|
||||
id
|
||||
originalFilename
|
||||
documentTitle
|
||||
isDuplicate
|
||||
ocrQualityScore
|
||||
}
|
||||
}
|
||||
```
|
||||
Variables: `{ "id": 42 }`
|
||||
|
||||
@@ -20,10 +20,11 @@ For a complete list of configuration options, see the [Configuration Guide](Conf
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
DocuElevate supports two primary authentication methods:
|
||||
DocuElevate supports multiple authentication methods that can be used independently or together:
|
||||
|
||||
1. **Simple Authentication** - Basic username/password authentication managed by DocuElevate
|
||||
2. **OpenID Connect** - Integration with identity providers like Authentik, Keycloak, or Auth0
|
||||
3. **Social Login** - Sign in with Google, Microsoft, Apple, or Dropbox accounts (see [Social Login Setup Guide](SocialLoginSetup.md))
|
||||
|
||||
## Session Security
|
||||
|
||||
@@ -189,3 +190,11 @@ If you encounter issues with authentication:
|
||||
- For most providers, you can visit the `/.well-known/openid-configuration` endpoint to verify their settings
|
||||
|
||||
For more general configuration issues, see the [Configuration Troubleshooting Guide](ConfigurationTroubleshooting.md).
|
||||
|
||||
## Social Login
|
||||
|
||||
DocuElevate supports social login with Google, Microsoft, Apple, and Dropbox. Social login allows users to authenticate using their existing accounts with these providers, without needing a separate DocuElevate password.
|
||||
|
||||
Social login can be used alongside any other authentication method (simple auth, OIDC, local signup). Each social provider is independently configured.
|
||||
|
||||
For detailed setup instructions, prerequisites, and provider-specific configuration, see the **[Social Login Setup Guide](SocialLoginSetup.md)**.
|
||||
|
||||
@@ -0,0 +1,190 @@
|
||||
# Compliance Templates Guide
|
||||
|
||||
DocuElevate includes pre-built compliance templates for **GDPR**, **HIPAA**, and **SOC 2** that help you configure your instance to meet regulatory requirements. This guide covers how to use the compliance dashboard, apply templates, and monitor your compliance status.
|
||||
|
||||
## Overview
|
||||
|
||||
The compliance templates feature provides:
|
||||
|
||||
- **Pre-built configurations** for GDPR, HIPAA, and SOC 2
|
||||
- **One-click apply** to configure all required settings at once
|
||||
- **Compliance status dashboard** to monitor your regulatory posture
|
||||
- **Individual check results** showing which settings are compliant and which need attention
|
||||
|
||||
## Accessing the Dashboard
|
||||
|
||||
The compliance dashboard is available to **admin users only**.
|
||||
|
||||
1. Log in as an administrator
|
||||
2. Click **Admin** in the navigation bar
|
||||
3. Select **Compliance** from the dropdown menu
|
||||
|
||||
Or navigate directly to: `/admin/compliance`
|
||||
|
||||
## Available Templates
|
||||
|
||||
### GDPR (General Data Protection Regulation)
|
||||
|
||||
The European Union regulation for data protection and privacy. The GDPR template enforces:
|
||||
|
||||
| Setting | Value | Purpose |
|
||||
|---------|-------|---------|
|
||||
| `AUTH_ENABLED` | `True` | Controls access to personal data |
|
||||
| `SENTRY_SEND_DEFAULT_PII` | `False` | Prevents PII leaking to external services |
|
||||
| `SECURITY_HEADERS_ENABLED` | `True` | Protects against common web vulnerabilities |
|
||||
| `SECURITY_HEADER_HSTS_ENABLED` | `True` | Ensures encrypted connections |
|
||||
| `SECURITY_HEADER_CSP_ENABLED` | `True` | Prevents XSS and injection attacks |
|
||||
| `SECURITY_HEADER_X_FRAME_OPTIONS_ENABLED` | `True` | Prevents clickjacking |
|
||||
| `ENABLE_DEDUPLICATION` | `True` | Data minimisation — avoids duplicate storage |
|
||||
|
||||
### HIPAA (Health Insurance Portability and Accountability Act)
|
||||
|
||||
United States regulation for protecting health information. The HIPAA template includes all GDPR settings plus:
|
||||
|
||||
| Setting | Value | Purpose |
|
||||
|---------|-------|---------|
|
||||
| `MULTI_USER_ENABLED` | `True` | Individual accounts for access accountability |
|
||||
|
||||
### SOC 2 (Service Organization Control 2)
|
||||
|
||||
Trust Service Criteria framework for service organisations. The SOC 2 template includes the same settings as HIPAA, mapped to SOC 2 Trust Service Criteria (CC6.x, PI1.x).
|
||||
|
||||
## Applying a Template
|
||||
|
||||
1. Navigate to the **Compliance** dashboard (`/admin/compliance`)
|
||||
2. Find the template you want to apply (GDPR, HIPAA, or SOC 2)
|
||||
3. Click **Apply Template**
|
||||
4. Confirm the action in the dialog
|
||||
5. The template settings are written to the database immediately
|
||||
|
||||
> **Note:** Applying a template writes configuration values to the database. Some settings (e.g., security headers) may require a restart to take effect. Check the Settings page for restart indicators.
|
||||
|
||||
## Understanding Compliance Status
|
||||
|
||||
Each template shows one of four statuses:
|
||||
|
||||
| Status | Badge | Meaning |
|
||||
|--------|-------|---------|
|
||||
| **Compliant** | Green | All checks are passing |
|
||||
| **Partial** | Yellow | Some checks are passing, others are not |
|
||||
| **Non-Compliant** | Red | No checks are passing |
|
||||
| **Not Applied** | Grey | Template has never been applied |
|
||||
|
||||
### Individual Checks
|
||||
|
||||
Click **Show Details** on any template card to see individual check results:
|
||||
|
||||
- ✅ **Passing** — The setting matches the expected compliance value
|
||||
- ❌ **Failing** — The setting does not match; the current and expected values are shown
|
||||
|
||||
## API Endpoints
|
||||
|
||||
The compliance feature exposes the following API endpoints under `/api/compliance/`:
|
||||
|
||||
### List Templates
|
||||
|
||||
```bash
|
||||
GET /api/compliance/templates
|
||||
```
|
||||
|
||||
Returns all compliance templates with their current status.
|
||||
|
||||
### Get Single Template
|
||||
|
||||
```bash
|
||||
GET /api/compliance/templates/{name}
|
||||
```
|
||||
|
||||
Returns a single template by name (`gdpr`, `hipaa`, or `soc2`).
|
||||
|
||||
### Apply Template
|
||||
|
||||
```bash
|
||||
POST /api/compliance/templates/{name}/apply
|
||||
```
|
||||
|
||||
Applies a compliance template, writing all its settings to the database.
|
||||
|
||||
### Get Template Status
|
||||
|
||||
```bash
|
||||
GET /api/compliance/templates/{name}/status
|
||||
```
|
||||
|
||||
Evaluates the live compliance status of a template against current settings.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "partial",
|
||||
"total": 7,
|
||||
"passed": 5,
|
||||
"failed": 2,
|
||||
"check_results": [
|
||||
{
|
||||
"key": "auth_enabled",
|
||||
"label": "Authentication enabled",
|
||||
"description": "User authentication must be enabled to control access to personal data.",
|
||||
"expected": "True",
|
||||
"actual": "True",
|
||||
"passing": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Compliance Summary
|
||||
|
||||
```bash
|
||||
GET /api/compliance/summary
|
||||
```
|
||||
|
||||
Returns an overall compliance summary across all templates.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"overall_status": "partial",
|
||||
"total_checks": 22,
|
||||
"total_passed": 18,
|
||||
"total_failed": 4,
|
||||
"templates": [
|
||||
{
|
||||
"name": "gdpr",
|
||||
"display_name": "GDPR (General Data Protection Regulation)",
|
||||
"enabled": true,
|
||||
"status": "compliant",
|
||||
"total": 7,
|
||||
"passed": 7,
|
||||
"failed": 0,
|
||||
"applied_at": "2026-03-09T12:00:00+00:00",
|
||||
"applied_by": "admin@example.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** All API endpoints require admin authentication.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `COMPLIANCE_ENABLED` | `True` | Enable the compliance templates dashboard. Set to `False` to hide the feature. |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Apply templates before going live** — Set up compliance before processing real documents
|
||||
2. **Monitor status regularly** — Check the compliance dashboard after configuration changes
|
||||
3. **Use the refresh button** — After changing settings elsewhere, refresh the compliance page to see updated status
|
||||
4. **Combine templates** — You can apply multiple templates; settings overlap is handled automatically
|
||||
5. **Review after updates** — After upgrading DocuElevate, review your compliance status as new checks may be added
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Configuration Guide](./ConfigurationGuide.md) — Full list of configuration options
|
||||
- [Privacy & Compliance Guide](./PrivacyCompliance.md) — Privacy notice and GDPR compliance details
|
||||
- [Deployment Guide](./DeploymentGuide.md) — Production deployment with security best practices
|
||||
- [Security Audit](../SECURITY_AUDIT.md) — Security findings and mitigations
|
||||
@@ -16,6 +16,7 @@ Configuration is primarily done through environment variables specified in a `.e
|
||||
| `GOTENBERG_URL` | Gotenberg PDF processing URL. | `http://gotenberg:3000` |
|
||||
| `EXTERNAL_HOSTNAME` | The external hostname for the application. | `docuelevate.example.com` |
|
||||
| `ALLOW_FILE_DELETE` | Enable file deletion in the web interface (`true`/`false`). | `true` |
|
||||
| `COMPLIANCE_ENABLED` | Enable the compliance templates dashboard (GDPR, HIPAA, SOC 2). | `true` |
|
||||
|
||||
### Batch Processing Settings
|
||||
|
||||
@@ -303,6 +304,42 @@ DocuElevate can automatically pull document attachments from IMAP mailboxes —
|
||||
| `IMAP1_SSL` | Use SSL (`true`/`false`). | `true` |
|
||||
| `IMAP1_POLL_INTERVAL_MINUTES` | Frequency in minutes to poll for new mail. | `5` |
|
||||
| `IMAP_READONLY_MODE` | When `true`, fetches and processes attachments but does **not** modify the mailbox (no starring, labeling, deleting, or flag changes). Use for pre-production instances sharing a mailbox with production. Default: `false`. | `false` |
|
||||
| `IMAP_ATTACHMENT_FILTER` | System-wide fallback for which attachment types are ingested when no ingestion profile is assigned to a mailbox. `documents_only` (default) ingests PDFs and office files only — images are skipped. `all` ingests every supported file type including images. Individual IMAP accounts can override this using ingestion profiles. | `documents_only` |
|
||||
|
||||
#### IMAP Ingestion Profiles
|
||||
|
||||
For fine-grained control, DocuElevate supports **Ingestion Profiles** — named configurations that let you choose exactly which file-type categories to accept from each mailbox.
|
||||
|
||||
Each profile contains a list of enabled **categories**:
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| `pdf` | PDF documents (`.pdf`) |
|
||||
| `office` | Microsoft Office files (Word, Excel, PowerPoint — `.docx`, `.xlsx`, `.pptx`, …) |
|
||||
| `opendocument` | LibreOffice/OpenOffice files (`.odt`, `.ods`, `.odp`, …) |
|
||||
| `text` | Plain text, CSV and RTF files (`.txt`, `.csv`, `.rtf`) |
|
||||
| `web` | HTML and Markdown files (`.html`, `.htm`, `.md`, `.markdown`) |
|
||||
| `images` | Image files (`.jpg`, `.png`, `.gif`, `.bmp`, `.tiff`, `.webp`, `.svg`) |
|
||||
|
||||
Two built-in system profiles are seeded automatically:
|
||||
|
||||
| Profile | Categories |
|
||||
|---------|------------|
|
||||
| **Documents Only** | pdf, office, opendocument, text, web (no images) |
|
||||
| **All Files** | All categories, including images |
|
||||
|
||||
Users can create their own custom profiles via the **Email Ingestion** dashboard (`/imap-accounts`) by clicking the **Manage profiles** link or the **+** button next to the profile dropdown. Custom profiles are private to the creating user and can be freely edited or deleted.
|
||||
|
||||
**API endpoints for ingestion profiles:**
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/imap-profiles/` | List all visible profiles (system + user's own) |
|
||||
| `POST` | `/api/imap-profiles/` | Create a new profile |
|
||||
| `GET` | `/api/imap-profiles/categories` | List available file-type categories |
|
||||
| `GET` | `/api/imap-profiles/{id}` | Get a single profile |
|
||||
| `PUT` | `/api/imap-profiles/{id}` | Update a profile (not built-in) |
|
||||
| `DELETE` | `/api/imap-profiles/{id}` | Delete a profile (not built-in) |
|
||||
|
||||
#### Per-User IMAP Integrations
|
||||
|
||||
@@ -335,6 +372,28 @@ Credentials are encrypted at rest using Fernet encryption.
|
||||
| `AUTHENTIK_CONFIG_URL` | Configuration URL for Authentik OpenID Connect. |
|
||||
| `OAUTH_PROVIDER_NAME` | Display name for the OAuth provider button. |
|
||||
|
||||
### Social Login Providers
|
||||
|
||||
Social login lets users sign in with their existing Google, Microsoft, Apple, or Dropbox accounts. Each provider is independently enabled and configured. For detailed setup instructions see the [Social Login Setup Guide](SocialLoginSetup.md).
|
||||
|
||||
| **Variable** | **Description** | **Default** |
|
||||
|---|---|---|
|
||||
| `SOCIAL_AUTH_GOOGLE_ENABLED` | Enable Google Sign-In. | `false` |
|
||||
| `SOCIAL_AUTH_GOOGLE_CLIENT_ID` | Google OAuth2 client ID from the Google Cloud Console. | *(empty)* |
|
||||
| `SOCIAL_AUTH_GOOGLE_CLIENT_SECRET` | Google OAuth2 client secret. | *(empty)* |
|
||||
| `SOCIAL_AUTH_MICROSOFT_ENABLED` | Enable Microsoft Sign-In (Azure AD / Microsoft Entra ID). | `false` |
|
||||
| `SOCIAL_AUTH_MICROSOFT_CLIENT_ID` | Microsoft application (client) ID from Azure App Registrations. | *(empty)* |
|
||||
| `SOCIAL_AUTH_MICROSOFT_CLIENT_SECRET` | Microsoft client secret. | *(empty)* |
|
||||
| `SOCIAL_AUTH_MICROSOFT_TENANT` | Azure AD tenant: `common`, `organizations`, `consumers`, or a tenant GUID. | `common` |
|
||||
| `SOCIAL_AUTH_APPLE_ENABLED` | Enable Sign in with Apple. | `false` |
|
||||
| `SOCIAL_AUTH_APPLE_CLIENT_ID` | Apple Services ID (e.g. `com.example.docuelevate`). | *(empty)* |
|
||||
| `SOCIAL_AUTH_APPLE_TEAM_ID` | Apple Developer Team ID. | *(empty)* |
|
||||
| `SOCIAL_AUTH_APPLE_KEY_ID` | Apple Sign-In private key ID. | *(empty)* |
|
||||
| `SOCIAL_AUTH_APPLE_PRIVATE_KEY` | Apple Sign-In private key (PEM format). | *(empty)* |
|
||||
| `SOCIAL_AUTH_DROPBOX_ENABLED` | Enable Dropbox Sign-In. | `false` |
|
||||
| `SOCIAL_AUTH_DROPBOX_CLIENT_ID` | Dropbox OAuth2 App Key. | *(empty)* |
|
||||
| `SOCIAL_AUTH_DROPBOX_CLIENT_SECRET` | Dropbox OAuth2 App Secret. | *(empty)* |
|
||||
|
||||
### Multi-User Mode
|
||||
|
||||
When multi-user mode is enabled, each authenticated user gets their own isolated document space.
|
||||
@@ -398,6 +457,142 @@ default overage buffer applied across all plans.
|
||||
|
||||
DocuElevate supports HTTP security headers to improve browser-side security. **These headers are disabled by default** since most deployments use a reverse proxy (Traefik, Nginx, etc.) that already adds them. Enable only if deploying directly without a reverse proxy. See [Deployment Guide - Security Headers](DeploymentGuide.md#security-headers) for detailed configuration examples.
|
||||
|
||||
### Application Logging
|
||||
|
||||
DocuElevate uses Python's standard `logging` module. Two environment variables control log verbosity:
|
||||
|
||||
| **Variable** | **Description** | **Default** |
|
||||
|-------------|----------------|-------------|
|
||||
| `LOG_LEVEL` | Root logger level. Accepts standard Python level names: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. | `INFO` |
|
||||
| `DEBUG` | Enable debug mode. When `true` **and** `LOG_LEVEL` is **not** explicitly set, the effective log level is automatically lowered to `DEBUG`. | `false` |
|
||||
|
||||
**Precedence rules (standard behaviour):**
|
||||
|
||||
1. If `LOG_LEVEL` is explicitly set, it always wins — regardless of `DEBUG`.
|
||||
2. If only `DEBUG=true` is set (no `LOG_LEVEL`), the effective level becomes `DEBUG`.
|
||||
3. If neither is set, the default level is `INFO`.
|
||||
|
||||
```bash
|
||||
# Typical production (default)
|
||||
# LOG_LEVEL=INFO
|
||||
|
||||
# Quick debug mode — sets level to DEBUG automatically
|
||||
DEBUG=true
|
||||
|
||||
# Explicit level override (DEBUG flag is ignored for level selection)
|
||||
LOG_LEVEL=WARNING
|
||||
```
|
||||
|
||||
> **Tip:** At `DEBUG` level, noisy third-party libraries (httpx, authlib, urllib3, etc.) are automatically pinned to `WARNING` so that application debug output remains readable.
|
||||
|
||||
#### Structured JSON Logging
|
||||
|
||||
Set `LOG_FORMAT=json` to emit structured JSON lines on stdout — one JSON object per log message. This is the standard format for log collectors and SIEM tools:
|
||||
|
||||
| **Variable** | **Description** | **Default** |
|
||||
|-------------|----------------|-------------|
|
||||
| `LOG_FORMAT` | Log output format: `text` (human-readable) or `json` (structured JSON lines). | `text` |
|
||||
|
||||
Each JSON log line contains: `timestamp` (ISO 8601), `level`, `logger`, `message`, `module`, `funcName`, `lineno`, and `exc_info` (when an exception is logged).
|
||||
|
||||
```bash
|
||||
# Enable JSON logging for SIEM / log aggregation
|
||||
LOG_FORMAT=json
|
||||
```
|
||||
|
||||
**Example JSON output:**
|
||||
```json
|
||||
{"timestamp": "2025-03-16T09:18:05.192000+00:00", "level": "INFO", "logger": "app.auth", "message": "[SECURITY] OAUTH_LOGIN_SUCCESS user=alice@example.com admin=False", "module": "auth", "funcName": "oauth_callback", "lineno": 654}
|
||||
```
|
||||
|
||||
**Compatible with:**
|
||||
- **Grafana Loki** — Promtail scrapes JSON from Docker stdout
|
||||
- **Splunk** — Universal Forwarder or HEC with JSON sourcetype
|
||||
- **ELK / OpenSearch** — Filebeat with JSON codec
|
||||
- **Datadog** — Agent auto-parses JSON logs
|
||||
- **Fluentd / Vector** — JSON input plugin
|
||||
- **Docker log drivers** — `--log-driver=json-file` (default) preserves structure
|
||||
|
||||
#### Syslog Forwarding (Application Logs)
|
||||
|
||||
For traditional (non-container) deployments, application logs can be forwarded directly to a syslog receiver. This is **separate** from audit-log SIEM forwarding (see below) — it sends _every_ Python log message, not just audit events.
|
||||
|
||||
| **Variable** | **Description** | **Default** |
|
||||
|-------------|----------------|-------------|
|
||||
| `LOG_SYSLOG_ENABLED` | Forward application logs to a syslog receiver in addition to stdout. | `false` |
|
||||
| `LOG_SYSLOG_HOST` | Hostname or IP of the syslog receiver. | `localhost` |
|
||||
| `LOG_SYSLOG_PORT` | Port of the syslog receiver. | `514` |
|
||||
| `LOG_SYSLOG_PROTOCOL` | Protocol: `udp` or `tcp`. | `udp` |
|
||||
|
||||
```bash
|
||||
# Forward all application logs to syslog
|
||||
LOG_SYSLOG_ENABLED=true
|
||||
LOG_SYSLOG_HOST=syslog.internal.example.com
|
||||
LOG_SYSLOG_PORT=514
|
||||
LOG_SYSLOG_PROTOCOL=udp
|
||||
|
||||
# Combine with JSON format for structured syslog messages
|
||||
LOG_FORMAT=json
|
||||
LOG_SYSLOG_ENABLED=true
|
||||
```
|
||||
|
||||
> **Note:** When `LOG_FORMAT=json`, syslog messages are also sent as JSON. When `LOG_FORMAT=text`, syslog messages use the standard `name - level - message` format.
|
||||
|
||||
### Audit Logging
|
||||
|
||||
DocuElevate provides comprehensive audit logging that records significant actions (logins, document CRUD, settings changes) to an append-only database table. Every entry captures the timestamp, user, action, resource, client IP, and optional JSON details.
|
||||
|
||||
| **Variable** | **Description** | **Default** |
|
||||
|--------------------------------|---------------------------------------------------------------------------------------------------|-------------|
|
||||
| `AUDIT_LOGGING_ENABLED` | Enable the HTTP request audit-logging middleware. | `true` |
|
||||
| `AUDIT_LOG_INCLUDE_CLIENT_IP` | Include the client IP address in audit log entries. Disable for GDPR-sensitive deployments. | `true` |
|
||||
|
||||
#### SIEM Integration
|
||||
|
||||
Audit events can be forwarded in real time to external SIEM systems for centralised monitoring, alerting, and long-term retention. Two transports are supported:
|
||||
|
||||
* **Syslog** – RFC 5424 structured-data messages over UDP or TCP. Works with rsyslog, syslog-ng, Graylog, Datadog, etc.
|
||||
* **HTTP** – JSON POST payloads compatible with Splunk HEC, Logstash HTTP input, Grafana Loki push API, and any generic webhook.
|
||||
|
||||
| **Variable** | **Description** | **Default** |
|
||||
|-------------------------------------|---------------------------------------------------------------------------------------------------|---------------|
|
||||
| `AUDIT_SIEM_ENABLED` | Enable forwarding of audit events to an external SIEM system. | `false` |
|
||||
| `AUDIT_SIEM_TRANSPORT` | Transport: `syslog` or `http`. | `syslog` |
|
||||
| `AUDIT_SIEM_SYSLOG_HOST` | Hostname or IP of the syslog receiver. | `localhost` |
|
||||
| `AUDIT_SIEM_SYSLOG_PORT` | Port of the syslog receiver. | `514` |
|
||||
| `AUDIT_SIEM_SYSLOG_PROTOCOL` | Protocol for syslog: `udp` or `tcp`. | `udp` |
|
||||
| `AUDIT_SIEM_HTTP_URL` | HTTP endpoint URL for SIEM delivery (e.g. Splunk HEC, Logstash, Loki). | *(empty)* |
|
||||
| `AUDIT_SIEM_HTTP_TOKEN` | Bearer / HEC token for the SIEM HTTP endpoint. | *(empty)* |
|
||||
| `AUDIT_SIEM_HTTP_CUSTOM_HEADERS` | Comma-separated `Key:Value` extra headers for SIEM HTTP requests. | *(empty)* |
|
||||
|
||||
**Example – Syslog to rsyslog:**
|
||||
|
||||
```bash
|
||||
AUDIT_SIEM_ENABLED=true
|
||||
AUDIT_SIEM_TRANSPORT=syslog
|
||||
AUDIT_SIEM_SYSLOG_HOST=syslog.internal.example.com
|
||||
AUDIT_SIEM_SYSLOG_PORT=514
|
||||
AUDIT_SIEM_SYSLOG_PROTOCOL=udp
|
||||
```
|
||||
|
||||
**Example – Splunk HEC:**
|
||||
|
||||
```bash
|
||||
AUDIT_SIEM_ENABLED=true
|
||||
AUDIT_SIEM_TRANSPORT=http
|
||||
AUDIT_SIEM_HTTP_URL=https://splunk.example.com:8088/services/collector/event
|
||||
AUDIT_SIEM_HTTP_TOKEN=your-hec-token
|
||||
```
|
||||
|
||||
**Example – Logstash HTTP input:**
|
||||
|
||||
```bash
|
||||
AUDIT_SIEM_ENABLED=true
|
||||
AUDIT_SIEM_TRANSPORT=http
|
||||
AUDIT_SIEM_HTTP_URL=https://logstash.example.com:8080
|
||||
AUDIT_SIEM_HTTP_TOKEN=
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
DocuElevate implements rate limiting to protect against DoS attacks and API abuse. **Rate limiting is enabled by default** and uses Redis for distributed rate limiting across multiple workers.
|
||||
@@ -739,6 +934,48 @@ OPENAI_API_KEY=sk-ant-... # passed as the api_key to LiteLLM
|
||||
|
||||
---
|
||||
|
||||
### Document Translation
|
||||
|
||||
After processing, DocuElevate can automatically translate a document's extracted text into a configurable *default language* (e.g. English). This reference translation is stored alongside the original text so users always have a version in a language they understand.
|
||||
|
||||
Other languages are translated **on the fly** via the AI provider and are not persisted.
|
||||
|
||||
#### Settings
|
||||
|
||||
| **Variable** | **Description** | **Default** |
|
||||
|------------------------------|-----------------------------------------------------------------------------------------------------------|-------------|
|
||||
| `DEFAULT_DOCUMENT_LANGUAGE` | ISO 639-1 code for the default translation target (e.g. `en`, `de`, `fr`). Documents whose detected language differs are automatically translated into this language after processing. | `en` |
|
||||
|
||||
Each user can override this global default in their profile (`UserProfile.default_document_language`).
|
||||
|
||||
#### How It Works
|
||||
|
||||
1. During metadata extraction the AI detects the document language (stored as `detected_language` on the file record).
|
||||
2. If the detected language differs from the default target language, a background Celery task (`translate_to_default_language`) translates the extracted text.
|
||||
3. The translated text is persisted in `default_language_text` and the target code in `default_language_code`.
|
||||
4. The file detail view shows both the original text and the default-language version.
|
||||
5. Users can also request on-the-fly translations to any language via the **Translate** dropdown.
|
||||
|
||||
#### API Endpoints
|
||||
|
||||
| **Endpoint** | **Method** | **Description** |
|
||||
|-----------------------------------------------|------------|------------------------------------------------------------------------|
|
||||
| `/api/files/{id}/translation/default` | GET | Returns the persisted default-language translation (404 if unavailable)|
|
||||
| `/api/files/{id}/translate?lang=xx` | GET | On-the-fly translation to any ISO 639-1 language code |
|
||||
| `/files/{id}/text/default-language` | GET | View endpoint returning the default-language text as JSON |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
# Get the stored English translation of a German document
|
||||
curl http://localhost:8000/api/files/42/translation/default
|
||||
|
||||
# Translate on the fly to French
|
||||
curl "http://localhost:8000/api/files/42/translate?lang=fr"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### OCR Providers
|
||||
|
||||
DocuElevate supports multiple OCR engines that can be used individually or in combination. Configure the list of active providers with `OCR_PROVIDERS` and tune each provider with the settings below.
|
||||
@@ -887,6 +1124,7 @@ TESSERACT_LANGUAGE=eng+deu
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|-------------------------------------|-----------------------------------------------------------------------------------------------------|
|
||||
| `PAPERLESS_ENABLED` | Set to `false` to disable Paperless-ngx uploads without removing credentials. Default: `true` |
|
||||
| `PAPERLESS_NGX_API_TOKEN` | API token for Paperless NGX. |
|
||||
| `PAPERLESS_HOST` | Root URL for Paperless NGX (e.g. `https://paperless.example.com`). |
|
||||
| `PAPERLESS_CUSTOM_FIELD_ABSENDER` | (Optional, Legacy) Name of the custom field in Paperless-ngx to store the sender ("absender") information. If set, the extracted sender will be automatically set as a custom field after document upload. Example: `Absender` or `Sender` |
|
||||
@@ -929,6 +1167,7 @@ PAPERLESS_CUSTOM_FIELDS_MAPPING='{"absender": "Sender", "empfaenger": "Recipient
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|-------------------------|--------------------------------------------------|
|
||||
| `DROPBOX_ENABLED` | Set to `false` to disable Dropbox uploads without removing credentials. Default: `true` |
|
||||
| `DROPBOX_APP_KEY` | Dropbox API app key. |
|
||||
| `DROPBOX_APP_SECRET` | Dropbox API app secret. |
|
||||
| `DROPBOX_REFRESH_TOKEN` | OAuth2 refresh token for Dropbox. |
|
||||
@@ -940,6 +1179,7 @@ For detailed setup instructions, see the [Dropbox Setup Guide](DropboxSetup.md).
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|-------------------------|---------------------------------------------------------------|
|
||||
| `NEXTCLOUD_ENABLED` | Set to `false` to disable Nextcloud uploads without removing credentials. Default: `true` |
|
||||
| `NEXTCLOUD_UPLOAD_URL` | Nextcloud WebDAV URL (e.g. `https://nc.example.com/remote.php/dav/files/<USERNAME>`). |
|
||||
| `NEXTCLOUD_USERNAME` | Nextcloud login username. |
|
||||
| `NEXTCLOUD_PASSWORD` | Nextcloud login password. |
|
||||
@@ -949,6 +1189,7 @@ For detailed setup instructions, see the [Dropbox Setup Guide](DropboxSetup.md).
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|---------------------------------|-------------------------------------------------------|
|
||||
| `GOOGLE_DRIVE_ENABLED` | Set to `false` to disable Google Drive uploads without removing credentials. Default: `true` |
|
||||
| `GOOGLE_DRIVE_USE_OAUTH` | Set to `true` to use OAuth flow (recommended) |
|
||||
| `GOOGLE_DRIVE_CLIENT_ID` | OAuth Client ID (required if using OAuth flow) |
|
||||
| `GOOGLE_DRIVE_CLIENT_SECRET` | OAuth Client Secret (required if using OAuth flow) |
|
||||
@@ -965,6 +1206,7 @@ For detailed setup instructions, see the [Google Drive Setup Guide](GoogleDriveS
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|-------------------------|---------------------------------------------------------------|
|
||||
| `WEBDAV_ENABLED` | Set to `false` to disable WebDAV uploads without removing credentials. Default: `true` |
|
||||
| `WEBDAV_URL` | WebDAV server URL (e.g. `https://webdav.example.com/path`). |
|
||||
| `WEBDAV_USERNAME` | WebDAV authentication username. |
|
||||
| `WEBDAV_PASSWORD` | WebDAV authentication password. |
|
||||
@@ -975,6 +1217,7 @@ For detailed setup instructions, see the [Google Drive Setup Guide](GoogleDriveS
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|-------------------------|---------------------------------------------------------------|
|
||||
| `FTP_ENABLED` | Set to `false` to disable FTP uploads without removing credentials. Default: `true` |
|
||||
| `FTP_HOST` | FTP server hostname or IP address. |
|
||||
| `FTP_PORT` | FTP port (default: `21`). |
|
||||
| `FTP_USERNAME` | FTP authentication username. |
|
||||
@@ -987,6 +1230,7 @@ For detailed setup instructions, see the [Google Drive Setup Guide](GoogleDriveS
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|------------------------------|-------------------------------------------------------|
|
||||
| `SFTP_ENABLED` | Set to `false` to disable SFTP uploads without removing credentials. Default: `true` |
|
||||
| `SFTP_HOST` | SFTP server hostname or IP address. |
|
||||
| `SFTP_PORT` | SFTP port (default: `22`). |
|
||||
| `SFTP_USERNAME` | SFTP authentication username. |
|
||||
@@ -1018,6 +1262,7 @@ For detailed setup instructions, see the [Google Drive Setup Guide](GoogleDriveS
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|----------------------------------|---------------------------------------------------------------------|
|
||||
| `DEST_EMAIL_ENABLED` | Set to `false` to disable email delivery without removing credentials. Default: `true` |
|
||||
| `DEST_EMAIL_HOST` | SMTP server hostname for document delivery. |
|
||||
| `DEST_EMAIL_PORT` | SMTP port for document delivery (default: `587`). |
|
||||
| `DEST_EMAIL_USERNAME` | SMTP authentication username for document delivery. |
|
||||
@@ -1030,6 +1275,7 @@ For detailed setup instructions, see the [Google Drive Setup Guide](GoogleDriveS
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|---------------------------------|-------------------------------------------------------|
|
||||
| `ONEDRIVE_ENABLED` | Set to `false` to disable OneDrive uploads without removing credentials. Default: `true` |
|
||||
| `ONEDRIVE_CLIENT_ID` | Azure AD application client ID |
|
||||
| `ONEDRIVE_CLIENT_SECRET` | Azure AD application client secret |
|
||||
| `ONEDRIVE_TENANT_ID` | Azure AD tenant ID: use "common" for personal accounts or your tenant ID for corporate accounts |
|
||||
@@ -1042,6 +1288,7 @@ For detailed setup instructions, see the [OneDrive Setup Guide](OneDriveSetup.md
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|---------------------------------|-------------------------------------------------------|
|
||||
| `S3_ENABLED` | Set to `false` to disable S3 uploads without removing credentials. Default: `true` |
|
||||
| `AWS_ACCESS_KEY_ID` | AWS IAM access key ID |
|
||||
| `AWS_SECRET_ACCESS_KEY` | AWS IAM secret access key |
|
||||
| `AWS_REGION` | AWS region where your S3 bucket is located (default: `us-east-1`) |
|
||||
@@ -1052,6 +1299,23 @@ For detailed setup instructions, see the [OneDrive Setup Guide](OneDriveSetup.md
|
||||
|
||||
For detailed setup instructions, see the [Amazon S3 Setup Guide](AmazonS3Setup.md).
|
||||
|
||||
### iCloud Drive (Apple)
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|---------------------------------|-------------------------------------------------------|
|
||||
| `ICLOUD_ENABLED` | Set to `false` to disable iCloud uploads without removing credentials. Default: `true` |
|
||||
| `ICLOUD_USERNAME` | Apple ID email address |
|
||||
| `ICLOUD_PASSWORD` | App-specific password (generate at [appleid.apple.com](https://appleid.apple.com/account/manage)) |
|
||||
| `ICLOUD_FOLDER` | Target folder path in iCloud Drive (e.g. `Documents/Uploads`) |
|
||||
| `ICLOUD_COOKIE_DIRECTORY` | Optional directory for session cookie persistence (default: `~/.pyicloud`) |
|
||||
|
||||
> **Note:** Apple does not provide a public REST API for iCloud Drive. This
|
||||
> integration uses the [pyicloud](https://github.com/picklepete/pyicloud)
|
||||
> library which relies on an unofficial, reverse-engineered protocol. Because
|
||||
> most Apple IDs have two-factor authentication enabled, you **must** generate
|
||||
> an [app-specific password](https://support.apple.com/en-us/102654) and use
|
||||
> it as `ICLOUD_PASSWORD`.
|
||||
|
||||
### Notification System
|
||||
|
||||
| **Variable** | **Description** |
|
||||
|
||||
@@ -0,0 +1,343 @@
|
||||
# Internationalization (i18n) & Localization (l10n) Guide
|
||||
|
||||
DocuElevate supports **77 languages** for its web UI, with automatic browser
|
||||
language detection, user-preference persistence, and an AI-powered fallback
|
||||
translator for strings that haven't been manually translated yet.
|
||||
|
||||
## Supported Languages
|
||||
|
||||
| Code | Language | Native Name | Flag | Priority |
|
||||
|---------|--------------------|--------------------|------|----------|
|
||||
| `en` | English | English | 🇬🇧 | Tier 1 |
|
||||
| `de` | German | Deutsch | 🇩🇪 | Tier 1 |
|
||||
| `fr` | French | Français | 🇫🇷 | Tier 1 |
|
||||
| `es` | Spanish | Español | 🇪🇸 | Tier 1 |
|
||||
| `it` | Italian | Italiano | 🇮🇹 | Tier 1 |
|
||||
| `pt` | Portuguese | Português | 🇵🇹 | Tier 1 |
|
||||
| `nl` | Dutch | Nederlands | 🇳🇱 | Tier 2 |
|
||||
| `nb` | Norwegian Bokmål | Norsk bokmål | 🇳🇴 | Tier 2 |
|
||||
| `no` | Norwegian | Norsk | 🇳🇴 | Tier 2 |
|
||||
| `da` | Danish | Dansk | 🇩🇰 | Tier 2 |
|
||||
| `sv` | Swedish | Svenska | 🇸🇪 | Tier 2 |
|
||||
| `fi` | Finnish | Suomi | 🇫🇮 | Tier 2 |
|
||||
| `is` | Icelandic | Íslenska | 🇮🇸 | Tier 2 |
|
||||
| `ga` | Irish | Gaeilge | 🇮🇪 | Tier 2 |
|
||||
| `lb` | Luxembourgish | Lëtzebuergesch | 🇱🇺 | Tier 2 |
|
||||
| `ca` | Catalan | Català | 🏴 | Tier 2 |
|
||||
| `cy` | Welsh | Cymraeg | 🏴 | Tier 2 |
|
||||
| `fy` | Western Frisian | Frysk | 🇳🇱 | Tier 2 |
|
||||
| `gl` | Galician | Galego | 🇪🇸 | Tier 2 |
|
||||
| `li` | Limburgish | Limburgs | 🇳🇱 | Tier 2 |
|
||||
| `vls` | Flemish | West-Vlams | 🇧🇪 | Tier 2 |
|
||||
| `nds` | Low German | Plattdüütsch | 🇩🇪 | Tier 2 |
|
||||
| `pl` | Polish | Polski | 🇵🇱 | Tier 3 |
|
||||
| `cs` | Czech | Čeština | 🇨🇿 | Tier 3 |
|
||||
| `sk` | Slovak | Slovenčina | 🇸🇰 | Tier 3 |
|
||||
| `hu` | Hungarian | Magyar | 🇭🇺 | Tier 3 |
|
||||
| `sl` | Slovenian | Slovenščina | 🇸🇮 | Tier 3 |
|
||||
| `hr` | Croatian | Hrvatski | 🇭🇷 | Tier 3 |
|
||||
| `ro` | Romanian | Română | 🇷🇴 | Tier 3 |
|
||||
| `bg` | Bulgarian | Български | 🇧🇬 | Tier 3 |
|
||||
| `el` | Greek | Ελληνικά | 🇬🇷 | Tier 3 |
|
||||
| `et` | Estonian | Eesti | 🇪🇪 | Tier 3 |
|
||||
| `lv` | Latvian | Latviešu | 🇱🇻 | Tier 3 |
|
||||
| `lt` | Lithuanian | Lietuvių | 🇱🇹 | Tier 3 |
|
||||
| `sr` | Serbian | Српски | 🇷🇸 | Tier 3 |
|
||||
| `tr` | Turkish | Türkçe | 🇹🇷 | Tier 4 |
|
||||
| `uk` | Ukrainian | Українська | 🇺🇦 | Tier 4 |
|
||||
| `he` | Hebrew | עברית | 🇮🇱 | Tier 4 |
|
||||
| `ar` | Arabic | العربية | 🇸🇦 | Tier 4 |
|
||||
| `fa` | Persian | فارسی | 🇮🇷 | Tier 4 |
|
||||
| `af` | Afrikaans | Afrikaans | 🇿🇦 | Tier 4 |
|
||||
| `zh` | Chinese | 中文 | 🇨🇳 | Tier 5 |
|
||||
| `zh-TW` | Traditional Chinese | 繁體中文 | 🇹🇼 | Tier 5 |
|
||||
| `ja` | Japanese | 日本語 | 🇯🇵 | Tier 5 |
|
||||
| `ko` | Korean | 한국어 | 🇰🇷 | Tier 5 |
|
||||
| `vi` | Vietnamese | Tiếng Việt | 🇻🇳 | Tier 5 |
|
||||
| `pa` | Punjabi | ਪੰਜਾਬੀ | 🇮🇳 | Tier 5 |
|
||||
| `kn` | Kannada | ಕನ್ನಡ | 🇮🇳 | Tier 5 |
|
||||
| `hi` | Hindi | हिन्दी | 🇮🇳 | Tier 5 |
|
||||
| `bn` | Bengali | বাংলা | 🇧🇩 | Tier 5 |
|
||||
| `gu` | Gujarati | ગુજરાતી | 🇮🇳 | Tier 5 |
|
||||
| `ml` | Malayalam | മലയാളം | 🇮🇳 | Tier 5 |
|
||||
| `mr` | Marathi | मराठी | 🇮🇳 | Tier 5 |
|
||||
| `ta` | Tamil | தமிழ் | 🇮🇳 | Tier 5 |
|
||||
| `te` | Telugu | తెలుగు | 🇮🇳 | Tier 5 |
|
||||
| `ur` | Urdu | اردو | 🇵🇰 | Tier 5 |
|
||||
| `si` | Sinhala | සිංහල | 🇱🇰 | Tier 5 |
|
||||
| `ne` | Nepali | नेपाली | 🇳🇵 | Tier 5 |
|
||||
| `th` | Thai | ไทย | 🇹🇭 | Tier 5 |
|
||||
| `km` | Khmer | ខ្មែរ | 🇰🇭 | Tier 5 |
|
||||
| `id` | Indonesian | Bahasa Indonesia | 🇮🇩 | Tier 5 |
|
||||
| `ms` | Malay | Bahasa Melayu | 🇲🇾 | Tier 5 |
|
||||
| `jv` | Javanese | Basa Jawa | 🇮🇩 | Tier 5 |
|
||||
| `tl` | Tagalog | Filipino | 🇵🇭 | Tier 5 |
|
||||
| `mn` | Mongolian | Монгол | 🇲🇳 | Tier 5 |
|
||||
| `kk` | Kazakh | Қазақ тілі | 🇰🇿 | Tier 5 |
|
||||
| `uz` | Uzbek | Oʻzbekcha | 🇺🇿 | Tier 5 |
|
||||
| `az` | Azerbaijani | Azərbaycan dili | 🇦🇿 | Tier 5 |
|
||||
| `hy` | Armenian | Հայերեն | 🇦🇲 | Tier 5 |
|
||||
| `ka` | Georgian | ქართული | 🇬🇪 | Tier 5 |
|
||||
| `sw` | Swahili | Kiswahili | 🇰🇪 | Tier 6 |
|
||||
| `am` | Amharic | አማርኛ | 🇪🇹 | Tier 6 |
|
||||
| `ha` | Hausa | Hausa | 🇳🇬 | Tier 6 |
|
||||
| `yo` | Yoruba | Yorùbá | 🇳🇬 | Tier 6 |
|
||||
| `ig` | Igbo | Igbo | 🇳🇬 | Tier 6 |
|
||||
| `zu` | Zulu | isiZulu | 🇿🇦 | Tier 6 |
|
||||
| `eo` | Esperanto | Esperanto | 🌍 | Tier 7 |
|
||||
|
||||
> **Tier 1** languages (major European) have complete, manually-reviewed
|
||||
> translations. **Tier 2–3** languages have complete translations but may
|
||||
> receive less frequent updates. **Tier 4** covers Non-EU European, Middle
|
||||
> Eastern, and South African (Afrikaans) languages. **Tier 5** covers Asian
|
||||
> and Central Asian languages. **Tier 6** covers African languages. **Tier 7**
|
||||
> covers constructed languages.
|
||||
|
||||
## How Language Is Detected
|
||||
|
||||
DocuElevate resolves the display language in the following priority order:
|
||||
|
||||
1. **User profile preference** — stored in the database (`UserProfile.preferred_language`)
|
||||
and loaded into the session on login
|
||||
2. **Cookie** — `docuelevate_lang` cookie (30-day expiry, set when user selects a language)
|
||||
3. **Browser `Accept-Language` header** — the highest-priority match among supported languages
|
||||
4. **Default** — English (`en`)
|
||||
|
||||
## Selecting Your Language
|
||||
|
||||
### Via the Navigation Bar
|
||||
|
||||
Click the 🌐 **globe icon** in the top navigation bar. A dropdown menu shows all
|
||||
available languages with their native names and flag emoji. The current language
|
||||
is highlighted with a blue checkmark.
|
||||
|
||||
### Via the API
|
||||
|
||||
```bash
|
||||
# Set language to German
|
||||
curl -X POST http://localhost:8000/api/i18n/language \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"language": "de"}'
|
||||
|
||||
# List all available languages
|
||||
curl http://localhost:8000/api/i18n/languages
|
||||
```
|
||||
|
||||
### Via Cookie (Programmatic)
|
||||
|
||||
Set the `docuelevate_lang` cookie to any supported language code:
|
||||
|
||||
```javascript
|
||||
document.cookie = "docuelevate_lang=fr; max-age=2592000; path=/";
|
||||
location.reload();
|
||||
```
|
||||
|
||||
## For Developers
|
||||
|
||||
### Translation File Structure
|
||||
|
||||
Translations are stored as flat JSON files in `frontend/translations/`:
|
||||
|
||||
```
|
||||
frontend/translations/
|
||||
├── en.json # English (base / reference)
|
||||
├── af.json # Afrikaans
|
||||
├── ar.json # Arabic
|
||||
├── bg.json # Bulgarian
|
||||
├── ca.json # Catalan
|
||||
├── cs.json # Czech
|
||||
├── cy.json # Welsh
|
||||
├── da.json # Danish
|
||||
├── de.json # German
|
||||
├── el.json # Greek
|
||||
├── eo.json # Esperanto
|
||||
├── es.json # Spanish
|
||||
├── et.json # Estonian
|
||||
├── fa.json # Persian
|
||||
├── fi.json # Finnish
|
||||
├── fr.json # French
|
||||
├── fy.json # Frisian
|
||||
├── ga.json # Irish
|
||||
├── gl.json # Galician
|
||||
├── he.json # Hebrew
|
||||
├── hr.json # Croatian
|
||||
├── hu.json # Hungarian
|
||||
├── is.json # Icelandic
|
||||
├── it.json # Italian
|
||||
├── ja.json # Japanese
|
||||
├── kn.json # Kannada
|
||||
├── ko.json # Korean
|
||||
├── lb.json # Luxembourgish
|
||||
├── li.json # Limburgish
|
||||
├── lt.json # Lithuanian
|
||||
├── lv.json # Latvian
|
||||
├── nb.json # Norwegian Bokmål
|
||||
├── nds.json # Low German (Plattdeutsch)
|
||||
├── nl.json # Dutch
|
||||
├── no.json # Norwegian
|
||||
├── pa.json # Punjabi
|
||||
├── pl.json # Polish
|
||||
├── pt.json # Portuguese
|
||||
├── ro.json # Romanian
|
||||
├── ru.json # Russian
|
||||
├── sk.json # Slovak
|
||||
├── sl.json # Slovenian
|
||||
├── sr.json # Serbian
|
||||
├── sv.json # Swedish
|
||||
├── tr.json # Turkish
|
||||
├── uk.json # Ukrainian
|
||||
├── vi.json # Vietnamese
|
||||
├── vls.json # West Flemish
|
||||
└── zh.json # Chinese
|
||||
```
|
||||
|
||||
Each file is a flat key-value dictionary with dot-notation namespacing:
|
||||
|
||||
```json
|
||||
{
|
||||
"nav.dashboard": "Dashboard",
|
||||
"nav.upload": "Upload",
|
||||
"upload.max_size": "Maximum file size: {size}",
|
||||
"footer.copyright": "DocuElevate {year}"
|
||||
}
|
||||
```
|
||||
|
||||
### Using Translations in Templates
|
||||
|
||||
The `_()` function is available globally in all Jinja2 templates:
|
||||
|
||||
```jinja2
|
||||
{# Simple translation #}
|
||||
<h1>{{ _("dashboard.title") }}</h1>
|
||||
|
||||
{# Translation with placeholders #}
|
||||
<p>{{ _("upload.max_size", size="50 MB") }}</p>
|
||||
|
||||
{# Translation in attributes #}
|
||||
<button aria-label="{{ _('common.save') }}">{{ _("common.save") }}</button>
|
||||
```
|
||||
|
||||
### Using Translations in Python
|
||||
|
||||
```python
|
||||
from app.utils.i18n import translate
|
||||
|
||||
# Basic translation
|
||||
text = translate("nav.dashboard", "de") # → "Übersicht"
|
||||
|
||||
# With placeholders
|
||||
text = translate("footer.copyright", "fr", year="2025") # → "DocuElevate 2025"
|
||||
```
|
||||
|
||||
### Localization Helpers
|
||||
|
||||
Format dates, times, and numbers according to locale conventions:
|
||||
|
||||
```jinja2
|
||||
{# In templates — locale is automatically detected #}
|
||||
<span>{{ format_date_l10n(document.created_at) }}</span>
|
||||
<span>{{ format_number_l10n(file_count) }}</span>
|
||||
```
|
||||
|
||||
```python
|
||||
# In Python
|
||||
from app.utils.i18n import format_date, format_number
|
||||
|
||||
format_date(date(2025, 3, 15), "de") # → "15. March 2025"
|
||||
format_date(date(2025, 3, 15), "de", short=True) # → "15.03.2025"
|
||||
format_number(1234567, "de") # → "1.234.567"
|
||||
format_number(1234.56, "en") # → "1,234.56"
|
||||
```
|
||||
|
||||
### Adding a New Translation Key
|
||||
|
||||
1. Add the key and English text to `frontend/translations/en.json`
|
||||
2. Use `{{ _("your.new.key") }}` in templates or `translate("your.new.key", locale)` in Python
|
||||
|
||||
That's it. An external automation script picks up new keys in `en.json` and propagates
|
||||
translations to all other language files. You never need to touch the non-English JSON
|
||||
files manually — the translate-and-sync pipeline takes care of it.
|
||||
|
||||
### AI Fallback Translation
|
||||
|
||||
When a translation key exists in English but not in the target language,
|
||||
DocuElevate can use the configured AI provider (OpenAI, Anthropic, etc.)
|
||||
to translate the string on-the-fly:
|
||||
|
||||
```python
|
||||
from app.utils.i18n import translate_with_ai_fallback
|
||||
|
||||
# Falls back to AI if no manual translation exists
|
||||
translated = translate_with_ai_fallback("Welcome to our platform", "de")
|
||||
```
|
||||
|
||||
The AI fallback:
|
||||
- Uses the `AI_MODEL` or `OPENAI_MODEL` setting
|
||||
- Caches results in memory for the process lifetime
|
||||
- Returns the original English text if the AI call fails
|
||||
- Is designed for graceful degradation — the UI never breaks
|
||||
|
||||
### Adding a New Language
|
||||
|
||||
1. Create a new JSON file in `frontend/translations/` (e.g., `ja.json`)
|
||||
2. Copy the structure from `en.json` and translate all values
|
||||
3. Add the language to `SUPPORTED_LANGUAGES` in `app/utils/i18n.py`:
|
||||
```python
|
||||
{"code": "ja", "name": "Japanese", "native": "日本語", "flag": "🇯🇵"},
|
||||
```
|
||||
4. Add locale formatting rules to `_LOCALE_FORMATS` in the same file
|
||||
5. Create a database migration if needed (the `preferred_language` column
|
||||
already accepts any string up to 10 characters)
|
||||
|
||||
### Database Migration
|
||||
|
||||
Migration `027_add_user_language_preference` adds a `preferred_language`
|
||||
column to the `user_profiles` table. This column stores the user's chosen
|
||||
UI language as an ISO 639-1 code (e.g., `"de"`, `"fr"`). A `NULL` value
|
||||
means "auto-detect from browser settings."
|
||||
|
||||
### API Reference
|
||||
|
||||
#### `GET /api/i18n/languages`
|
||||
|
||||
Returns all supported languages and the current active language.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"languages": [
|
||||
{"code": "en", "name": "English", "native": "English", "flag": "🇬🇧"},
|
||||
{"code": "de", "name": "German", "native": "Deutsch", "flag": "🇩🇪"}
|
||||
],
|
||||
"current": "en",
|
||||
"default": "en"
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /api/i18n/language`
|
||||
|
||||
Set the preferred UI language. Persists in session, cookie, and database.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{"language": "de"}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"language": "de",
|
||||
"message": "Language changed to Deutsch"
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
No additional configuration is required. The i18n system works out of the box
|
||||
with the default English language and automatically detects browser preferences.
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| Browser `Accept-Language` | Auto-detected | Used when no explicit preference is set |
|
||||
| `docuelevate_lang` cookie | Not set | Set when user selects a language via the UI |
|
||||
| `UserProfile.preferred_language` | `NULL` | Stored in DB for authenticated users |
|
||||
@@ -0,0 +1,364 @@
|
||||
# Mobile App
|
||||
|
||||
DocuElevate includes a native mobile application for iOS and Android built with **React Native** and **Expo**. The app allows users to capture documents with the device camera, pick files from the device storage, and receive push notifications when documents finish processing.
|
||||
|
||||
## Features
|
||||
|
||||
| Feature | iOS | Android |
|
||||
|---------|-----|---------|
|
||||
| SSO login (OAuth2) | ✅ | ✅ |
|
||||
| Local / basic auth login | ✅ | ✅ |
|
||||
| Auto-generated API token | ✅ | ✅ |
|
||||
| Camera capture → upload | ✅ | ✅ |
|
||||
| File picker upload | ✅ | ✅ |
|
||||
| Share Sheet / Share Intent | ✅ | ✅ |
|
||||
| Push notifications | ✅ | ✅ |
|
||||
| Document list | ✅ | ✅ |
|
||||
| Dark mode | ✅ | ✅ |
|
||||
|
||||
## Getting Started (Development)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 20.19.4 or later (use [nvm](https://github.com/nvm-sh/nvm): `nvm install` inside `mobile/` reads `.nvmrc` automatically)
|
||||
- [Expo CLI](https://docs.expo.dev/get-started/installation/): `npm install -g @expo/cli`
|
||||
- [Expo Go](https://expo.dev/client) app on your iOS or Android device (for development)
|
||||
- A running DocuElevate server reachable from your device
|
||||
|
||||
### Run in development mode
|
||||
|
||||
```bash
|
||||
cd mobile
|
||||
npm install
|
||||
npx expo start
|
||||
```
|
||||
|
||||
Scan the QR code with **Expo Go** on your device. On iOS you can also use the Camera app.
|
||||
|
||||
## Building for Production
|
||||
|
||||
DocuElevate uses **Expo Application Services (EAS)** to produce App Store / Play Store binaries.
|
||||
|
||||
```bash
|
||||
# Install EAS CLI globally
|
||||
npm install -g eas-cli
|
||||
|
||||
# Authenticate with Expo
|
||||
eas login
|
||||
|
||||
# Build for iOS (requires Apple Developer account)
|
||||
eas build --platform ios
|
||||
|
||||
# Build for Android
|
||||
eas build --platform android
|
||||
```
|
||||
|
||||
> **Note:** The mobile app uses `expo-build-properties` with `buildReactNativeFromSource: true` for iOS builds. This is required for Expo SDK 54 (React Native 0.81) compatibility — some native modules still use legacy bridge APIs (`RCTBridge`, `RCTViewManager`, etc.) that are no longer included in the default precompiled XCFrameworks. Building React Native from source makes these headers available, at the cost of slightly longer iOS build times.
|
||||
|
||||
See the [EAS Build documentation](https://docs.expo.dev/build/introduction/) for full setup instructions.
|
||||
|
||||
## Automated CI/CD
|
||||
|
||||
An **EAS Cloud Workflow** (`mobile/.eas/workflows/create-builds.yml`) automates production builds and iOS submission:
|
||||
|
||||
- **Path filtering:** The workflow only triggers on pushes to `main` that include changes inside the `mobile/` directory. Backend-only or documentation-only changes do not trigger a mobile build.
|
||||
- **Build:** Both iOS and Android production builds run in parallel on EAS Build.
|
||||
- **Auto-submit (iOS):** After a successful iOS build, the workflow automatically submits the binary to **App Store Connect** using the credentials configured in `eas.json` (`submit.production.ios`). The build then appears in **TestFlight** for internal testing and can be promoted to the App Store from App Store Connect.
|
||||
|
||||
> **Prerequisite:** An App Store Connect API Key must be configured in EAS for non-interactive submission. See [Troubleshooting → "Session expired"](#session-expired-local-session-during-ios-build) below for setup instructions.
|
||||
|
||||
### Version Management
|
||||
|
||||
Build numbers (iOS `buildNumber` / Android `versionCode`) are managed **remotely** by EAS. The `eas.json` configuration uses:
|
||||
|
||||
```json
|
||||
{
|
||||
"cli": { "appVersionSource": "remote" },
|
||||
"build": { "production": { "autoIncrement": true } }
|
||||
}
|
||||
```
|
||||
|
||||
- **`appVersionSource: "remote"`** — EAS stores the current build number on its servers instead of reading it from `app.json`. This ensures every CI build gets a unique, ever-increasing number without needing to commit version bumps back to the repository.
|
||||
- **`autoIncrement: true`** — EAS automatically increments the build number before each production build.
|
||||
|
||||
The `ios.buildNumber` and `android.versionCode` values in `app.json` serve as the **initial seed** when the remote version is first created; after that they are informational only. Do not rely on them for the actual version submitted to the stores.
|
||||
|
||||
> **Tip:** To check or manually set the remote version, use `eas build:version:get` and `eas build:version:set`.
|
||||
|
||||
## Authentication
|
||||
|
||||
### SSO Login Flow
|
||||
|
||||
The mobile app uses the server's existing OAuth2/SSO setup:
|
||||
|
||||
1. User enters the DocuElevate server URL on the login screen.
|
||||
2. The app opens `<server>/login?mobile=1&redirect_uri=docuelevate://callback` in the **system browser** (Safari / Chrome Custom Tabs).
|
||||
3. The server stores `docuelevate://callback` in the browser session and presents the login page.
|
||||
4. The user authenticates via SSO or local credentials.
|
||||
5. After successful authentication the server mints a long-lived API token and redirects the browser to `docuelevate://callback?token=<token>`.
|
||||
6. `WebBrowser.openAuthSessionAsync` intercepts the `docuelevate://` deep link and returns the URL to the app.
|
||||
7. The app extracts the token from the URL and stores it securely in the device's keychain (`expo-secure-store`).
|
||||
|
||||
> **Security note:** The `redirect_uri` is validated server-side; only URIs with the `docuelevate://` custom scheme (production) or the `exp://` scheme (Expo Go development) are accepted, preventing open-redirect attacks.
|
||||
|
||||
### Testing in Expo Go
|
||||
|
||||
When developing with **Expo Go** the app does not have the `docuelevate://` custom URL scheme registered. The auth flow adapts automatically:
|
||||
|
||||
1. `Linking.createURL('callback')` returns an `exp://` URI pointing at the local dev server (e.g. `exp://192.168.1.5:8081/--/callback`).
|
||||
2. This URI is sent to the server as `redirect_uri`; the server accepts it alongside the production `docuelevate://` scheme.
|
||||
3. After successful authentication the server redirects back to the `exp://` URI.
|
||||
4. `WebBrowser.openAuthSessionAsync` intercepts the deep link and the Expo Go app receives the token.
|
||||
|
||||
No extra configuration is needed — just run `npx expo start` and scan the QR code with the **Expo Go** app.
|
||||
|
||||
### Auto-generated Mobile Token
|
||||
|
||||
When the mobile app completes login it automatically creates a named API token (`"Mobile App – <device name>"`) via `POST /api/mobile/generate-token`. This token:
|
||||
|
||||
- Works identically to tokens created manually in the web UI.
|
||||
- Is shown in the **API Tokens** page (`/api-tokens`) and can be revoked there.
|
||||
- Is stored in the device's secure keychain, never in plain storage.
|
||||
|
||||
## Push Notifications
|
||||
|
||||
Push notifications are delivered via the **Expo Push Notification** service, which routes through Apple Push Notification service (APNs) for iOS and Firebase Cloud Messaging (FCM) for Android.
|
||||
|
||||
**No server-side APNs/FCM credentials are required** – Expo's servers handle the provider integration.
|
||||
|
||||
### How it works
|
||||
|
||||
1. After login, the app requests notification permission from the operating system.
|
||||
2. If granted, the app obtains an **Expo Push Token** (`ExponentPushToken[…]`).
|
||||
3. The token is registered with the backend via `POST /api/mobile/register-device`.
|
||||
4. When a document finishes processing, the server sends a push notification to all registered devices for that user.
|
||||
|
||||
### Managing registered devices
|
||||
|
||||
Users can see and remove their registered devices from the **Profile** tab in the app, or via the API:
|
||||
|
||||
```bash
|
||||
# List registered devices
|
||||
curl -H "Authorization: Bearer <token>" https://your-server/api/mobile/devices
|
||||
|
||||
# Remove a device
|
||||
curl -X DELETE -H "Authorization: Bearer <token>" https://your-server/api/mobile/devices/<id>
|
||||
```
|
||||
|
||||
## Uploading Documents
|
||||
|
||||
### Camera Capture
|
||||
|
||||
1. Open the **Upload** tab.
|
||||
2. Tap **Camera**.
|
||||
3. Point the camera at the document and take a photo.
|
||||
4. The image is immediately uploaded and queued for processing.
|
||||
|
||||
### Photo Library
|
||||
|
||||
1. Open the **Upload** tab.
|
||||
2. Tap **Photos**.
|
||||
3. Select an existing photo from the device's photo library.
|
||||
4. The image is uploaded and queued for processing.
|
||||
|
||||
### File Picker
|
||||
|
||||
1. Open the **Upload** tab.
|
||||
2. Tap **Files**.
|
||||
3. Browse to and select one or more files (PDF, DOCX, images, etc.).
|
||||
4. Files are uploaded and queued for processing.
|
||||
|
||||
### Share Sheet (iOS) / Share Intent (Android)
|
||||
|
||||
The app registers itself as a share target so any file can be sent directly to DocuElevate from another app:
|
||||
|
||||
1. Open a file in Files, Mail, Safari, or any other app.
|
||||
2. Tap the **Share** button (iOS) or **Share** (Android).
|
||||
3. Find and tap **DocuElevate** in the share sheet.
|
||||
4. The file is immediately uploaded and queued for processing.
|
||||
|
||||
> **Note:** The app must be installed on the device for it to appear in the share sheet.
|
||||
|
||||
#### iOS implementation
|
||||
|
||||
`app.json` declares `CFBundleDocumentTypes` (with `LSHandlerRank: Alternate`) inside the iOS `infoPlist`. This tells iOS that DocuElevate can open common document types, making it visible in the share sheet without overriding system defaults. When the user selects DocuElevate, iOS opens the app with a URL via `application:openURL:options:`.
|
||||
|
||||
The URL may arrive as a standard `file://` path **or** under the app's custom `docuelevate://` scheme (e.g. `docuelevate://private/var/mobile/Library/…/file.pdf`). The root layout detects the custom-scheme form and rewrites it to a `file://` URL before forwarding it to the Upload screen through `ShareContext`.
|
||||
|
||||
#### Android implementation
|
||||
|
||||
`app.json` declares `ACTION_SEND` and `ACTION_SEND_MULTIPLE` intent filters for `mimeType: "*/*"` in the `android.intentFilters` section. Incoming content URIs are received the same way as on iOS.
|
||||
|
||||
#### Upload status polling
|
||||
|
||||
After a file is uploaded the app polls `/api/files?search=<filename>` every 5 seconds to find the corresponding `FileRecord`, then polls `/api/files/{id}` to track the processing status in real time. Polling stops automatically once the status reaches a terminal state (`completed`, `failed`, or `duplicate`).
|
||||
|
||||
#### Retrying failed uploads
|
||||
|
||||
If a file upload fails (e.g. due to network issues or a server error), the failed item stays visible in the upload list with an error message and a **"Tap to retry"** hint. Users can retry the upload in two ways:
|
||||
|
||||
- **Tap** the failed item to immediately retry the upload.
|
||||
- **Long-press** the failed item to see a confirmation dialog with a **Retry** option.
|
||||
|
||||
The retry re-uses the original file URI so no re-selection is needed.
|
||||
|
||||
## Mobile API Endpoints
|
||||
|
||||
The backend exposes a dedicated `/api/mobile/` namespace:
|
||||
|
||||
| Method | Endpoint | Auth | Description |
|
||||
|--------|----------|------|-------------|
|
||||
| `POST` | `/api/mobile/generate-token` | Session | Exchange SSO session for API token |
|
||||
| `POST` | `/api/mobile/register-device` | Bearer | Register Expo push token |
|
||||
| `GET` | `/api/mobile/devices` | Bearer | List registered devices |
|
||||
| `DELETE` | `/api/mobile/devices/{id}` | Bearer | Deactivate a device |
|
||||
| `GET` | `/api/mobile/whoami` | Bearer | Get current user profile |
|
||||
|
||||
All other API endpoints (file upload, file listing, etc.) work with Bearer token authentication.
|
||||
|
||||
### POST /api/mobile/generate-token
|
||||
|
||||
Exchanges an active web session (cookie) for a permanent API token suitable for use in the mobile app.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{ "device_name": "John's iPhone" }
|
||||
```
|
||||
|
||||
**Response (201):**
|
||||
```json
|
||||
{
|
||||
"token": "de_AbCdEfGhIjKl...",
|
||||
"token_id": 42,
|
||||
"name": "Mobile App – John's iPhone",
|
||||
"created_at": "2026-03-10T09:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ The `token` value is returned **once only**. Store it in the device's secure keychain immediately.
|
||||
|
||||
### POST /api/mobile/register-device
|
||||
|
||||
Registers an Expo push token for the authenticated user.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"push_token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
|
||||
"device_name": "John's iPhone",
|
||||
"platform": "ios"
|
||||
}
|
||||
```
|
||||
|
||||
Supported platforms: `ios`, `android`, `web`.
|
||||
|
||||
Re-registering the same token is safe (idempotent).
|
||||
|
||||
### GET /api/mobile/whoami
|
||||
|
||||
Returns the current user's profile.
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
{
|
||||
"owner_id": "john@example.com",
|
||||
"display_name": "John Doe",
|
||||
"email": "john@example.com",
|
||||
"avatar_url": "https://www.gravatar.com/avatar/...",
|
||||
"is_admin": false
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
No server-side configuration is required to enable the mobile app. The Expo push notification routing does not need FCM or APNs credentials on the server.
|
||||
|
||||
If you wish to use **direct FCM/APNs** without Expo's relay, replace the `send_expo_push_notification` function in `app/utils/push_notification.py` with your own implementation.
|
||||
|
||||
## Project Structure (mobile/)
|
||||
|
||||
```
|
||||
mobile/
|
||||
├── App.tsx # Root component
|
||||
├── app.json # Expo/EAS configuration
|
||||
├── eas.json # EAS Build profiles
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
└── src/
|
||||
├── context/
|
||||
│ ├── AuthContext.tsx # Auth state + SSO login flow
|
||||
│ └── ShareContext.tsx # Shared-file queue (iOS Share Sheet / Android Intent)
|
||||
├── hooks/
|
||||
│ └── usePushNotifications.ts # Push token registration
|
||||
├── screens/
|
||||
│ ├── LoginScreen.tsx # Server URL + SSO button
|
||||
│ ├── UploadScreen.tsx # Camera capture + photo library + file picker
|
||||
│ ├── FilesScreen.tsx # Processed document list
|
||||
│ └── ProfileScreen.tsx # User profile + sign out
|
||||
└── services/
|
||||
└── api.ts # DocuElevate REST API client
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Session expired Local session" during iOS build
|
||||
|
||||
EAS stores an Apple ID session locally (in `~/.expo/`) to manage code-signing certificates and provisioning profiles. This session expires after a few weeks.
|
||||
|
||||
**To fix:**
|
||||
|
||||
1. **Refresh the session** by running `eas credentials` and re-authenticating with your Apple ID.
|
||||
2. **Recommended for automation:** Replace the Apple ID session with an [App Store Connect API Key](https://docs.expo.dev/app-signing/app-credentials/#app-store-connect-api-key). API keys do not expire and work fully non-interactively:
|
||||
- Create a key at [appstoreconnect.apple.com → Users → Integrations → Keys](https://appstoreconnect.apple.com/access/integrations/api)
|
||||
- Download the `.p8` file and note the **Key ID** and **Issuer ID**
|
||||
- Run `eas credentials` → iOS → *Add an App Store Connect API key*
|
||||
- Upload the `.p8` file when prompted
|
||||
|
||||
Once an API key is configured in EAS, automated builds (including CI and EAS Cloud Workflows) will no longer prompt for a password.
|
||||
|
||||
### Node.js deprecation warning `[DEP0169]` during EAS build
|
||||
|
||||
```
|
||||
(node:XXXXX) [DEP0169] DeprecationWarning: `url.parse()` behavior is not standardized…
|
||||
```
|
||||
|
||||
This warning is emitted by **EAS CLI** (an external tool) when it runs on **Node.js 22 or later**, which deprecates `url.parse()`. It does not indicate a problem in the DocuElevate mobile app itself and will not cause a build failure on its own.
|
||||
|
||||
The `eas.json` build profiles already include `"NODE_NO_WARNINGS": "1"` in their `env` sections to suppress this warning during EAS Cloud builds. For local builds with a system Node.js ≥ 22, suppress it by running:
|
||||
|
||||
```bash
|
||||
NODE_NO_WARNINGS=1 eas build --platform ios
|
||||
```
|
||||
|
||||
or by activating the project's pinned Node.js version first:
|
||||
|
||||
```bash
|
||||
cd mobile
|
||||
nvm use # reads .nvmrc → Node 20.19.4 (no deprecation warning)
|
||||
eas build --platform ios
|
||||
```
|
||||
|
||||
### "Authentication was cancelled or failed"
|
||||
|
||||
- Ensure the server URL is correct (including `https://`).
|
||||
- Verify the server is reachable from your device's network.
|
||||
- Confirm that `AUTH_ENABLED=True` on the server.
|
||||
|
||||
### Push notifications not arriving
|
||||
|
||||
1. Check that the app has notification permission (Settings → DocuElevate → Notifications).
|
||||
2. Verify the device is registered: `GET /api/mobile/devices`.
|
||||
3. Ensure the server can reach `https://exp.host` (outbound HTTPS on port 443).
|
||||
4. On Android, add `google-services.json` to the `mobile/` directory if you are building your own binary.
|
||||
|
||||
### "Connection refused" or timeout
|
||||
|
||||
- Verify that the DocuElevate server is running and accessible.
|
||||
- Ensure the server's `EXTERNAL_HOSTNAME` or reverse proxy is configured correctly.
|
||||
- Check that the server accepts CORS requests from `docuelevate://`.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [API Documentation](./API.md)
|
||||
- [Configuration Guide](./ConfigurationGuide.md)
|
||||
- [Deployment Guide](./DeploymentGuide.md)
|
||||
@@ -0,0 +1,375 @@
|
||||
# Social Login Setup Guide
|
||||
|
||||
This guide explains how to configure social login providers (Google, Microsoft, Apple, Dropbox) for DocuElevate. Social login lets your users sign in with their existing accounts, reducing friction and eliminating the need for separate passwords.
|
||||
|
||||
## Overview
|
||||
|
||||
DocuElevate supports four social login providers:
|
||||
|
||||
| Provider | Protocol | Best For |
|
||||
|----------|----------|----------|
|
||||
| **Google** | OAuth2 / OpenID Connect | Consumers and Google Workspace organizations |
|
||||
| **Microsoft** | OAuth2 / OpenID Connect | Microsoft 365 / Azure AD organizations and personal Microsoft accounts |
|
||||
| **Apple** | OAuth2 / OpenID Connect | iOS/macOS users, privacy-focused users |
|
||||
| **Dropbox** | OAuth2 | Teams already using Dropbox as a storage destination |
|
||||
|
||||
Each provider is **independently enabled** — you can use one, several, or all of them at the same time. Social login works alongside any other DocuElevate authentication method (simple auth, OIDC/Authentik, local signup).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before configuring any social login provider, ensure:
|
||||
|
||||
1. **Authentication is enabled**: `AUTH_ENABLED=true` in your `.env` file
|
||||
2. **Session secret is set**: `SESSION_SECRET` must be a random string of at least 32 characters
|
||||
3. **HTTPS is configured**: All social login providers require HTTPS redirect URIs in production. Use a reverse proxy (Traefik, Nginx, Caddy) with a valid TLS certificate
|
||||
4. **External hostname is set**: `EXTERNAL_HOSTNAME` must match your public domain (e.g., `docuelevate.example.com`)
|
||||
|
||||
> **Note:** Social login users are regular (non-admin) users by default. To grant admin access, use the Admin Panel (**Settings → User Management**) after the user's first login, or configure admin groups via Authentik/OIDC.
|
||||
|
||||
## Callback URLs
|
||||
|
||||
Each social login provider uses a callback URL to redirect users back to DocuElevate after authentication. The callback URL pattern is:
|
||||
|
||||
```
|
||||
https://<EXTERNAL_HOSTNAME>/social-callback/<provider>
|
||||
```
|
||||
|
||||
For example, if your DocuElevate instance is at `https://docuelevate.example.com`:
|
||||
|
||||
| Provider | Callback URL |
|
||||
|----------|-------------|
|
||||
| Google | `https://docuelevate.example.com/social-callback/google` |
|
||||
| Microsoft | `https://docuelevate.example.com/social-callback/microsoft` |
|
||||
| Apple | `https://docuelevate.example.com/social-callback/apple` |
|
||||
| Dropbox | `https://docuelevate.example.com/social-callback/dropbox` |
|
||||
|
||||
---
|
||||
|
||||
## Google Sign-In
|
||||
|
||||
### 1. Create OAuth Credentials in Google Cloud Console
|
||||
|
||||
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Create a new project (or select an existing one)
|
||||
3. Navigate to **APIs & Services → Credentials**
|
||||
4. Click **Create Credentials → OAuth client ID**
|
||||
5. If prompted, configure the **OAuth consent screen** first:
|
||||
- **User Type**: External (or Internal for Google Workspace)
|
||||
- **App name**: DocuElevate
|
||||
- **User support email**: Your email
|
||||
- **Authorized domains**: Your domain (e.g., `example.com`)
|
||||
- **Scopes**: Add `email`, `profile`, and `openid`
|
||||
6. Back on the Credentials page, create an **OAuth 2.0 Client ID**:
|
||||
- **Application type**: Web application
|
||||
- **Name**: DocuElevate
|
||||
- **Authorized redirect URIs**: `https://docuelevate.example.com/social-callback/google`
|
||||
7. Note the **Client ID** and **Client Secret**
|
||||
|
||||
### 2. Configure DocuElevate
|
||||
|
||||
Add to your `.env` file:
|
||||
|
||||
```bash
|
||||
SOCIAL_AUTH_GOOGLE_ENABLED=true
|
||||
SOCIAL_AUTH_GOOGLE_CLIENT_ID=123456789-abcdefg.apps.googleusercontent.com
|
||||
SOCIAL_AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-your-secret-here
|
||||
```
|
||||
|
||||
### 3. Restart DocuElevate
|
||||
|
||||
```bash
|
||||
docker compose restart api worker
|
||||
```
|
||||
|
||||
### Google-Specific Notes
|
||||
|
||||
- **Google Workspace**: If you want to restrict sign-in to users in your Google Workspace organization, set the OAuth consent screen to "Internal"
|
||||
- **Verification**: Google may require app verification if you're using External user type and requesting sensitive scopes. For small teams (<100 users), you can add test users instead
|
||||
- **Unified Auth**: If you also use Google Drive as a storage destination, users who sign in with Google will already be authenticated with a Google identity — simplifying the Google Drive integration experience
|
||||
|
||||
---
|
||||
|
||||
## Microsoft Sign-In (Azure AD / Microsoft Entra ID)
|
||||
|
||||
### 1. Register an Application in Azure
|
||||
|
||||
1. Go to the [Azure Portal](https://portal.azure.com/)
|
||||
2. Navigate to **Microsoft Entra ID → App registrations**
|
||||
3. Click **New registration**
|
||||
4. Fill in:
|
||||
- **Name**: DocuElevate
|
||||
- **Supported account types**: Choose based on your needs:
|
||||
- *Accounts in this organizational directory only* — single-tenant (your org only)
|
||||
- *Accounts in any organizational directory* — multi-tenant
|
||||
- *Accounts in any organizational directory and personal Microsoft accounts* — broadest reach
|
||||
- **Redirect URI**: Select **Web** and enter `https://docuelevate.example.com/social-callback/microsoft`
|
||||
5. Click **Register**
|
||||
6. Note the **Application (client) ID**
|
||||
7. Navigate to **Certificates & secrets → New client secret**
|
||||
8. Add a description and expiration, then click **Add**
|
||||
9. Note the **Value** (this is your client secret — it's only shown once!)
|
||||
|
||||
### 2. Configure API Permissions
|
||||
|
||||
1. In your app registration, go to **API permissions**
|
||||
2. Ensure these permissions are present (they're usually added by default):
|
||||
- `openid`
|
||||
- `profile`
|
||||
- `email`
|
||||
3. Click **Grant admin consent** if you're a tenant admin
|
||||
|
||||
### 3. Configure DocuElevate
|
||||
|
||||
Add to your `.env` file:
|
||||
|
||||
```bash
|
||||
SOCIAL_AUTH_MICROSOFT_ENABLED=true
|
||||
SOCIAL_AUTH_MICROSOFT_CLIENT_ID=12345678-abcd-efgh-ijkl-123456789012
|
||||
SOCIAL_AUTH_MICROSOFT_CLIENT_SECRET=your~client~secret~value
|
||||
SOCIAL_AUTH_MICROSOFT_TENANT=common
|
||||
```
|
||||
|
||||
**Tenant options:**
|
||||
|
||||
| Value | Who Can Sign In |
|
||||
|-------|----------------|
|
||||
| `common` | Any Microsoft account (personal + any Azure AD organization) |
|
||||
| `organizations` | Any Azure AD organization (work/school accounts only) |
|
||||
| `consumers` | Personal Microsoft accounts only (outlook.com, hotmail.com, etc.) |
|
||||
| `<tenant-id>` | Only users in a specific Azure AD tenant (use the GUID from Azure Portal) |
|
||||
|
||||
### 4. Restart DocuElevate
|
||||
|
||||
```bash
|
||||
docker compose restart api worker
|
||||
```
|
||||
|
||||
### Microsoft-Specific Notes
|
||||
|
||||
- **Client secret expiration**: Azure AD client secrets expire (max 2 years). Set a calendar reminder to rotate them before they expire
|
||||
- **Conditional Access**: If your organization uses Azure AD Conditional Access policies, social login will respect them
|
||||
- **Unified Auth**: If you also use OneDrive as a storage destination, users who sign in with Microsoft will already have a Microsoft identity — potentially simplifying OneDrive integration
|
||||
|
||||
---
|
||||
|
||||
## Apple Sign-In
|
||||
|
||||
Apple Sign-In requires an Apple Developer account ($99/year) and more setup than other providers.
|
||||
|
||||
### 1. Configure in Apple Developer Portal
|
||||
|
||||
1. Go to the [Apple Developer Portal](https://developer.apple.com/account/)
|
||||
2. Navigate to **Certificates, Identifiers & Profiles → Identifiers**
|
||||
3. Click **+** and select **App IDs** → Register an App ID:
|
||||
- **Description**: DocuElevate
|
||||
- **Bundle ID**: e.g., `com.example.docuelevate`
|
||||
- Enable **Sign In with Apple** capability
|
||||
4. Click **+** again and select **Services IDs**:
|
||||
- **Description**: DocuElevate Web
|
||||
- **Identifier**: e.g., `com.example.docuelevate.web` (this is your Client ID)
|
||||
- Enable **Sign In with Apple**
|
||||
- Click **Configure** next to Sign In with Apple:
|
||||
- **Primary App ID**: Select the App ID created above
|
||||
- **Domains**: `docuelevate.example.com`
|
||||
- **Return URLs**: `https://docuelevate.example.com/social-callback/apple`
|
||||
5. Click **Save** and **Continue** → **Register**
|
||||
6. Navigate to **Keys** → Click **+** to create a new key:
|
||||
- **Key Name**: DocuElevate Sign-In
|
||||
- Enable **Sign In with Apple**
|
||||
- Click **Configure** and select the App ID created above
|
||||
- Click **Continue** → **Register**
|
||||
- **Download the private key file** (`.p8`) — you can only download it once!
|
||||
- Note the **Key ID**
|
||||
7. Note your **Team ID** (shown in the top-right corner of the Developer Portal)
|
||||
|
||||
### 2. Configure DocuElevate
|
||||
|
||||
Add to your `.env` file:
|
||||
|
||||
```bash
|
||||
SOCIAL_AUTH_APPLE_ENABLED=true
|
||||
SOCIAL_AUTH_APPLE_CLIENT_ID=com.example.docuelevate.web
|
||||
SOCIAL_AUTH_APPLE_TEAM_ID=ABCDE12345
|
||||
SOCIAL_AUTH_APPLE_KEY_ID=FGHIJ67890
|
||||
SOCIAL_AUTH_APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
|
||||
MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQg...
|
||||
...your key content here...
|
||||
-----END PRIVATE KEY-----"
|
||||
```
|
||||
|
||||
> **Tip:** You can also store the private key as a single line with `\n` for line breaks:
|
||||
> ```bash
|
||||
> SOCIAL_AUTH_APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMG...\n-----END PRIVATE KEY-----"
|
||||
> ```
|
||||
|
||||
### 3. Restart DocuElevate
|
||||
|
||||
```bash
|
||||
docker compose restart api worker
|
||||
```
|
||||
|
||||
### Apple-Specific Notes
|
||||
|
||||
- **Email relay**: Apple offers a "Hide My Email" feature that provides a relay email address (e.g., `abc123@privaterelay.appleid.com`). DocuElevate accepts these addresses
|
||||
- **First login only**: Apple sends the user's name only on the very first authorization. If the user revokes and re-authorizes, their name may not be sent again
|
||||
- **Developer account required**: You need an Apple Developer account ($99/year) to use Sign In with Apple
|
||||
- **Key rotation**: Apple private keys don't expire, but if you suspect compromise, revoke the key in the Developer Portal and create a new one
|
||||
|
||||
---
|
||||
|
||||
## Dropbox Sign-In
|
||||
|
||||
### 1. Create a Dropbox App
|
||||
|
||||
1. Go to the [Dropbox App Console](https://www.dropbox.com/developers/apps)
|
||||
2. Click **Create app**
|
||||
3. Choose:
|
||||
- **API**: Scoped access
|
||||
- **Access type**: Full Dropbox (or App folder, depending on your needs)
|
||||
- **Name**: DocuElevate Auth (or reuse your existing Dropbox storage app)
|
||||
4. In the app settings, go to the **OAuth 2** section:
|
||||
- Add **Redirect URI**: `https://docuelevate.example.com/social-callback/dropbox`
|
||||
5. Note the **App key** (this is your Client ID) and **App secret** (this is your Client Secret)
|
||||
|
||||
> **Tip:** If you already have a Dropbox app configured for DocuElevate's storage integration, you can reuse the same app — just add the social login redirect URI. Alternatively, create a separate app for authentication to keep concerns separated.
|
||||
|
||||
### 2. Configure DocuElevate
|
||||
|
||||
Add to your `.env` file:
|
||||
|
||||
```bash
|
||||
SOCIAL_AUTH_DROPBOX_ENABLED=true
|
||||
SOCIAL_AUTH_DROPBOX_CLIENT_ID=your_dropbox_app_key
|
||||
SOCIAL_AUTH_DROPBOX_CLIENT_SECRET=your_dropbox_app_secret
|
||||
```
|
||||
|
||||
### 3. Restart DocuElevate
|
||||
|
||||
```bash
|
||||
docker compose restart api worker
|
||||
```
|
||||
|
||||
### Dropbox-Specific Notes
|
||||
|
||||
- **Unified Auth**: If you also use Dropbox as a storage destination, authenticating via Dropbox establishes the user's Dropbox identity — making it easier to manage Dropbox storage integration
|
||||
- **App review**: Dropbox may require app review for production apps with more than 50 users. See [Dropbox App Review](https://www.dropbox.com/developers/reference/developer-guide#app-review)
|
||||
- **Personal vs. Business**: The same app works for both personal Dropbox and Dropbox Business accounts
|
||||
|
||||
---
|
||||
|
||||
## Unified Authentication and Storage
|
||||
|
||||
One of the key advantages of social login in DocuElevate is the potential for **unified authentication** — using the same identity for both signing in and accessing cloud storage destinations:
|
||||
|
||||
| Social Login Provider | Related Storage Destination | Benefit |
|
||||
|---|---|---|
|
||||
| Google | Google Drive | User already has a Google identity for Drive integration |
|
||||
| Microsoft | OneDrive | User already has a Microsoft identity for OneDrive integration |
|
||||
| Dropbox | Dropbox | User already has a Dropbox identity for Dropbox integration |
|
||||
| Apple | *(none)* | Provides a familiar, privacy-respecting login option |
|
||||
|
||||
When a user signs in with a social provider that matches a configured storage destination, the administrator can leverage the same OAuth credentials or simplify the integration setup. Note that the storage integration credentials are configured separately in the admin settings — social login establishes the user's identity, not their storage permissions.
|
||||
|
||||
## Combining Multiple Auth Methods
|
||||
|
||||
DocuElevate supports running multiple authentication methods simultaneously:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ Login Page │
|
||||
├──────────────────────────────────────────────────┤
|
||||
│ Username / Password form (always shown) │
|
||||
│ │
|
||||
│ ─── Or continue with ─── │
|
||||
│ │
|
||||
│ [Authentik SSO] (if OIDC configured) │
|
||||
│ [Sign in with Google] (if Google enabled) │
|
||||
│ [Sign in with Microsoft] (if Microsoft enabled) │
|
||||
│ [Sign in with Apple] (if Apple enabled) │
|
||||
│ [Sign in with Dropbox] (if Dropbox enabled) │
|
||||
│ │
|
||||
│ [Create account] (if local signup enabled) │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
All methods create or update the same `UserProfile` record, so a user is consistently identified regardless of how they sign in.
|
||||
|
||||
## Admin Management
|
||||
|
||||
Social login users appear in the **Admin → User Management** panel like any other user. Admins can:
|
||||
|
||||
- View which provider a user authenticated with
|
||||
- Block or unblock social login users
|
||||
- Set upload limits and subscription tiers
|
||||
- Grant admin privileges (social login users are never automatically admin)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **HTTPS is required**: All social login providers require HTTPS callback URLs in production
|
||||
2. **Credentials are sensitive**: Store client secrets securely — use environment variables, never commit them to source control
|
||||
3. **Least privilege**: Only request the scopes you need (DocuElevate requests `openid`, `profile`, and `email`)
|
||||
4. **Rotate secrets**: Set calendar reminders to rotate OAuth client secrets before they expire (especially Microsoft, which has a max 2-year expiration)
|
||||
5. **Monitor logins**: Check the DocuElevate audit log for unusual login patterns
|
||||
6. **Social login users are not admins**: Admin access must be explicitly granted by an existing admin
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **"Unknown social provider" error**
|
||||
- The provider is not enabled or credentials are missing
|
||||
- Check that `SOCIAL_AUTH_<PROVIDER>_ENABLED=true` is set
|
||||
- Verify client ID and secret are configured
|
||||
|
||||
2. **"Could not retrieve email from provider" error**
|
||||
- The provider didn't return an email address
|
||||
- For Google: Ensure `email` scope is included (it is by default)
|
||||
- For Apple: User may have chosen "Hide My Email" — this is expected and should still work
|
||||
- For Dropbox: Ensure the app has permission to read the user's email
|
||||
|
||||
3. **Redirect URI mismatch**
|
||||
- The callback URL registered with the provider must exactly match what DocuElevate generates
|
||||
- Check your `EXTERNAL_HOSTNAME` setting
|
||||
- Ensure you're using HTTPS in production
|
||||
- The callback URL format is: `https://<EXTERNAL_HOSTNAME>/social-callback/<provider>`
|
||||
|
||||
4. **"Social login failed" error**
|
||||
- Check DocuElevate logs (`docker compose logs api`) for detailed error messages
|
||||
- Verify the provider's OAuth app is not suspended or in development mode
|
||||
- For Google: Check if the OAuth consent screen needs verification
|
||||
- For Microsoft: Ensure admin consent was granted for the required permissions
|
||||
|
||||
5. **User can't log in after changing provider settings**
|
||||
- After changing social login configuration, restart DocuElevate: `docker compose restart api worker`
|
||||
- Social login settings require a restart to take effect (`restart_required: true`)
|
||||
|
||||
### Debug Checklist
|
||||
|
||||
- [ ] `AUTH_ENABLED=true` is set
|
||||
- [ ] `SESSION_SECRET` is at least 32 characters
|
||||
- [ ] `EXTERNAL_HOSTNAME` matches your public domain
|
||||
- [ ] Provider-specific `_ENABLED=true` is set
|
||||
- [ ] Client ID and secret are correctly configured (no extra spaces)
|
||||
- [ ] Callback URL is registered with the provider
|
||||
- [ ] HTTPS is working on your domain
|
||||
- [ ] DocuElevate has been restarted after configuration changes
|
||||
|
||||
## Environment Variable Reference
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `SOCIAL_AUTH_GOOGLE_ENABLED` | No | Enable Google Sign-In (`true`/`false`). Default: `false` |
|
||||
| `SOCIAL_AUTH_GOOGLE_CLIENT_ID` | When Google enabled | Google OAuth2 client ID |
|
||||
| `SOCIAL_AUTH_GOOGLE_CLIENT_SECRET` | When Google enabled | Google OAuth2 client secret |
|
||||
| `SOCIAL_AUTH_MICROSOFT_ENABLED` | No | Enable Microsoft Sign-In (`true`/`false`). Default: `false` |
|
||||
| `SOCIAL_AUTH_MICROSOFT_CLIENT_ID` | When Microsoft enabled | Azure AD application (client) ID |
|
||||
| `SOCIAL_AUTH_MICROSOFT_CLIENT_SECRET` | When Microsoft enabled | Azure AD client secret |
|
||||
| `SOCIAL_AUTH_MICROSOFT_TENANT` | No | Azure AD tenant. Default: `common` |
|
||||
| `SOCIAL_AUTH_APPLE_ENABLED` | No | Enable Apple Sign-In (`true`/`false`). Default: `false` |
|
||||
| `SOCIAL_AUTH_APPLE_CLIENT_ID` | When Apple enabled | Apple Services ID |
|
||||
| `SOCIAL_AUTH_APPLE_TEAM_ID` | When Apple enabled | Apple Developer Team ID |
|
||||
| `SOCIAL_AUTH_APPLE_KEY_ID` | When Apple enabled | Apple Sign-In key ID |
|
||||
| `SOCIAL_AUTH_APPLE_PRIVATE_KEY` | When Apple enabled | Apple Sign-In private key (PEM) |
|
||||
| `SOCIAL_AUTH_DROPBOX_ENABLED` | No | Enable Dropbox Sign-In (`true`/`false`). Default: `false` |
|
||||
| `SOCIAL_AUTH_DROPBOX_CLIENT_ID` | When Dropbox enabled | Dropbox App Key |
|
||||
| `SOCIAL_AUTH_DROPBOX_CLIENT_SECRET` | When Dropbox enabled | Dropbox App Secret |
|
||||
@@ -348,6 +348,7 @@ in task messages or logs.
|
||||
| `PAPERLESS` | Paperless-ngx REST API, API token |
|
||||
| `EMAIL` | SMTP/STARTTLS, file as attachment |
|
||||
| `RCLONE` | `rclone copyto` subprocess, per-user rclone config |
|
||||
| `ICLOUD` | pyicloud library, Apple ID + app-specific password |
|
||||
|
||||
### Multiple Destinations
|
||||
|
||||
|
||||
+197
-39
@@ -2,6 +2,8 @@
|
||||
|
||||
This document provides solutions to common problems encountered when using DocuElevate.
|
||||
|
||||
> **Tip:** For configuration-specific issues, see also the [Configuration Troubleshooting](ConfigurationTroubleshooting.md) guide.
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Application Won't Start
|
||||
@@ -14,7 +16,7 @@ This document provides solutions to common problems encountered when using DocuE
|
||||
#### Possible Solutions
|
||||
1. **Check environment variables**
|
||||
```bash
|
||||
docker-compose config
|
||||
docker compose config
|
||||
```
|
||||
Ensure all required variables are set properly in your `.env` file.
|
||||
|
||||
@@ -30,6 +32,18 @@ This document provides solutions to common problems encountered when using DocuE
|
||||
```
|
||||
Ensure the port isn't already in use by another application.
|
||||
|
||||
4. **Check Redis connectivity**
|
||||
```bash
|
||||
docker compose logs redis
|
||||
```
|
||||
Ensure Redis is running — both the API server and Celery worker depend on it.
|
||||
|
||||
5. **Check database migrations**
|
||||
```bash
|
||||
docker compose exec api alembic upgrade head
|
||||
```
|
||||
Ensure the database schema is up-to-date.
|
||||
|
||||
### Document Upload Fails
|
||||
|
||||
#### Symptoms
|
||||
@@ -39,41 +53,51 @@ This document provides solutions to common problems encountered when using DocuE
|
||||
|
||||
#### Possible Solutions
|
||||
1. **Check file size limits**
|
||||
- Default maximum file size is 100MB
|
||||
- Adjust `client_max_body_size` in your reverse proxy configuration
|
||||
- Default maximum file size is 1 GB (`MAX_UPLOAD_SIZE`)
|
||||
- Individual file limit: `MAX_SINGLE_FILE_SIZE` (default: same as `MAX_UPLOAD_SIZE`)
|
||||
- If using a reverse proxy, adjust `client_max_body_size` (Nginx) or equivalent
|
||||
|
||||
2. **Verify storage space**
|
||||
```bash
|
||||
df -h
|
||||
```
|
||||
Ensure there's sufficient disk space available.
|
||||
Ensure there's sufficient disk space on the workdir volume.
|
||||
|
||||
3. **Check worker process**
|
||||
```bash
|
||||
docker-compose logs worker
|
||||
docker compose logs worker
|
||||
```
|
||||
Verify the Celery worker is running and processing tasks.
|
||||
|
||||
4. **Check upload quota**
|
||||
If multi-user mode and subscriptions are enabled, verify the user hasn't exceeded their daily upload limit (`DEFAULT_DAILY_UPLOAD_LIMIT`).
|
||||
|
||||
### OCR or Text Extraction Issues
|
||||
|
||||
#### Symptoms
|
||||
- Documents upload but text isn't extracted
|
||||
- Poor quality text extraction
|
||||
- API errors related to Azure services
|
||||
- API errors related to OCR services
|
||||
|
||||
#### Possible Solutions
|
||||
1. **Verify API credentials**
|
||||
Check the Azure Document Intelligence API key and endpoint in your `.env` file.
|
||||
1. **Verify the configured OCR provider**
|
||||
Check which provider is set via the `OCR_PROVIDER` environment variable (defaults to Azure Document Intelligence).
|
||||
|
||||
2. **Check document quality**
|
||||
2. **Verify API credentials**
|
||||
Check the credentials for your configured OCR provider in your `.env` file:
|
||||
- **Azure**: `AZURE_DI_KEY` and `AZURE_DI_ENDPOINT`
|
||||
- **Tesseract**: No credentials required (local), but ensure `TESSERACT_LANGUAGES` is set
|
||||
- **EasyOCR**: No credentials required (local)
|
||||
- **Mistral**: `MISTRAL_OCR_API_KEY`
|
||||
- **Google Document AI**: `GOOGLE_DOCAI_PROJECT_ID`, `GOOGLE_DOCAI_LOCATION`, `GOOGLE_DOCAI_PROCESSOR_ID`
|
||||
- **AWS Textract**: `AWS_TEXTRACT_ACCESS_KEY_ID`, `AWS_TEXTRACT_SECRET_ACCESS_KEY`, `AWS_TEXTRACT_REGION`
|
||||
|
||||
3. **Check document quality**
|
||||
- Ensure documents are clearly scanned
|
||||
- Try preprocessing images to improve quality before upload
|
||||
|
||||
3. **Test API connectivity**
|
||||
```bash
|
||||
curl -X GET -H "Ocp-Apim-Subscription-Key: YOUR_KEY" "YOUR_ENDPOINT"
|
||||
```
|
||||
Ensure the API is accessible from your server.
|
||||
4. **Try multi-provider OCR**
|
||||
Configure `OCR_PROVIDERS` (comma-separated list) with a merge strategy (`OCR_MERGE_STRATEGY`: `ai_merge`, `longest`, or `primary`) for better results.
|
||||
|
||||
### Email Integration Problems
|
||||
|
||||
@@ -84,92 +108,226 @@ This document provides solutions to common problems encountered when using DocuE
|
||||
|
||||
#### Possible Solutions
|
||||
1. **Verify IMAP settings**
|
||||
Check host, port, username, and password in your configuration.
|
||||
Check host, port, username, and password for `IMAP1_*` / `IMAP2_*` in your configuration.
|
||||
|
||||
2. **Test IMAP connectivity**
|
||||
```bash
|
||||
telnet mail.example.com 993
|
||||
docker compose exec api python -c "import imaplib; m = imaplib.IMAP4_SSL('mail.example.com', 993); print('OK')"
|
||||
```
|
||||
Ensure the IMAP server is accessible.
|
||||
Ensure the IMAP server is accessible from the container.
|
||||
|
||||
3. **Enable less secure apps**
|
||||
For Gmail and some providers, you may need to enable access for less secure apps or use app-specific passwords.
|
||||
3. **Check for app-specific passwords**
|
||||
For Gmail and some providers, you must use app-specific passwords instead of your account password.
|
||||
|
||||
4. **Check firewall settings**
|
||||
Ensure your server can make outbound connections to the mail server.
|
||||
Ensure your server can make outbound connections to the mail server on port 993 (IMAP SSL).
|
||||
|
||||
5. **Check attachment filter**
|
||||
If only certain attachments are expected, verify `IMAP_ATTACHMENT_FILTER` is set correctly (`documents_only` or `all`).
|
||||
|
||||
### Storage Integration Issues
|
||||
|
||||
#### Symptoms
|
||||
- Files aren't appearing in Dropbox/Nextcloud/Paperless
|
||||
- Files aren't appearing in configured storage destinations
|
||||
- Authentication errors in logs
|
||||
- API rate limiting errors
|
||||
|
||||
#### Possible Solutions
|
||||
1. **Verify API credentials**
|
||||
Double-check all API keys, tokens, and secrets.
|
||||
Double-check all API keys, tokens, and secrets for the relevant service.
|
||||
|
||||
2. **Check access permissions**
|
||||
Ensure the application has write permissions to the specified folders.
|
||||
Ensure the application has write permissions to the specified folders/buckets.
|
||||
|
||||
3. **Refresh tokens**
|
||||
For OAuth-based services like Dropbox, try generating new refresh tokens.
|
||||
For OAuth-based services like Dropbox, Google Drive, and OneDrive, try re-authorizing through the integration setup pages.
|
||||
|
||||
4. **Examine detailed logs**
|
||||
```bash
|
||||
docker-compose logs worker | grep -i dropbox
|
||||
docker compose logs worker | grep -i "upload_to"
|
||||
```
|
||||
Look for specific error messages related to the service.
|
||||
Look for specific error messages related to the storage service.
|
||||
|
||||
5. **Check integration status**
|
||||
Visit the **Integrations** page in the web UI to verify the connection status of each configured storage backend.
|
||||
|
||||
## Search Issues
|
||||
|
||||
### Symptoms
|
||||
- Search returns no results or incomplete results
|
||||
- Search page shows an error
|
||||
|
||||
### Possible Solutions
|
||||
1. **Check Meilisearch is running**
|
||||
```bash
|
||||
docker compose logs meilisearch
|
||||
```
|
||||
Ensure the Meilisearch container is healthy and accepting connections.
|
||||
|
||||
2. **Verify Meilisearch URL**
|
||||
Check `MEILISEARCH_URL` in your `.env` file (default: `http://meilisearch:7700`).
|
||||
|
||||
3. **Rebuild the search index**
|
||||
If documents are missing from search results, reprocessing them will re-index their content.
|
||||
|
||||
## Pipeline & Routing Issues
|
||||
|
||||
### Symptoms
|
||||
- Documents are not processed according to pipeline steps
|
||||
- Routing rules don't match expected documents
|
||||
|
||||
### Possible Solutions
|
||||
1. **Verify pipeline assignment**
|
||||
On the file detail page, check which pipeline (if any) is assigned. The system pipeline applies to all documents by default.
|
||||
|
||||
2. **Test routing rules**
|
||||
Use the **Evaluate** button on the Routing Rules page to test whether a rule matches a specific document.
|
||||
|
||||
3. **Check step ordering**
|
||||
Pipeline steps execute in order — ensure OCR comes before metadata extraction if the AI step depends on extracted text.
|
||||
|
||||
## Database Issues
|
||||
|
||||
#### Symptoms
|
||||
### Symptoms
|
||||
- Application errors related to database connections
|
||||
- Missing or corrupt data
|
||||
- Slow performance
|
||||
|
||||
#### Possible Solutions
|
||||
### Possible Solutions
|
||||
1. **Check database connection string**
|
||||
Verify the `DATABASE_URL` variable in your `.env` file.
|
||||
|
||||
2. **Inspect database integrity**
|
||||
For SQLite:
|
||||
```bash
|
||||
sqlite3 database.db "PRAGMA integrity_check;"
|
||||
```
|
||||
(For SQLite databases)
|
||||
For PostgreSQL (recommended for production):
|
||||
```bash
|
||||
docker compose exec api python -c "from app.database import engine; print(engine.url)"
|
||||
```
|
||||
|
||||
3. **Perform database migrations**
|
||||
```bash
|
||||
docker-compose exec api alembic upgrade head
|
||||
docker compose exec api alembic upgrade head
|
||||
```
|
||||
Ensure the database schema is up-to-date.
|
||||
|
||||
4. **Consider PostgreSQL for production**
|
||||
SQLite is suitable for small deployments, but PostgreSQL is recommended for multi-user production environments. See the [Database Configuration Guide](DatabaseConfiguration.md).
|
||||
|
||||
## Authentication Problems
|
||||
|
||||
#### Symptoms
|
||||
### Symptoms
|
||||
- Unable to log in
|
||||
- Redirect loops during authentication
|
||||
- OAuth errors
|
||||
|
||||
#### Possible Solutions
|
||||
1. **Verify Authentik configuration**
|
||||
Check client ID, client secret, and configuration URL.
|
||||
### Possible Solutions
|
||||
1. **Verify OAuth/OIDC configuration**
|
||||
Check client ID, client secret, and configuration URL for your identity provider.
|
||||
|
||||
2. **Check callback URLs**
|
||||
Ensure the redirect URIs are correctly configured in your OAuth provider.
|
||||
Ensure the redirect URIs are correctly configured in your OAuth provider. The callback URL is typically `https://your-domain/auth/callback`.
|
||||
|
||||
3. **Clear browser cookies and cache**
|
||||
Authentication issues can sometimes be resolved by clearing browser data.
|
||||
|
||||
4. **Check social login credentials**
|
||||
If using social login (Google, Microsoft, Apple, Dropbox), verify the corresponding `SOCIAL_AUTH_*` environment variables.
|
||||
|
||||
5. **Verify `EXTERNAL_HOSTNAME`**
|
||||
The `EXTERNAL_HOSTNAME` setting must match the domain users access DocuElevate from — OAuth redirect URLs depend on it.
|
||||
|
||||
## Mobile App Issues
|
||||
|
||||
### Symptoms
|
||||
- Can't connect to DocuElevate from the mobile app
|
||||
- Push notifications not received
|
||||
- Login fails
|
||||
|
||||
### Possible Solutions
|
||||
1. **Verify the server URL**
|
||||
Ensure the mobile app is configured with the correct DocuElevate server URL (including `https://`).
|
||||
|
||||
2. **Check API token**
|
||||
Generate a fresh API token from the web UI (Profile → API Tokens) and enter it in the mobile app settings.
|
||||
|
||||
3. **Check network connectivity**
|
||||
The mobile device must be able to reach your DocuElevate server. If using a private network, ensure VPN is connected.
|
||||
|
||||
4. **Push notifications**
|
||||
Push notifications require a valid Expo push token. Check the app settings and ensure notifications are enabled at the OS level.
|
||||
|
||||
See the [Mobile App Guide](MobileApp.md) for detailed setup instructions.
|
||||
|
||||
## CLI Issues
|
||||
|
||||
### Symptoms
|
||||
- CLI commands fail with connection errors
|
||||
- Authentication rejected
|
||||
|
||||
### Possible Solutions
|
||||
1. **Verify URL and token**
|
||||
```bash
|
||||
docuelevate --url https://your-instance --token de_xxx list
|
||||
```
|
||||
Ensure the URL is correct (include the scheme) and the API token is valid.
|
||||
|
||||
2. **Check environment variables**
|
||||
The CLI reads `DOCUELEVATE_URL` and `DOCUELEVATE_API_TOKEN` from the environment. Verify they are exported.
|
||||
|
||||
3. **Test API directly**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer de_xxx" https://your-instance/api/files
|
||||
```
|
||||
If this fails, the issue is with the server, not the CLI.
|
||||
|
||||
See the [CLI Guide](CLIGuide.md) for detailed usage.
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Symptoms
|
||||
- Slow document processing
|
||||
- High memory usage
|
||||
- Queue backing up
|
||||
|
||||
### Possible Solutions
|
||||
1. **Check worker concurrency**
|
||||
The Celery worker processes tasks in parallel. If the queue is backing up, consider scaling workers or adjusting concurrency.
|
||||
|
||||
2. **Enable batch throttling**
|
||||
Set `PROCESSALL_THROTTLE_THRESHOLD` and `PROCESSALL_THROTTLE_DELAY` to prevent overwhelming external APIs.
|
||||
|
||||
3. **Monitor the queue**
|
||||
Visit the **Admin → Queue** page to see pending, active, and failed tasks.
|
||||
|
||||
4. **Use PostgreSQL**
|
||||
SQLite can become a bottleneck under load. Migrate to PostgreSQL for better concurrent performance. See the [Database Configuration Guide](DatabaseConfiguration.md).
|
||||
|
||||
5. **Check Redis memory**
|
||||
```bash
|
||||
docker compose exec redis redis-cli info memory
|
||||
```
|
||||
Ensure Redis has sufficient memory for the task queue and cache.
|
||||
|
||||
## Getting Additional Help
|
||||
|
||||
If you continue to experience issues after trying these solutions:
|
||||
|
||||
1. **Check the logs** for detailed error messages
|
||||
1. **Check the logs** for detailed error messages:
|
||||
```bash
|
||||
docker-compose logs --tail=100
|
||||
docker compose logs --tail=200
|
||||
```
|
||||
|
||||
2. **Open an issue** on the [GitHub repository](https://github.com/christianlouis/document-processor/issues)
|
||||
2. **Check the status page** at `/status` in the web UI for an overview of all service connections.
|
||||
|
||||
3. **Contact the developer** via the information provided on the About page
|
||||
3. **Open an issue** on the [GitHub repository](https://github.com/christianlouis/DocuElevate/issues) with:
|
||||
- A description of the problem
|
||||
- Relevant log output
|
||||
- Your DocuElevate version (shown on the About page or in the `VERSION` file)
|
||||
|
||||
4. **Consult additional documentation**:
|
||||
- [Configuration Guide](ConfigurationGuide.md) — All environment variables
|
||||
- [Configuration Troubleshooting](ConfigurationTroubleshooting.md) — Configuration-specific issues
|
||||
- [Deployment Guide](DeploymentGuide.md) — Infrastructure and deployment
|
||||
|
||||
@@ -63,6 +63,15 @@ DocuElevate features a simple navigation system with the following main sections
|
||||
- **Search**: Dedicated full-text search across all document content
|
||||
- **About**: Information about DocuElevate
|
||||
|
||||
### Other Ways to Use DocuElevate
|
||||
|
||||
Beyond the web interface, DocuElevate is available through several additional clients:
|
||||
|
||||
- **Mobile App (iOS & Android)** — Capture documents with your phone camera or upload from your photo library. See the [Mobile App Guide](MobileApp.md) for setup and usage.
|
||||
- **Browser Extension** — Clip web pages or send files to DocuElevate directly from Chrome, Firefox, or Edge. See the [Browser Extension Guide](BrowserExtension.md) for installation.
|
||||
- **CLI Tool** — Upload, download, search, and manage documents from the command line or scripts. See the [CLI Guide](CLIGuide.md) for details.
|
||||
- **REST & GraphQL API** — Full programmatic access for automation and integrations. See the [API Documentation](API.md).
|
||||
|
||||
## Uploading Documents
|
||||
|
||||
DocuElevate provides multiple convenient ways to upload documents to the system.
|
||||
@@ -626,6 +635,58 @@ Pass no `pipeline_id` to clear the assignment and fall back to the system defaul
|
||||
|
||||
Admins can create **system pipelines** that appear in every user's pipeline list. These can be set as the global default so all users benefit from a consistent processing baseline. Navigate to **Pipelines** and check the **System pipeline** box when creating a new one (admin only).
|
||||
|
||||
### Conditional routing rules
|
||||
|
||||
Routing rules automatically assign incoming documents to the right pipeline
|
||||
based on their properties — no manual pipeline selection required.
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Define one or more routing rules via the API
|
||||
(`POST /api/routing-rules`).
|
||||
2. Each rule specifies a **field** to inspect, an **operator** (condition),
|
||||
a **value** to compare against, and a **target pipeline**.
|
||||
3. When a document is processed, rules are evaluated **in position order**
|
||||
(lowest first). The first matching rule wins and the document is routed
|
||||
to that pipeline.
|
||||
4. If no rule matches, the document is processed by the default pipeline.
|
||||
|
||||
**Available fields:**
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `file_type` | MIME type, e.g. `application/pdf` |
|
||||
| `filename` | Original filename |
|
||||
| `size` | File size in bytes |
|
||||
| `document_type` | AI-classified type (Invoice, Contract, …) |
|
||||
| `category` | Alias for `document_type` |
|
||||
| `metadata.<key>` | Any key from the AI-extracted metadata JSON |
|
||||
|
||||
**Available operators:**
|
||||
|
||||
| Operator | Description |
|
||||
|----------|-------------|
|
||||
| `equals` / `not_equals` | Exact match (case-insensitive) |
|
||||
| `contains` / `not_contains` | Substring match (case-insensitive) |
|
||||
| `regex` | Full Python regex match (case-insensitive) |
|
||||
| `gt` / `lt` / `gte` / `lte` | Numeric comparison (greater/less than) |
|
||||
|
||||
**Example:** Route invoices to one pipeline and large files to another:
|
||||
|
||||
```
|
||||
Rule 1: field=document_type, operator=equals, value=Invoice, target_pipeline=3
|
||||
Rule 2: field=size, operator=gt, value=1048576, target_pipeline=5
|
||||
```
|
||||
|
||||
With first-match-wins logic, an invoice of any size matches Rule 1 and is
|
||||
routed to pipeline 3. A non-invoice file larger than 1 MB matches Rule 2
|
||||
and is routed to pipeline 5. Everything else falls back to the default
|
||||
pipeline.
|
||||
|
||||
You can test your rules without actually routing a document using the
|
||||
**evaluate** endpoint (`POST /api/routing-rules/evaluate`). For the full
|
||||
API reference, see [API Documentation](API.md#routing-rules).
|
||||
|
||||
## API Access
|
||||
|
||||
For programmatic access, DocuElevate provides a comprehensive REST API:
|
||||
|
||||
@@ -63,6 +63,54 @@ DocuElevate will process the following attachment types from emails:
|
||||
| TIFF | `.tif`, `.tiff` | Common format from older scanners/fax |
|
||||
| Multi-page TIFF | `.tif` | Full multi-page support |
|
||||
|
||||
### Controlling Which Attachment Types Are Ingested
|
||||
|
||||
By default, DocuElevate only ingests **document** attachments (PDFs, Word, Excel, PowerPoint, OpenDocument, RTF, TXT, CSV, HTML, Markdown). Images are **not** ingested by default — this prevents cluttering your document archive with inline images or unrelated photo attachments.
|
||||
|
||||
#### Global Default (Admin Setting)
|
||||
|
||||
Set the `IMAP_ATTACHMENT_FILTER` environment variable to control the system-wide fallback when no ingestion profile is assigned to a mailbox:
|
||||
|
||||
| Value | Behaviour |
|
||||
|-------|-----------|
|
||||
| `documents_only` | **(Default)** Only PDFs and office/document files. Images are skipped. |
|
||||
| `all` | All supported file types, including images. |
|
||||
|
||||
```env
|
||||
IMAP_ATTACHMENT_FILTER=documents_only
|
||||
```
|
||||
|
||||
#### Ingestion Profiles (Fine-Grained Per-Mailbox Control)
|
||||
|
||||
For precise control, you can create **Ingestion Profiles** that let you pick exactly which file-type categories to accept from each mailbox. This is more powerful than the binary global toggle and works independently per mailbox.
|
||||
|
||||
**Available categories:**
|
||||
|
||||
| Category | File types included |
|
||||
|----------|---------------------|
|
||||
| PDF | `.pdf` |
|
||||
| Microsoft Office | `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`, and macro-enabled variants |
|
||||
| OpenDocument | `.odt`, `.ods`, `.odp`, `.odg`, `.odf` (LibreOffice / OpenOffice) |
|
||||
| Text & Data | `.txt`, `.csv`, `.rtf` |
|
||||
| Web & Markup | `.html`, `.htm`, `.md`, `.markdown` |
|
||||
| Images | `.jpg`, `.png`, `.gif`, `.bmp`, `.tiff`, `.webp`, `.svg` |
|
||||
|
||||
**Managing profiles:**
|
||||
|
||||
1. Go to **Email Ingestion** (`/imap-accounts`)
|
||||
2. Click **Manage profiles** (or the **+** icon next to the profile dropdown)
|
||||
3. Create a new profile, give it a name, and tick the categories you want
|
||||
4. When adding or editing a mailbox, select your profile from the dropdown
|
||||
|
||||
Two built-in profiles are always available and cannot be deleted:
|
||||
|
||||
- **Documents Only** — PDF, Office, OpenDocument, Text, Web (no images)
|
||||
- **All Files** — all categories including images
|
||||
|
||||
Users can also create unlimited **custom profiles** to mix and match exactly the categories they need per mailbox (e.g. a scanner mailbox that only accepts PDFs, or a finance mailbox that accepts Office and CSV but not images).
|
||||
|
||||
Custom profiles are created via the UI or the `/api/imap-profiles/` API.
|
||||
|
||||
---
|
||||
|
||||
## Setting Up Your Scanner/Device
|
||||
|
||||
Reference in New Issue
Block a user