Move installation instructions to READMEs
Signed-off-by: Tim Hansen <timbonicus@gmail.com>
This commit is contained in:
Tim Hansen
@@ -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`.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -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 <FlatRoutes>
|
||||
<Route path="/catalog" element={<CatalogIndexPage />} />
|
||||
<Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />}>
|
||||
{/*
|
||||
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 />
|
||||
</Route>
|
||||
```
|
||||
|
||||
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 <Sidebar>
|
||||
<SidebarItem icon={HomeIcon} to="/catalog" text="Home" />;
|
||||
```
|
||||
|
||||
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!
|
||||
@@ -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
|
||||
```
|
||||
@@ -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`.
|
||||
|
||||
@@ -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 <FlatRoutes>
|
||||
<Route path="/create" element={<ScaffolderPage />} />;
|
||||
```
|
||||
|
||||
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 <Sidebar>
|
||||
<SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />;
|
||||
```
|
||||
|
||||
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=<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
|
||||
```
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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",
|
||||
|
||||
+1
-2
@@ -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'
|
||||
|
||||
@@ -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.
|
||||
|
||||
+93
-12
@@ -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';
|
||||
|
||||
<FlatRoutes>
|
||||
+ <Route path="/catalog" element={<CatalogIndexPage />} />
|
||||
+ <Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />}>
|
||||
+ {/*
|
||||
+ 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}
|
||||
+ </Route>
|
||||
...
|
||||
</FlatRoutes>
|
||||
```
|
||||
|
||||
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<{}>) => (
|
||||
<SidebarPage>
|
||||
<Sidebar>
|
||||
+ <SidebarItem icon={HomeIcon} to="/catalog" text="Home" />
|
||||
...
|
||||
</Sidebar>
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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';
|
||||
|
||||
|
||||
<FlatRoutes>
|
||||
<Route path="/catalog" element={<CatalogIndexPage />} />
|
||||
<Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />}>
|
||||
{entityPage}
|
||||
</Route>
|
||||
+ <Route path="/create" element={<ScaffolderPage />} />;
|
||||
...
|
||||
</FlatRoutes>
|
||||
```
|
||||
|
||||
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<{}>) => (
|
||||
<SidebarPage>
|
||||
<Sidebar>
|
||||
+ <SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />;
|
||||
...
|
||||
</Sidebar>
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user