From 01ae205352e1890bb32dd32bfc67d3e84024fde2 Mon Sep 17 00:00:00 2001 From: Camila Belo Date: Tue, 7 Mar 2023 15:23:28 +0100 Subject: [PATCH] feat(search): update docs Co-authored-by: Emma Indal Signed-off-by: Camila Belo --- .changeset/nine-clouds-flow.md | 5 -- .changeset/tall-chairs-explain.md | 7 ++ .changeset/wet-lamps-happen.md | 7 ++ docs/features/search/how-to-guides.md | 86 ++++--------------- .../integrating-search-into-plugins.md | 2 +- .../CHANGELOG.md | 1 - .../search-backend-module-catalog/README.md | 24 +++++- .../CHANGELOG.md | 1 - .../search-backend-module-explore/README.md | 24 +++++- .../package.json | 1 - .../CHANGELOG.md | 1 - .../search-backend-module-techdocs/README.md | 24 +++++- .../package.json | 1 - yarn.lock | 3 +- 14 files changed, 101 insertions(+), 86 deletions(-) delete mode 100644 .changeset/nine-clouds-flow.md create mode 100644 .changeset/tall-chairs-explain.md create mode 100644 .changeset/wet-lamps-happen.md delete mode 100644 plugins/search-backend-module-catalog/CHANGELOG.md delete mode 100644 plugins/search-backend-module-explore/CHANGELOG.md delete mode 100644 plugins/search-backend-module-techdocs/CHANGELOG.md diff --git a/.changeset/nine-clouds-flow.md b/.changeset/nine-clouds-flow.md deleted file mode 100644 index fca6bbbf1c..0000000000 --- a/.changeset/nine-clouds-flow.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'example-backend-next': patch ---- - -Adds search plugin and search index registry to backend. diff --git a/.changeset/tall-chairs-explain.md b/.changeset/tall-chairs-explain.md new file mode 100644 index 0000000000..e7367d2d4a --- /dev/null +++ b/.changeset/tall-chairs-explain.md @@ -0,0 +1,7 @@ +--- +'@backstage/plugin-techdocs-backend': patch +'@backstage/plugin-catalog-backend': patch +'@backstage/plugin-explore-backend': patch +--- + +Deprecate the collator files in the backend package by extracting them into a separate module. diff --git a/.changeset/wet-lamps-happen.md b/.changeset/wet-lamps-happen.md new file mode 100644 index 0000000000..76e36d219d --- /dev/null +++ b/.changeset/wet-lamps-happen.md @@ -0,0 +1,7 @@ +--- +'@backstage/plugin-search-backend-module-techdocs': minor +'@backstage/plugin-search-backend-module-catalog': minor +'@backstage/plugin-search-backend-module-explore': minor +--- + +Extend the index with custom collators by creating search plugin modules. diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md index e8f58e9f26..da94bd4ca4 100644 --- a/docs/features/search/how-to-guides.md +++ b/docs/features/search/how-to-guides.md @@ -51,7 +51,7 @@ The TechDocs plugin has supported integrations to Search, meaning that it provides a default collator factory ready to be used. The purpose of this guide is to walk you through how to register the -[DefaultTechDocsCollatorFactory](https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/src/search/DefaultTechDocsCollatorFactory.ts) +[DefaultTechDocsCollatorFactory](https://github.com/backstage/backstage/blob/de294ce5c410c9eb56da6870a1fab795268f60e3/plugins/techdocs-backend/src/search/DefaultTechDocsCollatorFactory.ts) in your App, so that you can get TechDocs documents indexed. If you have been through the @@ -376,78 +376,30 @@ There are other more specific search results layout components that also accept 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 +In packages/backend-next/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'; +import { searchModuleElasticsearchEngine } from '@backstage/plugin-search-backend-module-elasticsearch/alpha'; +import { searchModuleCatalogCollator } from '@backstage/plugin-search-backend-module-catalog/alpha'; +import { searchModuleTechDocsCollator } from '@backstage/plugin-search-backend-module-techdocs/alpha'; +import { searchModuleExploreCollator } from '@backstage/plugin-search-backend-module-explore/alpha'; + +const schedule = { + frequency: { minutes: 10 }, + timeout: { minutes: 15 }, + initialDelay: { seconds: 3 }, +}; const backend = createBackend(); -// ...other modules +// adding the search plugin to the backend 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()); +// (optional) the default search engine is Lunr, if you want to extend the search backend with another search engine. +backend.add(searchModuleElasticsearchEngine()); +// extending search with collator modules to start index documents +backend.add(searchModuleCatalogCollator({ schedule })); +backend.add(searchModuleTechDocsCollator({ schedule })); +backend.add(searchModuleExploreCollator({ schedule })); backend.start(); ``` diff --git a/docs/plugins/integrating-search-into-plugins.md b/docs/plugins/integrating-search-into-plugins.md index 4e829b6ae9..7fb8e40b20 100644 --- a/docs/plugins/integrating-search-into-plugins.md +++ b/docs/plugins/integrating-search-into-plugins.md @@ -142,7 +142,7 @@ export class FaqCollatorFactory implements DocumentCollatorFactory { To verify your implementation works as expected make sure to add tests for it. For your convenience, there is the [`TestPipeline`](https://backstage.io/docs/reference/plugin-search-backend-node.testpipeline) utility that emulates a pipeline into which you can integrate your custom collator. -Look at [DefaultTechDocsCollatorFactory test](https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/src/search/DefaultTechDocsCollatorFactory.test.ts), for an example. +Look at [DefaultTechDocsCollatorFactory test](https://github.com/backstage/backstage/blob/de294ce5c410c9eb56da6870a1fab795268f60e3/plugins/techdocs-backend/src/search/DefaultTechDocsCollatorFactory.test.ts), for an example. #### 6. Make your plugins collator discoverable for others diff --git a/plugins/search-backend-module-catalog/CHANGELOG.md b/plugins/search-backend-module-catalog/CHANGELOG.md deleted file mode 100644 index c870819424..0000000000 --- a/plugins/search-backend-module-catalog/CHANGELOG.md +++ /dev/null @@ -1 +0,0 @@ -# @backstage/plugin-search-backend-module-catalog diff --git a/plugins/search-backend-module-catalog/README.md b/plugins/search-backend-module-catalog/README.md index 9860f86b1d..b6c734d893 100644 --- a/plugins/search-backend-module-catalog/README.md +++ b/plugins/search-backend-module-catalog/README.md @@ -1,7 +1,27 @@ # search-backend-module-catalog -... +> DISCLAIMER: The new backend system is in alpha, and so are the search backend module 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, you can find getting started guides below. -## Getting started +This package exports catalog backend modules responsible for extending search. + +## Example + +```tsx +// packages/backend-next/src/index.ts +import { createBackend } from '@backstage/backend-defaults'; +import { searchPlugin } from '@backstage/plugin-search-backend/alpha'; +import { searchModuleCatalogCollator } from '@backstage/plugin-search-backend-module-catalog/alpha'; + +const schedule = { + frequency: { minutes: 10 }, + timeout: { minutes: 15 }, + initialDelay: { seconds: 3 }, +}; + +const backend = createBackend(); +backend.add(searchPlugin()); +backend.add(searchModuleCatalogCollator({ schedule })); +backend.start(); +``` ... diff --git a/plugins/search-backend-module-explore/CHANGELOG.md b/plugins/search-backend-module-explore/CHANGELOG.md deleted file mode 100644 index 8640d14b73..0000000000 --- a/plugins/search-backend-module-explore/CHANGELOG.md +++ /dev/null @@ -1 +0,0 @@ -# @backstage/plugin-search-backend-module-explore diff --git a/plugins/search-backend-module-explore/README.md b/plugins/search-backend-module-explore/README.md index bbc8392f14..d2b00767e2 100644 --- a/plugins/search-backend-module-explore/README.md +++ b/plugins/search-backend-module-explore/README.md @@ -1,7 +1,27 @@ # search-backend-module-explore -... +> DISCLAIMER: The new backend system is in alpha, and so are the search backend module 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, you can find getting started guides below. -## Getting started +This package exports explore backend modules responsible for extending search. + +## Example + +```tsx +// packages/backend-next/src/index.ts +import { createBackend } from '@backstage/backend-defaults'; +import { searchPlugin } from '@backstage/plugin-search-backend/alpha'; +import { searchModuleExploreCollator } from '@backstage/plugin-search-backend-module-explore/alpha'; + +const schedule = { + frequency: { minutes: 10 }, + timeout: { minutes: 15 }, + initialDelay: { seconds: 3 }, +}; + +const backend = createBackend(); +backend.add(searchPlugin()); +backend.add(searchModuleExploreCollator({ schedule })); +backend.start(); +``` ... diff --git a/plugins/search-backend-module-explore/package.json b/plugins/search-backend-module-explore/package.json index 356059f845..c943f4480d 100644 --- a/plugins/search-backend-module-explore/package.json +++ b/plugins/search-backend-module-explore/package.json @@ -49,7 +49,6 @@ "@backstage/plugin-permission-common": "workspace:^", "@backstage/plugin-search-backend-node": "workspace:^", "@backstage/plugin-search-common": "workspace:^", - "@types/express": "^4.17.6", "dockerode": "^3.3.1", "express": "^4.17.1", "express-promise-router": "^4.1.0", diff --git a/plugins/search-backend-module-techdocs/CHANGELOG.md b/plugins/search-backend-module-techdocs/CHANGELOG.md deleted file mode 100644 index 85d533ae87..0000000000 --- a/plugins/search-backend-module-techdocs/CHANGELOG.md +++ /dev/null @@ -1 +0,0 @@ -# @backstage/plugin-search-backend-module-techdocs diff --git a/plugins/search-backend-module-techdocs/README.md b/plugins/search-backend-module-techdocs/README.md index 2711150d56..817bb40998 100644 --- a/plugins/search-backend-module-techdocs/README.md +++ b/plugins/search-backend-module-techdocs/README.md @@ -1,7 +1,27 @@ # search-backend-module-techdocs -... +> DISCLAIMER: The new backend system is in alpha, and so are the search backend module 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, you can find getting started guides below. -## Getting started +This package exports techdocs backend modules responsible for extending search. + +## Example + +```tsx +// packages/backend-next/src/index.ts +import { createBackend } from '@backstage/backend-defaults'; +import { searchPlugin } from '@backstage/plugin-search-backend/alpha'; +import { searchModuleTechDocsCollator } from '@backstage/plugin-search-backend-module-techdocs/alpha'; + +const schedule = { + frequency: { minutes: 10 }, + timeout: { minutes: 15 }, + initialDelay: { seconds: 3 }, +}; + +const backend = createBackend(); +backend.add(searchPlugin()); +backend.add(searchModuleTechDocsCollator({ schedule })); +backend.start(); +``` ... diff --git a/plugins/search-backend-module-techdocs/package.json b/plugins/search-backend-module-techdocs/package.json index 555e34ebdf..0e7a350938 100644 --- a/plugins/search-backend-module-techdocs/package.json +++ b/plugins/search-backend-module-techdocs/package.json @@ -49,7 +49,6 @@ "@backstage/plugin-search-backend-node": "workspace:^", "@backstage/plugin-search-common": "workspace:^", "@backstage/plugin-techdocs-node": "workspace:^", - "@types/express": "^4.17.6", "dockerode": "^3.3.1", "express": "^4.17.1", "express-promise-router": "^4.1.0", diff --git a/yarn.lock b/yarn.lock index 2046cd9ece..c4d07145e8 100644 --- a/yarn.lock +++ b/yarn.lock @@ -7843,7 +7843,6 @@ __metadata: "@backstage/plugin-permission-common": "workspace:^" "@backstage/plugin-search-backend-node": "workspace:^" "@backstage/plugin-search-common": "workspace:^" - "@types/express": ^4.17.6 dockerode: ^3.3.1 express: ^4.17.1 express-promise-router: ^4.1.0 @@ -7894,7 +7893,6 @@ __metadata: "@backstage/plugin-search-backend-node": "workspace:^" "@backstage/plugin-search-common": "workspace:^" "@backstage/plugin-techdocs-node": "workspace:^" - "@types/express": ^4.17.6 dockerode: ^3.3.1 express: ^4.17.1 express-promise-router: ^4.1.0 @@ -22596,6 +22594,7 @@ __metadata: "@backstage/plugin-search-backend-module-explore": "workspace:^" "@backstage/plugin-search-backend-module-techdocs": "workspace:^" "@backstage/plugin-search-backend-node": "workspace:^" + "@backstage/plugin-techdocs-backend": "workspace:^" "@backstage/plugin-todo-backend": "workspace:^" languageName: unknown linkType: soft