Configuration Reference¶

Paperless NGX Dedupe uses:

• Environment variables for server/runtime behavior
• Dedup settings stored in the app database and editable at runtime

Environment Variables¶

Core Runtime¶

* Provide either PAPERLESS_API_TOKEN or both PAPERLESS_USERNAME + PAPERLESS_PASSWORD.

If both token and username/password are set, token is used first.

Paperless connection settings and all credentials are environment-owned. The Settings page exposes the configured URL as read-only and only reports whether authentication is configured; it never reads, stores, exports, or accepts these values through the database or configuration API. Existing legacy credential rows in app_config are removed during startup migration. Keep the values in your deployment environment or secret manager when moving an installation.

Container Runtime¶

SvelteKit / Proxy¶

AI Processing (Optional)¶

The API key is required when AI_ENABLED=true. Runtime settings (model, prompt, etc.) are configured in the Settings page or via API. See AI Processing for full details.

Observability (Optional)¶

OpenTelemetry is off unless OTEL_ENABLED=true. Common vars:

• OTEL_ENABLED
• OTEL_SERVICE_NAME
• OTEL_EXPORTER_OTLP_ENDPOINT (or per-signal endpoints)
• OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER

See .env.example for the full list.

Continuous Profiling (Optional)¶

Profiles are labeled by operation (sync, analysis, ai_batch, worker) for flame graph filtering.

Prometheus Scrape Endpoint (Optional)¶

When enabled, all application metrics (sync, analysis, jobs, AI, observable gauges) are available in Prometheus exposition format at GET /api/v1/metrics. This can be used standalone (without OTEL_ENABLED) or alongside full OTEL for both push and pull metrics.

When both are active, the Prometheus endpoint exposes the same metrics as the OTLP pipeline.

Paperless-NGX System Metrics (Optional)¶

When enabled, Paperless NGX Dedupe collects system-level metrics from your Paperless-NGX instance — storage, document counts, tags, correspondents, and more. This provides the same observability as running a separate prometheus-paperless-exporter container, but delivered through whichever metrics pipeline you have active (OTLP, Prometheus, or both) — one fewer container to manage.

For the supported collectors, metric names match the Prometheus exporter (for example, paperless_status_storage_total_bytes and paperless_statistics_documents_total) for Grafana dashboard compatibility. Exporter collectors that this application does not provide, such as individual task and log metrics, are not exposed.

Paperless-NGX 3.x applies permissions to system-wide observability data. The API user needs paperless.view_system_monitoring for the status collector. Grant paperless.view_global_statistics if the statistics and document collectors should report global counts; without it, Paperless returns counts limited to objects visible to that user.

Available collectors:

All collectors are enabled by default. To enable only specific collectors:

PAPERLESS_METRICS_COLLECTORS=status,statistics,document

Metrics are collected on the same interval as OTEL metric exports (controlled by OTEL_METRIC_EXPORT_INTERVAL, default 60s). Instances with many tags, correspondents, or document types will produce proportionally more time series from the labeled collectors (tag, correspondent, document_type, storage_path). Disable these if cardinality is a concern.

Credit: metric definitions and collector design inspired by prometheus-paperless-exporter by hansmi.

Deduplication Settings¶

Change these in Settings or via PUT /api/v1/config/dedup.

Algorithm Parameters¶

Confidence Weights¶

The confidence model uses a 2-weight base score plus a discriminative penalty:

Base weights are integers 0-100 and must sum to 100:

Discriminative penalty reduces confidence when template-based documents have different structured data (dates, amounts, invoice numbers, routes):

The final confidence formula is:

base  = (jaccard × J_weight + fuzzy × F_weight) / (J_weight + F_weight)
final = base × (1 - penalty_strength/100 × (1 - discriminative_score))

When the discriminative score is high (documents share the same dates, amounts, and references), the penalty has little effect. When it is low (documents have different dates, amounts, invoice numbers, or routes despite sharing a template), the penalty reduces the confidence score.

Strength guidelines:

• Low (0-30%): Minimal impact. Monthly invoices or train tickets with different dates may still appear as duplicates.
• Medium (40-70%): Recommended for most libraries. Catches template-based false positives while keeping true duplicates intact.
• High (80-100%): Aggressive. Best for libraries with many monthly invoices, bank statements, or train/flight tickets. May over-penalize minor OCR differences in dates or amounts.

When any weight or penalty strength changes, existing group confidence scores are recalculated automatically.

Example API Updates¶

# Update threshold
curl -X PUT http://localhost:3000/api/v1/config/dedup \
  -H 'Content-Type: application/json' \
  -d '{"similarityThreshold":0.8}'

# Rebalance weights (must sum to 100)
curl -X PUT http://localhost:3000/api/v1/config/dedup \
  -H 'Content-Type: application/json' \
  -d '{
    "confidenceWeightJaccard":70,
    "confidenceWeightFuzzy":30
  }'

# Adjust discriminative penalty strength (0 = disabled, 100 = maximum)
curl -X PUT http://localhost:3000/api/v1/config/dedup \
  -H 'Content-Type: application/json' \
  -d '{"discriminativePenaltyStrength":75}'

Related¶

• Installation
• How It Works
• API Reference