From 785a42f802b512be3813bc3be035608b0fd7fbc8 Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Tue, 15 Jun 2021 15:00:15 -0600 Subject: [PATCH 1/2] Move installation instructions to READMEs Signed-off-by: Tim Hansen --- docs/features/software-catalog/index.md | 5 +- .../features/software-catalog/installation.md | 177 ----------- .../software-templates/configuration.md | 52 ++++ docs/features/software-templates/index.md | 6 +- .../software-templates/installation.md | 280 ------------------ .../techdocs/creating-and-publishing.md | 8 +- docs/plugins/github-apps.md | 9 + microsite/sidebars.json | 3 +- mkdocs.yml | 3 +- plugins/catalog-backend/README.md | 88 +++++- plugins/catalog/README.md | 105 ++++++- plugins/scaffolder-backend/README.md | 67 ++++- plugins/scaffolder/README.md | 84 +++++- 13 files changed, 371 insertions(+), 516 deletions(-) delete mode 100644 docs/features/software-catalog/installation.md create mode 100644 docs/features/software-templates/configuration.md delete mode 100644 docs/features/software-templates/installation.md diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index 70541b85db..2189b7d799 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -34,9 +34,8 @@ More specifically, the Service Catalog enables two main use-cases: ## Getting Started The Software Catalog is available to browse at `/catalog`. If you've followed -[Installing in your Backstage App](./installation.md) in your separate App or -[Getting Started with Backstage](../../getting-started) for this repo, you -should be able to browse the catalog at `http://localhost:3000`. +[Getting Started with Backstage](../../getting-started), you should be able to +browse the catalog at `http://localhost:3000`. ![](../../assets/software-catalog/service-catalog-home.png) diff --git a/docs/features/software-catalog/installation.md b/docs/features/software-catalog/installation.md deleted file mode 100644 index 0b622fb093..0000000000 --- a/docs/features/software-catalog/installation.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -id: installation -title: Installing in your Backstage App -description: Documentation on How to install Backstage Plugin ---- - -The catalog plugin comes in two packages, `@backstage/plugin-catalog` and -`@backstage/plugin-catalog-backend`. Each has their own installation steps, -outlined below. - -## Installing @backstage/plugin-catalog - -> **Note that if you used `npx @backstage/create-app`, the plugin is already -> installed and you can skip to -> [adding entries to the catalog](#adding-entries-to-the-catalog)** - -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 -``` - -### Adding the Plugin to your `packages/app` - -Add the two pages that the catalog plugin provides to your app. You can choose -any name for these routes, but we recommend the following: - -```tsx -// packages/app/src/App.tsx -import { - catalogPlugin, - CatalogIndexPage, - CatalogEntityPage, -} from '@backstage/plugin-catalog'; - -// Add to the top-level routes, directly within -} /> -}> - {/* - This is the root of the custom entity pages for your app, refer to the example app - in the main repo or the output of @backstage/create-app for an example - */} - - -``` - -The catalog plugin also has one external route that needs to be bound for it to -function: the `createComponent` route which should link to the page where the -user can create components. In a typical setup the create component route will -be linked to the Scaffolder plugin's template index page: - -```ts -// packages/app/src/App.tsx -import { catalogPlugin } from '@backstage/plugin-catalog'; -import { scaffolderPlugin } from '@backstage/plugin-scaffolder'; - -const app = createApp({ - // ... - bindRoutes({ bind }) { - bind(catalogPlugin.externalRoutes, { - createComponent: scaffolderPlugin.routes.root, - }); - }, -}); -``` - -You may also want to add a link to the catalog index page to your sidebar: - -```tsx -// packages/app/src/components/Root.tsx -import HomeIcon from '@material-ui/icons/Home'; - -// Somewhere within the -; -``` - -This is all that is needed for the frontend part of the Catalog plugin to work! - -## Gotchas that we will fix - -Since the catalog plugin currently ships with a sentry plugin `InfoCard` -installed by default, you'll need to set `sentry.organization` in your -`app-config.yaml`. For example: - -```yaml -sentry: - organization: Acme Corporation -``` - -If you've created an app with an older version of `@backstage/create-app` or -`@backstage/cli create-app`, be sure to remove the Welcome plugin from the app, -as that will conflict with the catalog routes. - -## Installing @backstage/plugin-catalog-backend - -> **Note that if you used `npx @backstage/create-app`, the plugin is already -> installed and you can skip to -> [adding entries to the catalog](#adding-entries-to-the-catalog)** - -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 -``` - -### Adding the Plugin to your `packages/backend` - -You'll need to add the plugin to the `backend`'s router. You can do this by -creating a file called `packages/backend/src/plugins/catalog.ts` with contents -matching -[catalog.ts in the create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts). - -Once the `catalog.ts` router setup file is in place, add the router to -`packages/backend/src/index.ts`: - -```ts -import catalog from './plugins/catalog'; - -const catalogEnv = useHotMemoize(module, () => createEnv('catalog')); - -const apiRouter = Router(); -/** several different routers */ -apiRouter.use('/catalog', await catalog(catalogEnv)); -``` - -### Adding Entries to the Catalog - -At this point the catalog backend is installed in your backend package, but you -will not have any entities loaded. - -To get up and running and try out some templates quickly, you can add some of -our example templates through static configuration. Add the following to the -`catalog.locations` section in your `app-config.yaml`: - -```yaml -catalog: - locations: - # Backstage Example Components - - type: url - target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/playback-order-component.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/podcast-api-component.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/queue-proxy-component.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/searcher-component.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/playback-lib-component.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/www-artist-component.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/shuffle-api-component.yaml -``` - -### Running the Backend - -Finally, start up Backstage with the new configuration: - -```bash -# Run from the root to start both backend and frontend -yarn dev - -# Alternatively, run only the backend from its own package -cd packages/backend -yarn start -``` - -If you've also set up the frontend plugin, you should be ready to go browse the -catalog at [localhost:3000](http://localhost:3000) now! diff --git a/docs/features/software-templates/configuration.md b/docs/features/software-templates/configuration.md new file mode 100644 index 0000000000..cdd8166889 --- /dev/null +++ b/docs/features/software-templates/configuration.md @@ -0,0 +1,52 @@ +--- +id: configuration +title: Software Template Configuration +sidebar_label: Configuration +description: Configuration options for Backstage Software Templates +--- + +Backstage software templates create source code, so your Backstage application +needs to be set up to allow repository creation. + +This is done in your `app-config.yaml` by adding +[Backstage integrations](https://backstage.io/docs/integrations/) for the +appropriate source code repository for your organization. + +> Note: Integrations may already be set up as part of your `app-config.yaml`. + +The next step is to add +[add templates](http://backstage.io/docs/features/software-templates/adding-templates) +to your Backstage app. + +### GitHub + +For GitHub, you can configure who can see the new repositories that are created +by specifying `visibility` option. Valid options are `public`, `private` and +`internal`. The `internal` option is for GitHub Enterprise clients, which means +public within the enterprise. + +```yaml +scaffolder: + github: + visibility: public # or 'internal' or 'private' +``` + +### Disabling Docker in Docker situation (Optional) + +Software Templates use +[Cookiecutter](https://github.com/cookiecutter/cookiecutter) as a templating +library. By default it will use the +[scaffolder-backend/Cookiecutter](https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/scripts/Cookiecutter.dockerfile) +docker image. + +If you are running Backstage from a Docker container and you want to avoid +calling a container inside a container, you can set up Cookiecutter in your own +image, this will use the local installation instead. + +You can do so by including the following lines in the last step of your +`Dockerfile`: + +```Dockerfile +RUN apt-get update && apt-get install -y python3 python3-pip +RUN pip3 install cookiecutter +``` diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index 12ce6e3ed3..1434d62a29 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -17,10 +17,8 @@ locations like GitHub or GitLab. ### Getting Started -> Be sure to have covered [Installing in your Backstage App](./installation.md) -> for your separate App or -> [Getting Started with Backstage](../../getting-started) for this repo before -> proceeding. +> Be sure to have covered +> [Getting Started with Backstage](../../getting-started) before proceeding. The Software Templates are available under `/create`. For local development you should be able to reach them at `http://localhost:3000/create`. diff --git a/docs/features/software-templates/installation.md b/docs/features/software-templates/installation.md deleted file mode 100644 index d5643ca955..0000000000 --- a/docs/features/software-templates/installation.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -id: installation -title: Installing in your Backstage App -description: Documentation on How to install Backstage App ---- - -The scaffolder plugin comes in two packages, `@backstage/plugin-scaffolder` and -`@backstage/plugin-scaffolder-backend`. Each has their own installation steps, -outlined below. - -The Scaffolder plugin also depends on the Software Catalog. Instructions for how -to set that up can be found [here](../software-catalog/installation.md). - -## Installing @backstage/plugin-scaffolder - -> **Note that if you used `npx @backstage/create-app`, the plugin may already be -> present** - -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 -``` - -### Adding the Plugin to your `packages/app` - -Add the root page that the Scaffolder plugin provides to your app. You can -choose any path for the route, but we recommend the following: - -```tsx -import { ScaffolderPage } from '@backstage/plugin-scaffolder'; - -// Add to the top-level routes, directly within -} />; -``` - -You may also want to add a link to the template index page to your sidebar: - -```tsx -import CreateComponentIcon from '@material-ui/icons/AddCircleOutline'; - -// Somewhere within the -; -``` - -This is all that is needed for the frontend part of the Scaffolder plugin to -work! - -## Installing @backstage/plugin-scaffolder-backend - -> **Note that if you used `npx @backstage/create-app`, the plugin may already be -> present** - -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 -``` - -### Adding the Plugin to your `packages/backend` - -You'll need to add the plugin to the `backend`'s router. You can do this by -creating a file called `packages/backend/src/plugins/scaffolder.ts` with the -following contents to get you up and running quickly. - -```ts -import { - DockerContainerRunner, - SingleHostDiscovery, -} from '@backstage/backend-common'; -import { - CookieCutter, - createRouter, - Preparers, - Publishers, - CreateReactAppTemplater, - Templaters, -} from '@backstage/plugin-scaffolder-backend'; -import type { PluginEnvironment } from '../types'; -import Docker from 'dockerode'; -import { CatalogClient } from '@backstage/catalog-client'; - -export default async function createPlugin({ - logger, - config, - database, - reader, -}: PluginEnvironment) { - const dockerClient = new Docker(); - const containerRunner = new DockerContainerRunner({ dockerClient }); - - const cookiecutterTemplater = new CookieCutter({ containerRunner }); - const craTemplater = new CreateReactAppTemplater({ containerRunner }); - const templaters = new Templaters(); - - templaters.register('cookiecutter', cookiecutterTemplater); - templaters.register('cra', craTemplater); - - const preparers = await Preparers.fromConfig(config, { logger }); - const publishers = await Publishers.fromConfig(config, { logger }); - - const discovery = SingleHostDiscovery.fromConfig(config); - const catalogClient = new CatalogClient({ discoveryApi: discovery }); - - return await createRouter({ - preparers, - templaters, - publishers, - logger, - config, - database, - catalogClient, - reader, - }); -} -``` - -Once the `scaffolder.ts` router setup file is in place, add the router to -`packages/backend/src/index.ts`: - -```ts -import scaffolder from './plugins/scaffolder'; - -const scaffolderEnv = useHotMemoize(module, () => createEnv('scaffolder')); - -const apiRouter = Router(); -/* several router .use calls */ - -/* add this line */ -apiRouter.use('/scaffolder', await scaffolder(scaffolderEnv)); -``` - -### Adding Templates - -At this point the scaffolder backend is installed in your backend package, but -you will not have any templates available to use. These need to be added to the -software catalog, as they are represented as entities of kind -[Template](../software-catalog/descriptor-format.md#kind-template). You can find -out more about adding templates [here](./adding-templates.md). - -To get up and running and try out some templates quickly, you can add some of -our example templates through static configuration. Add the following to the -`catalog.locations` section in your `app-config.yaml`: - -```yaml -catalog: - locations: - # Backstage Example Templates - - type: url - target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/react-ssr-template/template.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml - - type: url - target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/create-react-app/template.yaml - - type: url - target: https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml -``` - -### Runtime Dependencies / Configuration - -For the scaffolder backend plugin to function, you'll need to setup the -integrations config in your `app-config.yaml`. - -You can find help for different providers below. - -> Note: Some of this configuration may already be set up as part of your -> `app-config.yaml`. We're moving away from the duplicated config for -> authentication in the `scaffolder` section and using `integrations` instead. - -#### GitHub - -The GitHub access token is retrieved from environment variables via the config. -The config file needs to specify what environment variable the token is -retrieved from. Your config should have the following objects. - -You can configure who can see the new repositories that the scaffolder creates -by specifying `visibility` option. Valid options are `public`, `private` and -`internal`. The `internal` option is for GitHub Enterprise clients, which means -public within the enterprise. - -```yaml -integrations: - github: - - host: github.com - token: ${GITHUB_TOKEN} - -scaffolder: - github: - visibility: public # or 'internal' or 'private' -``` - -#### GitLab - -For GitLab, we currently support the configuration of the GitLab publisher and -allows to configure the private access token and the base URL of a GitLab -instance: - -```yaml -integrations: - gitlab: - - host: gitlab.com - token: ${GITLAB_TOKEN} -``` - -#### Bitbucket - -For Bitbucket there are two authentication methods supported. Either `token` or -a combination of `appPassword` and `username`. It looks like either of the -following: - -```yaml -integrations: - bitbucket: - - host: bitbucket.org - token: ${BITBUCKET_TOKEN} -``` - -or - -```yaml -integrations: - bitbucket: - - host: bitbucket.org - appPassword: ${BITBUCKET_APP_PASSWORD} - username: ${BITBUCKET_USERNAME} -``` - -#### Azure DevOps - -For Azure DevOps we support both the preparer and publisher stage with the -configuration of a private access token (PAT). For the publisher it's also -required to define the base URL for the client to connect to the service. This -will hopefully support on-prem installations as well but that has not been -verified. - -```yaml -integrations: - azure: - - host: dev.azure.com - token: ${AZURE_TOKEN} -``` - -### Running the Backend - -Finally, make sure you have a local Docker daemon running, and start up the -backend with the new configuration: - -```bash -cd packages/backend -GITHUB_TOKEN= yarn start -``` - -If you've also set up the frontend plugin, so you should be ready to go browse -the templates at [localhost:3000/create](http://localhost:3000/create) now! - -### Disabling Docker in Docker situation (Optional) - -Software Templates use -[Cookiecutter](https://github.com/cookiecutter/cookiecutter) as templating -library. By default it will use the -[spotify/backstage-cookiecutter](https://github.com/backstage/backstage/blob/37e35b910afc7d1270855aed0ec4718aba366c91/plugins/scaffolder-backend/scripts/Cookiecutter.dockerfile) -docker image. - -If you are running Backstage from a Docker container and you want to avoid -calling a container inside a container, you can set up Cookiecutter in your own -image, this will use the local installation instead. - -You can do so by including the following lines in the last step of your -`Dockerfile`: - -```Dockerfile -RUN apt-get update && apt-get install -y python3 python3-pip -RUN pip3 install cookiecutter -``` diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index b9340330a8..3fdc942ac4 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -28,10 +28,10 @@ scratch. ### Use the documentation template Your working Backstage instance should by default have a documentation template -added. If not, follow these -[instructions](../software-templates/installation.md#adding-templates) to add -the documentation template. The template creates a component with only TechDocs -configuration and default markdown files as below mentioned in manual +added. If not, copy the catalog locations from the +[create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs) +to add the documentation template. The template creates a component with only +TechDocs configuration and default markdown files as below mentioned in manual documentation setup, and is otherwise empty. ![Documentation Template](../../assets/techdocs/documentation-template.png) diff --git a/docs/plugins/github-apps.md b/docs/plugins/github-apps.md index 87d23b45d5..b7ad60b12f 100644 --- a/docs/plugins/github-apps.md +++ b/docs/plugins/github-apps.md @@ -84,3 +84,12 @@ integrations: apps: - $include: example-backstage-app-credentials.yaml ``` + +### Permissions for pull requests + +These are the minimum permissions required for creating a pull request with +Backstage software templates: + +- Read and Write permissions for `Contents`. +- Read and write permissions for `Pull Requests` and `Issues`. +- Read permissions on `Metadata`. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index f2ce425307..6caf14e854 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -33,7 +33,6 @@ "label": "Software Catalog", "ids": [ "features/software-catalog/software-catalog-overview", - "features/software-catalog/installation", "features/software-catalog/configuration", "features/software-catalog/system-model", "features/software-catalog/descriptor-format", @@ -62,7 +61,7 @@ "label": "Software Templates", "ids": [ "features/software-templates/software-templates-index", - "features/software-templates/installation", + "features/software-templates/configuration", "features/software-templates/adding-templates", "features/software-templates/writing-templates", "features/software-templates/builtin-actions", diff --git a/mkdocs.yml b/mkdocs.yml index 67b97b6ffb..c62824d39e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,7 +30,6 @@ nav: - Core Features: - Software Catalog: - Overview: 'features/software-catalog/index.md' - - Installing in your Backstage App: 'features/software-catalog/installation.md' - Catalog Configuration: 'features/software-catalog/configuration.md' - System Model: 'features/software-catalog/system-model.md' - YAML File Format: 'features/software-catalog/descriptor-format.md' @@ -49,7 +48,7 @@ nav: - Troubleshooting: 'features/kubernetes/troubleshooting.md' - Software Templates: - Overview: 'features/software-templates/index.md' - - Installing in your Backstage App: 'features/software-templates/installation.md' + - Configuration: 'features/software-templates/configuration.md' - Adding your own Templates: 'features/software-templates/adding-templates.md' - Writing Templates: 'features/software-templates/writing-templates.md' - Builtin Actions: 'features/software-templates/builtin-actions.md' diff --git a/plugins/catalog-backend/README.md b/plugins/catalog-backend/README.md index 2f06b9c062..ce97bb7a54 100644 --- a/plugins/catalog-backend/README.md +++ b/plugins/catalog-backend/README.md @@ -1,21 +1,80 @@ # Catalog Backend -This is the backend part of the default catalog plugin. +This is the backend for the default Backstage [software +catalog](http://backstage.io/docs/features/software-catalog/software-catalog-overview). +This provides an API for consumers such as the frontend [catalog +plugin](https://github.com/backstage/backstage/tree/master/plugins/catalog). -It comes with a builtin database backed implementation of the catalog, that can store -and serve your catalog for you. +It comes with a builtin database-backed implementation of the catalog that can +store and serve your catalog for you. -It can also act as a bridge to your existing catalog solutions, either ingesting their -data to store in the database, or by effectively proxying calls to an external catalog -service. +It can also act as a bridge to your existing catalog solutions, either ingesting +data to store in the database, or by effectively proxying calls to an +external catalog service. -## Getting Started +## Installation -This backend plugin can be started in a standalone mode from directly in this package -with `yarn start`. However, it will have limited functionality and that process is -most convenient when developing the catalog backend plugin itself. +This `@backstage/plugin-catalog-backend` package comes installed by default in +any Backstage application created with `npx @backstage/create-app`, so +installation is not usually required. -To evaluate the catalog and have a greater amount of functionality available, instead do +To check if you already have the package, look under +`packages/backend/package.json`, in the `dependencies` block, for +`@backstage/plugin-catalog-backend`. The instructions below walk through +restoring the plugin, if you previously removed it. + +### Install the package + +```bash +# From your Backstage root directory +cd packages/backend +yarn add @backstage/plugin-catalog-backend +``` + +### Adding the plugin to your `packages/backend` + +You'll need to add the plugin to the router in your `backend` package. You can +do this by creating a file called `packages/backend/src/plugins/catalog.ts` with +contents matching [catalog.ts in the create-app +template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts). + +With the `catalog.ts` router setup in place, add the router to +`packages/backend/src/index.ts`: + +```diff ++import catalog from './plugins/catalog'; + +async function main() { + ... + const createEnv = makeCreateEnv(config); + ++ const catalogEnv = useHotMemoize(module, () => createEnv('catalog')); + const scaffolderEnv = useHotMemoize(module, () => createEnv('scaffolder')); + + const apiRouter = Router(); ++ apiRouter.use('/catalog', await catalog(catalogEnv)); + ... + apiRouter.use(notFoundHandler()); + +``` + +### Adding catalog entities + +At this point the `catalog-backend` is installed in your backend package, but +you will not have any catalog entities loaded. See [Catalog +Configuration](https://backstage.io/docs/features/software-catalog/configuration) +for how to add locations, or copy the catalog locations from the [create-app +template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs) +to get up and running quickly. + +## Development + +This backend plugin can be started in a standalone mode from directly in this +package with `yarn start`. However, it will have limited functionality and that +process is most convenient when developing the catalog backend plugin itself. + +To evaluate the catalog and have a greater amount of functionality available, +run the entire Backstage example application from the root folder: ```bash # in one terminal window, run this from from the very root of the Backstage project @@ -23,9 +82,10 @@ cd packages/backend yarn start ``` -This will launch the full example backend, populated some example entities. +This will launch both frontend and backend in the same window, populated with +some example entities. ## Links -- [Frontend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/catalog) -- [The Backstage homepage](https://backstage.io) +- [catalog](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend) + is the frontend interface for this plugin. diff --git a/plugins/catalog/README.md b/plugins/catalog/README.md index 611d2989e8..8527c8da7c 100644 --- a/plugins/catalog/README.md +++ b/plugins/catalog/README.md @@ -1,26 +1,107 @@ # Backstage Catalog Frontend -This is the frontend part of the default catalog plugin. +This is the React frontend for the default Backstage [software +catalog](http://backstage.io/docs/features/software-catalog/software-catalog-overview). +This package supplies interfaces related to listing catalog entities or showing +more information about them on entity pages. -It will implement the core API for handling your catalog of software, and -supply the base views to show and manage them. +## Installation -## Getting Started +This `@backstage/plugin-catalog` package comes installed by default in any +Backstage application created with `npx @backstage/create-app`, so installation +is not usually required. -This frontend plugin can be started in a standalone mode from directly in this package -with `yarn start`. However, it will have limited functionality and that process is -most convenient when developing the catalog frontend plugin itself. +To check if you already have the package, look under +`packages/app/package.json`, in the `dependencies` block, for +`@backstage/plugin-catalog`. The instructions below walk through restoring the +plugin, if you previously removed it. -To evaluate the catalog and have a greater amount of functionality available, from the main -Backstage root folder, instead do: +### Install the package + +```bash +# From your Backstage root directory +cd packages/app +yarn add @backstage/plugin-catalog +``` + +### Add the plugin to your `packages/app` + +Add the two pages that the catalog plugin provides to your app. You can choose +any name for these routes, but we recommend the following: + +```diff +// packages/app/src/App.tsx +import { + CatalogIndexPage, + CatalogEntityPage, +} from '@backstage/plugin-catalog'; +import { entityPage } from './components/catalog/EntityPage'; + + ++ } /> ++ }> ++ {/* ++ This is the root of the custom entity pages for your app, refer to the example app ++ in the main repo or the output of @backstage/create-app for an example ++ */} ++ {entityPage} ++ + ... + +``` + +The catalog plugin also has one external route that needs to be bound for it to +function: the `createComponent` route which should link to the page where the +user can create components. In a typical setup the create component route will +be linked to the scaffolder plugin's template index page: + +```diff +// packages/app/src/App.tsx ++import { catalogPlugin } from '@backstage/plugin-catalog'; ++import { scaffolderPlugin } from '@backstage/plugin-scaffolder'; + +const app = createApp({ + // ... + bindRoutes({ bind }) { ++ bind(catalogPlugin.externalRoutes, { ++ createComponent: scaffolderPlugin.routes.root, ++ }); + }, +}); +``` + +You may also want to add a link to the catalog index page to your application +sidebar: + +```diff +// packages/app/src/components/Root/Root.tsx ++import HomeIcon from '@material-ui/icons/Home'; + +export const Root = ({ children }: PropsWithChildren<{}>) => ( + + ++ + ... + +``` + +## Development + +This frontend plugin can be started in a standalone mode from directly in this +package with `yarn start`. However, it will have limited functionality and that +process is most convenient when developing the catalog frontend plugin itself. + +To evaluate the catalog and have a greater amount of functionality available, +run the entire Backstage example application from the root folder: ```bash yarn dev ``` -This will launch both frontend and backend in the same window, populated with some example entities. +This will launch both frontend and backend in the same window, populated with +some example entities. ## Links -- [Backend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend) -- [The Backstage homepage](https://backstage.io) +- [catalog-backend](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend) + provides the backend API for this frontend. diff --git a/plugins/scaffolder-backend/README.md b/plugins/scaffolder-backend/README.md index 304d43a750..7efe33f7f6 100644 --- a/plugins/scaffolder-backend/README.md +++ b/plugins/scaffolder-backend/README.md @@ -1,25 +1,64 @@ # Scaffolder Backend -Welcome to the scaffolder plugin! +This is the backend for the default Backstage [software +templates](https://backstage.io/docs/features/software-templates/software-templates-index). +This provides the API for the frontend [scaffolder +plugin](https://github.com/backstage/backstage/tree/master/plugins/scaffolder), +as well as the built-in template actions, tasks and stages. -## Jobs +## Installation -Documentation for `Jobs` here +This `@backstage/plugin-scaffolder-backend` package comes installed by default +in any Backstage application created with `npx @backstage/create-app`, so +installation is not usually required. -## Stages +To check if you already have the package, look under +`packages/backend/package.json`, in the `dependencies` block, for +`@backstage/plugin-scaffolder-backend`. The instructions below walk through +restoring the plugin, if you previously removed it. -Documentation for `Stages` here +### Install the package -## Tasks +```bash +# From your Backstage root directory +cd packages/backend +yarn add @backstage/plugin-scaffolder-backend +``` -Documentation for `Tasks` here +### Adding the plugin to your `packages/backend` -## Actions +You'll need to add the plugin to the router in your `backend` package. You can +do this by creating a file called `packages/backend/src/plugins/scaffolder.ts` +with contents matching [scaffolder.ts in the create-app +template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/scaffolder.ts). -### Built-in: +With the `scaffolder.ts` router setup in place, add the router to +`packages/backend/src/index.ts`: -- #### GitHub Pull Request - - Minimum permissions required for GitHub App for creating a Pull Request with the built-in action: - - Read and Write permissions for `Contents`. - - Read and write permissions for `Pull Requests` and `Issues`. - - Read permissions on `Metadata`. +```diff ++import scaffolder from './plugins/scaffolder'; + +async function main() { + ... + const createEnv = makeCreateEnv(config); + + const catalogEnv = useHotMemoize(module, () => createEnv('catalog')); ++ const scaffolderEnv = useHotMemoize(module, () => createEnv('scaffolder')); + + const apiRouter = Router(); ++ apiRouter.use('/scaffolder', await scaffolder(scaffolderEnv)); + ... + apiRouter.use(notFoundHandler()); + +``` + +### Adding templates + +At this point the scaffolder backend is installed in your backend package, but +you will not have any templates available to use. These need to be [added to the +software +catalog](https://backstage.io/docs/features/software-templates/adding-templates). + +To get up and running and try out some templates quickly, you can or copy the +catalog locations from the [create-app +template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs). diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md index 05a68dafdd..0bfd2f8a35 100644 --- a/plugins/scaffolder/README.md +++ b/plugins/scaffolder/README.md @@ -1,10 +1,86 @@ # Scaffolder Frontend -WORK IN PROGRESS +This is the React frontend for the default Backstage [software +templates](https://backstage.io/docs/features/software-templates/software-templates-index). +This package supplies interfaces related to showing available templates in the +Backstage catalog and the workflow to create software using those templates. -This is the frontend part of the default scaffolder plugin. +## Installation + +This `@backstage/plugin-scaffolder` package comes installed by default in any +Backstage application created with `npx @backstage/create-app`, so installation +is not usually required. + +To check if you already have the package, look under +`packages/app/package.json`, in the `dependencies` block, for +`@backstage/plugin-scaffolder`. The instructions below walk through restoring +the plugin, if you previously removed it. + +### Install the package + +```bash +# From your Backstage root directory +cd packages/app +yarn add @backstage/plugin-scaffolder +``` + +### Add the plugin to your `packages/app` + +Add the root page that the scaffolder plugin provides to your app. You can +choose any path for the route, but we recommend the following: + +```diff +// packages/app/src/App.tsx ++import { ScaffolderPage } from '@backstage/plugin-scaffolder'; + + + + } /> + }> + {entityPage} + ++ } />; + ... + +``` + +The scaffolder plugin also has one external route that needs to be bound for it +to function: the `registerComponent` route which should link to the page where +the user can register existing software component. In a typical setup, the +register component route will be linked to the `catalog-import` plugin's import +page: + +```diff +// packages/app/src/App.tsx ++import { scaffolderPlugin } from '@backstage/plugin-scaffolder'; ++import { catalogImportPlugin } from '@backstage/plugin-catalog-import'; + +const app = createApp({ + // ... + bindRoutes({ bind }) { ++ bind(scaffolderPlugin.externalRoutes, { ++ registerComponent: catalogImportPlugin.routes.importPage, ++ }); + }, +}); +``` + +You may also want to add a link to the scaffolder page to your application +sidebar: + +```diff +// packages/app/src/components/Root/Root.tsx ++import CreateComponentIcon from '@material-ui/icons/AddCircleOutline'; + +export const Root = ({ children }: PropsWithChildren<{}>) => ( + + ++ ; + ... + +``` ## Links -- [Backend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend) -- [The Backstage homepage](https://backstage.io) +- [scaffolder-backend](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend) + provides the backend API for this frontend. From 71416fb64ebcd76772d40081890464f4b4754a40 Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Wed, 16 Jun 2021 11:29:04 -0600 Subject: [PATCH 2/2] changeset Signed-off-by: Tim Hansen --- .changeset/popular-rice-wonder.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 .changeset/popular-rice-wonder.md diff --git a/.changeset/popular-rice-wonder.md b/.changeset/popular-rice-wonder.md new file mode 100644 index 0000000000..f815ad949a --- /dev/null +++ b/.changeset/popular-rice-wonder.md @@ -0,0 +1,8 @@ +--- +'@backstage/plugin-catalog': patch +'@backstage/plugin-catalog-backend': patch +'@backstage/plugin-scaffolder': patch +'@backstage/plugin-scaffolder-backend': patch +--- + +Moved installation instructions from the main [backstage.io](https://backstage.io) documentation to the package README file. These instructions are not generally needed, since the plugin comes installed by default with `npx @backstage/create-app`.