Search Basics

In this lesson we explore Backstage’s search capabilities: how it indexes content, the components that power search, and how to extend it to include external sources like Confluence or Stack Exchange. Backstage centralizes developer tools and documentation, and its search is designed to surface everything relevant — from catalog entities to TechDocs and external knowledge bases. Out of the box, Backstage lets you query your software catalog and the documentation linked to those entries, helping you find features or identify responsible services even when you don’t know exact names. Backstage search is also extensible: you can add collators to index external resources such as Confluence, Stack Exchange, or any other data source with an available collator.

Backstage gives you control over what gets indexed and how results are presented. You can aggregate content from multiple sources and present unified search results to users, improving discoverability across your organization. Search engine backends Backstage supports multiple search engine backends. The default is Lunr (an in-memory index suitable for small to medium installations), but for larger or persistent indexes you can use Postgres or Elasticsearch/OpenSearch.

Use the table below to quickly compare common backend choices and when to pick each:

Backend	Best for	Notes
Lunr	Small deployments, low operational overhead	In-memory index; simple to run with Backstage defaults.
Postgres	Moderate scale, use existing DB infrastructure	Persists index in your Postgres database.
Elasticsearch / OpenSearch	Large scale, advanced search features, distributed index	Use when you need scalability, analytics, or cross-cluster setups. Configure provider as `elasticsearch` or `opensearch` in Backstage.

Collators — what they do Collators determine which data is discovered and indexed. A collator:

Discovers content in a specified location (catalog entities, TechDocs, Confluence spaces, Stack Exchange data, etc.).
Converts that content into canonical “documents” for the search indexer to consume.

Backstage ships with collators for catalog entities and built-in TechDocs. To index additional sources (for example Confluence or Stack Exchange), add and configure a collator for each source. Index scheduling Backstage maintains an index for all configured sources and lets you control how frequently each collator runs. Scheduling collators independently helps balance freshness and system load: frequently changing content can be indexed more often than stable sources.

A schematic titled "Scheduler" showing a "Collators" search function feeding a "Collecting index" that polls multiple sources. It lists targets like Catalog, Docs, Confluence and Stack Exchange with polling intervals (30 mins, 1 hr, 6 hrs, 2 days).

Example scheduling strategy:

Source	Example poll interval
Catalog (service listing)	30 minutes
Internal TechDocs	1 hour
Confluence spaces	6 hours
External knowledge base (e.g., Stack Exchange dataset)	2 days

Adjust polling intervals to match the change frequency and operational cost for each source in your environment. Switching to Elasticsearch / OpenSearch If your installation needs a persistent, scalable index, switch from the default Lunr to Elasticsearch or OpenSearch. Steps:

Add the Elasticsearch/OpenSearch backend collator module to your backend packages.
Register the module with your backend at startup.
Configure the connection details in app-config.yaml.

Install the backend module (run from your repository root or the workspace that contains packages/backend):

yarn --cwd packages/backend add @backstage/plugin-search-backend-module-elasticsearch

Register the search backend and Elasticsearch/OpenSearch module with your backend. Many Backstage backends perform dynamic imports, so you may need to await these imports. A typical pattern:

// backend/start.js (or index.ts)
const backend = createBackend();

await backend.add(await import('@backstage/plugin-search-backend'));
await backend.add(await import('@backstage/plugin-search-backend-module-elasticsearch'));

await backend.start();

When using dynamic imports, ensure the surrounding context supports await (for example, by using top-level await in an ES module) or wrap this logic inside an async function. Restart the backend after adding new modules.

Configure the Elasticsearch/OpenSearch connection in app-config.yaml. Example:

search:
  elasticsearch:
    provider: opensearch
    node: http://0.0.0.0:9200
    auth:
      username: opensearch
      password: changeme

Set provider to elasticsearch or opensearch depending on your server, and update node and credentials to match your deployment. Best practices

Start with Lunr for small teams or evaluations; move to Postgres or Elasticsearch/OpenSearch as scale demands.
Use per-source scheduling to reduce unnecessary indexing load.
Add collators only for data sources you need in search to keep the index relevant and performant.
Secure your Elasticsearch/OpenSearch endpoints and credentials (use secrets management where possible).

Summary

Backstage search indexes catalog entities, TechDocs, and any additional sources you enable via collators.
Choose Lunr for simplicity, Postgres for DB-backed indices, or Elasticsearch/OpenSearch for large-scale, feature-rich search.
Collators define what gets indexed and can be scheduled independently to balance freshness and cost.
To add Elasticsearch/OpenSearch: install the backend module, register it during backend startup, and configure connection settings in app-config.yaml.

Links and References

Backstage Search docs: https://backstage.io/docs/search/
Lunr: https://lunrjs.com
PostgreSQL: https://www.postgresql.org
Elasticsearch: https://www.elastic.co
OpenSearch: https://opensearch.org
Confluence: https://www.atlassian.com/software/confluence
Stack Exchange: https://stackexchange.com

Introduction

Backstage Basics

Catalog

Templates

TechDocs & Search

Customization & Plugins

Production Backstage

Watch Video