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`.
|
||||
|
||||
Reference in New Issue
Block a user