diff --git a/docs/assets/software-templates/added-to-the-catalog-list.png b/docs/assets/software-templates/added-to-the-catalog-list.png deleted file mode 100644 index c73c33ede3..0000000000 Binary files a/docs/assets/software-templates/added-to-the-catalog-list.png and /dev/null differ diff --git a/docs/assets/software-templates/complete.png b/docs/assets/software-templates/complete.png index 2a8de0ba1e..d63ddf982c 100644 Binary files a/docs/assets/software-templates/complete.png and b/docs/assets/software-templates/complete.png differ diff --git a/docs/assets/software-templates/create.png b/docs/assets/software-templates/create.png index 8123780cd3..ab9aaa484b 100644 Binary files a/docs/assets/software-templates/create.png and b/docs/assets/software-templates/create.png differ diff --git a/docs/assets/software-templates/disable-register-existing-component-button.png b/docs/assets/software-templates/disable-register-existing-component-button.png deleted file mode 100644 index 5ef8051ec7..0000000000 Binary files a/docs/assets/software-templates/disable-register-existing-component-button.png and /dev/null differ diff --git a/docs/assets/software-templates/failed.png b/docs/assets/software-templates/failed.png index 4cb7ce84cc..c8063ed05d 100644 Binary files a/docs/assets/software-templates/failed.png and b/docs/assets/software-templates/failed.png differ diff --git a/docs/assets/software-templates/go-to-catalog.png b/docs/assets/software-templates/go-to-catalog.png deleted file mode 100644 index ea03295846..0000000000 Binary files a/docs/assets/software-templates/go-to-catalog.png and /dev/null differ diff --git a/docs/assets/software-templates/review.png b/docs/assets/software-templates/review.png new file mode 100644 index 0000000000..2ce32f8100 Binary files /dev/null and b/docs/assets/software-templates/review.png differ diff --git a/docs/assets/software-templates/running.png b/docs/assets/software-templates/running.png index 681c3702f7..8c18f76c2b 100644 Binary files a/docs/assets/software-templates/running.png and b/docs/assets/software-templates/running.png differ diff --git a/docs/assets/software-templates/template-picked-2.png b/docs/assets/software-templates/template-picked-2.png index a1737c8e00..3c9c6d27ed 100644 Binary files a/docs/assets/software-templates/template-picked-2.png and b/docs/assets/software-templates/template-picked-2.png differ diff --git a/docs/assets/software-templates/template-picked.png b/docs/assets/software-templates/template-picked.png index 79b1e260e0..65f4809682 100644 Binary files a/docs/assets/software-templates/template-picked.png and b/docs/assets/software-templates/template-picked.png differ diff --git a/docs/assets/software-templates/template-start-over.png b/docs/assets/software-templates/template-start-over.png index 67d9caff34..bceedd30c8 100644 Binary files a/docs/assets/software-templates/template-start-over.png and b/docs/assets/software-templates/template-start-over.png differ diff --git a/docs/assets/software-templates/template-task-list.png b/docs/assets/software-templates/template-task-list.png index dc2bbfa310..8863af9edb 100644 Binary files a/docs/assets/software-templates/template-task-list.png and b/docs/assets/software-templates/template-task-list.png differ diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index b7f35f44c5..c880500ac4 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -17,9 +17,6 @@ locations like GitHub or GitLab. ## Getting Started -> Be sure to have covered -> [Getting Started with Backstage](../../getting-started) before proceeding. - :::note Note If you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to @@ -27,12 +24,17 @@ use the templates feature. One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage: `export NODE_OPTIONS="${NODE_OPTIONS:-} --no-node-snapshot"` -> It's important to append to the existing `NODE_OPTIONS` value, if it's already set, rather than overwriting it, since some NodeJS Debugging tools may rely on this environment variable to work properly. +It's important to append to the existing `NODE_OPTIONS` value, if it's already set, rather than overwriting it, since some NodeJS Debugging tools may rely on this environment variable to work properly. ::: -The Software Templates are available under `/create`. For local development you -should be able to reach them at `http://localhost:3000/create`. +These docs assume you have already gone over the [Backstage Getting Started](../../getting-started) section. + +## The Templates page + +Software Templates you have imported into Backstage can be found under `/create`. + +If you're running Backstage locally, this will be `http://localhost:3000/create`. Once there, you should see something that looks similar to this: @@ -47,25 +49,32 @@ internally. ![Enter some variables](../../assets/software-templates/template-picked.png) -After filling in these variables, you'll get some more fields to fill out which -are required for Backstage usage: the owner (which is a `user` in the backstage -system), and the `storePath` which is a destination URL to create for the -provider, for instance `https://github.com/backstage/my-new-repository`, or -`https://gitlab.com/myorg/myrepo`. +Templates generally consist of a set of steps, and each step can have its own set of required or optional inputs, as you can see in the image below we are now prompted to input some Github repository information. ![Enter Backstage vars](../../assets/software-templates/template-picked-2.png) -## Run! +## Review page -Once you've entered values and confirmed, you'll then get a popup box with live -progress of what is currently happening with the creation of your template. +Before you run the template, you'll be taken to a summary page where you can verify the inputs you have provided before we run the template. + +This is a good time to double check that you have provided the correct information and allows you to go back and change any of the inputs if you need to. + +![Review](../../assets/software-templates/review.png) + +## Run the template + +Once you are happy with the inputs you have provided, you can click on the `Create` button to run the template. ![Templating Running](../../assets/software-templates/running.png) -It shouldn't take too long, and you'll have a success screen! +## Success + +Once the template has finished running, you'll be taken to a success page where you can see the results of the template. ![Templating Complete](../../assets/software-templates/complete.png) +## Failure + If it fails, you'll be able to click on each section to get the log from the step that failed which can be helpful in debugging. @@ -75,23 +84,14 @@ only if it supports it. ![Templating failed](../../assets/software-templates/failed.png) -## View Component in Catalog +## View the Results -When it's been created, you'll see the `View in Catalog` button, which will take -you to the registered component in the catalog: - -![Catalog](../../assets/software-templates/go-to-catalog.png) - -And then you'll also be able to see it in the Catalog View table: - -![Catalog](../../assets/software-templates/added-to-the-catalog-list.png) +Once the template has finished running, and from the screenshot above, when its successful, you are presented with two links, clicking on them will take you to the templated repository we created! ## Disable Register Existing Component button There could be situations where you would like to disable the -`Register Existing Component` button for your users. For example: - -![Disable Button](../../assets/software-templates/disable-register-existing-component-button.png) +`Register Existing Component` button for your users. To do so, you need to explicitly disable the default route binding from the `scaffolderPlugin.registerComponent` to the Catalog Import page. @@ -120,12 +120,14 @@ app: After the change, you should no longer see the button. -## Previewing and Executing Previous Template Tasks +## Template Task List Each execution of a template is treated as a unique task, identifiable by its own unique ID. To view a list of previously executed template tasks, navigate to the "Create" page and access the "Task List" from the context menu (represented by the vertical ellipsis, or 'kebab menu', icon in the upper right corner). ![Template Task List](../../assets/software-templates/template-task-list.png) +## Starting Over + If you wish to re-run a previously executed template, navigate to the template tasks page. Locate the desired task and select the "Start Over" option from the context menu. ![Template Start Over](../../assets/software-templates/template-start-over.png) @@ -133,3 +135,7 @@ If you wish to re-run a previously executed template, navigate to the template t This action will initiate a new execution of the selected template, pre-populated with the same parameters as the previous run, but these parameters can be edited before re-execution. In the event of a failed template execution, the "Start Over" option can be used to re-execute the template. The parameters from the original run will be pre-filled, but they can be adjusted as needed before retrying the template. + +## Want to see it in action? + +The [Backstage Demo Site](https://demo.backstage.io/) has a template you are able to run, which is where the screenshots in this document were taken from!