paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

feat(search): update docs

Browse Source 
Co-authored-by: Emma Indal <emma.indahl@gmail.com>
Signed-off-by: Camila Belo <camilaibs@gmail.com>
This commit is contained in:
Camila Belo
2023-03-07 15:23:28 +01:00
parent d4c66877b0
commit 01ae205352
14 changed files with 101 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/nine-clouds-flow.md
-5
View File
@@ -1,5 +0,0 @@
---
'example-backend-next': patch
---
Adds search plugin and search index registry to backend.
.changeset/tall-chairs-explain.md
+7
View File
@@ -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.
.changeset/wet-lamps-happen.md
+7
View File
@@ -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.
docs/features/search/how-to-guides.md
+19 -67
View File
@@ -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();
```
docs/plugins/integrating-search-into-plugins.md
+1 -1
View File
@@ -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
plugins/search-backend-module-catalog/CHANGELOG.md
-1
View File
@@ -1 +0,0 @@
# @backstage/plugin-search-backend-module-catalog
plugins/search-backend-module-catalog/README.md
+22 -2
View File
@@ -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();
```
...
plugins/search-backend-module-explore/CHANGELOG.md
-1
View File
@@ -1 +0,0 @@
# @backstage/plugin-search-backend-module-explore
plugins/search-backend-module-explore/README.md
+22 -2
View File
@@ -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();
```
...
plugins/search-backend-module-explore/package.json
-1
View File
@@ -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",
plugins/search-backend-module-techdocs/CHANGELOG.md
-1
View File
@@ -1 +0,0 @@
# @backstage/plugin-search-backend-module-techdocs
plugins/search-backend-module-techdocs/README.md
+22 -2
View File
@@ -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();
```
...
plugins/search-backend-module-techdocs/package.json
-1
View File
@@ -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",
yarn.lock
+1 -2
View File
@@ -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