> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Basics
> Overview of Backstage search features, covering indexing, collators, backend choices (Lunr, Postgres, Elasticsearch/OpenSearch), scheduling, external source integration and deployment best practices.
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.
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:
1. Add the Elasticsearch/OpenSearch backend collator module to your backend packages.
2. Register the module with your backend at startup.
3. Configure the connection details in `app-config.yaml`.
Install the backend module (run from your repository root or the workspace that contains `packages/backend`):
```bash theme={null}
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:
```javascript theme={null}
// 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:
```yaml theme={null}
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/](https://backstage.io/docs/search/)
* Lunr: [https://lunrjs.com](https://lunrjs.com)
* PostgreSQL: [https://www.postgresql.org](https://www.postgresql.org)
* Elasticsearch: [https://www.elastic.co](https://www.elastic.co)
* OpenSearch: [https://opensearch.org](https://opensearch.org)
* Confluence: [https://www.atlassian.com/software/confluence](https://www.atlassian.com/software/confluence)
* Stack Exchange: [https://stackexchange.com](https://stackexchange.com)