Merge branch 'master' into mobile-sidebar

Signed-off-by: Philipp Hugenroth <philipph@spotify.com>

docs/api/utility-apis.md

@@ -128,8 +128,8 @@ the core APIs. The core APIs are the ones exported by
 [configApiRef](../reference/core-plugin-api.configapiref.md).
 
 The core APIs are loaded for any app created with
-[createApp](../reference/core-app-api.createapp.md) from
-[@backstage/core-plugin-api](../reference/core-plugin-api.md), which means that
+[createApp](../reference/app-defaults.createapp.md) from
+[@backstage/core-plugin-api](../reference/app-defaults.md), which means that
 there is no step that needs to be taken to include these APIs in an app.
 
 ### Plugin APIs
@@ -168,7 +168,7 @@ Lastly, the app itself is the final point where APIs can be added, and what has
 the final say in what APIs will be loaded at runtime. The app may override the
 factories for any of the core or plugin APIs, with the exception of the config,
 app theme, and identity APIs. These are static APIs that are tied into the
-[createApp](../reference/core-app-api.createapp.md) implementation, and
+[createApp](../reference/app-defaults.createapp.md) implementation, and
 therefore not possible to override.
 
 Overriding APIs is useful for apps that want to switch out behavior to tailor it
@@ -313,7 +313,7 @@ The common development environment for plugins is included in
 [createDevApp](../reference/dev-utils.createdevapp.md) function creates an
 application with implementations for all core APIs already present. Contrary to
 the method for wiring up Utility API implementations in an app created with
-[createApp](../reference/core-app-api.createapp.md),
+[createApp](../reference/app-defaults.createapp.md),
 [createDevApp](../reference/dev-utils.createdevapp.md) uses automatic dependency
 injection. This is to make it possible to replace any API implementation, and
 having that be reflected in dependents of that API.

docs/architecture-decisions/adr000-template.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr000
-title: ADR000: [TITLE]
+title: 'ADR000: [TITLE]'
+# prettier-ignore
 description: Architecture Decision Record (ADR) for [TITLE] [DESCRIPTION]
 ---
 

docs/architecture-decisions/adr001-add-adr-log.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr001
-title: ADR001: Architecture Decision Record (ADR) log
+title: 'ADR001: Architecture Decision Record (ADR) log'
+# prettier-ignore
 description: Architecture Decision Record (ADR) logs as a reference point for the team
 ---
 

docs/architecture-decisions/adr002-default-catalog-file-format.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr002
-title: ADR002: Default Software Catalog File Format
+title: 'ADR002: Default Software Catalog File Format'
+# prettier-ignore
 description: Architecture Decision Record (ADR) log on Default Software Catalog File Format
 ---
 

docs/architecture-decisions/adr003-avoid-default-exports.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr003
-title: ADR003: Avoid Default Exports and Prefer Named Exports
+title: 'ADR003: Avoid Default Exports and Prefer Named Exports'
+# prettier-ignore
 description: Architecture Decision Record (ADR) log on Avoid Default Exports and Prefer Named Exports
 ---
 

docs/architecture-decisions/adr004-module-export-structure.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr004
-title: ADR004: Module Export Structure
+title: 'ADR004: Module Export Structure'
+# prettier-ignore
 description: Architecture Decision Record (ADR) log on Module Export Structure
 ---
 

docs/architecture-decisions/adr005-catalog-core-entities.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr005
-title: ADR005: Catalog Core Entities
+title: 'ADR005: Catalog Core Entities'
+# prettier-ignore
 description: Architecture Decision Record (ADR) log on Catalog Core Entities
 ---
 

docs/architecture-decisions/adr006-avoid-react-fc.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr006
-title: ADR006: Avoid React.FC and React.SFC
+title: 'ADR006: Avoid React.FC and React.SFC'
+# prettier-ignore
 description: Architecture Decision Record (ADR) log on Avoid React.FC and React.SFC
 ---
 

docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr007
-title: ADR007: Use MSW to mock http requests
+title: 'ADR007: Use MSW to mock http requests'
+# prettier-ignore
 description: Architecture Decision Record (ADR) log on Use MSW to mock http requests
 ---
 

docs/architecture-decisions/adr008-default-catalog-file-name.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr008
-title: ADR008: Default Catalog File Name
+title: 'ADR008: Default Catalog File Name'
+# prettier-ignore
 description: Architecture Decision Record (ADR) log on Default Catalog File Name
 ---
 

docs/architecture-decisions/adr009-entity-references.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr009
-title: ADR009: Entity References
+title: 'ADR009: Entity References'
+# prettier-ignore
 description: Architecture Decision Record (ADR) log on Entity References
 ---
 

docs/architecture-decisions/adr010-luxon-date-library.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr010
-title: ADR010: Use the Luxon Date Library
+title: 'ADR010: Use the Luxon Date Library'
+# prettier-ignore
 description: Architecture Decision Record (ADR) for Luxon Date Library
 ---
 

docs/architecture-decisions/adr011-plugin-package-structure.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr011
-title: ADR011: Plugin Package Structure
+title: 'ADR011: Plugin Package Structure'
+# prettier-ignore
 description: Architecture Decision Record (ADR) for Plugin Package Structure
 ---
 

docs/architecture-decisions/adr012-use-luxon-locale-and-date-presets.md

@@ -1,6 +1,7 @@
 ---
 id: adrs-adr012
-title: ADR012: Use Luxon.toLocaleString and date/time presets
+title: 'ADR012: Use Luxon.toLocaleString and date/time presets'
+# prettier-ignore
 description: Architecture Decision Record (ADR) for using Luxon's toLocaleString method and date/time presets for displaying dates and times
 ---
 

docs/architecture-decisions/adr013-use-node-fetch.md

@@ -0,0 +1,71 @@
+---
+id: adrs-adr013
+title: 'ADR013: Proper use of HTTP fetching libraries'
+# prettier-ignore
+description: Architecture Decision Record (ADR) for the proper use of fetchApiRef, node-fetch, and cross-fetch for data fetching.
+---
+
+## Context
+
+Using multiple HTTP packages for data fetching increases the complexity and the
+support burden of keeping said package up to date.
+
+## Decision
+
+Backend (node) packages should use the `node-fetch` package for HTTP data
+fetching. Example:
+
+```ts
+import fetch from 'node-fetch';
+import { ResponseError } from '@backstage/errors';
+
+const response = await fetch('https://example.com/api/v1/users.json');
+if (!response.ok) {
+  throw await ResponseError.fromResponse(response);
+}
+const users = await response.json();
+```
+
+Frontend plugins and packages should prefer to use the
+[`fetchApiRef`](https://backstage.io/docs/reference/core-plugin-api.fetchapiref).
+It uses `cross-fetch` internally. Example:
+
+```ts
+import { useApi } from '@backstage/core-plugin-api';
+const { fetch } = useApi(fetchApiRef);
+
+const response = await fetch('https://example.com/api/v1/users.json');
+if (!response.ok) {
+  throw await ResponseError.fromResponse(response);
+}
+const users = await response.json();
+```
+
+Isomorphic packages should have a dependency on the `cross-fetch` package for
+mocking and type definitions. Preferably, classes and functions in isomorphic
+packages should accept an argument of type `typeof fetch` to let callers supply
+their preferred implementation of `fetch`. This lets them adorn the calls with
+auth or other information, and track metrics etc, in a cross-platform way.
+Example:
+
+```ts
+import crossFetch from 'cross-fetch';
+
+export class MyClient {
+  private readonly fetch: typeof crossFetch;
+
+  constructor(options: { fetch?: typeof crossFetch }) {
+    this.fetch = options.fetch || crossFetch;
+  }
+
+  async users() {
+    return await this.fetch('https://example.com/api/v1/users.json');
+  }
+}
+```
+
+## Consequences
+
+We will gradually transition away from third party packages such as `axios`,
+`got` and others. Once we have transitioned to `node-fetch` we will add lint
+rules to enforce this decision.

docs/architecture-decisions/index.md

@@ -2,6 +2,7 @@
 id: adrs-overview
 title: Architecture Decision Records (ADR)
 sidebar_label: Overview
+# prettier-ignore
 description: Overview of Architecture Decision Records (ADR)
 ---
 

docs/auth/microsoft/provider.md

@@ -48,6 +48,6 @@ The Microsoft provider is a structure with three configuration keys:
 
 ## Adding the provider to the Backstage frontend
 
-To add the provider to the frontend, add the `microsoftAuthApi` reference and
+To add the provider to the frontend, add the `microsoftAuthApiRef` reference and
 `SignInPage` component as shown in
 [Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page).

docs/conf/writing.md

@@ -67,7 +67,7 @@ production build.
 
 ## Configuration Files
 
-It is possible to have multiple configuration files (bundled and/or remote),
+It is possible to have multiple configuration files (bundled and/or remote\*),
 both to support different environments, but also to define configuration that is
 local to specific packages. The configuration files to load are selected using a
 `--config <local-path|url>` flag, and it is possible to load any number of
@@ -77,6 +77,9 @@ root when running the backend, you would use `--config ../../my-config.yaml`,
 and for config file on a config server you would use
 `--config https://some.domain.io/app-config.yaml`
 
+**Note**: In case URLs are passed, it is also needed to set the remote option in
+the loadBackendConfig call.
+
 If no `config` flags are specified, the default behavior is to load
 `app-config.yaml` and, if it exists, `app-config.local.yaml` from the repo root.
 In the provided project setup, `app-config.local.yaml` is `.gitignore`'d, making

docs/features/kubernetes/configuration.md

@@ -264,6 +264,12 @@ following objects:
 - horizontalpodautoscalers
 - ingresses
 
+The following RBAC permissions are required on the batch API group for the
+following objects:
+
+- jobs
+- cronjobs
+
 ## Surfacing your Kubernetes components as part of an entity
 
 There are two ways to surface your Kubernetes components as part of an entity.

docs/features/software-templates/writing-custom-field-extensions.md

@@ -26,7 +26,7 @@ You can create your own Field Extension by using the
 `API` like below:
 
 ```tsx
-//packages/app/scaffolder/MyCustomExtension/MyCustomExtension.tsx
+//packages/app/src/scaffolder/MyCustomExtension/MyCustomExtension.tsx
 import React from 'react';
 import { FieldProps, FieldValidation } from '@rjsf/core';
 import FormControl from '@material-ui/core/FormControl';
@@ -68,7 +68,7 @@ export const myCustomValidation = (
 ```
 
 ```tsx
-// packages/app/scaffolder/MyCustomExtension/extensions.ts
+// packages/app/src/scaffolder/MyCustomExtension/extensions.ts
 
 /*
   This is where the magic happens and creates the custom field extension.
@@ -94,7 +94,7 @@ export const MyCustomFieldExtension = plugin.provide(
 ```
 
 ```tsx
-// packages/app/scaffolder/MyCustomExtension/index.ts
+// packages/app/src/scaffolder/MyCustomExtension/index.ts
 
 export { MyCustomFieldExtension } from './extension';
 ```
@@ -102,7 +102,7 @@ export { MyCustomFieldExtension } from './extension';
 Once all these files are in place, you then need to provide your custom
 extension to the `scaffolder` plugin.
 
-You do this in `packages/app/App.tsx`. You need to provide the
+You do this in `packages/app/src/App.tsx`. You need to provide the
 `customFieldExtensions` as children to the `ScaffolderPage`.
 
 ```tsx
@@ -118,7 +118,7 @@ const routes = (
 Should look something like this instead:
 
 ```tsx
-import { MyCustomFieldExtension } from './scafffolder/MyCustomExtension';
+import { MyCustomFieldExtension } from './scaffolder/MyCustomExtension';
 const routes = (
   <FlatRoutes>
     ...

docs/features/techdocs/configuring-ci-cd.md

@@ -10,7 +10,7 @@ TechDocs reads the static generated documentation files from a cloud storage
 bucket (GCS, AWS S3, etc.). The documentation site is generated on the CI/CD
 workflow associated with the repository containing the documentation files. This
 document explains the steps needed to generate docs on CI and publish to a cloud
-storage using [`techdocs-cli`](https://github.com/backstage/techdocs-cli).
+storage using [`techdocs-cli`](./cli.md).
 
 The steps here target all kinds of CI providers (GitHub Actions, CircleCI,
 Jenkins, etc.). Specific tools for individual providers will also be made
@@ -40,9 +40,8 @@ techdocs-cli publish --publisher-type awsS3 --storage-name <bucket/container> --
 
 That's it!
 
-Take a look at
-[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the
-complete command reference, details, and options.
+Take a look at [`techdocs-cli`](./cli.md) for the complete command reference,
+details, and options.
 
 ## Steps
 
@@ -74,7 +73,7 @@ Install [`npx`](https://www.npmjs.com/package/npx) to use it for running
 `techdocs-cli`. Or you can install using `npm install -g @techdocs/cli`.
 
 We are going to use the
-[`techdocs-cli generate`](https://github.com/backstage/techdocs-cli#generate-techdocs-site-from-a-documentation-project)
+[`techdocs-cli generate`](./cli.md#generate-techdocs-site-from-a-documentation-project)
 command in this step.
 
 ```sh
@@ -93,8 +92,7 @@ necessary authentication environment variables.
 - [AWS authentication](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html)
 
 And then run the
-[`techdocs-cli publish`](https://github.com/backstage/techdocs-cli#publish-generated-techdocs-sites)
-command.
+[`techdocs-cli publish`](./cli.md#publish-generated-techdocs-sites) command.
 
 ```sh
 npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <bucket/container> --entity <namespace/kind/name> --directory ./site

docs/features/techdocs/how-to-guides.md

@@ -421,3 +421,24 @@ folder (/docs) or replace the content in this file.
 > on how you have configured your `template.yaml`
 
 Done! You now have support for TechDocs in your own software template!
+
+## how to enable iframes in TechDocs
+
+Techdocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) to sanitizes
+HTML and prevents XSS attacks
+
+It's possible to allow some iframes based on a list of allowed hosts. To do
+this, add the allowed hosts in the `techdocs.sanitizer.allowedIframeHosts`
+configuration of your `app-config.yaml`
+
+E.g.
+
+```yaml
+techdocs:
+  sanitizer:
+    allowedIframeHosts:
+      - drive.google.com
+```
+
+This way, all iframes where the host of src attribute is in the
+`sanitizer.allowedIframeHosts` list will be displayed

docs/getting-started/app-custom-theme.md

@@ -54,7 +54,7 @@ For example, adding the theme that we created in the previous section can be
 done like this:
 
 ```ts
-import { createApp } from '@backstage/core-app-api';
+import { createApp } from '@backstage/app-defaults';
 
 const app = createApp({
   apis: ...,

docs/getting-started/configuration.md

@@ -0,0 +1,311 @@
+---
+id: configuration
+title: Getting Started, configuring Backstage
+description: Getting started with your initial Backstage configuration
+---
+
+This is part two of the Getting Started documentation of Backstage. The steps in
+this tutorial assume you've installed Backstage app from the npm repository,
+like in the [Getting Started guide](./index.md) and want to configure Backstage.
+
+At the end of this tutorial, you can expect:
+
+- Backstage to use a PostgreSQL database
+- You'll authenticate using one of the auth providers
+- The Backstage GitHub integration to be configured
+- You're able to use Software Templates
+
+### Prerequisites
+
+- Access to a Linux-based operating system, such as Linux, MacOS or
+  [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/)
+- An account with elevated rights to install prerequisites on your operating
+  system
+- If the database is not hosted on the same server as the Backstage app, the
+  PostgreSQL port needs to be accessible (the default is 5432 or 5433)
+
+### Install and configure PostgreSQL
+
+These instructions can be skipped if you already have a PostgreSQL server
+installed and created a schema and user. The example below is for Linux, but
+luckily there's detailed instructions on how to
+[install PostgreSQL](https://www.postgresql.org/download/) to help you get
+started.
+
+```shell
+sudo apt-get install postgresql
+```
+
+Test if your database is working:
+
+```shell
+sudo -u postgres psql
+```
+
+You should see a very welcoming message, like:
+
+```shell
+psql (12.9 (Ubuntu 12.9-0ubuntu0.20.04.1))
+Type "help" for help.
+
+postgres=#
+```
+
+For this tutorial we're going to use the existing postgres user. The next step
+is to set the password for this user:
+
+```shell
+postgres=# ALTER USER postgres PASSWORD 'secret';
+```
+
+That's enough database administration to get started. Type `\q`, followed by
+pressing the enter key. Then again type `exit` and press enter. Next, you need
+to install and configure the client.
+
+Stop Backstage, and go to the root directory of your freshly installed Backstage
+App. Use the following commands to start the PostgreSQL client installation:
+
+```shell
+# From your Backstage root directory
+cd packages/backend
+yarn add pg
+```
+
+Use your favorite editor to open `app-config.yaml` and add your PostgreSQL
+configuration. in the root directory of your Backstage app using the credentials
+from the previous steps.
+
+```diff
+backend:
+  database:
+-    client: sqlite3
+-    connection: ':memory:'
++    # config options: https://node-postgres.com/api/client
++    client: pg
++    connection:
++      host: ${POSTGRES_HOST}
++      port: ${POSTGRES_PORT}
++      user: ${POSTGRES_USER}
++      password: ${POSTGRES_PASSWORD}
++      # https://node-postgres.com/features/ssl
++      #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
++        #ca: # if you have a CA file and want to verify it you can uncomment this section
++        #$file: <file-path>/ca/server.crt
+```
+
+You'll use the connection details from the previous step. You can either set the
+`POSTGRES_` environment variables prior to launching Backstage, or remove the
+`${...}` values and set actual values in this configuration file.
+
+The default port for PostgreSQL is `5432` or `5433`, and the host name could be
+`127.0.0.1` if installed locally. A word of caution: In general, using
+connection details in a configuration file is not recommended.
+
+Start the Backstage app:
+
+```shell
+yarn dev
+```
+
+After Backstage is completely started you'll notice the catalog is populated
+with the information, still coming from the configuration files. If you add a
+new component, or register an existing one it will be saved in the database.
+Later in this tutorial you'll add a service, and you can test if it's persistent
+as advertised.
+
+If you want to read more about the database configuration, here's some helpful
+links:
+
+- [Configuring Plugin Databases](../tutorials/configuring-plugin-databases.md#privileges)
+- [Read more about Knex](http://knexjs.org/), which is the library we use for
+  the database backend
+
+### Setting up authentication
+
+There's multiple authentication providers available for you to use with
+Backstage, feel free to follow
+[the instructions for adding authentication](../auth/).
+
+For this tutorial we choose to use GitHub, a free service most of you might be
+familiar with. For other options, see
+[the auth provider documentation](../auth/github/provider.md#create-an-oauth-app-on-github).
+
+Go to
+[https://github.com/settings/applications/new](https://github.com/settings/applications/new)
+to create your OAuth App. The `Homepage URL` should point to Backstage's
+frontend, in our tutorial it would be `http://127.0.0.1:3000`. The
+`Authorization callback URL` will point to the auth backend, which will most
+likely be `http://127.0.0.1:7007/api/auth/github/handler/frame`.
+
+<p align='center'>
+  <img src='../assets/getting-started/gh-oauth.png' alt='Screenshot of the GitHub OAuth creation page' />
+</p>
+
+Take note of the `Client ID` and the `Client Secret`. Open `app-config.yaml`,
+and add your `clientId` and `clientSecret` to this file. It should end up
+looking like this:
+
+```yaml
+auth:
+  # see https://backstage.io/docs/auth/ to learn about auth providers
+  environment: development
+  providers:
+    github:
+      development:
+        clientId: YOUR CLIENT ID
+        clientSecret: YOUR CLIENT SECRET
+```
+
+Backstage will re-read the configuration. If there's no errors, that's great! We
+can continue with the last part of the configuration. The next step is needed to
+change the sign-in page, this you actually need to add in the source code.
+
+Open `packages/app/src/App.tsx` and below the last `import` line, add:
+
+```typescript
+import { githubAuthApiRef } from '@backstage/core-plugin-api';
+import { SignInProviderConfig, SignInPage } from '@backstage/core-components';
+
+const githubProvider: SignInProviderConfig = {
+  id: 'github-auth-provider',
+  title: 'GitHub',
+  message: 'Sign in using GitHub',
+  apiRef: githubAuthApiRef,
+};
+```
+
+Search for `const app = createApp({` in this file, and below `apis,` add:
+
+```typescript
+components: {
+   SignInPage: props => (
+     <SignInPage
+       {...props}
+       auto
+       provider={githubProvider}
+     />
+   ),
+ },
+```
+
+That should be it. You can stop your Backstage App. When you start it again and
+go to your Backstage portal in your browser, you should have your login prompt!
+
+To learn more about Authentication in Backstage, there's the following docs you
+could read:
+
+- [Adding Authentication](../auth/)
+- [Adding a new Authentication Provider](../auth/add-auth-provider.md)
+- [Using authentication and identity](../auth/using-auth.md)
+- [Using organizational data from GitHub](../integrations/github/org.md)
+
+### Setting up a GitHub Integration
+
+The GitHub integration supports loading catalog entities from GitHub or GitHub
+Enterprise. Entities can be added to static catalog configuration, registered
+with the catalog-import plugin, or discovered from a GitHub organization. Users
+and Groups can also be loaded from an organization. While using GitHub Apps
+might be the best way to set up integrations, for this tutorial you'll use a
+Personal Access Token.
+
+Create your Personal Access Token by opening the
+[the GitHub token creation page](https://github.com/settings/tokens/new). Use a
+name to identify this token and put it in the notes field. Choose a number of
+days for expiration. If you have a hard time picking a number, we suggest to go
+for 7 days, it's a lucky number.
+
+<p align='center'>
+  <img src='../assets/getting-started/gh-pat.png' alt='Screenshot of the GitHub Personal Access Token creation page' />
+</p>
+
+Set the scope to your likings. For this tutorial, selecting "repo" should be
+enough.
+
+In the `app-config.yaml`, search for `integrations:` and add your token, like we
+did in below example:
+
+```yaml
+integrations:
+  github:
+    - host: github.com
+      token: ghp_urtokendeinfewinfiwebfweb
+```
+
+That's settled. This information will be leveraged by other plugins.
+
+Some helpful links, for if you want to learn more about:
+
+- [Other available integrations](../integrations/)
+- [Using GitHub Apps instead of a Personal Access Token](../plugins/github-apps.md#docsNav)
+
+### Explore what we've done so far
+
+## Login to Backstage and check profile
+
+Open your Backstage frontend. You should see your login screen if you're not
+logged in yet. As soon as you've logged in, go to Settings, you'll see your
+profile. Hopefully you'll recognize the profile picture and name on your screen,
+otherwise something went terribly wrong.
+
+## Register an existing component
+
+- Register a new component, by going to `create` and choose
+  `Register existing component`
+
+<p align='center'>
+  <img data-zoomable src='../assets/getting-started/b-existing-1.png' alt='Software template main screen, with a blue button to add an existing component' />
+</p>
+
+- As URL use `https://github.com/backstage/demo/blob/master/catalog-info.yaml`.
+  This is used by our [demo site](https://demo.backstage.io).
+
+<p align='center'>
+  <img src='../assets/getting-started/b-existing-2.png' alt='Register a new component wizard, asking for an URL to the existing component YAML file' />
+</p>
+- Hit `Analyze` and review the changes. Apply them if correct
+
+<p align='center'>
+  <img src='../assets/getting-started/b-existing-3.png' alt='Register a new component wizard, showing the metadata for the component YAML we use in this tutorial' />
+</p>
+
+- You should receive a message that your entities have been added.
+- If you go back to `Home`, you should be able to find `demo`. You should be
+  able to click it and see the details
+
+## Create a new component using a software template
+
+- Go to `create` and choose to create a website with the `React SSR Template`
+- Type in a name, let's use `tutorial`
+- Select the group `group-a` which will own this new website, and go to the next
+  step
+
+<p align='center'>
+  <img src='../assets/getting-started/b-scaffold-1.png' alt='Software template deployment input screen asking for a name, the group owning this, and a description' />
+</p>
+
+- For the location, we're going to use the default
+- As owner, type your GitHub username
+- For the repository name, type `tutorial`. Go to the next step
+
+<p align='center'>
+  <img src='../assets/getting-started/b-scaffold-2.png' alt='Software template deployment input screen asking for the GitHub username, and name of the new repo to create' />
+</p>
+
+- Review the details of this new service, and press `Create` if you want to
+  deploy it like this.
+  - You can follow along with the progress, and as soon as every step is
+    finished, you can take a look at your new service
+
+Achievement unlocked. You've set up an installation of the core Backstage App,
+made it persistent, and configured it so you are now able to use software
+templates.
+
+Let us know how your experience was: [on discord](https://discord.gg/EBHEGzX),
+file issues for any
+[feature](https://github.com/backstage/backstage/issues/new?labels=help+wanted&template=feature_template.md)
+or
+[plugin suggestions](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME),
+or
+[bugs](https://github.com/backstage/backstage/issues/new?labels=bug&template=bug_template.md)
+you have, and feel free to
+[contribute](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md)!

docs/getting-started/index.md

@@ -87,14 +87,11 @@ carry on with the database steps.
   <img src='../assets/getting-started/portal.png' alt='Screenshot of the Backstage portal.'/>
 </p>
 
-The most common next steps are to move to a persistent database, configure
-authentication, and add a plugin:
+In the next part of this tutorial, you'll learn how to change to a persistent
+database, configure authentication, and add your first integration. Continue
+with [getting started: Configuring Backstage](configuration.md).
 
-- [Switching from SQLite to PostgresQL](https://backstage.io/docs/tutorials/switching-sqlite-postgres)
-- [Setting up Authentication](https://backstage.io/docs/auth/)
-- [Adding a plugin](https://backstage.io/docs/getting-started/configure-app-with-plugins)
-
-Congratulations! That should be it. Let us know how it went:
+Share your experiences, comments, or suggestions with us:
 [on discord](https://discord.gg/EBHEGzX), file issues for any
 [feature](https://github.com/backstage/backstage/issues/new?labels=help+wanted&template=feature_template.md)
 or

docs/local-dev/cli-commands.md

@@ -434,7 +434,8 @@ Usage: backstage-cli build [options]
 
 Options:
   --outputs <formats>  List of formats to output [types,cjs,esm]
-  -h, --help           display help for command
+  --minify                   Minify the generated code
+  -h, --help                 display help for command
 ```
 
 ## lint

docs/overview/roadmap.md

@@ -65,11 +65,6 @@ cycle will vary based on maintainer schedules.
 
 The following features are planned for release:
 
-- **Composable homepage:** We’re seeing lots of interest from the community in
-  reusable components to build a homepage experience where users can easily
-  surface what they might find useful to start their tasks. Check out the
-  [milestone](https://github.com/backstage/backstage/milestone/34) for further
-  details.
 - **Improved responsiveness:** Check out the
   [RFC here](https://github.com/backstage/backstage/issues/6318) for further
   details on how to improve the responsiveness for Backstage's UI.
@@ -120,23 +115,6 @@ The following features are planned for release:
   strong caching mechanism. The current version often requires fetching a
   relevant amount of data, especially at scale.
 
-### Search
-
-The following features are planned for release:
-
-- ElasticSearch integration: Add ElasticSearch to the Search Platform as the
-  underlying search engine. Check out the
-  [milestone here](https://github.com/backstage/backstage/milestone/27) for
-  further details.
-
-### TechDocs
-
-The following features are planned for release:
-
-- **TechDocs beta release:** Fix remaining bugs to get TechDocs to Beta. Check
-  out the [milestone here](https://github.com/backstage/backstage/milestone/29)
-  for further details.
-
 ## Future work
 
 The following feature list doesn’t represent a commitment to develop and the
@@ -165,11 +143,6 @@ the maintainers’ radar, with clear interest expressed by the community.
   bottleneck many concurrent projects created simultaneously.
 - **API discovery and documentation:** Add better support for the
   [gRPC](https://grpc.io/).
-- **Adding TechDocs search to the Search Platform:** Having this capability in
-  place will provide a better and new major version of the Search Platform
-  (v3.0). You can refer to the
-  [milestone here](https://github.com/backstage/backstage/milestone/28) for
-  further details.
 - **TechDocs GA release:** Work toward enhancements necessary to get TechDocs to
   general availability. Check out the
   [milestone here](https://github.com/backstage/backstage/milestone/30) for
@@ -179,6 +152,10 @@ the maintainers’ radar, with clear interest expressed by the community.
 
 Read more about the completed (and released) features for reference.
 
+- [[Search] ElasticSearch integration](https://backstage.io/docs/features/search/search-engines#elasticsearch)
+- [[Search] TechDocs search capabilities](https://backstage.io/docs/features/search/how-to-guides#how-to-index-techdocs-documents)
+- [TechDocs Beta](https://backstage.spotify.com/blog/product-updates/techdocs-beta-has-landed)
+- [[Home] Composable homepage](https://github.com/backstage/backstage/milestone/34)
 - [[Search] Out-of-the-Box Implementation (Alpha)](https://github.com/backstage/backstage/milestone/26)
 - [Deploy a product demo at `demo.backstage.io`](https://demo.backstage.io)
 - [Kubernetes plugin - v1](https://github.com/backstage/backstage/tree/master/plugins/kubernetes)

docs/overview/what-is-backstage.md

@@ -15,6 +15,8 @@ high-quality code quickly — without compromising autonomy.
 Backstage unifies all your infrastructure tooling, services, and documentation
 to create a streamlined development environment from end to end.
 
+<iframe width="672" height="378" src="https://www.youtube.com/embed/85TQEpNCaU0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
 Out of the box, Backstage includes:
 
 - [Backstage Software Catalog](../features/software-catalog/index.md) for

docs/plugins/composability.md

@@ -368,7 +368,7 @@ The following is an example of creation and usage of a parameterized route:
 ```tsx
 // Creation of a parameterized route
 const myRouteRef = createRouteRef({
-  title: 'My Named Route',
+  id: 'myroute',
   params: ['name']
 })
 

docs/tutorials/backend-to-backend-auth.md

@@ -22,6 +22,10 @@ resulting value.
 node -p 'require("crypto").randomBytes(24).toString("base64")'
 ```
 
+**NOTE**: For ease of development, we auto-generate a key for you if you haven't
+configured a secret in dev mode. You _must set your own secret_ in order for
+backend-to-backend authentication to work in production.
+
 Requests originating from a backend plugin can be authenticated by decorating
 them with a backend token. Backend tokens can be generated using a
 `TokenManager`, which can be passed to plugin backends via the
@@ -43,7 +47,7 @@ function makeCreateEnv(config: Config) {
   const cacheManager = CacheManager.fromConfig(config);
   const databaseManager = DatabaseManager.fromConfig(config);
 - const tokenManager = ServerTokenManager.noop();
-+ const tokenManager = ServerTokenManager.fromConfig(config);
++ const tokenManager = ServerTokenManager.fromConfig(config, { logger: root });
 ```
 
 With this `tokenManager`, you can then generate a server token for requests:

docs/tutorials/journey.md

@@ -48,7 +48,6 @@ that implements the `OAuthApi` type, it's now working in the frontend too.
 ```ts
 const spotifyAuthApiRef = createApiRef<OAuthApi>({
   id: 'core.auth.spotify',
-  description: 'Provides authentication towards Spotify APIs',
 });
 ```
 

docs/tutorials/using-backstage-proxy-within-plugin.md

@@ -99,7 +99,6 @@ export interface MyAwesomeApi {
 
 export const myAwesomeApiRef = createApiRef<MyAwesomeApi>({
   id: 'plugin.my-awesome-api.service',
-  description: 'Example API definition',
 });
 ```