paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 47 Packages Projects Releases Wiki Activity

Move installation instructions to READMEs

Browse Source 
Signed-off-by: Tim Hansen <timbonicus@gmail.com>
This commit is contained in:
Tim Hansen
2021-06-15 15:00:15 -06:00
parent e855326632
commit 785a42f802
13 changed files with 371 additions and 516 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/catalog-backend/README.md
+74 -14
View File
@@ -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.
plugins/catalog/README.md
+93 -12
View File
@@ -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.
plugins/scaffolder-backend/README.md
+53 -14
View File
@@ -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).
plugins/scaffolder/README.md
+80 -4
View File
@@ -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.