Merge pull request #6049 from backstage/timbonicus/move-installation

Move `catalog` and `scaffolder` installation instructions to READMEs
2021-06-17 15:14:07 +02:00
parent 0a825e3745 71416fb64e
commit ffe7759de8
14 changed files with 379 additions and 516 deletions
@@ -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).