Backstage search engine: Elasticsearch, OpenSearch or PostgreSQL

Backstage search with Elasticsearch, OpenSearch or PostgreSQL: when your portal needs more than the default

Your portal's catalog and documentation are growing, and developers now expect search to find a service owner, a runbook or an API definition in seconds. For a small portal, the built-in search engine is usually enough. For a larger one, the choice is between PostgreSQL, Elasticsearch or OpenSearch, and the search plugin in Backstage is configured the same way in each case: through collators, which gather documents from sources such as the Software Catalog and TechDocs, and through indexing schedules that decide how often those documents are refreshed. The architecture overview lists search as a plugin alongside the Software Catalog, Software Templates and TechDocs, so the engine choice is a deployment decision layered on top of plugin configuration that already has to exist.

The search plugin is the component that accepts queries from the portal, reads from the search index and returns results across every registered collator. Two questions decide when a team needs to move off the simplest setup: how many documents the index must hold across catalog entities and documentation pages, and how much query load and indexing churn the portal produces during working hours. Confirm both numbers with your own catalog and TechDocs inventory before choosing an engine, and check the current engine support in the Backstage architecture overview. A portal that already runs PostgreSQL for other Backstage plugins has a lower operational cost to start with, while a separate search cluster adds a system to patch, back up and monitor.

Plan the indexing schedule before you choose the engine. Each collator runs on its own schedule, so a catalog collator that refreshes every few minutes and a documentation collator that refreshes after each TechDocs build place different loads on the engine. Ask your platform team who will own the search cluster, how it will be upgraded, and what happens to search results when an index is rebuilt. Those answers will shape the engine decision more than the first query benchmark.

Which search engine fits your portal

Lunr is the built-in search option and suits a small portal with a limited catalog and few TechDocs sites. It runs inside the Backstage backend, so there is no separate service to provision, back up, patch or secure. The trade-off is that the index is built in the same process that serves requests, which keeps operations simple but limits how far the setup can grow.

Who runs it: the team that already operates the Backstage backend, with no separate search administrator.
Infrastructure: no additional stateful service, so no separate storage, replication or upgrade cycle.
Licensing: Backstage itself is Apache 2.0. Confirm the license of Lunr and of any packages you add before you build on them.
Resource use: indexing competes with the backend for memory and CPU as entities and documents grow. Confirm how each backend replica builds and serves its index before you scale out.
Feature depth: relevance tuning, filtering and faceting are narrower than in a dedicated engine. Confirm that your users need only what Lunr provides.

Before you choose Lunr for production, check your current entity and document counts, and confirm with the current Backstage documentation how the search index behaves across replicas.

Search engine options and when each one fits

This table compares Lunr, the PostgreSQL engine, OpenSearch and Elasticsearch for Backstage search across index size, added infrastructure, security features, upgrade effort and team skills. Read each row against your catalog and TechDocs volume, your existing operations skills and the access rules your search results must follow. The main takeaway is that the engine choice is a platform decision as much as a search decision, and the Backstage side still needs its own engine configuration in every case.

Decision factor	Lunr and PostgreSQL engine	OpenSearch	Elasticsearch
Index size expectations	Lunr suits small catalogs and documentation sets held in memory; the PostgreSQL engine suits moderate indexes that a team already sizes with its database	Suited to larger catalogs, many collators and heavier query load, with capacity planned as a separate cluster	Suited to the same larger workloads as OpenSearch; confirm sizing guidance with the current vendor documentation
Added infrastructure	None for Lunr; the PostgreSQL engine reuses the Backstage database, which needs PostgreSQL 12 or later	A separate search cluster with nodes, storage, TLS and backups to operate	A separate search cluster with nodes, storage, TLS and backups to operate
Security features	Access follows Backstage permissions applied to indexed results; no separate search security layer	OpenSearch Security provides role-based access, document-level and field-level security, field masking and audit logs	Confirm the security feature set and licensing tier with the current vendor terms before relying on them
Licensing	Lunr and the PostgreSQL engine ship with Backstage under Apache-2.0	OpenSearch is released under Apache License 2.0 with no paid edition described in its FAQ	Confirm current licensing terms with the vendor, since these terms are not covered here
Upgrade effort	Tied to Backstage and PostgreSQL upgrade paths, with the database upgrade planned alongside the portal	Plan upgrades on OpenSearch's roughly eight-week minor cadence and its maintenance windows for each version	Plan upgrades against the vendor's release and support schedule, which you should confirm directly
Lineage and compatibility	Not applicable	Forked from Elasticsearch 7.10 and wire-compatible with it, so Backstage configuration should be checked against the engine version you run	Confirm which Elasticsearch versions the Backstage search engine supports before choosing the version
Team skills needed	Backend developers and the team that already runs PostgreSQL	Operators who run search clusters, TLS, index lifecycle and role mapping	Operators who run search clusters; confirm skills needed for current feature tiers
Backstage configuration	Set the search engine in the Backstage search configuration and confirm the PostgreSQL version	Configure the OpenSearch engine in Backstage search settings, separately from OpenSearch's own security configuration	Configure the Elasticsearch engine in Backstage search settings, separately from the cluster's own security configuration

What collators index and how catalog and TechDocs feed search

Backstage search is only as useful as what the collators put into the index. The catalog and TechDocs are the two built-in sources, and each one runs on its own schedule and writes to the same search engine. The cards below cover what each source contributes, what sits outside the defaults, and what to check before you pick an engine.

Catalog collator

The catalog collator reads entities from the Software Catalog and writes them into the search index, so owners, names, descriptions and tags can be found from the search bar. Its output depends on what is registered in the catalog, which makes catalog hygiene a search concern as well as a catalog concern. Check that entity descriptions and ownership are filled in for the services teams expect to find, and confirm which entity kinds your configuration includes.

TechDocs collator

The TechDocs collator indexes the text of generated documentation sites, so readers can search inside docs and not only by entity name. It reads what has already been built and published, which means documentation that is never built or published never reaches the index. Confirm your build and publish pipeline runs before you expect documentation search results to be complete.

Custom plugin sources

Search does not index other plugin data by default. Any source beyond the catalog and TechDocs, such as a plugin's own records, needs a custom collator that you write and schedule. Plan that work separately, and read the sibling page on indexing custom sources before you commit to a source list.

Indexing schedule

Each collator runs on a schedule, so a new catalog entity or published docs page can take until the next run to appear in results. Set the frequency for each source separately, based on how often entities change and how much load the catalog and storage can take during a run. Ask your team to confirm the interval in your own configuration before users rely on it.

Filtering what gets indexed

Collators can be limited so that only selected entities, kinds or documentation are written to the index. Filtering keeps the index smaller and reduces noise in results, but it also hides content from search if the rules are too narrow. Review the filter rules with the catalog owners and document who approves changes to them.

Permission-aware results

Search results must respect what each signed-in user is allowed to see. Whether a result is filtered at query time depends on how the permission framework is wired to search, so confirm that behavior with a test user before rollout. Do not assume that an indexed document is hidden from users who lack catalog or TechDocs access.

How to set up Backstage search step by step

This sequence takes a Backstage instance from an engine choice to verified search results across catalog entities and TechDocs pages, with each step closing on a check you can run. Confirm the current release on the Backstage releases page before you start, since the Backstage line ships monthly and weekly.

Confirm the Backstage release line and Node.js version
The platform team checks which Backstage release line the instance runs and which Node.js versions that release supports. The Backstage versioning policy supports two adjacent even-numbered Node.js releases, and as of Backstage 1.46.0 those are Node.js 22 and 24. Confirm the current release on the Backstage releases page, then record the exact @backstage package versions in your repository. You are done when the instance starts on a supported Node.js version and the package versions match your records.
Choose the search engine for your scale
The platform team and the owners of the catalog and documentation decide between Lunr for small setups, PostgreSQL, or Elasticsearch or OpenSearch for larger indexes. Ask how many catalog entities and TechDocs pages you expect, how many people search daily, and whether you already run a managed search service or a PostgreSQL cluster you operate. Note that the PostgreSQL engine requires PostgreSQL 12 or later, so confirm that version with your database owners before you commit. You are done when the choice and its reasons are written in your architecture record.
Deploy the engine with security settings enabled
The infrastructure team deploys the chosen engine in the infrastructure you control, using the installation method your platform standards allow. For OpenSearch, enable TLS for node and client traffic and set up the Security plugin with roles that limit the Backstage service account to the search indexes it writes and reads. For PostgreSQL, use a dedicated database and role for search, with a password or certificate method rather than trust authentication. You are done when the engine answers an authenticated health request from the Backstage backend host and rejects an unauthenticated one.
Add the search backend module and engine configuration
The Backstage developers install the search backend module for the chosen engine and add its settings to the app configuration, including the endpoint, credentials read from your secret store, and the index prefix. Keep credentials out of the committed configuration files and load them through environment variables or your secret manager. Start the backend locally against a test engine instance. You are done when the backend starts without configuration errors and logs that the search engine is initialized.
Register the catalog and TechDocs collators
The developers register the catalog collator and the TechDocs collator in the search backend, so entity metadata and documentation pages are sent to the index. Confirm that the TechDocs collator matches how your docs are built and stored, since its settings depend on your TechDocs setup. Add any further collators only after the first two work. You are done when a search for a known service name returns its catalog entity and a search for a phrase from a TechDocs page returns that page.
Set the indexing schedule
The platform team sets how often each collator refreshes the index, using the schedule settings in the search configuration. Choose intervals that match how often the catalog and documentation change, and check that a run does not overlap with heavy catalog ingestion. Confirm the schedule with the teams that publish docs so they know when their changes appear. You are done when a change to a test entity appears in search after the next scheduled run, and the backend logs show that run completing.
Verify results with test queries
The QA owner and a few pilot users run a fixed set of test queries covering entity names, owners, tags, and TechDocs phrases, and record the expected result for each. Include queries for entities the user should not see if you use catalog permissions, and confirm the results match those rules. Repeat the checks after each engine upgrade or Backstage upgrade. You are done when every test query returns its expected result and the test list is stored with the runbook.

Setting indexing schedules that keep results fresh without overloading the engine

Indexing frequency is a trade-off between how quickly search results reflect the catalog and TechDocs, and how much load the search engine and the source backends absorb. Each collator reads from its own source. The catalog collator reads entities from the catalog backend, and the TechDocs collator reads documentation metadata that the TechDocs backend serves. Every scheduled run adds reads to those backends and writes to the engine, so a schedule that suits a small catalog can stress a larger one. Before you choose an interval, measure how long a full index of each collator takes in a staging environment that mirrors production volume, and record how much the backends slow down while it runs.

Full reindexing rebuilds the whole index and costs the most at every run. Incremental updates touch only documents that changed, which is cheaper but depends on the collator and the engine handling deletions and partial updates correctly. Confirm in the Backstage search documentation which of these modes each collator you plan to use supports, and how the scheduler handles a run that overlaps the next one. Set schedules per collator rather than one global interval, because catalog changes usually arrive in bursts from pipelines while documentation changes less often. A full rebuild of a large set of documentation sites can be far heavier than a catalog refresh, so it may deserve a slower, off-peak schedule.

Plan for failures as part of the schedule. A failed run leaves the index stale, so alert on indexing errors and on the age of the last successful run per collator, and confirm how the search engine's own operators, such as OpenSearch index snapshots or PostgreSQL maintenance windows, interact with scheduled writes. Ask the team that runs the engine what write load it can absorb during business hours, and test a worst-case catalog import while the schedule is active. Revisit the intervals after each catalog growth milestone, since the measurements you took at the start will drift as the portal grows.

Security and access controls for the search index

A search index mirrors catalog and TechDocs content, so it can expose more than the portal shows if it is left open. The cards below cover network placement, transport and sign-in to the engine, field and role controls, audit trails and permission alignment, which should be designed together before the first index build.

Network exposure of the engine

Keep the search engine on a private network segment reachable only from the Backstage backend, not from developer browsers or the public internet. Backstage queries the engine through its backend, so no user should need direct access to the cluster ports. Confirm how your chosen engine and hosting platform restrict inbound addresses, and test that the port is unreachable from outside the backend's network.

TLS between Backstage and the engine

Encrypt traffic between the Backstage backend and the search engine, including node-to-node traffic in a multi-node cluster. OpenSearch documents TLS for node and client traffic through its Security plugin, and PostgreSQL supports certificate-based connections, but the exact configuration keys and certificate chain depend on your deployment. Confirm certificate rotation and trust store handling with your engine's documentation before go-live.

Authentication to the engine

Decide how the Backstage backend authenticates to the engine, and give it a dedicated service identity rather than an administrator account. OpenSearch Security supports SAML, OpenID Connect, Active Directory, LDAP, Kerberos and JSON Web Token backends. Confirm which of these your organization already runs, and make sure the service credential can be rotated without a portal outage.

Role and field-level controls

Restrict the Backstage index user to read and write only the indices it owns. OpenSearch Security offers role-based access control, document-level security, field-level security and field masking, which can hide sensitive catalog attributes such as internal annotations from users who should not see them. Verify that these controls apply to the search API paths Backstage uses, and that the role cannot reach other application indices.

Audit logs for index access

Enable audit logging on the engine so you can see who queried or changed the index and when. OpenSearch Security provides audit logs, and you should decide where they are shipped, how long they are kept and who reviews them. Confirm with your engine documentation which request categories are logged by default, because verbose logging can add storage cost on a busy portal.

Index content and catalog permissions

Search results can reveal entities that a user could not open in the catalog, so align indexed content with catalog read permissions. Backstage search results are filtered at query time when permissions are enabled, but the index still holds the full data, so anyone with direct engine access can read everything. Test with a restricted user that search results match what the catalog shows, and plan a re-index when permission rules change.

Questions teams ask before they choose a search engine

How much effort and cost should we expect for Backstage search?

Effort and cost depend mainly on the search engine you choose, how many sources you index, how often the indexes refresh, where the engine runs, and what skills your team already has. Lunr needs little beyond the Backstage backend, while Elasticsearch, OpenSearch or PostgreSQL add a service you must size, secure, patch and back up. Cost has two parts: the engagement fee, which is one-time for design and build, and the recurring cost of hosting, storage and upgrades. The supplied facts do not give fees or hours, so ask for a fixed-scope quote based on your written scope. That quote should list each engine option, each collator, the indexing schedule, and what you will operate after handover.

How long does Backstage search setup take?

Duration depends on the engine, the number of catalog and TechDocs sources, any custom collators, the hosting platform, and how quickly your identity and network teams can grant access. A Lunr setup inside an existing Backstage instance is the shortest path. A managed search service in your own cloud account takes longer because provisioning, TLS, access control and load testing must be agreed first. DeployOpen does not publish timelines, so the timeline should come from the written scope and be confirmed in the fixed-scope quote.

What does our team need to provide for a search engine build?

Most of the work depends on access and decisions from your side. You need to confirm where the search engine will run, whether it can be reached from the Backstage backend, and which network paths and certificates are allowed. Identity matters because the engine's access controls and Backstage sign-in must agree on who can search what. Your team should also give access to the software catalog and TechDocs sources, the list of sources to index, and a named owner for the engine after handover. Confirm each of these before work starts so the scope is not reopened.

Can our internal team set up Backstage search without a partner?

Yes, an experienced team can do it alone, especially with Lunr or a single engine in an environment it already runs. The harder parts are indexing custom collators, operating a search cluster, handling upgrades, and keeping access controls aligned with Backstage permissions. Before deciding, check whether your team has someone who can run a search service, has time for upgrades, and can test the index after each change. If those gaps exist, a partner can design the build and hand over runbooks, or your team can own the work with a retainer for ongoing support.

When should we move from Lunr to a larger search engine?

Move when the default in-process search stops meeting your needs for index size, query speed, or the number of sources you want to search. Other signs include indexing that takes too long for your schedule, a need for shared search across several Backstage instances, or a requirement to run search as an audited service. Backstage's PostgreSQL search engine is a middle option for teams that already operate PostgreSQL, but it requires PostgreSQL 12 or later. Check the Backstage search documentation and your own index size before you choose, because the switch changes operations and backups.

Which engine should we choose between Elasticsearch, OpenSearch and PostgreSQL?

The choice depends on your licensing position, your existing operations skills, and how much search volume you expect. OpenSearch is released under the Apache License, Version 2.0, and the OpenSearch FAQ does not describe a paid edition. OpenSearch is a fork of Elasticsearch 7.10, so compatibility with Elasticsearch-based clients should be tested before you commit. PostgreSQL is released under the PostgreSQL License, and teams that already run PostgreSQL can reuse that operating model. Confirm your Elasticsearch license terms with your legal team, because this page does not cover them.

What should we confirm before asking for a search engine quote?

Prepare a short written scope that names the engine options you are considering, the catalog and TechDocs sources and any custom sources, the indexing schedule you need, and where the engine will run. Add your Backstage version and the Node.js version you plan to use, since the Backstage versioning policy supports two adjacent even-numbered Node.js releases. Also confirm your sign-in provider, your secrets and backup standards, and who will own upgrades. A fixed-scope quote is based on this written scope, so the more specific it is, the more accurate the quote.

What operational risks should we plan for after search goes live?

The main risks are stale indexes, failed scheduled indexing, search results that show content users should not see, and an engine that falls behind the supported version range. Plan a monitored indexing schedule, a test that checks index contents after each change, and a review of access rules whenever a permission or identity source changes. Upgrades to the engine and Backstage must be scheduled, because OpenSearch and PostgreSQL each publish their own maintenance and end-of-life windows. Ask for runbooks and an upgrade plan as part of any quote.

Limits to confirm in your environment

Search for Backstage depends on versions, licensing and hosting choices that change over time. The cards below are checks to complete against your own Backstage release, your hosting provider and your sources before you commit to an engine.

Engine version supported by your release

Confirm which search engine versions your Backstage release and its search plugin support before you choose a version. Backstage moves its main release line monthly and its next line weekly, so a version that worked at install time may need a change at upgrade. Check the version your chosen engine uses against the Backstage versioning policy and the release notes for the Backstage version you plan to run, and record the pair in your design document.

PostgreSQL 12 requirement for the Postgres engine

The PostgreSQL search engine has its own database version requirement, which is separate from the PostgreSQL version you run for the Backstage catalog. Confirm the minimum PostgreSQL version stated in the search plugin documentation for your release, then check that your managed or self-hosted database is on a version still in support. Because PostgreSQL 12 is no longer among the supported major versions, plan a database upgrade if your current instance runs it.

Elasticsearch licensing fit

Confirm that the Elasticsearch license terms and features you need fit your use before you select it. Elasticsearch and OpenSearch have different licensing histories, so do not assume the open source terms of one apply to the other. Ask your legal or procurement team to review the license for your deployment model, and confirm which features Backstage needs, such as the engine's security features, are available under the terms you accept.

Engine versions offered by your host

If you use a managed search service, confirm which OpenSearch or Elasticsearch versions the provider offers and how long each version receives maintenance. Check whether the provider supports the engine version your Backstage release requires, how it applies patches, and what upgrade windows apply. A managed version that lags behind the version you chose can block the search upgrade you planned.

Custom collator effort for non-core sources

Estimate the work for each source beyond the catalog and TechDocs before you promise indexing for it. Each custom collator needs a data source, a mapping to searchable fields, access rules that match the source's permissions, and a schedule. Ask your engineers to list every non-core source and the owner of its data, then confirm the effort with a written scope, since a collator that exposes restricted content creates a permission problem as well as a build task.

How DeployOpen scopes a search engine decision

DeployOpen engagements are fixed-scope, so the scope, deliverables and timeline for a search engine decision are agreed in writing before any work starts. The engine choice itself is sized from three inputs: the size and churn of the Software Catalog and TechDocs content, the list of sources that will be indexed beyond those two (collators for other plugins), and the operating model your team can sustain. Those inputs decide whether Lunr is enough, PostgreSQL is the simpler production path, or Elasticsearch or OpenSearch is justified by index size, query load or operational skills already in house.

The scoping conversation also covers the items that often get missed. Ask who will own the search cluster after go-live, how sign-in and network access to the engine will be controlled, where backups and index rebuilds fit, and how the indexing schedule will be monitored. For an OpenSearch choice, confirm the version line you plan to run against the OpenSearch releases page and your own support window before the build is locked. Each of these answers changes effort, so they belong in the written scope rather than in a later change request.

Ongoing work is available as a retainer after the initial build. That can cover search engine upgrades, reviewing collator output as new sources are added, and periodic checks on index health and indexing jobs. Retainer terms, response expectations and what is included are set out in the agreement, not promised in advance. Results depend on your catalog quality, data volumes and environment, so DeployOpen will not promise search performance or relevance outcomes before the scope has been validated in your setting.

How DeployOpen delivers Backstage search

DeployOpen scopes, builds and hands over Backstage search in the search engine your organization chooses, whether that is Lunr, PostgreSQL, Elasticsearch or OpenSearch. Each engagement starts with the size of your catalog, TechDocs and custom sources, then sets the indexing schedule, access model and operating runbook in writing.

How we scope

Inventory the entities, TechDocs sites and custom sources that search must cover
Decide the engine by index size, hosting constraints and the team that will operate it
Write the scope, deliverables and timeline in writing before any build work starts
Confirm which search engine versions and support dates your platform team will accept

How we build

Configure the Backstage search plugin with catalog and TechDocs collators for your sources
Set indexing schedules and test that new catalog entities appear in results as expected
Connect the chosen engine with TLS, access controls and separate credentials for the backend
Test queries, permissions and index rebuilds in a non-production environment before cutover

How we hand over

Document the collator configuration, index names, schedules and engine settings for your team
Provide a runbook covering index rebuilds, failed indexing jobs and engine upgrades
Walk your platform and engineering staff through the setup and the recovery steps
Record the search engine version and the upgrade path your team needs to follow

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after handover
Review search engine version changes and Backstage upgrades that affect indexing
Adjust collators and schedules as new custom sources are added to the portal
Confirm support terms for your engine and Backstage versions before the retainer starts