From 5d1670f95909d8f8ca6af4af44865abfb649166a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 4 Sep 2024 11:15:41 +0200 Subject: [PATCH] update installation instructions in readme files for new backend system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/early-swans-grab.md | 12 +++++ plugins/devtools-backend/README.md | 43 +++++++++-------- .../README.md | 47 ++++--------------- .../README.md | 29 +++--------- .../README.md | 47 +++---------------- .../scaffolder-backend-module-rails/README.md | 37 +++------------ .../README.md | 26 +++------- .../README.md | 30 +++--------- plugins/user-settings-backend/README.md | 40 ++-------------- 9 files changed, 79 insertions(+), 232 deletions(-) create mode 100644 .changeset/early-swans-grab.md diff --git a/.changeset/early-swans-grab.md b/.changeset/early-swans-grab.md new file mode 100644 index 0000000000..4526067275 --- /dev/null +++ b/.changeset/early-swans-grab.md @@ -0,0 +1,12 @@ +--- +'@backstage/plugin-scaffolder-backend-module-confluence-to-markdown': patch +'@backstage/plugin-scaffolder-backend-module-cookiecutter': patch +'@backstage/plugin-scaffolder-backend-module-gitlab': patch +'@backstage/plugin-scaffolder-backend-module-sentry': patch +'@backstage/plugin-scaffolder-backend-module-yeoman': patch +'@backstage/plugin-scaffolder-backend-module-rails': patch +'@backstage/plugin-user-settings-backend': patch +'@backstage/plugin-devtools-backend': patch +--- + +Update README installation instructions diff --git a/plugins/devtools-backend/README.md b/plugins/devtools-backend/README.md index bf0eb64a98..d9ffb3e076 100644 --- a/plugins/devtools-backend/README.md +++ b/plugins/devtools-backend/README.md @@ -4,7 +4,30 @@ Welcome to the DevTools backend plugin! This plugin provides data for the [DevTo ## Setup -Here's how to get the DevTools Backend up and running: +Here's how to get the DevTools Backend up and running in the new backend system: + +1. First we need to add the `@backstage/plugin-devtools-backend` package to your backend: + + ```sh + # From the Backstage root directory + yarn --cwd packages/backend add @backstage/plugin-devtools-backend + ``` + +2. Then add the plugin to your backend index file: + + ```ts + // In packages/backend/src/index.ts + const backend = createBackend(); + // ... other feature additions + backend.add(import('@backstage/plugin-devtools-backend')); + ``` + +3. Now run `yarn start-backend` from the repo root +4. Finally open `http://localhost:7007/api/devtools/health` in a browser and it should return `{"status":"ok"}` + +## Old Backend System + +If you are still on the old backend system, please consider migrating to the new backend system. But to install this plugin in an old backend, see below. 1. First we need to add the `@backstage/plugin-devtools-backend` package to your backend: @@ -50,24 +73,6 @@ Here's how to get the DevTools Backend up and running: 4. Now run `yarn start-backend` from the repo root 5. Finally open `http://localhost:7007/api/devtools/health` in a browser and it should return `{"status":"ok"}` -### New Backend System - -The DevTools backend plugin has support for the [new backend system](https://backstage.io/docs/backend-system/), here's how you can set that up: - -In your `packages/backend/src/index.ts` make the following changes: - -```diff - import { createBackend } from '@backstage/backend-defaults'; - - const backend = createBackend(); - - // ... other feature additions - -+ backend.add(import('@backstage/plugin-devtools-backend')); - - backend.start(); -``` - ## Links - [Frontend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/devtools) diff --git a/plugins/scaffolder-backend-module-confluence-to-markdown/README.md b/plugins/scaffolder-backend-module-confluence-to-markdown/README.md index 1e64004041..aa7b9fee79 100644 --- a/plugins/scaffolder-backend-module-confluence-to-markdown/README.md +++ b/plugins/scaffolder-backend-module-confluence-to-markdown/README.md @@ -15,47 +15,16 @@ From your Backstage root directory run: yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-confluence-to-markdown ``` -Then configure the action: -(you can check the [docs](https://backstage.io/docs/features/software-templates/writing-custom-actions#registering-custom-actions) to see all options): +Then ensure that both the scaffolder and this module are added to your backend: ```typescript -// packages/backend/src/plugins/scaffolder.ts - -import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend'; -import { ScmIntegrations } from '@backstage/integration'; -import { createConfluenceToMarkdownAction } from '@backstage/plugin-scaffolder-backend-module-confluence-to-markdown'; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - const catalogClient = new CatalogClient({ discoveryApi: env.discovery }); - const integrations = ScmIntegrations.fromConfig(env.config); - - const builtInActions = createBuiltinActions({ - integrations, - catalogClient, - config: env.config, - reader: env.reader, - }); - - const actions = [ - ...builtInActions, - createConfluenceToMarkdownAction({ - integrations, - config: env.config, - reader: env.reader, - }), - ]; - - return createRouter({ - actions, - catalogClient: catalogClient, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, - }); -} +// In packages/backend/src/index.ts +const backend = createBackend(); +// ... +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +backend.add( + import('@backstage/plugin-scaffolder-backend-module-confluence-to-markdown'), +); ``` ### Configuration diff --git a/plugins/scaffolder-backend-module-cookiecutter/README.md b/plugins/scaffolder-backend-module-cookiecutter/README.md index 643154c826..ba2cd14cb2 100644 --- a/plugins/scaffolder-backend-module-cookiecutter/README.md +++ b/plugins/scaffolder-backend-module-cookiecutter/README.md @@ -13,31 +13,14 @@ You need to configure the action in your backend: yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-cookiecutter ``` -Configure the action: -(you can check the [docs](https://backstage.io/docs/features/software-templates/writing-custom-actions#registering-custom-actions) to see all options): +Then ensure that both the scaffolder and this module are added to your backend: ```typescript -// packages/backend/src/plugins/scaffolder.ts - -const actions = [ - createFetchCookiecutterAction({ - integrations, - reader: env.reader, - }), - ...createBuiltInActions({ - ... - }) -]; - -return await createRouter({ - containerRunner, - catalogClient, - actions, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, -}); +// In packages/backend/src/index.ts +const backend = createBackend(); +// ... +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +backend.add(import('@backstage/plugin-scaffolder-backend-module-cookiecutter')); ``` After that you can use the action in your template: diff --git a/plugins/scaffolder-backend-module-gitlab/README.md b/plugins/scaffolder-backend-module-gitlab/README.md index 3aee2b6681..3f991bf308 100644 --- a/plugins/scaffolder-backend-module-gitlab/README.md +++ b/plugins/scaffolder-backend-module-gitlab/README.md @@ -13,50 +13,17 @@ Here you can find all Gitlab related features to improve your scaffolder: yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-gitlab ``` -Configure the action: -(you can check the [docs](https://backstage.io/docs/features/software-templates/writing-custom-actions#registering-custom-actions) to see all options): +Then ensure that both the scaffolder and this module are added to your backend: ```typescript -// packages/backend/src/plugins/scaffolder.ts - -import { - createGitlabProjectAccessTokenAction, - createGitlabProjectDeployTokenAction, - createGitlabProjectVariableAction, - createGitlabGroupEnsureExistsAction, - createGitlabIssueAction, -} from '@backstage/plugin-scaffolder-backend-module-gitlab'; - -// Create BuiltIn Actions -const builtInActions = createBuiltinActions({ - integrations, - catalogClient, - config: env.config, - reader: env.reader, -}); - -// Add Gitlab Actions -const actions = [ - ...builtInActions, - createGitlabProjectAccessTokenAction({ integrations: integrations }), - createGitlabProjectDeployTokenAction({ integrations: integrations }), - createGitlabProjectVariableAction({ integrations: integrations }), - createGitlabGroupEnsureExistsAction({ integrations: integrations }), - createGitlabIssueAction({ integrations: integrations }), -]; - -// Create Scaffolder Router -return await createRouter({ - catalogClient, - actions, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, -}); +// In packages/backend/src/index.ts +const backend = createBackend(); +// ... +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +backend.add(import('@backstage/plugin-scaffolder-backend-module-gitlab')); ``` -After that you can use the action in your template: +After that you can use the actions in your template: ```yaml apiVersion: scaffolder.backstage.io/v1beta3 diff --git a/plugins/scaffolder-backend-module-rails/README.md b/plugins/scaffolder-backend-module-rails/README.md index 18e16a7567..27db5656c5 100644 --- a/plugins/scaffolder-backend-module-rails/README.md +++ b/plugins/scaffolder-backend-module-rails/README.md @@ -18,26 +18,14 @@ You need to configure the action in your backend: yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-rails ``` -Configure the action (you can check -the [docs](https://backstage.io/docs/features/software-templates/writing-custom-actions#registering-custom-actions) to -see all options): +Then ensure that both the scaffolder and this module are added to your backend: ```typescript -const actions = [ - createFetchRailsAction({ - integrations, - reader: env.reader, - }), -]; - -return await createRouter({ - catalogClient, - actions, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, -}); +// In packages/backend/src/index.ts +const backend = createBackend(); +// ... +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +backend.add(import('@backstage/plugin-scaffolder-backend-module-rails')); ``` After that you can use the action in your template: @@ -244,16 +232,3 @@ steps: system: ${{ parameters.system }} railsArguments: ${{ parameters.railsArguments }} ``` - -You also need to configure the list of allowed images as part of the creating the action for the scaffolder backend: - -```typescript -const actions = [ - createFetchRailsAction({ - integrations, - reader: env.reader, - containerRunner, - allowedImageNames: ['repository/rails:tag'], - }), -]; -``` diff --git a/plugins/scaffolder-backend-module-sentry/README.md b/plugins/scaffolder-backend-module-sentry/README.md index 5cb1f1b810..d13f923a2a 100644 --- a/plugins/scaffolder-backend-module-sentry/README.md +++ b/plugins/scaffolder-backend-module-sentry/README.md @@ -15,28 +15,14 @@ You need to configure the action in your backend: yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-sentry ``` -Configure the action (you can check -the [docs](https://backstage.io/docs/features/software-templates/writing-custom-actions#registering-custom-actions) to -see all options): +Then ensure that both the scaffolder and this module are added to your backend: ```typescript -const actions = [ - createSentryCreateProjectAction({ - integrations, - reader: env.reader, - containerRunner, - }), -]; - -return await createRouter({ - containerRunner, - catalogClient, - actions, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, -}); +// In packages/backend/src/index.ts +const backend = createBackend(); +// ... +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +backend.add(import('@backstage/plugin-scaffolder-backend-module-sentry')); ``` You need to define your Sentry API Token in your `app-config.yaml`: diff --git a/plugins/scaffolder-backend-module-yeoman/README.md b/plugins/scaffolder-backend-module-yeoman/README.md index 05bbf6064b..3a32dd2124 100644 --- a/plugins/scaffolder-backend-module-yeoman/README.md +++ b/plugins/scaffolder-backend-module-yeoman/README.md @@ -13,32 +13,14 @@ You need to configure the action in your backend: yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-yeoman ``` -Configure the action: -(you can check the [docs](https://backstage.io/docs/features/software-templates/writing-custom-actions#registering-custom-actions) to see all options): +Then ensure that both the scaffolder and this module are added to your backend: ```typescript -// packages/backend/src/plugins/scaffolder.ts - -const actions = [ - createRunYeomanAction(), - ...createBuiltInActions({ - containerRunner, - catalogClient, - integrations, - config: env.config, - reader: env.reader, - }), -]; - -return await createRouter({ - containerRunner, - catalogClient, - actions, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, -}); +// In packages/backend/src/index.ts +const backend = createBackend(); +// ... +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +backend.add(import('@backstage/plugin-scaffolder-backend-module-yeoman')); ``` After that you can use the action in your template: diff --git a/plugins/user-settings-backend/README.md b/plugins/user-settings-backend/README.md index a1fb504415..249edec592 100644 --- a/plugins/user-settings-backend/README.md +++ b/plugins/user-settings-backend/README.md @@ -10,48 +10,16 @@ Install the backend plugin ```bash # From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-user-settings-backend +yarn --cwd packages/backend add @backstage/plugin-user-settings-backend @backstage/plugin-signals-backend ``` -### New backend - Add the plugin to your backend in `packages/backend/src/index.ts`: ```ts backend.add(import('@backstage/plugin-user-settings-backend/alpha')); -``` - -To get real-time updates of the user settings across different user sessions, you must also install -the `@backstage/plugin-signals-backend` plugin. - -### Old backend - -1. Configure the routes by adding a new `userSettings.ts` file in - `packages/backend/src/plugins/`: - -```ts -// packages/backend/src/plugins/userSettings.ts -import { createRouter } from '@backstage/plugin-user-settings-backend'; -import { PluginEnvironment } from '../types'; - -export default async function createPlugin(env: PluginEnvironment) { - return await createRouter({ - database: env.database, - identity: env.identity, - }); -} -``` - -2. Add the new routes to your backend by modifying `packages/backend/src/index.ts`: - -```diff - // packages/backend/src/index.ts -+import userSettings from './plugins/userSettings'; - async function main() { -+ const userSettingsEnv = useHotMemoize(module, () => createEnv('user-settings')); - const apiRouter = Router(); -+ apiRouter.use('/user-settings', await userSettings(userSettingsEnv)); -} +// The signals backend is technically optional but enables real-time update of user +// settings across different sessions +backend.add(import('@backstage/plugin-signals-backend')); ``` ## Setup app