Guide¶

How to install and set up Paperless Unified Search, how it finds documents and decides who sees them, what it needs, how to use it, and how it handles security and privacy.

Quick start¶

Install Paperless Unified Search from the Nextcloud App Store under Apps, or with occ app:install paperless_unified_search.
In Paperless-ngx, create an account that may read the documents to search, and an API token for it.
In Nextcloud, open Administration settings → Paperless Unified Search, enter the Paperless URL and the token, and select Test connection and save. With Paperless Sync installed, the account it writes the archive with is the Archive account; otherwise enter the account that owns the synchronized files.
Search in Nextcloud, switch on Search connected services and look under Paperless documents. A result appears for every document whose synchronized file you can open: a file of the archive account with [P<ID>] in its name, your own if you are that account, or one it shared with you. Paperless Sync creates such files.

Configuration and Usage have the details.

How it works¶

flowchart TB
    search(["Nextcloud's search"]) -- "invoice" --> app["Paperless Unified Search"]
    app -- "searches the OCR text" --> paperless[("Paperless-ngx")]
    app -- "finds the file of each hit<br/>by its marker" --> archive[("Archive in Nextcloud<br/>… invoice [P412].pdf")]
    paperless -. "every document" .-> sync["Paperless Sync"]
    sync -. "writes it as a file<br/>with its marker" .-> archive

Nextcloud forwards an enabled external-search query to Paperless-ngx.
Paperless returns results from its native OCR/full-text index.
The app maps each Paperless document ID to a synchronized file of the archive account whose name contains the unique marker [P<ID>], for example [P123]. The archive account is the one that owns the synchronized files: the account of Paperless Sync, or the one of the settings.
A result is returned only if the current Nextcloud user can access that file: the archive account itself, or a user it shared the file with. A file with the marker in its name that belongs to another account stands for no document.
Selecting a result opens the synchronized file in Nextcloud, not Paperless. Browsers use Nextcloud's /f/{fileId} viewer route. The official iOS app receives its native nextcloud://open-file deep link, while Android receives the file ID and user-relative path required by its in-app viewer.

Who sees document 412, when paperless is the archive account and has shared its archive with jamie:

flowchart LR
    subgraph owner["paperless, the archive account"]
        own["… invoice [P412].pdf"]
    end
    subgraph reader["jamie"]
        shared["… invoice [P412].pdf<br/>shared read-only"]
    end
    subgraph other["sam"]
        copy["Copy [P412].pdf<br/>a file of sam's own"]
    end
    own -- "share" --> shared
    own --> seen1(["✓ document 412"])
    shared --> seen2(["✓ document 412"])
    copy --> unseen(["✗ no document"])
    classDef yes fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef no fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    class seen1,seen2 yes
    class unseen no

This app does not synchronize documents itself. For a native, configurable synchronization solution, use the companion Paperless Sync app. Both apps use the same stable [P<ID>] marker and are designed to work together without coupling their release cycles.

Requirements¶

Nextcloud 33 through 35
PHP 8.2 or newer as supported by the corresponding Nextcloud release
A reachable Paperless-ngx instance with API access
Synchronized files whose names contain [P<ID>], owned by one Nextcloud account, for example those of Paperless Sync

Configuration¶

Create a dedicated Paperless account with the minimum read permissions required for document search.
Create an API token for that account.
In Nextcloud, open Administration settings → Paperless Unified Search.
Enter the Paperless base URL and API token.
Under Archive account, enter the Nextcloud account that owns the synchronized files, or leave it blank to use the account that Paperless Sync writes the archive with.
Optionally enable Always include Paperless in global search to treat the configured Paperless server as trusted.
Select Test connection and save.

The configuration is global. Access control remains user-specific because the app discards every Paperless hit for which the searching Nextcloud user can't open a matching file of the archive account. Share the archive read-only with the users who may see its documents. Without an archive account, the search shows no Paperless documents.

When Paperless documents are missing from the search, look at Search problems at the end of the settings. A failed search shows the users no Paperless documents and no error, and a request to Paperless that gets no answer at all, as when the connection fails, is sent a second time before the search gives up. The settings count both, the failed searches and the requests that only their second try answered, and list the latest 20 with the time, the step, asking Paperless or looking for the files in Nextcloud, the kind and the message of the error and how long it took, along with since when searches work again after the last failure. This helps where the hoster keeps the log of Nextcloud from administrators. Clear history and Disconnect forget the history; saving the settings keeps it.

By default, Nextcloud searches Paperless only after the user enables Search connected services. When the trusted-service option is enabled, every global search term from every Nextcloud user is sent to Paperless automatically and the connected-services switch no longer controls this provider. Reload Nextcloud after changing this option.

Usage¶

Open Nextcloud's global search, enable Search connected services, and select Paperless documents. Nextcloud 32 and later disable external providers after a page reload, so this switch must be enabled again unless an administrator has enabled trusted-service mode.

Documents without a synchronized [P<ID>] file of the archive account are intentionally omitted. This also keeps Inbox-only documents out of Nextcloud search when the synchronization process does not export them.

Security and privacy¶

The Paperless API token is stored only in Nextcloud's server-side credentials manager.
The token is never returned to browser JavaScript or rendered into HTML.
Search results are filtered through the current user's Nextcloud filesystem view.
The settings show administrators the history of the problems of the search without the API token, the search term or the query of any URL.
Search terms are sent server-to-server only when connected-services search or trusted-service mode is enabled.
Administrators can explicitly trust the configured Paperless server to include it automatically in every user's global searches.
No deployment credentials, private hostnames, internal addresses, or instance configuration belong in this repository.
Gitleaks scans every push and pull request.
Dependency Review blocks newly introduced vulnerable or unapproved dependencies.
Psalm analyzes the PHP code and CodeQL scans the JavaScript on every pull request.
Every release includes an SPDX SBOM, a detached signature, and public Sigstore build provenance.
OpenSSF Scorecard audits the repository's supply-chain security every week.

See SECURITY.md for reporting security issues.