Nextcloud full text search with Elasticsearch

Administrators should understand one point before any rollout: the search index holds a copy of document text, and access is decided each time someone searches. When a user uploads or edits a file, the Nextcloud full text search framework and its files provider app queue that file for indexing. A background job also works through files that existed before the search apps were enabled. The Elasticsearch backend receives the extracted text along with metadata such as file path and owner, and stores it in an index. When a user searches, Nextcloud checks which hits that user may open before showing results. Confirm for your app versions which metadata is written to the index, how the queue is processed, and whether moved or deleted files are removed from the index automatically.

Indexing depends on the indexer being able to read the file. Text extraction works on the content Nextcloud stores, so scanned PDFs without a text layer, images and some binary formats may produce little or nothing searchable unless an OCR or extraction step is configured. Files protected by end-to-end encryption are not readable by the server-side indexer, so they will not appear in results. Server-side encryption modes also differ in whether the indexer can read content, so confirm that against the mode you run. If your chosen app uses an extraction service outside the Nextcloud host, that service receives document content and must sit under the same access, logging and network controls as the index.

Results are filtered so that a user only sees documents they can already access, but the rules come from Nextcloud's sharing model, and each sharing path needs its own check. A file shared directly with one user, a file reached through a group folder whose access follows group membership, a file shared by public link, and a file shared with a guest or a federated user each grant access in a different way. The index does not decide access on its own. A removed share, a changed group membership or a moved file can leave an index entry that looks stale until metadata is refreshed, so the window between an access change and the next index update is a risk to plan for. Confirm how long that window is for your version and configuration, and whether search snippets can show text from a file the user has lost access to.

Test this with accounts that reflect your actual sharing patterns. An administrator account can see far more than an ordinary user, so results from it prove little. Create one account with no shares, one with a restricted share to a single file, one that gets access through a group folder with read-only permissions, one guest limited to a shared folder, and one federated user if you use federation. Place a unique test phrase in files in each location. Search as each account and check the results, snippets, previews and direct links. Then repeat the checks after revoking a share, moving a file and changing group membership. Record every result so the same script can run again after each upgrade.

Treat any hit that a test account should not see as a security defect. Until the cause is confirmed, limit search for the affected users or disable the search app, and agree with your security team who owns that decision. Decide before go-live who runs the test script after each Nextcloud upgrade and after each change to group folders, sharing policy or the Elasticsearch version. Those changes are where permission drift usually appears, and a short scheduled run catches it sooner than a user report would.

Index size follows from what Elasticsearch stores for each document, so the planning starts with a file inventory, not with the total storage Nextcloud already holds. The two largest inputs are document count and average document size. Plain text, Markdown and source files add a small amount of searchable content per file. PDFs, scanned documents and office files add extracted text, and the index also keeps its own structures for every term, field and shard. Content type therefore changes the ratio between source size and index size, sometimes by a wide margin. Ask for counts and sizes broken down by file type, because an average across the whole instance hides the files that drive the result.

Extraction settings and retention rules decide which content reaches the index at all. Check which file types the search app extracts, whether there is a maximum file size for extraction, and whether scanned images go through optical character recognition. Then check whether files in the trash, and older versions kept by the versions feature, are indexed. Users often assume deleted or replaced content is gone, yet it can remain searchable until the index entry is removed. Your retention decisions, including automatic deletion rules, should be settled before sizing, since they change both the document count and the growth rate. Confirm each of these behaviors against the app version you plan to run.

Initial indexing time depends on four things. The first is file volume, which sets the number of documents to read. The second is extraction work, which is usually CPU-bound and varies widely between a plain text file and a large, image-heavy PDF, so per-file cost is uneven. The third is backend capacity, meaning the Elasticsearch node count, CPU, memory, and disk throughput available during the run. The fourth is how many users are active while indexing runs. Active users create new uploads and edits that queue behind the initial job, and they compete with the same servers and network links. Plan a run window with a known load profile, and decide whether indexing should be throttled to protect interactive performance.

Measure a representative sample in a test environment before committing to a production window. Build the sample from your inventory so that it covers the file types, size bands and folder ages you hold, not only the easy cases. Run full extraction and indexing against it on hardware that matches the planned production backend. Record index size relative to source size for each file type, throughput per hour, CPU and disk usage, and error counts from extraction. Repeat the test with the number of concurrent users you expect during the run. Extrapolating from the sample works best within each file type, because large PDFs and office files do not scale in a straight line with file count.

Ask for a sizing estimate built from your own file inventory rather than from a generic ratio. The estimate should state its assumptions: counts and sizes by file type, version and trash retention, extraction scope, expected growth, the planned Elasticsearch topology including replicas, and the user activity assumed during the initial run. Ask for a low and high case so that disk and time planning both have margin. Confirm with the search app documentation and your Elasticsearch version how index storage and replicas are configured. DeployOpen builds these estimates from the written scope of each engagement, and the quote follows from the agreed assumptions, so review each assumption before accepting the figures.

Search breaks in predictable places during a Nextcloud upgrade, so the search apps and the Elasticsearch backend belong in the upgrade plan from the start rather than being checked after the core server is updated. Nextcloud does not allow skipping major releases, so administrators move through each major version in order, back up before every step, and disable third-party apps until each one is confirmed compatible with the new core. For a search deployment, the apps in question are the full text search app, its Elasticsearch connector, and any document extraction component the team has added. Each of these needs an explicit compatibility decision before the core upgrade begins, not after users report missing results.

Compatibility has to be checked in two directions. The Nextcloud version determines which search app versions are supported, and the Elasticsearch version determines which client and connector behavior is valid. Before each Nextcloud step, record the current core, app and backend versions, then confirm in each app's release notes and the vendor's compatibility documentation that the target combination is supported. Do not assume that a backend upgrade is safe on the current core. Treat each combination as a tested pair, and keep the upgrade order documented so that the backend, the apps and the core can be rolled back in a known sequence if a check fails.

Some changes force a reindex, and the plan should treat that as a scheduled event with its own capacity budget. A reindex is needed when the Elasticsearch major version changes in a way the index format does not carry forward, when the index mapping is altered, or when the app changes how it extracts or stores document content. Ask the search app vendor which of these changes require a full reindex and whether the app can rebuild in place or needs a new index. Estimate the time from your own measured initial indexing run on a representative data set, because search users will see incomplete results until the reindex finishes, and that window should be communicated before the upgrade.

Keep a test environment for each upgrade step. It should run the same Nextcloud major version, app versions and Elasticsearch version as production, with a copy of the production data or a representative subset. Run the search test cases there: a query for a known document, a check that a user without access to a folder receives no result from it, and a confirmation that new uploads are indexed. Because Nextcloud releases a new major version every four months and supports each for one year, plan the cadence around the supported release schedule rather than around individual dates. Confirm the current supported versions on the maintenance schedule page before setting the calendar, and review the upgrade notes for every version in the path.