diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index 10968b427c..36bb724be6 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -8,44 +8,36 @@ The Kubernetes feature is a plugin to Backstage, and it is exposed as a tab when viewing entities in the software catalog. If you haven't setup Backstage already, read the -[Getting Started](../../getting-started/index.md). +[Getting Started](../../getting-started/index.md) guide. ## Adding the Kubernetes frontend plugin -The first step is to add the frontend Kubernetes plugin to your Backstage -application. Navigate to your new Backstage application directory. And then to +The first step is to add the Kubernetes frontend plugin to your Backstage +application. Navigate to your new Backstage application directory, and then to your `packages/app` directory, and install the `@backstage/plugin-kubernetes` package. ```bash -cd my-backstage-app/ +# From your Backstage root directory cd packages/app yarn add @backstage/plugin-kubernetes ``` Once the package has been installed, you need to import the plugin in your app -by adding the "Kubernetes" tab to the catalog entity page. In -`packages/app/src/components/catalog/EntityPage.tsx`, you'll add a router to get -to the tab, and add the tab itself. - -`EntityPage.tsx`: +by adding the "Kubernetes" tab to the respective catalog pages. ```tsx -import { Router as KubernetesRouter } from '@backstage/plugin-kubernetes'; +// In packages/app/src/components/catalog/EntityPage.tsx +import { EntityKubernetesContent } from '@backstage/plugin-kubernetes'; -// ... - -const ServiceEntityPage = ({ entity }: { entity: Entity }) => ( - - // ... - } - /> - // ... - -); +// You can add the tab to any number of pages, the service page is shown as an +// example here +const serviceEntityPage = ( + + {/* other tabs... */} + + + ``` That's it! But now, we need the Kubernetes Backend plugin for the frontend to @@ -57,17 +49,16 @@ Navigate to `packages/backend` of your Backstage app, and install the `@backstage/plugin-kubernetes-backend` package. ```bash -cd my-backstage-app/ +# From your Backstage root directory cd packages/backend yarn add @backstage/plugin-kubernetes-backend ``` Create a file called `kubernetes.ts` inside `packages/backend/src/plugins/` and -add the following - -`kubernetes.ts`: +add the following: ```typescript +// In packages/backend/src/plugins/kubernetes.ts import { createRouter } from '@backstage/plugin-kubernetes-backend'; import { PluginEnvironment } from '../types'; @@ -83,18 +74,15 @@ And import the plugin to `packages/backend/src/index.ts`. There are three lines of code you'll need to add, and they should be added near similar code in your existing Backstage backend. -`index.ts`: - ```typescript +// In packages/backend/src/index.ts import kubernetes from './plugins/kubernetes'; - // ... - -const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes')); - -// ... - -apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv)); +async function main() { + // ... + const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes')); + // ... + apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv)); ``` That's it! The Kubernetes frontend and backend have now been added to your diff --git a/docs/features/software-catalog/installation.md b/docs/features/software-catalog/installation.md index df473f886f..0b622fb093 100644 --- a/docs/features/software-catalog/installation.md +++ b/docs/features/software-catalog/installation.md @@ -18,6 +18,7 @@ The catalog frontend plugin should be installed in your `app` package, which is created as a part of `@backstage/create-app`. To install the package, run: ```bash +# From your Backstage root directory cd packages/app yarn add @backstage/plugin-catalog ``` @@ -103,6 +104,7 @@ The catalog backend should be installed in your `backend` package, which is created as a part of `@backstage/create-app`. To install the package, run: ```bash +# From your Backstage root directory cd packages/backend yarn add @backstage/plugin-catalog-backend ``` diff --git a/docs/features/software-templates/installation.md b/docs/features/software-templates/installation.md index c682ca6ddf..5acaf0e499 100644 --- a/docs/features/software-templates/installation.md +++ b/docs/features/software-templates/installation.md @@ -20,6 +20,7 @@ The scaffolder frontend plugin should be installed in your `app` package, which is created as a part of `@backstage/create-app`. To install the package, run: ```bash +# From your Backstage root directory cd packages/app yarn add @backstage/plugin-scaffolder ``` @@ -57,6 +58,7 @@ The scaffolder backend should be installed in your `backend` package, which is created as a part of `@backstage/create-app`. To install the package, run: ```bash +# From your Backstage root directory cd packages/backend yarn add @backstage/plugin-scaffolder-backend ``` diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 223b276d68..520db2245c 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -22,7 +22,7 @@ Navigate to your new Backstage application directory. And then to your `packages/app` directory, and install the `@backstage/plugin-techdocs` package. ```bash -cd my-backstage-app/ +# From your Backstage root directory cd packages/app yarn add @backstage/plugin-techdocs ``` @@ -54,7 +54,7 @@ Navigate to `packages/backend` of your Backstage app, and install the `@backstage/plugin-techdocs-backend` package. ```bash -cd my-backstage-app/ +# From your Backstage root directory cd packages/backend yarn add @backstage/plugin-techdocs-backend ``` diff --git a/docs/plugins/integrating-plugin-into-service-catalog.md b/docs/plugins/integrating-plugin-into-service-catalog.md index 01de779635..047b6f14e6 100644 --- a/docs/plugins/integrating-plugin-into-service-catalog.md +++ b/docs/plugins/integrating-plugin-into-service-catalog.md @@ -1,7 +1,7 @@ --- id: integrating-plugin-into-service-catalog title: Integrate into the Service Catalog -description: Documentation on How to integrate plugin into service catalog +description: How to integrate a plugin into service catalog --- > This is an advanced use case and currently is an experimental feature. Expect diff --git a/docs/tutorials/switching-sqlite-postgres.md b/docs/tutorials/switching-sqlite-postgres.md index a759b7dc49..fafd2ad586 100644 --- a/docs/tutorials/switching-sqlite-postgres.md +++ b/docs/tutorials/switching-sqlite-postgres.md @@ -17,11 +17,11 @@ switch between database backends. ## Install PostgreSQL -First, swap out SQLite for PostgreSQL in your `backend` package: +First, add PostgreSQL to your `backend` package: ```shell +# From your Backstage root directory cd packages/backend -yarn remove sqlite3 yarn add pg ``` @@ -46,7 +46,6 @@ backend: + #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) + #ca: # if you have a CA file and want to verify it you can uncomment this section + #$file: /ca/server.crt - ``` If you have an `app-config.local.yaml` for local development, a similar update diff --git a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md index 65102c919f..7289878bc1 100644 --- a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md +++ b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md @@ -45,7 +45,7 @@ The only thing you need to do is to start the app: ```bash cd my-app -yarn start +yarn dev ``` And you are good to go! 👍 @@ -101,18 +101,12 @@ We provide a collection of public Backstage plugins (look for packages with the Install in your app’s package folder (`/packages/app`) with: ```bash +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin- ``` -Then add it to your app's `plugin.ts` file to import and register it: - -`/packages/app/src/plugin.ts`: - -```js -export { plugin as PluginName } from '@backstage/plugin-'; -``` - -A plugin registers its own `route` in the app — read the documentation for the specific plugin you are installing for more information on that. +After that, you inject the plugin into the application where you want it to be exposed. Please read the documentation for the specific plugin you are installing for more information. ### Creating an internal plugin diff --git a/packages/backend-common/README.md b/packages/backend-common/README.md index dc08d89416..dc69790bc3 100644 --- a/packages/backend-common/README.md +++ b/packages/backend-common/README.md @@ -8,6 +8,8 @@ error handling and similar. Add the library to your backend package: ```sh +# From your Backstage root directory +cd packages/backend yarn add @backstage/backend-common ``` diff --git a/packages/backend/src/plugins/kubernetes.ts b/packages/backend/src/plugins/kubernetes.ts index 131c5c8eee..7906765533 100644 --- a/packages/backend/src/plugins/kubernetes.ts +++ b/packages/backend/src/plugins/kubernetes.ts @@ -15,12 +15,11 @@ */ import { createRouter } from '@backstage/plugin-kubernetes-backend'; -import { Router } from 'express'; import { PluginEnvironment } from '../types'; export default async function createPlugin({ logger, config, -}: PluginEnvironment): Promise { +}: PluginEnvironment) { return await createRouter({ logger, config }); } diff --git a/packages/cli/README.md b/packages/cli/README.md index cd6ad8094e..eb5e0e461b 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -7,13 +7,13 @@ This package provides a CLI for developing Backstage plugins and apps. Install the package via npm or Yarn: ```sh -$ npm install --save @backstage/cli +npm install --save @backstage/cli ``` or ```sh -$ yarn add @backstage/cli +yarn add @backstage/cli ``` ## Development diff --git a/packages/core-api/README.md b/packages/core-api/README.md index f7b8b6c337..a4325a9c5d 100644 --- a/packages/core-api/README.md +++ b/packages/core-api/README.md @@ -7,13 +7,13 @@ This package provides the core API used by Backstage plugins and apps. Do not install this package directly, it is reexported by `@backstage/core`. Install that instead: ```sh -$ npm install --save @backstage/core +npm install --save @backstage/core ``` or ```sh -$ yarn add @backstage/core +yarn add @backstage/core ``` ## Documentation diff --git a/packages/core/README.md b/packages/core/README.md index 6d8519d46f..0f827d6074 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -7,13 +7,13 @@ This package provides the core API used by Backstage plugins and apps. Install the package via npm or Yarn: ```sh -$ npm install --save @backstage/core +npm install --save @backstage/core ``` or ```sh -$ yarn add @backstage/core +yarn add @backstage/core ``` ## Documentation diff --git a/packages/dev-utils/README.md b/packages/dev-utils/README.md index 4b08a5ca6d..85d961ad0b 100644 --- a/packages/dev-utils/README.md +++ b/packages/dev-utils/README.md @@ -9,13 +9,13 @@ This package provides utilities that help in developing plugins for Backstage, l Install the package via npm or Yarn: ```sh -$ npm install --save-dev @backstage/dev-utils +npm install --save-dev @backstage/dev-utils ``` or ```sh -$ yarn add -D @backstage/dev-utils +yarn add -D @backstage/dev-utils ``` ## Documentation diff --git a/packages/test-utils/README.md b/packages/test-utils/README.md index 0f95d4ab26..ace7339733 100644 --- a/packages/test-utils/README.md +++ b/packages/test-utils/README.md @@ -7,13 +7,13 @@ This package provides utilities that can be used to test plugins and apps for Ba Install the package via npm or Yarn: ```sh -$ npm install --save-dev @backstage/test-utils +npm install --save-dev @backstage/test-utils ``` or ```sh -$ yarn add -D @backstage/test-utils +yarn add -D @backstage/test-utils ``` ## Documentation diff --git a/packages/theme/README.md b/packages/theme/README.md index 9855d6730d..de94ff1623 100644 --- a/packages/theme/README.md +++ b/packages/theme/README.md @@ -7,13 +7,13 @@ This package provides the extended Material UI Theme(s) that power Backstage. Install the package via npm or Yarn: ```sh -$ npm install --save @backstage/theme +npm install --save @backstage/theme ``` or ```sh -$ yarn add @backstage/theme +yarn add @backstage/theme ``` ## Documentation diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index dac4b6ff4d..60d8986d9b 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -28,15 +28,15 @@ To link that a component provides or consumes an API, see the [`providesApis`](h 1. Install the API docs plugin ```bash -# packages/app - +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-api-docs ``` 2. Add the `ApiExplorerPage` extension to the app: ```tsx -// packages/app/src/App.tsx +// In packages/app/src/App.tsx import { ApiExplorerPage } from '@backstage/plugin-api-docs'; @@ -56,7 +56,7 @@ import { } from '@backstage/plugin-api-docs'; const apiPage = ( - + @@ -80,7 +80,7 @@ const apiPage = ( - + ); // ... diff --git a/plugins/app-backend/README.md b/plugins/app-backend/README.md index 2dc302accb..a35cecfb9c 100644 --- a/plugins/app-backend/README.md +++ b/plugins/app-backend/README.md @@ -7,7 +7,9 @@ This backend plugin can be installed to serve static content of a Backstage app. Add both this package and your local frontend app package as dependencies to your backend, for example ```bash -yarn add @backstage/plugin-app-backend example-app +# From your Backstage root directory +cd packages/backend +yarn add @backstage/plugin-app-backend app ``` By adding the app package as a dependency we ensure that it is built as part of the backend, and that it can be resolved at runtime. diff --git a/plugins/bitrise/README.md b/plugins/bitrise/README.md index 411db3198e..1add03df23 100644 --- a/plugins/bitrise/README.md +++ b/plugins/bitrise/README.md @@ -8,9 +8,9 @@ Welcome to the Bitrise plugin! ## Installation ```sh -# The plugin must be added in the app package -$ cd packages/app -$ yarn add @backstage/plugin-bitrise +# From your Backstage root directory +cd packages/app +yarn add @backstage/plugin-bitrise ``` Bitrise Plugin exposes an entity tab component named `EntityBitriseContent`. You can include it in the @@ -22,7 +22,7 @@ import { EntityBitriseContent } from '@backstage/plugin-bitrise'; // Farther down at the website declaration const websiteEntityPage = ( - + {/* Place the following section where you want the tab to appear */} diff --git a/plugins/catalog-import/README.md b/plugins/catalog-import/README.md index 5e773ad288..bad48a8486 100644 --- a/plugins/catalog-import/README.md +++ b/plugins/catalog-import/README.md @@ -18,8 +18,8 @@ Some features are not yet available for all supported Git providers. 1. Install the Catalog Import Plugin: ```bash -# packages/app - +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-catalog-import ``` diff --git a/plugins/circleci/README.md b/plugins/circleci/README.md index 868ae6e26a..c878c66e56 100644 --- a/plugins/circleci/README.md +++ b/plugins/circleci/README.md @@ -7,34 +7,35 @@ Website: [https://circleci.com/](https://circleci.com/) ## Setup -1. If you have standalone app (you didn't clone this repo), then do +1. If you have a standalone app (you didn't clone this repo), then do ```bash +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-circleci ``` -2. Add the `EntityCircleCIContent` extension to the entity page in the app: +2. Add the `EntityCircleCIContent` extension to the entity page in your app: ```tsx -// packages/app/src/components/catalog/EntityPage.tsx -import { EntityCircleCIContent } from '@backstage/plugin-circleci'; +// In packages/app/src/components/catalog/EntityPage.tsx +import { + EntityCircleCIContent, + isCircleCIAvailable, +} from '@backstage/plugin-circleci'; -// ... -const serviceEntityPage = ( - - ... - +// For example in the CI/CD section +const cicdContent = ( + + - - ... - -); + ``` 4. Add proxy config: ```yaml -// app-config.yaml +# In app-config.yaml proxy: '/circleci/api': target: https://circleci.com/api/v1.1 @@ -42,10 +43,11 @@ proxy: Circle-Token: ${CIRCLECI_AUTH_TOKEN} ``` -5. Get and provide `CIRCLECI_AUTH_TOKEN` as env variable (https://circleci.com/docs/api/#add-an-api-token) -6. Add `circleci.com/project-slug` annotation to your catalog-info.yaml file in format // (https://backstage.io/docs/architecture-decisions/adrs-adr002#format) +5. Get and provide a `CIRCLECI_AUTH_TOKEN` as an environment variable (see the [CircleCI docs](https://circleci.com/docs/api/#add-an-api-token)). +6. Add a `circleci.com/project-slug` annotation to your respective `catalog-info.yaml` files, on the format // (https://backstage.io/docs/architecture-decisions/adrs-adr002#format). ```yaml +# Example catalog-info.yaml entity definition file apiVersion: backstage.io/v1alpha1 kind: Component metadata: diff --git a/plugins/cost-insights/README.md b/plugins/cost-insights/README.md index f737c022f3..3fee89e77a 100644 --- a/plugins/cost-insights/README.md +++ b/plugins/cost-insights/README.md @@ -16,6 +16,8 @@ Learn more with the Backstage blog post [New Cost Insights plugin: The engineer' ## Install ```bash +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-cost-insights ``` diff --git a/plugins/cost-insights/contrib/aws-cost-explorer-api.md b/plugins/cost-insights/contrib/aws-cost-explorer-api.md index 10622b7917..d6c5250759 100644 --- a/plugins/cost-insights/contrib/aws-cost-explorer-api.md +++ b/plugins/cost-insights/contrib/aws-cost-explorer-api.md @@ -33,6 +33,8 @@ Cost Explorer permission policy: Install the AWS Cost Explorer SDK. The AWS docs recommend using the SDK over making calls to the API directly as it simplifies authentication and provides direct access to commands. ```bash +# From your Backstage root directory +cd packages/app yarn add @aws-sdk/client-cost-explorer ``` diff --git a/plugins/fossa/README.md b/plugins/fossa/README.md index 11f3e90e1c..6ca2e1a96f 100644 --- a/plugins/fossa/README.md +++ b/plugins/fossa/README.md @@ -9,8 +9,8 @@ The FOSSA Plugin displays code statistics from [FOSSA](https://fossa.com/). 1. Install the FOSSA Plugin: ```bash -# packages/app - +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-fossa ``` diff --git a/plugins/github-actions/README.md b/plugins/github-actions/README.md index 87c68839c1..d027368c8b 100644 --- a/plugins/github-actions/README.md +++ b/plugins/github-actions/README.md @@ -11,15 +11,15 @@ TBD ### Generic Requirements 1. Provide OAuth credentials: - 1. [Create an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) with callback URL set to `http://localhost:7000/api/auth/github`. - 2. Take Client ID and Client Secret from the newly created app's settings page and put them into `AUTH_GITHUB_CLIENT_ID` and `AUTH_GITHUB_CLIENT_SECRET` env variables. + 1. [Create an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) with the callback URL set to `http://localhost:7000/api/auth/github`. + 2. Take the Client ID and Client Secret from the newly created app's settings page and put them into `AUTH_GITHUB_CLIENT_ID` and `AUTH_GITHUB_CLIENT_SECRET` environment variables. 2. Annotate your component with a correct GitHub Actions repository and owner: The annotation key is `github.com/project-slug`. Example: - ``` + ```yaml apiVersion: backstage.io/v1alpha1 kind: Component metadata: @@ -38,6 +38,7 @@ TBD 1. Install the plugin dependency in your Backstage app package: ```bash +# From your Backstage root directory cd packages/app yarn add @backstage/plugin-github-actions ``` @@ -45,22 +46,24 @@ yarn add @backstage/plugin-github-actions 2. Add to the app `EntityPage` component: ```tsx -// packages/app/src/components/catalog/EntityPage.tsx -import { EntityGithubActionsContent } from '@backstage/plugin-github-actions'; +// In packages/app/src/components/catalog/EntityPage.tsx +import { + EntityGithubActionsContent, + isGithubActionsAvailable, +} from '@backstage/plugin-github-actions'; -// ... +// You can add the tab to any number of pages, the service page is shown as an +// example here const serviceEntityPage = ( - - ... + + {/* other tabs... */} - ... - -); ``` -2. Run the app with `yarn start` and the backend with `yarn --cwd packages/backend start`, navigate to `/github-actions/`. +3. Run the app with `yarn start` and the backend with `yarn start-backend`. + Then navigate to `/github-actions/` under any entity. ## Features diff --git a/plugins/github-deployments/README.md b/plugins/github-deployments/README.md index 1bb8846105..8284ceba56 100644 --- a/plugins/github-deployments/README.md +++ b/plugins/github-deployments/README.md @@ -13,8 +13,8 @@ The GitHub Deployments Plugin displays recent deployments from GitHub. 1. Install the GitHub Deployments Plugin. ```bash -# packages/app - +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-github-deployments ``` diff --git a/plugins/graphiql/README.md b/plugins/graphiql/README.md index 39372890d1..b95f055a56 100644 --- a/plugins/graphiql/README.md +++ b/plugins/graphiql/README.md @@ -12,6 +12,7 @@ By exposing GraphiQL as a plugin instead of a standalone app, it's possible to p Start out by installing the plugin in your Backstage app: ```bash +# From your Backstage root directory cd packages/app yarn add @backstage/plugin-graphiql ``` diff --git a/plugins/jenkins/README.md b/plugins/jenkins/README.md index f406393190..69304cb847 100644 --- a/plugins/jenkins/README.md +++ b/plugins/jenkins/README.md @@ -11,25 +11,25 @@ Website: [https://jenkins.io/](https://jenkins.io/) 1. If you have a standalone app (you didn't clone this repo), then do ```bash +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-jenkins ``` 2. Add the `EntityJenkinsContent` extension to the entity page in the app: ```tsx -// packages/app/src/components/catalog/EntityPage.tsx -import { EntityJenkinsContent } from '@backstage/plugin-circleci'; +// In packages/app/src/components/catalog/EntityPage.tsx +import { EntityJenkinsContent } from '@backstage/plugin-jenkins'; -// ... +// You can add the tab to any number of pages, the service page is shown as an +// example here const serviceEntityPage = ( - - ... + + {/* other tabs... */} - ... - -); ``` 3. Add proxy configuration to `app-config.yaml` @@ -43,14 +43,18 @@ proxy: Authorization: Basic ${JENKINS_BASIC_AUTH_HEADER} ``` -4. Add an environment variable which contains the Jenkins credentials, (note: use an API token not your password). Here user is the name of the user created in Jenkins. +4. Add an environment variable which contains the Jenkins credentials (NOTE: + use an API token, not your password). Here `user` is the name of the user + created in Jenkins. ```shell export JENKINS_BASIC_AUTH_HEADER=$(echo -n user:api-token | base64) ``` -5. Run app with `yarn start` -6. Add the Jenkins folder annotation to your `catalog-info.yaml`, (note: currently this plugin only supports folders and Git SCM) +5. Run the app with `yarn start` + +6. Add the Jenkins folder annotation to your `catalog-info.yaml`, (NOTE: + currently this plugin only supports folders and Git SCM) ```yaml apiVersion: backstage.io/v1alpha1 @@ -68,11 +72,11 @@ spec: 7. Register your component -8. Click the component in the catalog you should now see Jenkins builds, and a last build result for your master build. +8. Click the component in the catalog. You should now see Jenkins builds, and a + last build result for your master build. -Note: - -If you are not using environment variable then you can directly type API token in app-config.yaml +Note: If you are not using environment variables, you can directly type the API +token into `app-config.yaml`. ```yaml proxy: @@ -83,7 +87,8 @@ proxy: Authorization: Basic YWRtaW46MTFlYzI1NmU0Mzg1MDFjM2Y1Yzc2Yjc1MWE3ZTQ3YWY4Mw== ``` -YWRtaW46MTFlYzI1NmU0Mzg1MDFjM2Y1Yzc2Yjc1MWE3ZTQ3YWY4Mw== is the base64 of user and it's API token e.g. admin:11ec256e438501c3f5c76b751a7e47af83 +The string starting with `YWR...` is the base64 encoding of the user and their +API token, e.g. `admin:11ec256e438501c3f5c76b751a7e47af83`. ## Features @@ -94,4 +99,5 @@ YWRtaW46MTFlYzI1NmU0Mzg1MDFjM2Y1Yzc2Yjc1MWE3ZTQ3YWY4Mw== is the base64 of user a ## Limitations - Only works with organization folder projects backed by GitHub -- No pagination support currently, limited to 50 projects - don't run this on a Jenkins with lots of builds +- No pagination support currently, limited to 50 projects - don't run this on a + Jenkins instance with lots of builds diff --git a/plugins/kafka-backend/README.md b/plugins/kafka-backend/README.md index 14914e5ba6..d18a232fa4 100644 --- a/plugins/kafka-backend/README.md +++ b/plugins/kafka-backend/README.md @@ -1,6 +1,7 @@ # Kafka Backend -This is the backend part of the Kafka plugin. It responds to Kafka requests from the frontend. +This is the backend part of the Kafka plugin. It responds to Kafka requests +from the frontend. ## Configuration @@ -16,7 +17,9 @@ A list of the brokers' host names and ports to connect to. ### `ssl` (optional) -Configure TLS connection to the Kafka cluster. The options are passed directly to [tls.connect] and used to create the TLS secure context. Normally these would include `key` and `cert`. +Configure TLS connection to the Kafka cluster. The options are passed directly +to [tls.connect] and used to create the TLS secure context. Normally these +would include `key` and `cert`. Example: @@ -39,7 +42,7 @@ kafka: clusters: - name: prod brokers: - - my-cluser:9092 + - my-cluster:9092 ssl: true sasl: mechanism: plain # or 'scram-sha-256' or 'scram-sha-512' diff --git a/plugins/kafka/README.md b/plugins/kafka/README.md index a2ea01cf7d..7da44ae9b6 100644 --- a/plugins/kafka/README.md +++ b/plugins/kafka/README.md @@ -7,7 +7,9 @@ 1. Run: ```bash -yarn add @backstage/plugin-kafka @backstage/plugin-kafka-backend +# From your Backstage root directory +yarn --cwd packages/app add @backstage/plugin-kafka +yarn --cwd packages/backend add @backstage/plugin-kafka-backend ``` 2. Add the plugin backend: @@ -29,41 +31,31 @@ export default async function createPlugin({ And then add to `packages/backend/src/index.ts`: ```js -// ... +// In packages/backend/src/index.ts import kafka from './plugins/kafka'; // ... async function main() { // ... const kafkaEnv = useHotMemoize(module, () => createEnv('kafka')); // ... - - const apiRouter = Router(); - // ... apiRouter.use('/kafka', await kafka(kafkaEnv)); - // ... ``` -3. Add the plugin frontend to `packages/app/src/plugin.ts`: - -```js -export { plugin as Kafka } from '@backstage/plugin-kafka'; -``` - -4. Register the plugin frontend router in `packages/app/src/components/catalog/EntityPage.tsx`: +3. Add the plugin as a tab to your service entities: ```jsx -import { Router as KafkaRouter } from '@backstage/plugin-kafka'; +// In packages/app/src/components/catalog/EntityPage.tsx +import { EntityKafkaContent } from '@backstage/plugin-kafka'; -// Then, somewhere inside - -} -/>; +const serviceEntityPage = ( + + {/* other tabs... */} + + + ``` -5. Add broker configs for the backend in your `app-config.yaml` (see +4. Add broker configs for the backend in your `app-config.yaml` (see [kafka-backend](https://github.com/backstage/backstage/blob/master/plugins/kafka-backend/README.md) for more options): @@ -76,7 +68,7 @@ kafka: - localhost:9092 ``` -6. Add `kafka.apache.org/consumer-groups` annotation to your services: +5. Add the `kafka.apache.org/consumer-groups` annotation to your services: ```yaml apiVersion: backstage.io/v1alpha1 diff --git a/plugins/lighthouse/README.md b/plugins/lighthouse/README.md index 028547ea3e..06c9a1da12 100644 --- a/plugins/lighthouse/README.md +++ b/plugins/lighthouse/README.md @@ -28,20 +28,21 @@ _It's likely you will need to [enable CORS](https://developer.mozilla.org/en-US/ When you have an instance running that Backstage can hook into, first install the plugin into your app: ```sh -$ yarn add @backstage/plugin-lighthouse +# From your Backstage root directory +cd packages/app +yarn add @backstage/plugin-lighthouse ``` Modify your app routes in `App.tsx` to include the `LighthousePage` component exported from the plugin, for example: ```tsx -// At the top imports +// In packages/app/src/App.tsx import { LighthousePage } from '@backstage/plugin-lighthouse'; - - // ... - } /> - // ... -; +const routes = ( + + {/* ...other routes */} + } /> ``` Then configure the `lighthouse-audit-service` URL in your [`app-config.yaml`](https://github.com/backstage/backstage/blob/master/app-config.yaml). @@ -63,55 +64,45 @@ kind: Component metadata: # ... annotations: - # ... lighthouse.com/website-url: # A single website url e.g. https://backstage.io/ ``` > NOTE: The plugin only supports one website URL per component at this time. -Add a **Lighthouse tab** to the EntityPage: +Add a Lighthouse tab to the entity page: ```tsx -// packages/app/src/components/catalog/EntityPage.tsx -import { EmbeddedRouter as LighthouseRouter } from '@backstage/plugin-lighthouse'; +// In packages/app/src/components/catalog/EntityPage.tsx +import { EntityLighthouseContent } from '@backstage/plugin-lighthouse'; -// ... -const WebsiteEntityPage = ({ entity }: { entity: Entity }) => ( - - // ... - } - /> - -); +const websiteEntityPage = ( + + {/* other tabs... */} + + + ``` -> NOTE: The embedded router renders page content without a header section allowing it to be rendered within a -> catalog plugin page. +> NOTE: The embedded router renders page content without a header section +> allowing it to be rendered within a catalog plugin page. Add a **Lighthouse card** to the overview tab on the EntityPage: ```tsx -// packages/app/src/components/catalog/EntityPage.tsx +// In packages/app/src/components/catalog/EntityPage.tsx import { - LastLighthouseAuditCard, - isPluginApplicableToEntity as isLighthouseAvailable, + EntityLastLighthouseAuditCard, + isLighthouseAvailable, } from '@backstage/plugin-lighthouse'; -// ... - -const OverviewContent = ({ entity }: { entity: Entity }) => ( - - // ... - {isLighthouseAvailable(entity) && ( - - - - )} - -); +const overviewContent = ( + + {/* ...other content */} + + + + + + + ``` - -Link Lighthouse diff --git a/plugins/lighthouse/src/components/Intro/index.tsx b/plugins/lighthouse/src/components/Intro/index.tsx index a89518a5ed..6b0307f9ec 100644 --- a/plugins/lighthouse/src/components/Intro/index.tsx +++ b/plugins/lighthouse/src/components/Intro/index.tsx @@ -46,7 +46,8 @@ with the environment variable \`LAS_CORS\` set to \`true\`._ When you have an instance running that Backstage can hook into, first install the plugin into your app: \`\`\`sh -$ yarn add @backstage/plugin-lighthouse +cd packages/app +yarn add @backstage/plugin-lighthouse \`\`\` Modify your app routes in \`App.tsx\` to include the \`LighthousePage\` component exported from the plugin, for example: diff --git a/plugins/pagerduty/README.md b/plugins/pagerduty/README.md index 36f380fdd5..e1ec7f89c7 100644 --- a/plugins/pagerduty/README.md +++ b/plugins/pagerduty/README.md @@ -19,6 +19,8 @@ This plugin provides: Install the plugin: ```bash +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-pagerduty ``` diff --git a/plugins/register-component/README.md b/plugins/register-component/README.md index 9c5304385e..47db1a7a55 100644 --- a/plugins/register-component/README.md +++ b/plugins/register-component/README.md @@ -19,6 +19,7 @@ When installed it is accessible on [localhost:3000/register-component](localhost 1. Install plugin and its dependency `plugin-catalog` ```bash +# From your Backstage root directory cd packages/app yarn add @backstage/plugin-register-component ``` diff --git a/plugins/rollbar/README.md b/plugins/rollbar/README.md index 3a33fe223c..bdf0541fa0 100644 --- a/plugins/rollbar/README.md +++ b/plugins/rollbar/README.md @@ -9,25 +9,23 @@ Website: [https://rollbar.com/](https://rollbar.com/) 2. If you have standalone app (you didn't clone this repo), then do ```bash +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-rollbar ``` 3. Add to the app `EntityPage` component: ```tsx -// packages/app/src/components/catalog/EntityPage.tsx +// In packages/app/src/components/catalog/EntityPage.tsx import { EntityRollbarContent } from '@backstage/plugin-rollbar'; -// ... const serviceEntityPage = ( - - ... + + {/* other tabs... */} - ... - -); ``` 4. Setup the `app-config.yaml` and account token environment variable diff --git a/plugins/sentry/README.md b/plugins/sentry/README.md index 9bdb2dc16d..e0c56e842c 100644 --- a/plugins/sentry/README.md +++ b/plugins/sentry/README.md @@ -9,8 +9,8 @@ The Sentry Plugin displays issues from [Sentry](https://sentry.io). 1. Install the Sentry Plugin: ```bash -# packages/app - +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-sentry ``` diff --git a/plugins/sonarqube/README.md b/plugins/sonarqube/README.md index 5c12832e57..d0251e91ef 100644 --- a/plugins/sonarqube/README.md +++ b/plugins/sonarqube/README.md @@ -9,7 +9,8 @@ The SonarQube Plugin displays code statistics from [SonarCloud](https://sonarclo 1. Install the SonarQube Plugin: ```bash -# packages/app +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-sonarqube ``` diff --git a/plugins/splunk-on-call/README.md b/plugins/splunk-on-call/README.md index 5c1dda33fc..33cfa091ca 100644 --- a/plugins/splunk-on-call/README.md +++ b/plugins/splunk-on-call/README.md @@ -20,6 +20,8 @@ This plugin provides: Install the plugin: ```bash +# From your Backstage root directory +cd packages/app yarn add @backstage/plugin-splunk-on-call ``` diff --git a/plugins/tech-radar/README.md b/plugins/tech-radar/README.md index 7f97f88ed4..814ab6cba5 100644 --- a/plugins/tech-radar/README.md +++ b/plugins/tech-radar/README.md @@ -26,6 +26,7 @@ The Tech Radar can be used in two ways: For either simple or advanced installations, you'll need to add the dependency using Yarn: ```sh +# From your Backstage root directory cd packages/app yarn add @backstage/plugin-tech-radar ``` @@ -35,12 +36,12 @@ yarn add @backstage/plugin-tech-radar Modify your app routes to include the Router component exported from the tech radar, for example: ```tsx -// in packages/app/src/App.tsx +// In packages/app/src/App.tsx import { TechRadarPage } from '@backstage/plugin-tech-radar'; const routes = ( - {/* ... */} + {/* ...other routes */} } diff --git a/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md b/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md index 9f8e1bd739..f41ab1d506 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md @@ -5,19 +5,19 @@ This page provides some sample code which may be used in your example component. This code uses TypeScript, and the Markdown code fence to wrap the code. ```typescript -const DefaultEntityPage = ({ entity }: { entity: Entity }) => ( - - } - /> - } - /> - +const serviceEntityPage = ( + + + + + + + + + + + + ); ```