From 1469daa409e313f4ecb966ec773aab10df81ef0a Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Mon, 6 Mar 2023 15:27:33 +0100 Subject: [PATCH] add changesets and how to guide Signed-off-by: Emma Indal Co-authored-by: Camila Loiola --- .changeset/funny-pots-hide.md | 5 ++ .changeset/giant-hairs-serve.md | 6 ++ .changeset/nine-clouds-flow.md | 5 ++ .changeset/warm-buses-switch.md | 5 ++ docs/features/search/how-to-guides.md | 82 +++++++++++++++++++++++++++ 5 files changed, 103 insertions(+) create mode 100644 .changeset/funny-pots-hide.md create mode 100644 .changeset/giant-hairs-serve.md create mode 100644 .changeset/nine-clouds-flow.md create mode 100644 .changeset/warm-buses-switch.md diff --git a/.changeset/funny-pots-hide.md b/.changeset/funny-pots-hide.md new file mode 100644 index 0000000000..32388a93a5 --- /dev/null +++ b/.changeset/funny-pots-hide.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-search-backend': minor +--- + +Exports search plugin that can be used with the new backend system. For documentation on how to migrate, check out the [how to migrate to the new backend system guide](../docs/features/search/how-to-guides.md#how-to-migrate-to-use-search-together-with-the-new-backend-system). diff --git a/.changeset/giant-hairs-serve.md b/.changeset/giant-hairs-serve.md new file mode 100644 index 0000000000..ae450234d1 --- /dev/null +++ b/.changeset/giant-hairs-serve.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-search-backend-module-elasticsearch': minor +'@backstage/plugin-search-backend-module-pg': minor +--- + +Search backend modules migrated to the new backend system. For documentation on how to migrate, check out the [how to migrate to the new backend system guide](../docs/features/search/how-to-guides.md#how-to-migrate-to-use-search-together-with-the-new-backend-system). diff --git a/.changeset/nine-clouds-flow.md b/.changeset/nine-clouds-flow.md new file mode 100644 index 0000000000..fca6bbbf1c --- /dev/null +++ b/.changeset/nine-clouds-flow.md @@ -0,0 +1,5 @@ +--- +'example-backend-next': patch +--- + +Adds search plugin and search index registry to backend. diff --git a/.changeset/warm-buses-switch.md b/.changeset/warm-buses-switch.md new file mode 100644 index 0000000000..5564f33d67 --- /dev/null +++ b/.changeset/warm-buses-switch.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-search-backend-node': minor +--- + +Exports services and extension points that can be used with the new backend system. For documentation on how to migrate, check out the [how to migrate to the new backend system guide](../docs/features/search/how-to-guides.md#how-to-migrate-to-use-search-together-with-the-new-backend-system). diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md index 5b28e259b5..e8f58e9f26 100644 --- a/docs/features/search/how-to-guides.md +++ b/docs/features/search/how-to-guides.md @@ -369,3 +369,85 @@ export const SearchModal = ({ toggleModal }: { toggleModal: () => void }) => ( ``` There are other more specific search results layout components that also accept result item extensions, check their documentation: [SearchResultList](https://backstage.io/storybook/?path=/story/plugins-search-searchresultlist--with-result-item-extensions) and [SearchResultGroup](https://backstage.io/storybook/?path=/story/plugins-search-searchresultgroup--with-result-item-extensions). + +## How to migrate to use Search together with the new backend system + +> DISCLAIMER: The new backend system is in alpha, and so are the search backend support for the new backend system. We don't recommend you to migrate your backend installations to the new system yet. But if you want to experiment, this is the guide for you! + +Recently, the Backstage maintainers [announced the new Backend System](https://backstage.io/blog/2023/02/15/backend-system-alpha). The search plugins are now migrated to support the new backend system. In this guide you will learn how to update your backend set up. + +1. In packages/backend/search.ts + +```ts +import { + coreServices, + createBackendModule, +} from '@backstage/backend-plugin-api'; +import { searchIndexRegistryExtensionPoint } from '@backstage/plugin-search-backend-node/alpha'; +import { DefaultCatalogCollatorFactory } from '@backstage/plugin-catalog-backend'; +import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-techdocs-backend'; +import { ToolDocumentCollatorFactory } from '@backstage/plugin-explore-backend'; +import { loggerToWinstonLogger } from '@backstage/backend-common'; + +export const searchIndexRegistry = createBackendModule({ + moduleId: 'searchIndexRegistry', + pluginId: 'search', + register(env) { + env.registerInit({ + deps: { + indexRegistry: searchIndexRegistryExtensionPoint, + config: coreServices.config, + discovery: coreServices.discovery, + tokenManager: coreServices.tokenManager, + logger: coreServices.logger, + scheduler: coreServices.scheduler, + }, + async init({ + indexRegistry, + config, + logger, + discovery, + tokenManager, + scheduler, + }) { + // define scheule, the same way you did it before + const schedule = scheduler.createScheduledTaskRunner({ + frequency: { minutes: 10 }, + timeout: { minutes: 15 }, + // A 3 second delay gives the backend server a chance to initialize before + // any collators are executed, which may attempt requests against the API. + initialDelay: { seconds: 3 }, + }); + + indexRegistry.addCollator({ + schedule, + factory: DefaultCatalogCollatorFactory.fromConfig(config, { + discovery, + tokenManager, + }), + }); + + // .... other collators and decorators + }, + }); + }, +}); +``` + +2. In packages/backend/index.ts + +```ts +import { searchPlugin } from '@backstage/plugin-search-backend/alpha'; +import { elasticSearchEngineModule } from '@backstage/plugin-search-backend-module-elasticsearch/alpha'; +import { searchIndexRegistry } from './plugins/search'; + +const backend = createBackend(); +// ...other modules +backend.add(searchPlugin()); +backend.add(searchIndexRegistry()); + +// the default search engine is Lunr, if you want to extend the search backend with another search engine. +backend.add(elasticSearchEngineModule()); + +backend.start(); +```