Merge branch 'master' of github.com:spotify/backstage into shmidt-i/app-catalog-tabs-routes-everything-is-connected

2020-08-31 23:21:23 +02:00
parent 713060d1f3 3305bac3b1
commit 68474750db
315 changed files with 5576 additions and 2578 deletions
@@ -1,7 +1,7 @@
 ---
 name: 'Feature Request'
 about: 'Suggest new features and changes'
-labels: help wanted
+labels: enhancement
 ---

 <!--- Provide a general summary of the feature request in the Title above -->
@@ -14,7 +14,37 @@ jobs:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0 # Required to retrieve git history
-      - run: yarn install && yarn build-storybook
+
+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
+      - name: use node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+      - name: yarn install
+        run: yarn install --frozen-lockfile
+      # End of yarn setup
+
+      - run: yarn build-storybook
+
      - uses: chromaui/action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
@@ -1,11 +1,11 @@
-name: Frontend CI
+name: CI

 on:
  pull_request:
    paths-ignore:
      - 'microsite/**'
 jobs:
-  build:
+  verify:
    runs-on: ubuntu-latest

    strategy:
@@ -20,34 +20,52 @@ jobs:
      - uses: actions/checkout@v2
      - name: fetch branch master
        run: git fetch origin master
-      - name: find location of global yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-      - name: cache global yarn cache
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-      - name: cache node_modules
-        uses: actions/cache@v2
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-modules-${{ hashFiles('yarn.lock') }}
+
+      # Beginning of yarn setup, keep in sync between all workflows.
+      # TODO(Rugvip): move this to composite action once all features we use are supported
      - name: use node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+
+      # Cache every node_modules folder inside the monorepo
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          # We use both yarn.lock and package.json as cache keys to ensure that
+          # changes to local monorepo packages bust the cache.
+          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+
+      # If we get a cache hit for node_modules, there's no need to bring in the global
+      # yarn cache or run yarn install, as all dependencies will be installed already.
+
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - name: yarn install
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: yarn install --frozen-lockfile
+      # End of yarn setup

      - name: check for yarn.lock changes
        id: yarn-lock
        run: git diff --quiet origin/master HEAD -- yarn.lock
        continue-on-error: true

-      - name: yarn install
-        run: yarn install --frozen-lockfile
-
      - name: verify doc links
        run: node docs/verify-links.js

@@ -59,8 +77,7 @@ jobs:

      - name: build changed packages
        if: ${{ steps.yarn-lock.outcome == 'success' }}
-        # Need to build all dependencies as well to be able to run tests later
-        run: yarn lerna -- run build --since origin/master --include-dependencies
+        run: yarn lerna -- run build --since origin/master

      - name: build all packages
        if: ${{ steps.yarn-lock.outcome == 'failure' }}
@@ -79,6 +96,3 @@ jobs:

      - name: verify plugin template
        run: yarn lerna -- run diff -- --check
-
-      - name: verify storybook
-        run: yarn workspace storybook build-storybook
@@ -1,12 +1,13 @@
-name: CLI Test Windows
+name: E2E Test Windows

-# Building on windows is really slow, so this workflow is separate from cli.yml and only builds on changes
+# Building on windows is really slow, so this workflow is separate from e2e.yml and only builds on changes
 # to the cli itself. They're more likely to introduce issues on windows, compared to changes to core and yarn.lock.
 on:
  pull_request:
    paths:
-      - '.github/workflows/cli-win.yml'
+      - '.github/workflows/e2e-win.yml'
      - 'packages/cli/**'
+      - 'packages/e2e/**'
      - 'packages/create-app/**'

 jobs:
@@ -25,6 +26,13 @@ jobs:
    name: Node ${{ matrix.node-version }} on ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v2
+
+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
+      - name: use node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
      - name: find location of global yarn cache
        id: yarn-cache
        run: echo "::set-output name=dir::$(yarn cache dir)"
@@ -32,16 +40,15 @@ jobs:
        uses: actions/cache@v2
        with:
          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-yarn-
-      - name: use node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
-        with:
-          node-version: ${{ matrix.node-version }}
      - name: yarn install
        run: yarn install --frozen-lockfile
+      # End of yarn setup
+
      - run: yarn tsc
-      - run: yarn build
-      - name: verify app and plugin creation
-        run: node ${{ github.workspace }}/packages/cli/e2e-test/cli-e2e-test.js
+      - name: yarn build
+        run: yarn build --ignore example-app --ignore example-backend --ignore @techdocs/cli --ignore backstage-microsite
+      - name: run E2E test
+        run: yarn workspace e2e-test start
@@ -1,11 +1,10 @@
-name: CLI Test
+name: E2E Test Linux

 on:
  pull_request:
    paths-ignore:
      - 'microsite/**'

-
 jobs:
  build:
    runs-on: ${{ matrix.os }}
@@ -34,30 +33,44 @@ jobs:
    name: Node ${{ matrix.node-version }} on ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v2
-      - name: find location of global yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-      - name: cache global yarn cache
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
+
+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
      - name: use node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
      - name: yarn install
        run: yarn install --frozen-lockfile
+      # End of yarn setup
+
      - run: yarn tsc
-      - run: yarn build
-      - name: verify app and plugin creation
+      - name: yarn build
+        run: yarn build --ignore example-app --ignore example-backend --ignore @techdocs/cli --ignore backstage-microsite
+      - name: run E2E test
+        run: |
+          sudo sysctl fs.inotify.max_user_watches=524288
+          yarn workspace e2e-test start
        env:
          POSTGRES_HOST: localhost
          POSTGRES_PORT: ${{ job.services.postgres.ports[5432] }}
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
-        run: |
-          sudo sysctl fs.inotify.max_user_watches=524288
-          node ${{ github.workspace }}/packages/cli/e2e-test/cli-e2e-test.js
@@ -0,0 +1,45 @@
+name: Master Build Windows
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  build:
+    runs-on: windows-latest
+
+    strategy:
+      matrix:
+        node-version: [12.x]
+
+    env:
+      CI: true
+      NODE_OPTIONS: --max-old-space-size=4096
+
+    steps:
+      - uses: actions/checkout@v2
+
+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
+      - name: use node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+      - name: find location of global yarn cache
+        id: yarn-cache
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+      - name: yarn install
+        run: yarn install --frozen-lockfile
+      # End of yarn setup
+
+
+# Tests are broken on Windows, disabled for now
+      # - name: test
+      #   run: yarn lerna -- run test
@@ -1,4 +1,4 @@
-name: Master Build
+name: Main Master Build

 on:
  push:
@@ -18,29 +18,34 @@ jobs:

    steps:
      - uses: actions/checkout@v2
-      - name: find location of global yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-      - name: cache global yarn cache
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-      - name: cache node_modules
-        uses: actions/cache@v2
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-modules-${{ hashFiles('yarn.lock') }}
+
+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
      - name: use node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
          registry-url: https://registry.npmjs.org/ # Needed for auth
-
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
      - name: yarn install
        run: yarn install --frozen-lockfile
+      # End of yarn setup

      - name: lint
        run: yarn lerna -- run lint
@@ -69,3 +74,11 @@ jobs:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
          package_root: "packages/core"
          tag_prefix: "v"
+
+      - name: Discord notification
+        if: ${{ failure() }}
+        uses: Ilshidur/action-discord@0.2.0
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        with:
+          args: 'Master build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'
@@ -21,32 +21,34 @@ jobs:

    steps:
      - uses: actions/checkout@v2
-      - name: find location of global yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-
-      - name: cache global yarn cache
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-
-      - name: cache node_modules
-        uses: actions/cache@v2
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-modules-${{ hashFiles('yarn.lock') }}

+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
      - name: use node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
          registry-url: https://registry.npmjs.org/ # Needed for auth
-
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
      - name: yarn install
        run: yarn install --frozen-lockfile
+      # End of yarn setup

      - name: build microsite
        run: yarn workspace backstage-microsite build
@@ -25,32 +25,34 @@ jobs:

    steps:
      - uses: actions/checkout@v2
-      - name: find location of global yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-
-      - name: cache global yarn cache
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-
-      - name: cache node_modules
-        uses: actions/cache@v2
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-modules-${{ hashFiles('yarn.lock') }}

+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
      - name: use node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
          registry-url: https://registry.npmjs.org/ # Needed for auth
-
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
      - name: yarn install
        run: yarn install --frozen-lockfile
+      # End of yarn setup

      - name: build microsite
        run: yarn workspace backstage-microsite build
@@ -1,13 +1,14 @@
-| Organization                            | Contact                                                      | Description of Use                                                                               |
-| --------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
-| [Spotify](https://www.spotify.com)      | [@stefanalund](https://github.com/stefanalund)               | Main interface towards all of Spotify's infrastructure and technical documentation.              |
-| [bol.com](https://www.bol.com)          | [@RoyJacobs](https://github.com/RoyJacobs)                   | Initial work being done to unify platform tooling.                                               |
-| [DFDS](https://www.dfds.com)            | [@carlsendk](https://github.com/carlsendk)                   | V2 self-service platform.                                                                        |
-| [Roadie](https://roadie.io)             | [@dtuite](https://github.com/dtuite)                         | Hosted, managed Backstage with easy set-up                                                       |
-| [Roku](https://www.roku.com)            | [@timurista](https://github.com/timurista)                   | Initial work on Cloud engineering service platform.                                              |
-| [SDA SE](https://sda.se)                | [@Fox32](https://github.com/Fox32)                           | Central place for developing and sharing services in our insurance ecosystem.                    |
-| [H-E-B](https://www.heb.com)            | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform.                                             |
-| [American Airlines](https://www.aa.com) | [@paulpach](https://github.com/paulpach)                     | Central place for developers to develop and maintain applications                                |
-| [Kiwi.com](https://kiwi.com)            | [@aexvir](https://github.com/aexvir)                         | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry. |
-| [Voi](https://www.voiscooters.com/)     | [@K-Phoen](https://github.com/K-Phoen)                       | Developer portal, main gateway to our infrastructure, documentation and internal tooling.        |
-| [Talkdesk](https://www.talkdesk.com)    | [@jaime-talkdesk](https://github.com/jaime-talkdesk)         | Initial work for Engineering Portal and Self Provisioning to R&D                                 |
+| Organization                                 | Contact                                                      | Description of Use                                                                               |
+| -------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| [Spotify](https://www.spotify.com)           | [@stefanalund](https://github.com/stefanalund)               | Main interface towards all of Spotify's infrastructure and technical documentation.              |
+| [bol.com](https://www.bol.com)               | [@RoyJacobs](https://github.com/RoyJacobs)                   | Initial work being done to unify platform tooling.                                               |
+| [DFDS](https://www.dfds.com)                 | [@carlsendk](https://github.com/carlsendk)                   | V2 self-service platform.                                                                        |
+| [Roadie](https://roadie.io)                  | [@dtuite](https://github.com/dtuite)                         | Hosted, managed Backstage with easy set-up                                                       |
+| [Roku](https://www.roku.com)                 | [@timurista](https://github.com/timurista)                   | Initial work on Cloud engineering service platform.                                              |
+| [SDA SE](https://sda.se)                     | [@Fox32](https://github.com/Fox32)                           | Central place for developing and sharing services in our insurance ecosystem.                    |
+| [H-E-B](https://www.heb.com)                 | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform.                                             |
+| [American Airlines](https://www.aa.com)      | [@paulpach](https://github.com/paulpach)                     | Central place for developers to develop and maintain applications                                |
+| [Kiwi.com](https://kiwi.com)                 | [@aexvir](https://github.com/aexvir)                         | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry. |
+| [Voi](https://www.voiscooters.com/)          | [@K-Phoen](https://github.com/K-Phoen)                       | Developer portal, main gateway to our infrastructure, documentation and internal tooling.        |
+| [Talkdesk](https://www.talkdesk.com)         | [@jaime-talkdesk](https://github.com/jaime-talkdesk)         | Initial work for Engineering Portal and Self Provisioning to R&D                                 |
+| [Wealthsimple](https://www.wealthsimple.com) | [@andrewthauer](https://github.com/andrewthauer)             | Developer portal, service catalog, documentation and tooling                                     |
@@ -8,6 +8,10 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re

 > Collect changes for the next release below

+## v0.1.1-alpha.20
+
+- Includes https://github.com/spotify/backstage/pull/2097 to resolve issues with create-plugin command.
+
 ## v0.1.1-alpha.19

 ### @backstage/create-app
@@ -29,16 +29,6 @@ For more information go to [backstage.io](https://backstage.io) or join our [Dis

 A detailed project roadmap, including already delivered milestones, is available [here](https://backstage.io/docs/overview/roadmap).

-## Overview
-
-The Backstage platform consists of a number of different components:
-
- **app** - Main web application that users interact with. It's built up by a number of different _Plugins_. This repo contains an example implementation of an app (located in `packages/app`) and you can easily get started with your own app by [creating one](docs/getting-started/create-an-app.md).
- [**plugins**](https://github.com/spotify/backstage/tree/master/plugins) - Each plugin is treated as a self-contained web app and can include almost any type of content. Plugins all use a common set of platform API's and reusable UI components. Plugins can fetch data either from the _backend_ or through any RESTful API exposed through the _proxy_.
- [**service catalog**](https://github.com/spotify/backstage/tree/master/packages/backend) - Service that holds the model of your software ecosystem, including organisational information and what team owns what software. The backend also has a Plugin model for extending its graph.
- [**proxy**](https://github.com/spotify/backstage/tree/master/plugins/proxy-backend) - Terminates HTTPS and exposes any RESTful API to Plugins.
- **identity** - A backend service that holds your organisation's metadata.
-
 ## Getting Started

 There are two different ways to get started with Backstage, either by creating a standalone app, or by cloning this repo. Which method you use depends on what you're planning to do.
@@ -14,21 +14,15 @@ backend:
    client: sqlite3
    connection: ':memory:'

+# See README.md in the proxy-backend plugin for information on the configuration format
 proxy:
-  '/circleci/api':
-    target: 'https://circleci.com/api/v1.1'
-    changeOrigin: true
-    pathRewrite:
-      '^/proxy/circleci/api/': '/'
+  '/circleci/api': https://circleci.com/api/v1.1
  '/jenkins/api':
-    target: 'http://localhost:8080'
-    changeOrigin: true
+    target: http://localhost:8080
    headers:
      Authorization:
        $secret:
          env: JENKINS_BASIC_AUTH_HEADER
-    pathRewrite:
-      '^/proxy/jenkins/api/': '/'

 organization:
  name: Spotify
@@ -50,6 +44,46 @@ newrelic:
    baseUrl: 'https://api.newrelic.com/v2'
    key: NEW_RELIC_REST_API_KEY

+lighthouse:
+  baseUrl: http://localhost:3003
+
+catalog:
+  processors:
+    githubApi:
+      privateToken:
+        $secret:
+          env: GITHUB_PRIVATE_TOKEN
+    bitbucketApi:
+      username:
+        $secret:
+          env: BITBUCKET_USERNAME
+      appPassword:
+        $secret:
+          env: BITBUCKET_APP_PASSWORD
+    gitlabApi:
+      privateToken:
+        $secret:
+          env: GITLAB_PRIVATE_TOKEN
+    azureApi:
+      privateToken:
+        $secret:
+          env: AZURE_PRIVATE_TOKEN
+  exampleEntityLocations:
+    github:
+      - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
+      - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-order-component.yaml
+      - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/podcast-api-component.yaml
+      - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/queue-proxy-component.yaml
+      - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/searcher-component.yaml
+      - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-lib-component.yaml
+      - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/www-artist-component.yaml
+      - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/shuffle-api-component.yaml
+      - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/react-ssr-template/template.yaml
+      - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml
+      - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/create-react-app/template.yaml
+      - https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml
+      - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/docs-template/template.yaml
+
 auth:
  providers:
    google:
@@ -122,3 +156,14 @@ auth:
        domain:
          $secret:
            env: AUTH_AUTH0_DOMAIN
+    microsoft:
+      development:
+        clientId:
+          $secret:
+            env: AUTH_MICROSOFT_CLIENT_ID
+        clientSecret:
+          $secret:
+            env: AUTH_MICROSOFT_CLIENT_SECRET
+        tenantId:
+          $secret:
+            env: AUTH_MICROSOFT_TENANT_ID
@@ -7,6 +7,7 @@ metadata:
  annotations:
    github.com/project-slug: spotify/backstage
    backstage.io/github-actions-id: spotify/backstage
+    backstage.io/techdocs-ref: github:https://github.com/spotify/backstage.git
 spec:
  type: library
  owner: Spotify
@@ -3,7 +3,7 @@ id: FAQ
 title: FAQ
 ---

-## Product FAQ:
+## Product FAQ

 ### Can we call Backstage something different? So that it fits our company better?

@@ -67,7 +67,7 @@ valuable as you grow.
 Yes! The Backstage UI is built using Material-UI. With the theming capabilities
 of Material-UI, you are able to adapt the interface to your brand guidelines.

-## Technical FAQ:
+## Technical FAQ

 ### Why Material-UI?

@@ -1,104 +1,3 @@
-# Documentation structure
+# Documentation

-**Note!** This documentation structure is very much work in progress. If (when,
-really 😆) you find broken links or missing content, please create an issue or,
-better yet, a pull request.
-
-# Plugins
-
- Overview
-  - [What is Backstage?](overview/what-is-backstage.md)
-  - [Backstage architecture](overview/architecture-overview.md)
-  - [Architecture and terminology](overview/architecture-terminology.md)
-  - [Roadmap](overview/roadmap.md)
-  - [Vision](overview/vision.md)
- Getting started
-  - [Running Backstage locally](getting-started/index.md)
-  - [Installation](getting-started/installation.md)
-  - [Local development](getting-started/development-environment.md)
-  - [Demo deployment](https://backstage-demo.roadie.io)
-  - Production deployments
-    - [Create an App](getting-started/create-an-app.md)
-    - App configuration
-      - [Configuring App with plugins](getting-started/configure-app-with-plugins.md)
-      - [Customize the look-and-feel of your App](getting-started/app-custom-theme.md)
-    - Deployment scenarios
-      - [Kubernetes](getting-started/deployment-k8s.md)
-      - [Other](getting-started/deployment-other.md)
- Features
-  - Software Catalog
-    - [Overview](features/software-catalog/index.md)
-    - [System model](features/software-catalog/system-model.md)
-    - [YAML File Format](features/software-catalog/descriptor-format.md)
-    - [Extending the model](features/software-catalog/extending-the-model.md)
-    - [External integrations](features/software-catalog/external-integrations.md)
-    - [API](features/software-catalog/api.md)
-  - Software creation templates
-    - [Overview](features/software-templates/index.md)
-    - [Adding templates](features/software-templates/adding-templates.md)
-      - Extending the Scaffolder:
-        - [Overview](features/software-templates/extending/index.md)
-        - [Create your own Templater](features/software-templates/extending/create-your-own-templater.md)
-        - [Create your own Publisher](features/software-templates/extending/create-your-own-publisher.md)
-        - [Create your own Preparer](features/software-templates/extending/create-your-own-preparer.md)
-  - Docs-like-code
-    - [Overview](features/techdocs/README.md)
-    - [Getting Started](features/techdocs/getting-started.md)
-    - [Concepts](features/techdocs/concepts.md)
-    - [Creating and Publishing Documentation](features/techdocs/creating-and-publishing.md)
-    - [FAQ](features/techdocs/FAQ.md)
- Plugins
-  - [Overview](plugins/index.md)
-  - [Existing plugins](plugins/existing-plugins.md)
-  - [Creating a new plugin](plugins/create-a-plugin.md)
-  - [Developing a plugin](plugins/plugin-development.md)
-  - [Structure of a plugin](plugins/structure-of-a-plugin.md)
-  - Backends and APIs
-    - [Proxying](plugins/proxying.md)
-    - [Backstage backend plugin](plugins/backend-plugin.md)
-    - [Call existing API](plugins/call-existing-api.md)
-  - Testing
-    - [Overview](plugins/testing.md)
-  - Publishing
-    - [Open source and NPM](plugins/publishing.md)
-    - [Private/internal (non-open source)](plugins/publish-private.md)
- Configuration
-  - [Overview](conf/index.md)
-  - [Reading Configuration](conf/reading.md)
-  - [Writing Configuration](conf/writing.md)
-  - [Defining Configuration](conf/defining.md)
- Authentication and identity
-  - [Overview](auth/index.md)
-  - [Add auth provider](auth/add-auth-provider.md)
-  - [Auth backend](auth/auth-backend.md)
-  - [OAuth](auth/oauth.md)
-  - [Glossary](auth/glossary.md)
- Designing for Backstage
-  - [Backstage Design Language System (DLS)](dls/design.md)
-  - [Storybook -- reusable UI components](http://backstage.io/storybook)
-  - [Contributing to Storybook](dls/contributing-to-storybook.md)
-  - [Figma resources](dls/figma.md)
- API references
-  - TypeScript API
-    - [Utility APIs](api/utility-apis.md)
-    - [Utility API References](reference/utility-apis/README.md)
-    - [createPlugin](reference/createPlugin.md)
-    - [createPlugin-feature-flags](reference/createPlugin-feature-flags.md)
-    - [createPlugin-router](reference/createPlugin-router.md)
-  - Backend APIs
-    - [Backend](api/backend.md)
- Tutorials
-  - [Overview](tutorials/index.md)
- Architecture Decision Records (ADRs)
-  - [Overview](architecture-decisions/index.md)
-  - [ADR001 - Architecture Decision Record (ADR) log](architecture-decisions/adr001-add-adr-log.md)
-  - [ADR002 - Default Software Catalog File Format](architecture-decisions/adr002-default-catalog-file-format.md)
-  - [ADR003 - Avoid Default Exports and Prefer Named Exports](architecture-decisions/adr003-avoid-default-exports.md)
-  - [ADR004 - Module Export Structure](architecture-decisions/adr004-module-export-structure.md)
-  - [ADR005 - Catalog Core Entities](architecture-decisions/adr005-catalog-core-entities.md)
-  - [ADR006 - Avoid React.FC and React.SFC](architecture-decisions/adr006-avoid-react-fc.md)
-  - [ADR007 - Use MSW for Mocking Network Requests](architecture-decisions/adr007-use-msw-to-mock-service-requests.md)
-  - [ADR008 - Default Catalog File Name](architecture-decisions/adr008-default-catalog-file-name.md)
- [Contribute](../CONTRIBUTING.md)
- [Support](overview/support.md)
- [FAQ](FAQ.md)
+The Backstage documentation is available at https://backstage.io/docs
@@ -71,18 +71,23 @@ import {
  AlertApiForwarder,
  ErrorApiForwarder,
  ErrorAlerter,
+  ConfigApi
 } from '@backstage/core';

-const builder = ApiRegistry.builder();

-// The alert API is a self-contained implementation that shows alerts to the user.
-const alertApi = builder.add(alertApiRef, new AlertApiForwarder());
+const apis = (config: ConfigApi) => {
+  const builder = ApiRegistry.builder();

-// The error API uses the alert API to send error notifications to the user.
-builder.add(errorApiRef, new ErrorAlerter(alertApi, new ErrorApiForwarder()));
+  // The alert API is a self-contained implementation that shows alerts to the user.
+  const alertApi = builder.add(alertApiRef, new AlertApiForwarder());
+
+  // The error API uses the alert API to send error notifications to the user.
+  builder.add(errorApiRef, new ErrorAlerter(alertApi, new ErrorApiForwarder()));
+  return builder.build();
+}

 const app = createApp({
-  apis: apiBuilder.build(),
+  apis,
  // ... other config
 });
 ```
@@ -4,8 +4,6 @@ title: Architecture Decision Records (ADR)
 sidebar_label: Overview
 ---

-#
-
 The substantial architecture decisions made in the Backstage project lives here.
 For more information about ADRs, when to write them, and why, please see
 [this blog post](https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-architecture-decision-record/).
@@ -25,7 +23,10 @@ Records should be stored under the `architecture-decisions` directory.
 - Submit a pull request
 - Address and integrate feedback from the community
 - Eventually, assign a number
- Add the full path of the ADR to the [`mkdocs.yml`](/mkdocs.yml)
+- Add the path of the ADR to the microsite sidebar in
+  [`sidebars.json`](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json)
+- Add the path of the ADR to the
+  [`mkdocs.yml`](https://github.com/spotify/backstage/blob/master/mkdocs.yml)
 - Merge the pull request

 ## Superseding an ADR
@@ -1,4 +1,7 @@
-# Authentication Backend Classes Layout and Description
+---
+id: auth-backend-classes
+title: Auth backend classes
+---

 ## How Does Authentication Work?

@@ -104,6 +104,8 @@ request an access token.

 The following diagram visualizes the flow described in the previous section.

+![](oauth-popup-flow.svg)
+
 <!--
@startuml oauth-popup-flow

@@ -152,5 +154,3 @@ Browser <- Backend: Tokens and info

@enduml
 -->
-
-![](oauth-popup-flow.svg)
@@ -0,0 +1,57 @@
+---
+id: software-catalog-configuration
+title: Catalog Configuration
+---
+
+## Static Location Configuration
+
+To enable declarative catalog setups, it is possible to add locations to the
+catalog via [static configuration](../../conf/index.md). Locations are added to
+the catalog under the `catalog.locations` key, for example:
+
+```yaml
+catalog:
+  locations:
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
+```
+
+The locations added through static configuration can not be removed through the
+catalog locations API. To remove the locations, you have to remove them from the
+configuration.
+
+## Catalog Rules
+
+By default the catalog will only allow ingestion of entities with the kind
+`Component` and `API`. In order to allow entities of other kinds to be added,
+you need to add rules to the catalog. Rules are added either in a separate
+`catalog.rules` key, or added to statically configured locations.
+
+For example, given the following configuration:
+
+```yaml
+catalog:
+  rules:
+    - allow: [Component, API, System]
+
+  locations:
+    - type: github
+      target: https://github.com/org/example/blob/master/org-data.yaml
+      allow: [Group]
+```
+
+We are able to add entities of kind `Component`, `API`, or `System` from any
+location, and `Group` entities from the `org-data.yaml`, which will also be read
+as statically configured location.
+
+Note that if the `catalog.rules` key is present it will replace the default
+value, meaning that you need to add rules for `Component` and `API` kinds if you
+want those to be allowed.
+
+The following configuration will reject any kind of entities from being added to
+the catalog:
+
+```yaml
+catalog:
+  rules: []
+```
@@ -370,8 +370,8 @@ metadata:
  description:
    Next.js application skeleton for creating isomorphic web applications.
  tags:
-    - Recommended
-    - React
+    - recommended
+    - react
 spec:
  owner: web@example.com
  templater: cookiecutter
@@ -12,7 +12,7 @@ Backstage natively supports tracking of the following component
 - Documentation
 - Other

-![](bsc-extend.png)
+![](../../assets/software-catalog/bsc-extend.png)

 Since these types are likely not the only kind of software you will want to
 track in Backstage, it is possible to
@@ -31,9 +31,10 @@ catalog.
 It might be tempting to put software that doesn't fit into any of the existing
 types into Other. There are a few reasons why we advice against this; firstly,
 we have found that it is preferred to match the conceptual model that your
-engineers have when describing your sofware. Secondly, Backstage helps your
-engineers manage their software by integrating the infratrucure tooling through
-plugins. Different plugins are used for managing different types of components.
+engineers have when describing your software. Secondly, Backstage helps your
+engineers manage their software by integrating the infrastructure tooling
+through plugins. Different plugins are used for managing different types of
+components.

 For example, the
 [Lighthouse plugin](https://github.com/spotify/backstage/tree/master/plugins/lighthouse)
@@ -1,6 +1,7 @@
 ---
 id: software-catalog-overview
 title: Backstage Service Catalog (alpha)
+sidebar_label: Backstage Service Catalog
 ---

 ## What is a Service Catalog?
@@ -54,18 +55,18 @@ There are 3 ways to add components to the catalog:
 Users can register new components by going to `/create` and clicking the
 **REGISTER EXISTING COMPONENT** button:

-![](bsc-register-1.png)
+![](../../assets/software-catalog/bsc-register-1.png)

 Backstage expects the full URL to the YAML in your source control. Example:

-```
+```bash
 https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
 ```

 _More examples can be found
 [here](https://github.com/spotify/backstage/tree/master/packages/catalog-model/examples)._

-![](bsc-register-2.png)
+![](../../assets/software-catalog/bsc-register-2.png)

 It is important to note that any kind of software can be registered in
 Backstage. Even if the software is not maintained by your company (SaaS
@@ -78,12 +79,28 @@ All software created through the
 [Backstage Software Templates](../software-templates/index.md) are automatically
 registered in the catalog.

+### Static catalog configuration
+
+In addition to manually registering components, it is also possible to register
+components though [static configuration](../../conf/index.md). For example, the
+above example can be added using the following configuration:
+
+```yaml
+catalog:
+  locations:
+    - type: github
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
+```
+
+More information about catalog configuration can be found
+[here](configuration.md).
+
 ### Updating component metadata

 Teams owning the components are responsible for maintaining the metadata about
 them, and do so using their normal Git workflow.

-![](bsc-edit.png)
+![](../../assets/software-catalog/bsc-edit.png)

 Once the change has been merged, Backstage will automatically show the updated
 metadata in the service catalog after a short while.
@@ -92,25 +109,25 @@ metadata in the service catalog after a short while.

 By default the service catalog shows components owned by the team of the logged
 in user. But you can also switch to _All_ to see all the components across your
-companie's software ecosystem. Basic inline _search_ and _column filtering_
-makes it easy to browse a big set of components.
+company's software ecosystem. Basic inline _search_ and _column filtering_ makes
+it easy to browse a big set of components.

-![](bsc-search.png)
+![](../../assets/software-catalog/bsc-search.png)

 ## Starring components

 For easy and quick access to components you visit frequently, Backstage supports
 _starring_ of components:

-![](bsc-starred.png)
+![](../../assets/software-catalog/bsc-starred.png)

 ## Integrated tooling through plugins

-The service catalog is a great way to organise the infrastructure tools you use
+The service catalog is a great way to organize the infrastructure tools you use
 to manage the software. This is how Backstage creates one developer portal for
 all your tools. Rather than asking teams to jump between different
-infrastructure UI’s (and incurring additional cognitive overhead each time they
-make a context switch), most of these tools can be organised around the entities
+infrastructure UIs (and incurring additional cognitive overhead each time they
+make a context switch), most of these tools can be organized around the entities
 in the catalog.

 ![tools](https://backstage.io/blog/assets/20-05-20/tabs.png)
@@ -3,55 +3,26 @@ id: system-model
 title: System Model
 ---

-We believe that a strong shared understanding and terminology around systems,
-software and resources leads to a better Backstage experience.
+We believe that a strong shared understanding and terminology around software
+and resources leads to a better Backstage experience.

 _This description originates from
 [this RFC](https://github.com/spotify/backstage/issues/390). Note that some of
 the concepts are not yet supported in Backstage._

-## Concepts
+## Core Entities

-We model our technology using these five concepts (further explained below):
+We model software in the Backstage catalogue using these three core entities
+(further explained below):
+
+- **Components** are individual pieces of software
+
+- **APIs** are the boundaries between different components

- **Domains** are a high-level grouping of systems
- **Systems** encapsulate the implementation of APIs
- **APIs** are the boundaries between different components and systems
- **Components** are pieces of software
 - **Resources** are physical or virtual infrastructure needed to operate a
-  system
+  component

-![Software Ecosystem Model_ Public Github version](https://user-images.githubusercontent.com/24575/77633084-39bcde80-6f4f-11ea-8251-f8df561a3652.png)
-
-### Domain
-
-While systems are the basic level of encapsulation for resources, components and
-APIs, it is often useful to group a collection of systems that share
-terminology, domain models, business purpose, or documentation, i.e. they form a
-bounded context.
-
-For example, it would make sense if the different systems in the “Payments”
-domain would come with some documentation on how to accept payments for a new
-product or use-case, share the same entity types in their APIs, and integrate
-well with each other.
-
-### System
-
-With increasing complexity in software, we believe that systems form an
-important abstraction level to help us reason about software ecosystems. Systems
-are a useful concept in that they allow us to ignore the implementation details
-of a certain functionality for consumers, while allowing the owning team to make
-changes as they see fit (leading to low coupling).
-
-A system, in this sense, is a collection of resources and components that
-exposes one or several APIs. Components and resources in a system are typically
-owned by the same team and are expected to co-evolve. As such, systems usually
-consist of at most a handful of components.
-
-For example, a playlist management system might encapsulate a backend service to
-update playlists, a backend service to query them, and a database to store them.
-It could expose an RPC API, a daily snapshots dataset, and an event stream of
-playlist updates.
+![](../../assets/software-catalog/software-model-core-entities.png)

 ### Component

@@ -60,34 +31,80 @@ backend service or data pipeline (list not exhaustive). A component can be
 tracked in source control, or use some existing open source or commercial
 software.

-A component can implement APIs for other components to consume. It might depend
-on the resources of the system it belongs to, and APIs from other components or
-other systems. All other aspects of the component, e.g. any code dependencies,
-must be encapsulated.
+A component can implement APIs for other components to consume. In turn it might
+depend on APIs implemented by other components, or resources that are attached
+to it at runtime.

 ### API

-We believe APIs form an important (maybe the most important) abstraction that
-allows large software ecosystems to scale. Thus, APIs are a first class citizen
-in the Backstage model and the primary way to discover existing functionality in
-the ecosystem.
+APIs form an important (maybe the most important) abstraction that allows large
+software ecosystems to scale. Thus, APIs are a first class citizen in the
+Backstage model and the primary way to discover existing functionality in the
+ecosystem.

-APIs are implemented by components and form boundaries between components and
-systems. They might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a
-data schema (eg Avro, TFRecord, ...), or as code interfaces. In any case, APIs
-exposed by components need to be in a known machine-readable format so we can
-build further tooling and analysis on top.
+APIs are implemented by components and form boundaries between components. They
+might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a data schema (eg
+Avro, TFRecord, ...), or as code interfaces. In any case, APIs exposed by
+components need to be in a known machine-readable format so we can build further
+tooling and analysis on top.

-Some APIs might be exposed by the system, making them available for any other
-Spotify component to consume. Those public APIs must be documented and humanly
-discoverable in Backstage.
+APIs have a visibility: they are either public (making them available for any
+other component to consume), restricted (only available to a whitelisted set of
+consumers), or private (only available within their system). As public APIs are
+going to be the primary way interaction between components, Backstage supports
+documenting, indexing and searching all APIs so we can browse them as
+developers.

 ### Resource

-Resources are the infrastructure a system needs to operate, like BigTable
-databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with
-components and systems will better allow us to visualize resource footprint, and
-create tooling around them.
+Resources are the infrastructure a component needs to operate at runtime, like
+BigTable databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together
+with components and systems will better allow us to visualize resource
+footprint, and create tooling around them.
+
+## Ecosystem Modeling
+
+A large catalogue of components, APIs and resources can be highly granular and
+hard to understand as a whole. It might thus be convenient to further categorize
+these entities using the following (optional) concepts:
+
+- **Systems** are a collection of entities that cooperate to perform some
+  function
+- **Domains** relate entities and systems to part of the business
+
+### System
+
+With increasing complexity in software, systems form an important abstraction
+level to help us reason about software ecosystems. Systems are a useful concept
+in that they allow us to ignore the implementation details of a certain
+functionality for consumers, while allowing the owning team to make changes as
+they see fit (leading to low coupling).
+
+A system, in this sense, is a collection of resources and components that
+exposes one or several public APIs. The main benefit of modelling a system is
+that it hides its resources and private APIs between the components for any
+consumers. This means that as the owner, you can evolve the implementation, in
+terms of components and resources, without your consumers being able to notice.
+Typically, a system will consist of at most a handful of components (see Domain
+for a grouping of systems).
+
+For example, a playlist management system might encapsulate a backend service to
+update playlists, a backend service to query them, and a database to store them.
+It could expose an RPC API, a daily snapshots dataset, and an event stream of
+playlist updates.
+
+### Domain
+
+While systems are the basic level of encapsulation for related entities, it is
+often useful to group a collection of systems that share terminology, domain
+models, metrics, KPIs, business purpose, or documentation, i.e. they form a
+bounded context.
+
+For example, it would make sense if the different systems in the “Payments”
+domain would come with some documentation on how to accept payments for a new
+product or use-case, share the same entity types in their APIs, and integrate
+well with each other. Other domains could be “Content Ingestion”, “Ads” or
+“Search”.

 ## Current status

@@ -22,8 +22,8 @@ metadata:
    Next.js application skeleton for creating isomorphic web applications.
  # some tags to display in the frontend
  tags:
-    - Recommended
-    - React
+    - recommended
+    - react
 spec:
  # which templater key to use in the templaters builder
  templater: cookiecutter
@@ -54,11 +54,11 @@ contains more information about the required fields.
 Once we have a `template.yaml` ready, we can then add it to the service catalog
 for use by the scaffolder.

-Currently the catalog supports loading definitions from Github + Local Files. To
+Currently the catalog supports loading definitions from GitHub + Local Files. To
 load from other places, not only will there need to be another preparer, but the
 support to load the location will also need to be added to the Catalog.

-For loading from a file the following command should work when the backend is
+For loading from a file, the following command should work when the backend is
 running:

 ```sh
@@ -69,7 +69,7 @@ curl \
  --data-raw "{\"type\": \"file\", \"target\": \"${YOUR PATH HERE}/template.yaml\"}"
 ```

-If loading from a git location, you can run the following
+If loading from a Git location, you can run the following

 ```sh
 curl \
@@ -83,7 +83,7 @@ This should then have added the catalog, and also should now be listed under the
 create page at http://localhost:3000/create.

 Alternatively, if you want to get setup with some mock templates that are
-already provided for you, you can run the following to load those templates:
+already provided, run the following to load those templates:

 ```
 yarn lerna run mock-data
@@ -54,7 +54,7 @@ The `protocol` is set on the
 when added to the service catalog. You can see more about this `PreparerKey`
 here in [Register your own template](../adding-templates.md)

-**note:** Currently the catalog supports loading definitions from Github + Local
+**note:** Currently the catalog supports loading definitions from GitHub + Local
 Files, which translate into the two `PreparerKeys` `file` and `github`. To load
 from other places, not only will there need to be another preparer, but the
 support to load the location will also need to be added to the Catalog.
@@ -7,8 +7,8 @@ Publishers are responsible for pushing and storing the templated skeleton after
 the values have been templated by the `Templater`. See
 [Create your own templater](./create-your-own-templater.md) for more info.

-They recieve a directory or location where the templater has sucessfully run on,
-and is now ready to store somewhere. They also get given some other options
+They receive a directory or location where the templater has sucessfully run
+and is now ready to store somewhere. They also are given some other options
 which are sent from the frontend, such as the `storePath` which is a string of
 where the frontend thinks we should save this templated folder.

@@ -17,7 +17,7 @@ Currently we provide the following `publishers`:
 - `github`

 This publisher is passed through to the `createRouter` function of the
-`@spotify/plugin-scaffolder-backend`. Currently only one publisher is supported,
+`@spotify/plugin-scaffolder-backend`. Currently, only one publisher is supported,
 but PR's are always welcome.

 An full example backend can be found
@@ -8,14 +8,14 @@ returned by the preparers, and then executing the templating command on top of
 the file and returning the completed template path. This may or may not be the
 same directory as the input directory.

-They also recieve additional values from the frontend, which can be used to
+They also receive additional values from the frontend, which can be used to
 interpolate into the skeleton files.

 Currently we provide the following templaters:

 - `cookiecutter`

-This templater is added the `TemplaterBuilder` and then passed into the
+This templater is added to the `TemplaterBuilder` and then passed into the
 `createRouter` function of the `@spotify/plugin-scaffolder-backend`

 An full example backend can be found
@@ -48,7 +48,7 @@ This `TemplaterKey` is used to select the correct templater from the
 `spec.templater` in the
 [Template Entity](../../software-catalog/descriptor-format.md#kind-template).

-If you wish to add a new templater you'll need to register it with the
+If you wish to add a new templater, you'll need to register it with the
 `TemplaterBuilder`.

 ### Creating your own Templater to add to the `TemplaterBuilder`
@@ -83,10 +83,10 @@ follows:
 - `dockerClient` - a [dockerode](https://github.com/apocas/dockerode) client to
  be able to run docker containers.

-_note_ currently the templaters that we provide are basically docker action
+_note_ Currently the templaters that we provide are basically Docker action
 containers that are run on top of the skeleton folder. This keeps dependencies
 to a minimal for running backstage scaffolder, but you don't /have/ to use
-docker. You could create your own templater that spins up an EC2 instance and
+Docker. You could create your own templater that spins up an EC2 instance and
 downloads the folder and does everything using an AMI if you want. It's entirely
 up to you!

@@ -116,8 +116,8 @@ metadata:
  description:
    Next.js application skeleton for creating isomorphic web applications.
  tags:
-    - Recommended
-    - React
+    - recommended
+    - react
 spec:
  owner: web@example.com
  templater: handlebars
@@ -138,7 +138,7 @@ spec:
        description: Description of the component
 ```

-You see that the `spec.templater` is set as `handlebars`, you'll need to
+You see that the `spec.templater` is set as `handlebars`, so you'll need to
 register this with the `TemplaterBuilder` like so:

 ```ts
@@ -5,11 +5,11 @@ title: Extending the Scaffolder

 Welcome. Take a seat. You're at the Scaffolder Documentation.

-So - You wanna create stuff inside your company from some prebaked templates?
+So, you want to create stuff inside your company from some prebaked templates?
 You're at the right place.

-This guide is gonna take you through how the Scaffolder in Backstage works.
-We'll dive into some jargon and run through whats going on in the backend to be
+This guide is going to take you through how the Scaffolder in Backstage works.
+We'll dive into some jargon and run through what's going on in the backend to be
 able to create these templates. There's also more guides that you might find
 useful at the bottom of this document. At it's core, theres 3 simple stages.

@@ -25,9 +25,9 @@ scaffolder that you will need to know:
 3. Publish

 Each of these steps can be configured for your own use case, but we provide some
-sensible defaults too.
+sensible defaults, too.

-Lets dive a little deeper into these phases.
+Let's dive a little deeper into these phases.

 ### Glossary and Jargon

@@ -38,8 +38,8 @@ the router to pick the correct `Preparer` to run for the `Template` entity.

 **Templater** - The templater is responsible for actually running the chosen
 templater on top of the previously returned temporary directory from the
-**Preprarer**. We advise making these docker containers as it can keep all
-dependencies, for example Cookiecutter, self contained and not a dependency on
+**Preprarer**. We advise making these Docker containers as it can keep all
+dependencies--for example Cookiecutter--self contained and not a dependency on
 the host machine.

 **Publisher** - The publisher is responsible for taking the finished directory,
@@ -50,11 +50,11 @@ passed through to the scaffolder backend.

 ### How it works

-The main of the heavy lifting is done in the
+Most of the heavy lifting is done in the
 [router.ts](https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/service/router.ts#L93)
 file in the `scaffolder-backend` plugin.

-There are 2 routes defined in the router. `POST /v1/jobs` and
+There are two routes defined in the router: `POST /v1/jobs` and
 `GET /v1/job/:jobId`

 To create a scaffolding job, a JSON object containing the
@@ -78,7 +78,7 @@ additional templating values must be posted as the post body.
 The values should represent something that is valid with the `schema` part of
 the [Template Entity](../../software-catalog/descriptor-format.md#kind-template)

-Once that has been posted, a job will be setup with different stages. And the
+Once that has been posted, a job will be setup with different stages, and the
 job processor will complete each stage before moving onto the next stage, whilst
 collecting logs and mutating the running job.

@@ -4,8 +4,8 @@ title: Software Templates
 ---

 The Software Templates part of Backstage is a tool that can help you create
-Components inside Backstage. It by default has the ability to load skeletons of
-code, template in some variables and then publish the template to some location
+Components inside Backstage. By default, it  has the ability to load skeletons of
+code, template in some variables, and then publish the template to some location
 like GitHub.

 <video width="100%" height="100%" controls>
@@ -33,8 +33,8 @@ 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 right now must be a Github Organisation and a
+are required for backstage usage: the owner, (which is a `user` in the backstage
+system), the `storePath` (which right now must be a GitHub Organisation), and a
 non-existing github repository name in the format `organisation/reponame`.

 ![Enter backstage vars](../../assets/software-templates/template-picked-2.png)
@@ -51,13 +51,13 @@ It shouldn't take too long, and you'll have a success screen!
 ![Templating Complete](../../assets/software-templates/complete.png)

 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 to debug.
+step that failed which can be helpful in debugging.

 ![Templating failed](../../assets/software-templates/failed.png)

 ### View Component in Catalog

-When it's been created you'll see the `View in Catalog` button, which will take
+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)
@@ -109,7 +109,7 @@ export default async function createPlugin({ logger }: PluginEnvironment) {
  preparers.register('file', filePreparer);
  preparers.register('github', githubPreparer);

-  // Create Github client with your access token from environment variables
+  // Create GitHub client with your access token from environment variables
  const githubClient = new Octokit({ auth: process.env.GITHUB_ACCESS_TOKEN });
  const publisher = new GithubPublisher({ client: githubClient });

@@ -101,3 +101,7 @@ more to come...
  https://github.com/spotify/backstage/blob/master/packages/techdocs-container
 [techdocs/cli]:
  https://github.com/spotify/backstage/blob/master/packages/techdocs-cli
+
+## TechDocs Big Picture
+
+![TechDocs Big Picture](../..//assets/techdocs/techdocs_big_picture.png)
@@ -42,7 +42,7 @@ sites with the Backstage UI.

 The TechDocs Reader purpose is also to open up the opportunity to integrate
 TechDocs widgets for a customized full-featured TechDocs experience.
-([coming soon V.2](https://github.com/spotify/backstage/milestone/17))
+([coming soon V.3](./README.md#project-roadmap))

 [TechDocs Reader](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md)

@@ -53,4 +53,4 @@ Reader. The reason why transformers were introduced was to provide a way to
 transform the HTML content on pre and post render (e.g. rewrite docs links or
 modify css).

-[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/transformers/README.md)
+[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md)
@@ -6,26 +6,43 @@ sidebar_label: Creating and Publishing Documentation

 This section will guide you through:

- Creating a basic setup for your documentation
- Writing and previewing your documentation in a local Backstage environment
- Creating a build ready for publication
- Publishing your documentation and making your Backstage instance read your
-  published docs.
+- [Create a basic documentation setup](#create-a-basic-documentation-setup)
+  - [Use the documentation template](#use-the-documentation-template)
+  - [Manually add documentation setup to already existing repository](#manually-add-documentation-setup-to-already-existing-repository)
+- [Writing and previewing your documentation](#writing-and-previewing-your-documentation)

 ## Prerequisities

- [Docker](https://docs.docker.com/get-docker/)
- Static file hosting
 - A working Backstage instance with TechDocs installed (see
  [TechDocs getting started](getting-started.md))

 ## Create a basic documentation setup

-In your home directory (also known as `~`), create a directory that contains
-your documentation (for example, `hello-docs`). Inside this directory, create a
-file called `mkdocs.yml`. Below is a basic example of how it could look.
+### Use the documentation template

-The `~/hello-docs/mkdocs.yml` file should have the following content:
+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.
+
+![Documentation Template](../../assets/techdocs/documentation-template.png)
+
+Create an entity from the documentation template and you will get the needed
+setup for free.
+
+!!! warning Currently the Backstage Software Templates are limited to create repositories
+inside GitHub organizations. You also need to generate an personal access token
+and use as an environment variable. Read more about this
+[here](../software-templates/installation.md#runtime-dependencies).
+
+### Manually add documentation setup to already existing repository
+
+Prerequisities:
+
+- `catalog-info.yml` file registered to Backstage.
+
+Create a `mkdocs.yml` file in the root of the repository with the following
+content:

 ```yaml
 site_name: 'example-docs'
@@ -37,7 +54,20 @@ plugins:
  - techdocs-core
 ```

-The `~/hello-docs/docs/index.md` should have the following content:
+Update your `catalog-info.yaml` file in the root of the repository with the
+following content:
+
+```yaml
+metadata:
+  annotations:
+    backstage.io/techdocs-ref: dir:./
+```
+
+Create a `/docs` folder in the root of the project with at least a `index.md`
+file. _(If you add more markdown files, make sure to update the nav in the
+mkdocs.yml file to get a proper navigation for your documentation.)_
+
+The `docs/index.md` can for example have the following content:

 ```md
 # example docs
@@ -45,6 +75,9 @@ The `~/hello-docs/docs/index.md` should have the following content:
 This is a basic example of documentation.
 ```

+Commit your changes, open a pull request and merge. You will now get your
+updated documentation next time you run Backstage!
+
 ## Writing and previewing your documentation

 Using the `techdocs-cli` you can preview your docs inside a local Backstage
@@ -54,83 +87,6 @@ want to write your documentation.
 To do this you can run:

 ```bash
-cd ~/hello-docs/
+cd ~/<repository-path>/
 npx techdocs-cli serve
 ```
-
-## Build production ready documentation
-
-To get a build suitable for publication you can build your docs using the
-`spotify/techdocs` container:
-
-```bash
-cd ~/hello-docs/
-docker run -it -w /content -v $(pwd):/content spotify/techdocs build
-```
-
-You should now have a folder called `~/hello-docs/site/`.
-
-## Deploy to a file server
-
-In order to serve documentation to TechDocs, our Backstage plugin needs to
-download the HTML rendered from the previous step. This will likely exist on an
-external file server, or a storage solution such as Google Cloud Storage.
-
-When deploying documentation, it should be deployed on that file server/storage
-solution with the following convention: `{id}/{file}`. For example, if you want
-to upload the `getting-started/index.html` file for the `backstage`
-documentation site, we would upload it to our file server as
-`backstage/getting-started/index.html`.
-
-To explain further what this would look like for multiple documentation sites,
-take a look at this example file tree that would be represented on your file
-server:
-
-```md
-/backstage/index.html /backstage/getting-started/index.html
-/backstage/contributing/index.html /mkdocs/index.html
-/mkdocs/plugin-development/index.html
-/mkdocs/plugin-development/debugging/index.html
-```
-
-In this file tree, we have two documentation sites available: `backstage` and
-`mkdocs`. Each of them expose several pages. Let's say both of these are hosted
-on `http://example.com` as the server URL.
-
-When you configure the TechDocs plugin in Backstage to use `http://example.com`
-as the file server/storage solution, it will translate the following URLs to the
-file server:
-
-| Backstage URL                                             | File Server URL                                         |
-| --------------------------------------------------------- | ------------------------------------------------------- |
-| https://demo.backstage.io/docs/backstage/                 | http://example.com/backstage/index.html                 |
-| https://demo.backstage.io/docs/mkdocs/plugin-development/ | http://example.com/mkdocs/plugin-development/index.html |
-
-Then deploying new sites is easy: simply copy over the `site/` folder produced
-in the [Create documentation](#build-production-ready-documentation) step above
-to the file server/storage solution under the ID of the documentation site. It
-will then become immediately available in Backstage under the same ID as you can
-see in the table above.
-
-So, if the URL to your file server is `http://example.com/`, your
-`~/hello-docs/site` folder containing the documentation should be accessible at
-`http://example.com/hello-docs/`.
-
-## Configure TechDocs to read from file server
-
-In order for Backstage to show your documentation, it needs to know where you
-uploaded it.
-
-Make sure you have Backstage set up using
-[TechDocs getting started](getting-started.md).
-
-To point Backstage to your docs storage, add or change the following lines in
-your Backstage `app-config.yaml`:
-
-```yaml
-techdocs:
-  storageUrl: http://example.com
-```
-
-You can now start Backstage using `yarn start` and open up your browser at
-`http://localhost:3000/docs/hello-docs` to view your docs.
@@ -3,16 +3,6 @@ id: getting-started
 title: Getting Started
 ---

-> TechDocs is not yet feature complete - currently you can't set up a complete
-> end-to-end working TechDocs plugin without customizing the plugin itself.
-
-> What you can expect from TechDocs V.0 is a demonstration of how to integrate
-> docs into Backstage. TechDocs can create docs using
-> [mkdocs](https://www.mkdocs.org/), as well as read published docs. If you
-> publish generated docs and pass in a `storageUrl` in your `app-config.yaml`,
-> you can view them in Backstage by going to
-> `http://localhost:3000/docs/<remote-folder>`.
-
 TechDocs functions as a plugin to Backstage, so you will need to use Backstage
 to use TechDocs.

@@ -48,8 +38,8 @@ containing your new Backstage application.

 ## Installing TechDocs

-TechDocs is not provided with the Backstage application by default, so you will
-now need to set up TechDocs manually. It should take less than a minute.
+TechDocs is provided with the Backstage application by default. If you want to
+set up TechDocs manually, keep follow the instructions below.

 ### Adding the package

@@ -84,19 +74,29 @@ export { plugin as TechDocs } from '@backstage/plugin-techdocs';
 ### Setting the configuration

 TechDocs allows for configuration of the docs storage URL through your
-`app-config` file. The URL provided here is for demo docs to use for testing
-purposes.
+`app-config` file.

-To use the demo docs, add the following lines to `app-config.yaml`:
+The default storage URL:

 ```yaml
 techdocs:
-  storageUrl: https://techdocs-mock-sites.storage.googleapis.com
+  storageUrl: http://localhost:7000/techdocs/static/docs
 ```

+If you want to configure this to point to another storage URL, change the value
+of `storageUrl`.
+
 ## Run Backstage locally

-Change folder to your Backstage application root and run the following command:
+Change folder to `<backstage-project-root>/packages/backend` and run the
+following command:
+
+```bash
+yarn start
+```
+
+Open a new command line window. Change directory to your Backstage application
+root and run the following command:

 ```bash
 yarn start
@@ -85,7 +85,3 @@ yarn create-plugin # Create a new plugin
 > See
 > [package.json](https://github.com/spotify/backstage/blob/master/package.json)
 > for other yarn commands/options.
-
-[Next Step - Create a Backstage plugin](../plugins/create-a-plugin.md)
-
-[Back to Docs](../README.md)
@@ -3,9 +3,22 @@ id: index
 title: Running Backstage Locally
 ---

+First make sure you are using NodeJS with an Active LTS Release, currently v12.
+This is made easy with a version manager such as nvm which allows for version switching.
+
+```bash
+# Checking your version
+node --version
+> v14.7.0
+
+# Adding a second node version
+nvm install 12
+> Downloading and installing node v12.18.3...
+> Now using node v12.18.3 (npm v6.14.6)
+```
+
 To get up and running with a local Backstage to evaluate it, let's clone it off
-of GitHub and run an initial build. First make sure that you have at least node
-version 12 installed locally.
+of GitHub and run an initial build.

 ```bash
 # Start from your local development folder
@@ -0,0 +1,160 @@
+---
+id: adopting
+title: Strategies for adopting
+---
+
+This document outlines some general best practices that have been key to
+Backstage's success inside Spotify. Every organization is different and some of
+these learnings will therefore not be applicable for your company. We are hoping
+that this can become a living document, and strongly encourage you to contribute
+back whatever learnings you gather while adopting Backstage inside your company.
+
+## Organizational setup
+
+The true value of Backstage is unlocked when it becomes _THE_ developer portal
+at your company. As such it is important to recognize that you will need a
+central team that owns your Backstage deployment and treats it like a product.
+
+This team will have **four** primary objectives:
+
+1. Maintain and operate your deployment of Backstage. This includes customer
+   support, infrastructure, CI/CD and, as your Backstage product grows, on-call
+   support.
+
+2. Drive adoption of customers (developers at your company).
+
+3. Work with senior tech leadership and architects to ensure your organizations
+   best practices for software development are encoded into a set of
+   [Software Templates](../features/software-templates/index.md).
+
+4. Evangelize Backstage as a central platform towards other
+   infrastructure/platform teams.
+
+## Internal evangelization
+
+The last objective deserves more attention, since it is the least obvious, but
+also the most critical to successfully creating a consolidated platform. When
+done right, Backstage acts as a "platform of platforms" or marketplace between
+infra/platform teams and end-users:
+
+![pop](../assets/pop.png)
+
+While anyone at your company can contribute to the platform, the vast majority
+of work will be done by teams that also has internal engineers as their
+customers. The central team should treat these _contributing teams_ as customers
+of the platform as well.
+
+These teams should be able to autonomously deliver value directly to their
+customers. This is done primarily by building [plugins](../plugins/index.md).
+Contributing teams should themselves treat their plugins as, or part of, the
+products they maintain.
+
+> Case study: Inside Spotify we have a team that owns our CI platform. They
+> don't only maintain the pipelines and build servers, but also expose their
+> product in Backstage through a plugin. Since they also
+> [maintain their own API](../plugins/call-existing-api.md), they can improve
+> their product by iterating on API and UI in lockstep. Because the plugin
+> follows our [platform design guidelines](../dls/design.md) their customers get
+> a CI experience that is consistent with other tools on the platform (and users
+> don't have to become experts in Jenkins).
+
+### Tactics
+
+Example of tactics we have used to evangelize Backstage internally:
+
+- Arrange "Lunch & Learns" and seminars. Frequently offer teams interested in
+  Backstage development to come to a seminar where you show, for example, how to
+  build a plugin from scratch.
+
+- Embedding. As contributing teams start development of their first plugin it is
+  often very appreciated to have one person from the central team come over and
+  "embed" for a Sprint or two.
+
+- Hack days. Backstage-focused Hackathons or hack days is a fun way to get
+  people into plugin development.
+
+- Show & tell meetings. In order to build an internal community around Backstage
+  we have quarterly meetings where anyone working on Backstage is invited to
+  present their work. This is a not only a great way to get early feedback, but
+  also helps coordination between teams that are building overlapping
+  experiences.
+
+- Provide metrics. Add instrumentation to your Backstage deployment and make
+  metrics available to contributing teams. At Spotify we have even gone so far
+  as sending out weekly digest email showing how usage metrics have changed for
+  individual plugins.
+
+- Pro-actively identify new plugins. Reach out to teams that own internal UIs or
+  platforms that you think would make sense to consolidate into Backstage.
+
+## KPIs and metrics
+
+These are some of the metrics that you can use to verify if Backstage has a
+successful impact on your software development process:
+
+- **Onboarding time** Time until new engineers are productive. At Spotify we
+  measure this as the time until the employee has merged their 10th PR (this
+  metric was down 55% two years after deploying Backstage). Even though you may
+  not be onboarding engineers at a rapid pace, this metric is a great proxy for
+  the overall complexity of your ecosystem. Reducing it will therefore benefit
+  your whole engineering organization, not just new joiners.
+
+- **Number of merges per developer/day** Less time spent jumping between
+  different tools and looking for information means more time to focus on
+  shipping code. A second level of bottlenecks can be identified if you
+  categorize contributions by domain (services, web, data, etc).
+
+- **Deploys to production** Cousin to the metric above: How many times does an
+  engineer push changes into production.
+
+- **MTTR** With clear ownership of all the pieces in your micro services
+  ecosystem and all tools integrated into one place, Backstage makes it quicker
+  for teams to find the root cause of failures, and fix them.
+
+- **Context switching** Reducing context switching can help engineers stay in
+  the "zone". We measure the number of different tools an engineer have to
+  interact with in order to get a certain job done (e.g. push a change, follow
+  it into production and validate it did not break anything).
+
+- **T-shapedness** A
+  [T-shaped](https://medium.com/@jchyip/why-t-shaped-people-e8706198e437)
+  engineer is someone that is able to contribute to different domains of
+  engineering. Teams with T-shaped people have fewer bottlenecks and can
+  therefore deliver more consistently. Backstage makes it easier to be T-shaped
+  since tools and infrastructure is consistent between domains, and information
+  is available centrally.
+
+- **eNPS** Surveys asking about how productive people feel, how easy it is to
+  find information and overall satisfaction with internal tools.
+
+- **Fragmentation** _(Experimental)_ Backstage
+  [Software Templates](../features/software-templates/index.md) helps drive
+  standardization in your software ecosystem. By measuring the variance in
+  technology between different software components it is possible to get a sense
+  of the overall fragmentation in your ecosystem. Examples could include:
+  framework versions, languages, deployment methods and various code quality
+  measurements.
+
+Additionally, these proxy metrics can be used to validate the success of
+Backstage as _the_ platform:
+
+- Nr of teams that have contributed at least one plugin (currently 63 inside
+  Spotify)
+
+- Nr of total plugins (currently 135 inside Spotify)
+
+- % of contributions coming from outside the central Backstage team (currently
+  85% inside Spotify)
+
+- Traditional metrics such as visits (MAU, DAU, etc) and page views. Currently
+  ~50% of all Spotifiers use Backstage on a monthly basis, even though the
+  percentage of engineers is below 50%. Most engineers actually use Backstage on
+  a daily basis.
+
+Again, any feedback is appreciated. Please use the Edit button at the top of the
+page to make a suggestion.
+
+_**Note!** It might be tempting to try to optimize Backstage usage and
+"engagement". Even though you want to consolidate all your tooling and technical
+documentation in Backstage, it is important to remember that time spent in
+Backstage is time not spent writing code_ 🙃
@@ -0,0 +1,30 @@
+---
+id: background
+title: The Spotify Story
+---
+
+Backstage was born out of necessity at Spotify. We found that as we grew, our
+infrastructure was becoming more fragmented, our engineers less productive.
+
+Instead of building and testing code, teams were spending more time looking for
+the right information just to get started. “Where’s the API for that service
+we’re all supposed to be using?” “What version of that framework is everyone
+on?” “This service isn’t responding, who owns it?” “I can’t find documentation
+for anything!”
+
+Context switching and cognitive overload were dragging engineers down, day by
+day. We needed to make it easier for our engineers to do their work without
+having to become an expert in every aspect of infrastructure tooling.
+
+Our idea was to centralize and simplify end-to-end software development with an
+abstraction layer that sits on top of all of our infrastructure and developer
+tooling. That’s Backstage.
+
+It’s a developer portal powered by a centralized service catalog — with a plugin
+architecture that makes it endlessly extensible and customizable.
+
+Manage all your services, software, tooling, and testing in Backstage. Start
+building a new microservice using an automated template in Backstage. Create,
+maintain, and find the documentation for all that software in Backstage.
+
+One place for everything. Accessible to everyone.
@@ -18,12 +18,15 @@ Out of the box, Backstage includes:
 - [Backstage Service Catalog](../features/software-catalog/index.md) for
  managing all your software (microservices, libraries, data pipelines,
  websites, ML models, etc.)
+
 - [Backstage Software Templates](../features/software-templates/index.md) for
  quickly spinning up new projects and standardizing your tooling with your
  organization’s best practices
+
 - [Backstage TechDocs](../features/techdocs/README.md) for making it easy to
  create, maintain, find, and use technical documentation, using a "docs like
  code" approach
+
 - Plus, a growing ecosystem of
  [open source plugins](https://github.com/spotify/backstage/tree/master/plugins)
  that further expand Backstage’s customizability and functionality
@@ -33,12 +36,15 @@ Out of the box, Backstage includes:
 - For _engineering managers_, it allows you to maintain standards and best
  practices across the organization, and can help you manage your whole tech
  ecosystem, from migrations to test certification.
+
 - For _end users_ (developers), it makes it fast and simple to build software
  components in a standardized way, and it provides a central place to manage
  all projects and documentation.
+
 - For _platform engineers_, it enables extensibility and scalability by letting
  you easily integrate new tools and services (via plugins), as well as
  extending the functionality of existing ones.
+
 - For _everyone_, it’s a single, consistent experience that ties all your
  infrastructure tooling, resources, standards, owners, contributors, and
  administrators together in one place.
@@ -0,0 +1,23 @@
+---
+id: add-to-marketplace
+title: Add to Marketplace
+---
+
+## Adding a Plugin to the Marketplace
+
+To add a new plugin to the [plugin marketplace](https://backstage.io/plugins)
+create a file in `data/plugins` with your plugin's information. Example:
+
+```yaml
+---
+title: Your Plugin
+author: Your Name
+authorUrl: # A link to information about the author E.g. Company url, github user profile, etc
+category: Monitoring # A single category e.g. CI, Machine Learning, Services, Monitoring
+description: A brief description of the plugin. # Max 170 characters
+documentation: # A link to your documentation E.g. Your github README
+iconUrl: # Used as the src attribute for your logo.
+# You can provide an external url or add your logo under static/img and provide a path
+# relative to static/ e.g. img/my-logo.png
+npmPackageName: # Your npm package name E.g. '@backstage/plugin-<etc>' quotes are required
+```
@@ -71,11 +71,7 @@ Example:
 ```yaml
 # In app-config.yaml
 proxy:
-  '/frobs':
-    target: 'http://api.frobsco.com/v1'
-    changeOrigin: true
-    pathRewrite:
-      '^/proxy/frobs/': '/'
+  '/frobs': http://api.frobsco.com/v1
 ```

 ```ts
@@ -86,9 +82,8 @@ fetch(`${backendUrl}/proxy/frobs/list`)
  .then(payload => setFrobs(payload as Frob[]));
 ```

-The proxy is powered by the `http-proxy-middleware` package, and supports all of
-its
-[configuration options](https://github.com/chimurai/http-proxy-middleware#options).
+The proxy is powered by the `http-proxy-middleware` package. See
+[Proxying](proxying.md) for a full description of its configuration options.

 Internally at Spotify, the proxy option has been the overwhelmingly most popular
 choice for plugin makers. Since we have DNS based service discovery in place and
@@ -15,20 +15,16 @@ dependencies, then run the following on your command line (invoking the
 yarn create-plugin
 ```

-<p align='center'>
-    <img src='https://github.com/spotify/backstage/raw/master/docs/getting-started/create-plugin_output.png' width='600' alt='create plugin'>
-</p>
+![](../assets/getting-started/create-plugin_output.png)

 This will create a new Backstage Plugin based on the ID that was provided. It
 will be built and added to the Backstage App automatically.

-_If `yarn start` is already running you should be able to see the default page
-for your new plugin directly by navigating to
-`http://localhost:3000/my-plugin`._
+> If `yarn start` is already running you should be able to see the default page
+> for your new plugin directly by navigating to
+> `http://localhost:3000/my-plugin`.

-<p align='center'>
-    <img src='https://github.com/spotify/backstage/raw/master/docs/plugins/my-plugin_screenshot.png' width='600' alt='my plugin'>
-</p>
+![](../assets/my-plugin_screenshot.png)

 You can also serve the plugin in isolation by running `yarn start` in the plugin
 directory. Or by using the yarn workspace command, for example:
@@ -40,7 +36,3 @@ yarn workspace @backstage/plugin-welcome start # Also supports --check
 This method of serving the plugin provides quicker iteration speed and a faster
 startup and hot reloads. It is only meant for local development, and the setup
 for it can be found inside the plugin's `dev/` directory.
-
-[Next Step - Structure of a plugin](structure-of-a-plugin.md)
-
-[Back to Getting Started](../README.md)
@@ -1,6 +1,6 @@
 ---
 id: index
-title: Intro
+title: Intro to plugins
 ---

 Backstage is a single-page application composed of a set of plugins.
@@ -1,6 +1,6 @@
 ---
 id: plugin-development
-title: Plugin Development in Backstage
+title: Plugin Development
 ---

 Backstage plugins provide features to a Backstage App.
@@ -10,28 +10,12 @@ type of content. Plugins all use a common set of platform APIs and reusable UI
 components. Plugins can fetch data from external sources using the regular
 browser APIs or by depending on external modules to do the work.

-<!-- MOVED TO create-a-plugin.md ## Creating a new plugin
-On your command line, invoke the `backstage-cli` to create a new plugin:
-```bash
-yarn create-plugin
-```
-
-![](create-plugin_output.png)
-
-This will create a new Backstage Plugin based on the ID that was provided. It will be built and
-added to the Backstage App automatically.
-
-*If `yarn start` is already running you should be able to see the default page for your new
-plugin directly by navigating to `http://localhost:3000/my-plugin`.*
-
-![](my-plugin_screenshot.png) -->
-
 ## Developing guidelines

 - Consider writing plugins in `TypeScript`.
 - Plan the directory structure of your plugin so that it becomes easy to manage.
- Prefer using the Backstage components, otherwise go with
-  [Material-UI](https://material-ui.com/).
+- Prefer using the [Backstage components](https://backstage.io/storybook),
+  otherwise go with [Material-UI](https://material-ui.com/).
 - Check out the shared Backstage APIs before building a new one.

 ## Plugin concepts / API
@@ -3,4 +3,73 @@ id: proxying
 title: Proxying
 ---

-## TODO
+## Overview
+
+The Backstage backend comes packaged with a basic HTTP proxy, that can aid in
+reaching backend service APIs from frontend plugin code. See
+[Call Existing API](call-existing-api.md) for a description of when the proxy
+can be the best choice for communicating with an API.
+
+## Getting Started
+
+The plugin is already added to a default Backstage project.
+
+In `packages/backend/src/index.ts`:
+
+```ts
+const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));
+
+const service = createServiceBuilder(module)
+  .loadConfig(configReader)
+  /** ... other routers ... */
+  .addRouter('/proxy', await proxy(proxyEnv, '/proxy'));
+```
+
+## Configuration
+
+Configuration for the proxy plugin lives under a `proxy` root key of your
+`app-config.yaml` file.
+
+Example:
+
+```yaml
+# in app-config.yaml
+proxy:
+  '/simple-example': http://simple.example.com:8080
+  '/larger-example/v1':
+    target: http://larger.example.com:8080/svc.v1
+    headers:
+      Authorization:
+        $secret:
+          env: EXAMPLE_AUTH_HEADER
+```
+
+Each key under the proxy configuration entry is a route to match, below the
+prefix that the proxy plugin is mounted on. It must start with a slash. For
+example, if the backend mounts the proxy plugin as `/proxy`, the above
+configuration will lead to the proxy acting on backend requests to
+`/proxy/simple-example/...` and `/proxy/larger-example/v1/...`.
+
+The value inside each route is either a simple URL string, or an object on the
+format accepted by
+[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware).
+
+If the value is a string, it is assumed to correspond to:
+
+```yaml
+target: <the string>
+changeOrigin: true
+pathRewrite:
+  '^<url prefix><the string>/': '/'
+```
+
+When the target is an object, it is given verbatim to `http-proxy-middleware`
+except with the following caveats for convenience:
+
+- If `changeOrigin` is not specified, it is set to `true`. This is the most
+  commonly useful value.
+- If `pathRewrite` is not specified, it is set to a single rewrite that removes
+  the entire prefix and route. In the above example, a rewrite of
+  `'^/proxy/larger-example/v1/': '/'` is added. That means that a request to
+  `/proxy/larger-example/v1/some/path` will be translated to a request to
+  `http://larger.example.com:8080/svc.v1/some/path`.
@@ -37,5 +37,3 @@ const myPluginRouteRef = createRouteRef({
  title: 'My Plugin',
 });
 ```
-
-[Back to References](../README.md)
@@ -55,7 +55,7 @@ ApiRef:

 ## githubAuth

-Provides authentication towards Github APIs
+Provides authentication towards GitHub APIs

 Implemented types: [OAuthApi](./OAuthApi.md),
 [ProfileInfoApi](./ProfileInfoApi.md),
@@ -67,7 +67,7 @@ ApiRef:

 ## gitlabAuth

-Provides authentication towards Gitlab APIs
+Provides authentication towards GitLab APIs

 Implemented types: [OAuthApi](./OAuthApi.md),
 [ProfileInfoApi](./ProfileInfoApi.md),
@@ -1,6 +0,0 @@
---
-id: index
-title: Overview
---
-
-## Coming soon!
@@ -1,12 +1,15 @@
-# Purpose
+---
+id: journey
+title: Future developer journey
+---

-This RFC describes a possible journey of a future Backstage plugin developer as
-they build a plugin that touches many different aspects of a Backstage. The
-story invents many new things that are not part of Backstage today, but are
-things that I'm suggesting we should add as long term or north star goals. The
-idea is to discuss what parts of the story makes sense to aim for, and what we'd
-want to do differently or not at all. The "chapters" are numbered to make it a
-bit easier to comment on parts of the story.
+> This document describes a possible journey of a **_future_** Backstage plugin
+> developer as they build a plugin that touches many different aspects of a
+> Backstage. The story invents many new things that are not part of Backstage
+> today, but are things that I'm suggesting we should add as long term or north
+> star goals. The idea is to discuss what parts of the story makes sense to aim
+> for, and what we'd want to do differently or not at all. The "chapters" are
+> numbered to make it a bit easier to comment on parts of the story.

 # The Protagonist

@@ -23,7 +23,7 @@
 | app.resources               | Kubernetes Pod resource requests/limits                   | `{}`                |
 | app.nodeSelector            | Node selectors for scheduling app/frontend pods           | `{}`                |
 | app.tolerations             | Tolerations for scheduling app/frontend pods              | `{}`                |
-| app.affinity                | Affinity setttings for scheduling app/frontend pods       | `{}`                |
+| app.affinity                | Affinity settings for scheduling app/frontend pods        | `{}`                |

 ## Backend Values

@@ -48,4 +48,4 @@
 | backend.resources               | Kubernetes Pod resource requests/limits                       | `{}`                |
 | backend.nodeSelector            | Node selectors for scheduling backend pods                    | `{}`                |
 | backend.tolerations             | Tolerations for scheduling backend pods                       | `{}`                |
-| backend.affinity                | Affinity setttings for scheduling backend pods                | `{}`                |
+| backend.affinity                | Affinity settings for scheduling backend pods                 | `{}`                |
@@ -2,5 +2,5 @@
  "packages": ["packages/*", "plugins/*"],
  "npmClient": "yarn",
  "useWorkspaces": true,
-  "version": "0.1.1-alpha.18"
+  "version": "0.1.1-alpha.20"
 }
@@ -13,7 +13,7 @@ Two days ago, we released the open source version of [Backstage](https://backsta

 ## What’s the big infrastructure problem?

-As companies grow, their infrastructure systems get messier. Consider a team that wants to deploy something to the cloud. While Spotify has many awesome engineers, not every engineer is well-versed in our chosen cloud-provider tooling. Yet everyone is required to know and understand Terraform, GCP/AWS/Azure CLIs, Gitlab CI, Prometheus, Kubernetes, Docker, various monitoring and alerting tools, and much, much more. Once other resources come into play (databases, queueing, etc.), each engineer requires even more tools and domain-specific knowledge (or “disciplines”), from backend to machine learning, to mobile and data.
+As companies grow, their infrastructure systems get messier. Consider a team that wants to deploy something to the cloud. While Spotify has many awesome engineers, not every engineer is well-versed in our chosen cloud-provider tooling. Yet everyone is required to know and understand Terraform, GCP/AWS/Azure CLIs, GitLab CI, Prometheus, Kubernetes, Docker, various monitoring and alerting tools, and much, much more. Once other resources come into play (databases, queueing, etc.), each engineer requires even more tools and domain-specific knowledge (or “disciplines”), from backend to machine learning, to mobile and data.

 ## What’s the fix?

@@ -0,0 +1,9 @@
+---
+title: CircleCI
+author: Spotify
+authorUrl: https://www.spotify.com/
+category: CI
+description: Automate your development process with CI hosted in the cloud or on a private server.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/circleci
+iconUrl: https://d3r49iyjzglexf.cloudfront.net/logo-wordmark-26f8eaea9b0f6e13b90d3f4a8fd8fda31490f5af41daab98bbede45037682576.svg
+npmPackageName: '@backstage/plugin-circleci'
@@ -0,0 +1,14 @@
+---
+title: GitOps Clusters
+author: Weaveworks
+authorUrl: https://www.weave.works/
+category: Kubernetes
+description: Create GitOps-managed Kubernetes clusters. Currently, it supports provisioning EKS clusters on GitHub via GitHub Actions.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/gitops-profiles
+iconUrl: https://res-5.cloudinary.com/crunchbase-production/image/upload/c_lpad,h_256,w_256,f_auto,q_auto:eco/v1462316670/i9d3delzvx1erzjhmcws.png
+npmPackageName: '@backstage/plugin-gitops-profiles'
+tags:
+  - kubernetes
+  - gitops
+  - github
+  - eks
@@ -0,0 +1,13 @@
+---
+title: GraphiQL
+author: Spotify
+authorUrl: https://www.spotify.com/
+category: Debugging
+description: Integrates GraphiQL as a tool to browse GraphiQL endpoints inside Backstage.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/lighthouse
+iconUrl: https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/GraphQL_Logo.svg/1024px-GraphQL_Logo.svg.png
+npmPackageName: '@backstage/plugin-graphiql'
+tags:
+  - graphql
+  - github
+  - gitlab
@@ -0,0 +1,14 @@
+---
+title: Lighthouse
+author: Spotify
+authorUrl: https://www.spotify.com/
+category: Accessibility
+description: Google's Lighthouse tool is a great resource for benchmarking and improving the accessibility, performance, SEO, and best practices of your website.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/lighthouse
+iconUrl: https://seeklogo.com/images/G/google-lighthouse-logo-1C7FA08580-seeklogo.com.png
+npmPackageName: '@backstage/plugin-lighthouse'
+tags:
+  - web
+  - seo
+  - accessibility
+  - performance
@@ -0,0 +1,14 @@
+---
+title: New Relic
+author: '@timwheelercom'
+authorUrl: https://github.com/timwheelercom
+category: Monitoring
+description: Observability platform built to help engineers create and monitor their software.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/newrelic
+iconUrl: https://www.mulesoft.com/sites/default/files/2018-10/New_relic.png
+npmPackageName: '@backstage/plugin-newrelic'
+tags:
+  - performance
+  - monitoring
+  - errors
+  - alerting
@@ -0,0 +1,10 @@
+---
+title: Rollbar
+author: '@andrewthauer'
+authorUrl: https://github.com/andrewthauer
+category: Monitoring
+description: View Rollbar errors for your services in Backstage.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/rollbar
+iconUrl: https://rollbar.com/assets/media/rollbar-mark-color.png
+npmPackageName: '@backstage/plugin-rollbar'
+
@@ -0,0 +1,10 @@
+---
+title: Sentry
+author: Spotify
+authorUrl: https://www.spotify.com/
+category: Monitoring
+description: View Sentry issues in Backstage.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/sentry
+iconUrl: https://sentry-brand.storage.googleapis.com/sentry-glyph-white.png
+npmPackageName: '@backstage/plugin-sentry'
+
@@ -0,0 +1,9 @@
+---
+title: Tech Radar
+author: Spotify
+authorUrl: https://www.spotify.com/
+category: Discovery
+description: Visualize the your company's official guidelines of different areas of software development.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/tech-radar
+iconUrl: https://github.com/spotify/backstage/raw/master/plugins/tech-radar/docs/screenshot.png
+npmPackageName: '@backstage/plugin-tech-radar'
@@ -0,0 +1,10 @@
+---
+title: Travis CI
+author: roadie.io
+authorUrl: https://roadie.io/
+category: CI
+description: View Travis CI builds for your service in Backstage.
+documentation: https://roadie.io/backstage/plugins/travis-ci
+iconUrl: https://roadie.io/static/af2941eaf0af675facb281d566f42e14/45f2b/travis-ci-mascot-200x200.png
+npmPackageName: '@roadiehq/backstage-plugin-travis-ci'
+
@@ -51,7 +51,7 @@
        "title": "Adding authentication providers"
      },
      "auth/auth-backend-classes": {
-        "title": "auth/auth-backend-classes"
+        "title": "Auth backend classes"
      },
      "auth/auth-backend": {
        "title": "Auth backend"
@@ -103,7 +103,8 @@
        "title": "External integrations"
      },
      "features/software-catalog/software-catalog-overview": {
-        "title": "Backstage Service Catalog (alpha)"
+        "title": "Backstage Service Catalog (alpha)",
+        "sidebar_label": "Backstage Service Catalog"
      },
      "features/software-catalog/installation": {
        "title": "features/software-catalog/installation"
@@ -174,8 +175,8 @@
      "getting-started/installation": {
        "title": "Installation"
      },
-      "journey": {
-        "title": "journey"
+      "overview/adopting": {
+        "title": "Strategies for adopting"
      },
      "overview/architecture-overview": {
        "title": "Architecture overview"
@@ -183,6 +184,9 @@
      "overview/architecture-terminology": {
        "title": "Architecture terminology"
      },
+      "overview/background": {
+        "title": "The Spotify Story"
+      },
      "overview/roadmap": {
        "title": "Project roadmap"
      },
@@ -195,6 +199,9 @@
      "overview/what-is-backstage": {
        "title": "What is Backstage?"
      },
+      "plugins/add-to-marketplace": {
+        "title": "Add to Marketplace"
+      },
      "plugins/backend-plugin": {
        "title": "Backend plugin"
      },
@@ -208,13 +215,13 @@
        "title": "Existing plugins"
      },
      "plugins/index": {
-        "title": "Intro"
+        "title": "Intro to plugins"
      },
      "plugins/integrating-plugin-into-service-catalog": {
        "title": "Integrate into the catalog service"
      },
      "plugins/plugin-development": {
-        "title": "Plugin Development in Backstage"
+        "title": "Plugin Development"
      },
      "plugins/proxying": {
        "title": "Proxying"
@@ -285,16 +292,16 @@
      "reference/utility-apis/StorageApi": {
        "title": "reference/utility-apis/StorageApi"
      },
-      "tutorials/index": {
-        "title": "Overview"
+      "tutorials/journey": {
+        "title": "Future developer journey"
      }
    },
    "links": {
      "GitHub": "GitHub",
      "Docs": "Docs",
+      "Plugins": "Plugins",
      "Blog": "Blog",
      "Demos": "Demos",
-      "The Spotify story": "The Spotify story",
      "Newsletter": "Newsletter"
    },
    "categories": {
@@ -1,5 +1,5 @@
 {
-  "version": "0.1.1-alpha.19",
+  "version": "0.1.1-alpha.20",
  "name": "backstage-microsite",
  "license": "Apache-2.0",
  "private": true,
@@ -13,6 +13,7 @@
    "rename-version": "docusaurus-rename-version"
  },
  "devDependencies": {
-    "docusaurus": "^2.0.0-alpha.61"
+    "docusaurus": "^2.0.0-alpha.61",
+    "js-yaml": "^3.14.0"
  }
 }
@@ -1,122 +0,0 @@
-/**
- * Copyright (c) 2017-present, Facebook, Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-const React = require('react');
-const Components = require(`${process.cwd()}/core/Components.js`);
-const Block = Components.Block;
-const Breakpoint = Components.Breakpoint;
-
-const Background = props => {
-  const { config: siteConfig } = props;
-  const { baseUrl } = siteConfig;
-  return (
-    <div className="mainWrapper">
-      <Block>
-        <Block.Container column>
-          <Block.TitleBox story>The Spotify Story</Block.TitleBox>
-          <Block.TextBox>
-            <Block.Paragraph>
-              Backstage was born out of necessity at Spotify. We found that as
-              we grew, our infrastructure was becoming more fragmented, our
-              engineers less productive.{' '}
-            </Block.Paragraph>
-
-            <Block.Paragraph>
-              Instead of building and testing code, teams were spending more
-              time looking for the right information just to get started.
-              “Where’s the API for that service we’re all supposed to be using?”
-              “What version of that framework is everyone on?” “This service
-              isn’t responding, who owns it?” “I can’t find documentation for
-              anything!”{' '}
-            </Block.Paragraph>
-            <Breakpoint
-              narrow={
-                <Block small>
-                  <Block.QuoteContainer>
-                    <Block.Divider quote />
-
-                    <Block.Quote>
-                      One place for everything. Accessible to everyone.
-                    </Block.Quote>
-                  </Block.QuoteContainer>
-                </Block>
-              }
-            ></Breakpoint>
-            <Block.Paragraph>
-              Context switching and cognitive overload were dragging engineers
-              down, day by day. We needed to make it easier for our engineers to
-              do their work without having to become an expert in every aspect
-              of infrastructure tooling.
-            </Block.Paragraph>
-
-            <Block.Paragraph>
-              Our idea was to centralize and simplify end-to-end software
-              development with an abstraction layer that sits on top of all of
-              our infrastructure and developer tooling. That’s Backstage.
-            </Block.Paragraph>
-
-            <Block.Paragraph>
-              It’s a developer portal powered by a centralized service catalog —
-              with a plugin architecture that makes it endlessly extensible and
-              customizable.
-            </Block.Paragraph>
-
-            <Block.Paragraph>
-              Manage all your services, software, tooling, and testing in
-              Backstage. Start building a new microservice using an automated
-              template in Backstage. Create, maintain, and find the
-              documentation for all that software in Backstage.{' '}
-            </Block.Paragraph>
-
-            <Block.Paragraph>
-              One place for everything. Accessible to everyone.
-            </Block.Paragraph>
-            <Breakpoint
-              narrow={
-                <Block small>
-                  <Block.LinkButton stretch href={'https://backstage.io/'}>
-                    Explore Features
-                  </Block.LinkButton>
-                </Block>
-              }
-            ></Breakpoint>
-          </Block.TextBox>
-        </Block.Container>
-      </Block>
-      <Breakpoint
-        wide={
-          <Block small>
-            <Block.QuoteContainer>
-              <Block.Divider quote />
-
-              <Block.Quote>
-                One place for everything. Accessible to everyone.
-              </Block.Quote>
-              <Block.LinkButton stretch href={'https://backstage.io/'}>
-                Explore Features
-              </Block.LinkButton>
-            </Block.QuoteContainer>
-          </Block>
-        }
-      ></Breakpoint>
-
-      <div
-        style={{
-          zIndex: -1,
-          position: 'absolute',
-          top: 0,
-          left: 0,
-          right: 0,
-          bottom: 0,
-          backgroundImage: `linear-gradient( to bottom, rgb(18, 18, 18), rgba(0, 0, 0, 0) ), url(../img/dot.svg)`,
-        }}
-      />
-    </div>
-  );
-};
-
-module.exports = Background;
@@ -0,0 +1,12 @@
+const React = require('react');
+const Redirect = require('../../core/Redirect.js');
+
+const siteConfig = require(process.cwd() + '/siteConfig.js');
+
+function Docs() {
+  return (
+    <Redirect redirect="/docs/overview/what-is-backstage" config={siteConfig} />
+  );
+}
+
+module.exports = Docs;
@@ -353,10 +353,20 @@ class Index extends React.Component {
            </Block.TextBox>
            <Breakpoint
              wide={
-                <img
-                  style={{ margin: 'auto' }}
-                  src={`${baseUrl}img/techdocs-web.png`}
-                />
+                <Block.Graphics padding={0}>
+                  <Block.Graphic
+                    x={-55}
+                    y={-5}
+                    width={210}
+                    src={`${baseUrl}img/techdocs-web.png`}
+                  />
+                  <Block.Graphic
+                    x={-55}
+                    y={-5}
+                    width={210}
+                    src={`${baseUrl}img/techdocs2.gif`}
+                  />
+                </Block.Graphics>
              }
            />
          </Block.Container>
@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const fs = require('fs');
+const yaml = require('js-yaml');
+const React = require('react');
+const Components = require(`${process.cwd()}/core/Components.js`);
+const {
+  Block: { Container },
+  BulletLine,
+} = Components;
+
+const pluginsDirectory = require('path').join(process.cwd(), 'data/plugins');
+const pluginMetadata = fs
+  .readdirSync(pluginsDirectory)
+  .map(file =>
+    yaml.safeLoad(fs.readFileSync(`./data/plugins/${file}`, 'utf8')),
+  );
+const truncate = text =>
+  text.length > 170 ? text.substr(0, 170) + '...' : text;
+
+const addPluginDocsLink = '/docs/plugins/add-to-marketplace';
+const defaultIconUrl = 'img/logo-gradient-on-dark.svg';
+
+const Plugins = () => (
+  <main className="MainContent">
+    <div className="PluginPageLayout">
+      <div className="PluginPageHeader">
+        <h2>Plugins</h2>
+        <span>
+          <a
+            className="PluginAddNewButton ButtonFilled"
+            href={addPluginDocsLink}
+          >
+            <b>Add Plugin</b>
+          </a>
+        </span>
+      </div>
+      <BulletLine style={{ width: '100% ' }} />
+      <Container wrapped className="grid">
+        {pluginMetadata.map(
+          ({
+            iconUrl,
+            title,
+            description,
+            author,
+            authorUrl,
+            documentation,
+            category,
+          }) => (
+            <div className="PluginCard">
+              <div className="PluginCardHeader">
+                <img src={iconUrl || defaultIconUrl} alt={title} />
+                <h2 className="PluginCardTitle">{title}</h2>
+                <p className="Author">
+                  by <a href={authorUrl}>{author}</a>
+                </p>
+                <span className="ChipOutlined">{category}</span>
+              </div>
+              <div className="PluginCardBody">
+                <p>{truncate(description)}</p>
+              </div>
+              <Container className="PluginCardFooter">
+                <span>
+                  <a
+                    className="PluginCardLink ButtonFilled"
+                    href={documentation}
+                  >
+                    docs
+                  </a>
+                </span>
+              </Container>
+            </div>
+          ),
+        )}
+      </Container>
+    </div>
+  </main>
+);
+
+module.exports = Plugins;
@@ -5,7 +5,9 @@
      "overview/architecture-overview",
      "overview/architecture-terminology",
      "overview/roadmap",
-      "overview/vision"
+      "overview/vision",
+      "overview/background",
+      "overview/adopting"
    ],
    "Getting Started": [
      "getting-started/index",
@@ -37,7 +39,6 @@
          "features/software-catalog/software-catalog-overview",
          "features/software-catalog/system-model",
          "features/software-catalog/descriptor-format",
-          "features/software-catalog/populating-catalog",
          "features/software-catalog/extending-the-model",
          "features/software-catalog/external-integrations",
          "features/software-catalog/software-catalog-api"
@@ -91,7 +92,7 @@
      {
        "type": "subcategory",
        "label": "Publishing",
-        "ids": ["plugins/publishing", "plugins/publish-private"]
+        "ids": ["plugins/publishing", "plugins/publish-private", "plugins/add-to-marketplace"]
      }
    ],
    "Configuration": [
@@ -132,7 +133,7 @@
        "ids": ["api/backend"]
      }
    ],
-    "Tutorials": ["tutorials/index"],
+    "Tutorials": ["tutorials/journey"],
    "Architecture Decision Records (ADRs)": [
      "architecture-decisions/adrs-overview",
      "architecture-decisions/adrs-adr001",
@@ -17,17 +17,12 @@ const siteConfig = {
  url: 'https://backstage.io', // Your website URL
  cname: 'backstage.io',
  baseUrl: '/', // Base URL for your project */
-  // For github.io type URLs, you would set the url and baseUrl like:
-  //   url: 'https://facebook.github.io',
-  //   baseUrl: '/test-site/',
+  editUrl: 'https://github.com/spotify/backstage/edit/master/docs/',

  // Used for publishing and more
  projectName: 'backstage',
  organizationName: 'Spotify',
  fossWebsite: 'https://spotify.github.io/',
-  // For top-level user or org sites, the organization is still the same.
-  // e.g., for the https://JoelMarcey.github.io site, it would be set like...
-  //   organizationName: 'JoelMarcey'

  // Google Analytics
  gaTrackingId: 'UA-48912878-10',
@@ -35,13 +30,18 @@ const siteConfig = {
  // For no header links in the top nav bar -> headerLinks: [],
  headerLinks: [
    {
-      href: 'https://github.com/spotify/backstage#backstage',
+      href: 'https://github.com/spotify/backstage',
      label: 'GitHub',
    },
    {
      doc: 'overview/what-is-backstage',
+      href: '/docs',
      label: 'Docs',
    },
+    {
+      page: 'plugins',
+      label: 'Plugins',
+    },
    {
      page: 'blog',
      blog: true,
@@ -51,10 +51,6 @@ const siteConfig = {
      page: 'demos',
      label: 'Demos',
    },
-    {
-      page: 'background',
-      label: 'The Spotify story',
-    },
    {
      href: 'https://mailchi.mp/spotify/backstage-community',
      label: 'Newsletter',
@@ -118,6 +114,12 @@ const siteConfig = {
  stylesheets: [
    'https://fonts.googleapis.com/css?family=IBM+Plex+Mono:500,700&display=swap',
  ],
+
+  algolia: {
+    apiKey: '8d115c9875ba0f4feaee95bab55a1645',
+    indexName: 'backstage',
+    searchParameters: {}, // Optional (if provided by Algolia)
+  },
 };

 module.exports = siteConfig;
@@ -58,7 +58,7 @@ ol,
 li,
 td {
  font-family: Helvetica Neue, sans-serif;
-  color: $textColor;
+  color: #e4e4e4;
 }

 .mainWrapper {
@@ -0,0 +1,111 @@
+.PluginCard {
+    background-color: #272822;
+    height: 100%;
+    padding: 16px;
+    display: flex;
+    flex-direction: column;
+}
+
+.grid {
+    display: grid;
+    grid-gap: 1rem;
+    grid-template-columns: repeat(4, 1fr);
+    grid-auto-rows: 1fr;
+    padding-top: 32px;
+}
+
+@media (max-width: 1200px) {
+    .grid {
+        grid-template-columns: repeat(3, 1fr);
+    }
+}
+
+@media only screen and (max-width: 815px) {
+    .grid {
+        grid-template-columns: repeat(2, 1fr);
+    }
+}
+
+.PluginCard img {
+    float: left;
+    margin: 0px 16px 8px 0px;
+    height: 100px;
+    width: 100px;
+}
+
+.PluginCardHeader {
+    max-height: fit-content;
+    min-height: fit-content;
+}
+
+.PluginCardTitle {
+    color:  white;
+    vertical-align: top;
+    margin: 8px 0px 0px 16px;
+}
+
+.PluginAddNewButton {
+    position: absolute;
+    bottom: 16px;
+    right: 0px;
+}
+
+.ButtonFilled {
+    padding: 4px 8px;
+    border-radius: 4px;
+    background-color: #36BAA2;
+    color: white;
+    margin-top: 36px;
+}
+
+.ButtonFilled:hover {
+    border: 1px solid #36BAA2;
+    background-color: transparent;
+}
+
+.ChipOutlined {
+    font-size: small;
+    border-radius: 16px;
+    padding: 2px 8px;
+    border: 1px solid #36BAA2;
+    color: #36BAA2;
+}
+
+.PluginCardLink {
+    padding: 2px 8px;
+    position: absolute;
+    bottom: 0;
+    right: 0;
+}
+
+.PluginPageLayout {
+    margin: auto;
+    max-width: 1430px;
+    padding: 20px;
+}
+
+.PluginPageHeader {
+    position: relative;
+}
+
+.PluginPageHeader h2 {
+    display: inline-block;
+}
+
+.PluginCardBody {
+    padding-top: 8px;
+}
+
+.PluginCardFooter {
+    position: relative;
+    min-height: 2em;
+}
+
+.Author, .Author a {
+    margin-bottom: 0.25em;
+    color: rgba(255,255,255, 0.6);
+}
+
+ .Author a:hover {
+    color: white;
+}
@@ -8,6 +8,8 @@ nav:
      - Architecture and terminology: 'overview/architecture-terminology.md'
      - Roadmap: 'overview/roadmap.md'
      - Vision: 'overview/vision.md'
+      - The Spotify story: 'overview/background.md'
+      - Strategies for adopting: 'overview/adopting.md'
  - Getting started:
      - Running Backstage locally: 'getting-started/index.md'
      - Installation: 'getting-started/installation.md'
@@ -26,6 +28,7 @@ nav:
          - Overview: 'features/software-catalog/index.md'
          - System model: 'features/software-catalog/system-model.md'
          - YAML File Format: 'features/software-catalog/descriptor-format.md'
+          - Configuration: 'features/software-catalog/configuration.md'
          - Extending the model: 'features/software-catalog/extending-the-model.md'
          - External integrations: 'features/software-catalog/external-integrations.md'
          - API: 'features/software-catalog/api.md'
@@ -41,11 +44,7 @@ nav:
          - Overview: 'features/techdocs/README.md'
          - Getting Started: 'features/techdocs/getting-started.md'
          - Concepts: 'features/techdocs/concepts.md'
-          - Reading Documentation: 'features/techdocs/reading-documentation.md'
-          - Writing Documentation: 'features/techdocs/writing-documentation.md'
-          - Publishing Documentation: 'features/techdocs/publishing-documentation.md'
-          - Contributing: 'features/techdocs/contributing.md'
-          - Debugging: 'features/techdocs/debugging.md'
+          - Creating and Publishing Documentation: 'features/techdocs/creating-and-publishing.md'
          - FAQ: 'features/techdocs/FAQ.md'
  - Plugins:
      - Overview: 'plugins/index.md'
@@ -60,5 +60,10 @@
    "*.{json,md}": [
      "prettier --write"
    ]
+  },
+  "jest": {
+    "transformModules": [
+      "@kyma-project/asyncapi-react"
+    ]
  }
 }
@@ -1,30 +1,30 @@
 {
  "name": "example-app",
-  "version": "0.1.1-alpha.19",
+  "version": "0.1.1-alpha.20",
  "private": true,
  "dependencies": {
-    "@backstage/cli": "^0.1.1-alpha.19",
-    "@backstage/core": "^0.1.1-alpha.19",
-    "@backstage/catalog-model": "^0.1.1-alpha.19",
-    "@backstage/plugin-api-docs": "^0.1.1-alpha.19",
-    "@backstage/plugin-catalog": "^0.1.1-alpha.19",
-    "@backstage/plugin-circleci": "^0.1.1-alpha.19",
-    "@backstage/plugin-explore": "^0.1.1-alpha.19",
-    "@backstage/plugin-github-actions": "^0.1.1-alpha.19",
-    "@backstage/plugin-gitops-profiles": "^0.1.1-alpha.19",
-    "@backstage/plugin-graphiql": "^0.1.1-alpha.19",
-    "@backstage/plugin-jenkins": "^0.1.1-alpha.19",
-    "@backstage/plugin-lighthouse": "^0.1.1-alpha.19",
-    "@backstage/plugin-newrelic": "^0.1.1-alpha.19",
-    "@backstage/plugin-register-component": "^0.1.1-alpha.19",
-    "@backstage/plugin-rollbar": "^0.1.1-alpha.19",
-    "@backstage/plugin-scaffolder": "^0.1.1-alpha.19",
-    "@backstage/plugin-sentry": "^0.1.1-alpha.19",
-    "@backstage/plugin-tech-radar": "^0.1.1-alpha.19",
-    "@backstage/plugin-techdocs": "^0.1.1-alpha.19",
-    "@backstage/plugin-welcome": "^0.1.1-alpha.19",
-    "@backstage/test-utils": "^0.1.1-alpha.19",
-    "@backstage/theme": "^0.1.1-alpha.19",
+    "@backstage/cli": "^0.1.1-alpha.20",
+    "@backstage/catalog-model": "^0.1.1-alpha.20",
+    "@backstage/core": "^0.1.1-alpha.20",
+    "@backstage/plugin-api-docs": "^0.1.1-alpha.20",
+    "@backstage/plugin-catalog": "^0.1.1-alpha.20",
+    "@backstage/plugin-circleci": "^0.1.1-alpha.20",
+    "@backstage/plugin-explore": "^0.1.1-alpha.20",
+    "@backstage/plugin-github-actions": "^0.1.1-alpha.20",
+    "@backstage/plugin-gitops-profiles": "^0.1.1-alpha.20",
+    "@backstage/plugin-graphiql": "^0.1.1-alpha.20",
+    "@backstage/plugin-jenkins": "^0.1.1-alpha.20",
+    "@backstage/plugin-lighthouse": "^0.1.1-alpha.20",
+    "@backstage/plugin-newrelic": "^0.1.1-alpha.20",
+    "@backstage/plugin-register-component": "^0.1.1-alpha.20",
+    "@backstage/plugin-rollbar": "^0.1.1-alpha.20",
+    "@backstage/plugin-scaffolder": "^0.1.1-alpha.20",
+    "@backstage/plugin-sentry": "^0.1.1-alpha.20",
+    "@backstage/plugin-tech-radar": "^0.1.1-alpha.20",
+    "@backstage/plugin-techdocs": "^0.1.1-alpha.20",
+    "@backstage/plugin-welcome": "^0.1.1-alpha.20",
+    "@backstage/test-utils": "^0.1.1-alpha.20",
+    "@backstage/theme": "^0.1.1-alpha.20",
    "@material-ui/core": "^4.9.1",
    "@material-ui/icons": "^4.9.1",
    "@octokit/rest": "^18.0.0",
@@ -27,6 +27,9 @@ describe('App', () => {
          data: {
            app: { title: 'Test' },
            backend: { baseUrl: 'http://localhost:7000' },
+            lighthouse: {
+              baseUrl: 'http://localhost:3003',
+            },
            techdocs: {
              storageUrl: 'http://localhost:7000/techdocs/static/docs',
            },
@@ -24,12 +24,15 @@ import {
  ErrorAlerter,
  featureFlagsApiRef,
  FeatureFlags,
+  discoveryApiRef,
+  UrlPatternDiscovery,
  GoogleAuth,
  GithubAuth,
  OAuth2,
  OktaAuth,
  GitlabAuth,
  Auth0Auth,
+  MicrosoftAuth,
  oauthRequestApiRef,
  OAuthRequestManager,
  googleAuthApiRef,
@@ -38,6 +41,7 @@ import {
  oktaAuthApiRef,
  gitlabAuthApiRef,
  auth0AuthApiRef,
+  microsoftAuthApiRef,
  storageApiRef,
  WebStorage,
 } from '@backstage/core';
@@ -88,6 +92,10 @@ export const apis = (config: ConfigApi) => {

  const builder = ApiRegistry.builder();

+  const discoveryApi = builder.add(
+    discoveryApiRef,
+    UrlPatternDiscovery.compile(`${backendUrl}/{{ pluginId }}`),
+  );
  const alertApi = builder.add(alertApiRef, new AlertApiForwarder());
  const errorApi = builder.add(
    errorApiRef,
@@ -106,7 +114,7 @@ export const apis = (config: ConfigApi) => {

  builder.add(featureFlagsApiRef, new FeatureFlags());

-  builder.add(lighthouseApiRef, new LighthouseRestApi('http://localhost:3003'));
+  builder.add(lighthouseApiRef, LighthouseRestApi.fromConfig(config));

  builder.add(travisCIApiRef, new TravisCIApi());
  builder.add(githubPullRequestsApiRef, new GithubPullRequestsClient());
@@ -119,8 +127,15 @@ export const apis = (config: ConfigApi) => {
  builder.add(
    googleAuthApiRef,
    GoogleAuth.create({
-      backendUrl,
-      basePath: '/auth/',
+      discoveryApi,
+      oauthRequestApi,
+    }),
+  );
+
+  builder.add(
+    microsoftAuthApiRef,
+    MicrosoftAuth.create({
+      discoveryApi,
      oauthRequestApi,
    }),
  );
@@ -128,8 +143,7 @@ export const apis = (config: ConfigApi) => {
  const githubAuthApi = builder.add(
    githubAuthApiRef,
    GithubAuth.create({
-      backendUrl,
-      basePath: '/auth/',
+      discoveryApi,
      oauthRequestApi,
    }),
  );
@@ -137,8 +151,7 @@ export const apis = (config: ConfigApi) => {
  builder.add(
    oktaAuthApiRef,
    OktaAuth.create({
-      backendUrl,
-      basePath: '/auth/',
+      discoveryApi,
      oauthRequestApi,
    }),
  );
@@ -146,8 +159,7 @@ export const apis = (config: ConfigApi) => {
  builder.add(
    gitlabAuthApiRef,
    GitlabAuth.create({
-      backendUrl,
-      basePath: '/auth/',
+      discoveryApi,
      oauthRequestApi,
    }),
  );
@@ -155,8 +167,7 @@ export const apis = (config: ConfigApi) => {
  builder.add(
    auth0AuthApiRef,
    Auth0Auth.create({
-      backendUrl,
-      basePath: '/auth/',
+      discoveryApi,
      oauthRequestApi,
    }),
  );
@@ -164,8 +175,7 @@ export const apis = (config: ConfigApi) => {
  builder.add(
    oauth2ApiRef,
    OAuth2.create({
-      backendUrl,
-      basePath: '/auth/',
+      discoveryApi,
      oauthRequestApi,
    }),
  );
@@ -178,21 +188,9 @@ export const apis = (config: ConfigApi) => {
    }),
  );

-  builder.add(
-    catalogApiRef,
-    new CatalogClient({
-      apiOrigin: backendUrl,
-      basePath: '/catalog',
-    }),
-  );
+  builder.add(catalogApiRef, new CatalogClient({ discoveryApi }));

-  builder.add(
-    scaffolderApiRef,
-    new ScaffolderApi({
-      apiOrigin: backendUrl,
-      basePath: '/scaffolder/v1',
-    }),
-  );
+  builder.add(scaffolderApiRef, new ScaffolderApi({ discoveryApi }));

  builder.add(gitOpsApiRef, new GitOpsRestApi('http://localhost:3008'));

@@ -213,13 +211,7 @@ export const apis = (config: ConfigApi) => {
    ]),
  );

-  builder.add(
-    rollbarApiRef,
-    new RollbarClient({
-      apiOrigin: backendUrl,
-      basePath: '/rollbar',
-    }),
-  );
+  builder.add(rollbarApiRef, new RollbarClient({ discoveryApi }));

  builder.add(
    techdocsStorageApiRef,
@@ -39,6 +39,7 @@ import {
  SidebarUserSettings,
  SidebarThemeToggle,
  SidebarPinButton,
+  DefaultProviderSettings,
 } from '@backstage/core';
 import { NavLink } from 'react-router-dom';
 import { graphiQLRouteRef } from '@backstage/plugin-graphiql';
@@ -107,7 +108,7 @@ const Root: FC<{}> = ({ children }) => (
      <SidebarSpace />
      <SidebarDivider />
      <SidebarThemeToggle />
-      <SidebarUserSettings />
+      <SidebarUserSettings providerSettings={<DefaultProviderSettings />} />
      <SidebarPinButton />
    </Sidebar>
    {children}
@@ -19,6 +19,7 @@ import {
  gitlabAuthApiRef,
  oktaAuthApiRef,
  githubAuthApiRef,
+  microsoftAuthApiRef,
 } from '@backstage/core';

 export const providers = [
@@ -28,16 +29,22 @@ export const providers = [
    message: 'Sign In using Google',
    apiRef: googleAuthApiRef,
  },
+  {
+    id: 'microsoft-auth-provider',
+    title: 'Microsoft',
+    message: 'Sign In using Microsoft Azure AD',
+    apiRef: microsoftAuthApiRef,
+  },
  {
    id: 'gitlab-auth-provider',
-    title: 'Gitlab',
-    message: 'Sign In using Gitlab',
+    title: 'GitLab',
+    message: 'Sign In using GitLab',
    apiRef: gitlabAuthApiRef,
  },
  {
    id: 'github-auth-provider',
-    title: 'Github',
-    message: 'Sign In using Github',
+    title: 'GitHub',
+    message: 'Sign In using GitHub',
    apiRef: githubAuthApiRef,
  },
  {
@@ -1,7 +1,7 @@
 {
  "name": "@backstage/backend-common",
  "description": "Common functionality library for Backstage backends",
-  "version": "0.1.1-alpha.19",
+  "version": "0.1.1-alpha.20",
  "main": "src/index.ts",
  "types": "src/index.ts",
  "private": false,
@@ -29,22 +29,24 @@
    "clean": "backstage-cli clean"
  },
  "dependencies": {
-    "@backstage/cli-common": "^0.1.1-alpha.19",
-    "@backstage/config": "^0.1.1-alpha.19",
-    "@backstage/config-loader": "^0.1.1-alpha.19",
+    "@backstage/cli-common": "^0.1.1-alpha.20",
+    "@backstage/config": "^0.1.1-alpha.20",
+    "@backstage/config-loader": "^0.1.1-alpha.20",
    "@types/cors": "^2.8.6",
    "@types/express": "^4.17.6",
    "compression": "^1.7.4",
    "cors": "^2.8.5",
    "express": "^4.17.1",
+    "express-prom-bundle": "^6.1.0",
    "express-promise-router": "^3.0.3",
    "helmet": "^4.0.0",
    "knex": "^0.21.1",
    "lodash": "^4.17.15",
    "morgan": "^1.10.0",
+    "prom-client": "^12.0.0",
+    "selfsigned": "^1.10.7",
    "stoppable": "^1.1.0",
-    "winston": "^3.2.1",
-    "selfsigned": "^1.10.7"
+    "winston": "^3.2.1"
  },
  "peerDependencies": {
    "pg-connection-string": "^2.3.0"
@@ -55,7 +57,7 @@
    }
  },
  "devDependencies": {
-    "@backstage/cli": "^0.1.1-alpha.19",
+    "@backstage/cli": "^0.1.1-alpha.20",
    "@types/compression": "^1.7.0",
    "@types/http-errors": "^1.6.3",
    "@types/morgan": "^1.9.0",
@@ -37,6 +37,7 @@ import {
  HttpsSettings,
 } from './config';
 import { createHttpServer, createHttpsServer } from './hostFactory';
+import { metricsHandler } from './metrics';

 const DEFAULT_PORT = 7000;
 // '' is express default, which listens to all interfaces
@@ -48,6 +49,7 @@ export class ServiceBuilderImpl implements ServiceBuilder {
  private logger: Logger | undefined;
  private corsOptions: cors.CorsOptions | undefined;
  private httpsSettings: HttpsSettings | undefined;
+  private enableMetrics: boolean = true;
  private routers: [string, Router][];
  // Reference to the module where builder is created - needed for hot module
  // reloading
@@ -82,6 +84,9 @@ export class ServiceBuilderImpl implements ServiceBuilder {
      this.httpsSettings = httpsSettings;
    }

+    // For now, configuration of metrics is a simple boolean and active by default
+    this.enableMetrics = backendConfig.getOptionalBoolean('metrics') !== false;
+
    return this;
  }

@@ -131,6 +136,9 @@ export class ServiceBuilderImpl implements ServiceBuilder {
    }
    app.use(compression());
    app.use(express.json());
+    if (this.enableMetrics) {
+      app.use(metricsHandler());
+    }
    app.use(requestLoggingHandler());
    for (const [root, route] of this.routers) {
      app.use(root, route);
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import prom from 'prom-client';
+import promBundle from 'express-prom-bundle';
+import { RequestHandler } from 'express';
+
+/**
+ * Adds a /metrics endpoint, register default runtime metrics and instrument the router.
+ */
+export function metricsHandler(): RequestHandler {
+  // We can only initialize the metrics once and have to clean them up between hot reloads
+  prom.register.clear();
+
+  return promBundle({
+    includeMethod: true,
+    includePath: true,
+    // Using includePath alone is problematic, as it will include path labels with high
+    // cardinality (e.g. path params). Instead we would have to template them. However, this
+    // is difficult, as every backend plugin might use different routes. Instead we only take
+    // the first directory of the path, to have at least an idea how each plugin performs:
+    normalizePath: [['^/([^/]*)/.*', '/$1']],
+    promClient: { collectDefaultMetrics: {} },
+  });
+}
@@ -1,6 +1,6 @@
 {
  "name": "example-backend",
-  "version": "0.1.1-alpha.19",
+  "version": "0.1.1-alpha.20",
  "main": "dist/index.cjs.js",
  "types": "src/index.ts",
  "private": true,
@@ -18,18 +18,20 @@
    "migrate:create": "knex migrate:make -x ts"
  },
  "dependencies": {
-    "@backstage/backend-common": "^0.1.1-alpha.19",
-    "@backstage/catalog-model": "^0.1.1-alpha.19",
-    "@backstage/config": "^0.1.1-alpha.19",
-    "@backstage/plugin-auth-backend": "^0.1.1-alpha.19",
-    "@backstage/plugin-catalog-backend": "^0.1.1-alpha.19",
-    "@backstage/plugin-graphql-backend": "^0.1.1-alpha.19",
-    "@backstage/plugin-identity-backend": "^0.1.1-alpha.19",
-    "@backstage/plugin-proxy-backend": "^0.1.1-alpha.19",
-    "@backstage/plugin-rollbar-backend": "^0.1.1-alpha.19",
-    "@backstage/plugin-scaffolder-backend": "^0.1.1-alpha.19",
-    "@backstage/plugin-sentry-backend": "^0.1.1-alpha.19",
-    "@backstage/plugin-techdocs-backend": "^0.1.1-alpha.19",
+    "example-app": "^0.1.1-alpha.20",
+    "@backstage/backend-common": "^0.1.1-alpha.20",
+    "@backstage/catalog-model": "^0.1.1-alpha.20",
+    "@backstage/config": "^0.1.1-alpha.20",
+    "@backstage/plugin-app-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-auth-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-catalog-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-graphql-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-identity-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-proxy-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-rollbar-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-scaffolder-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-sentry-backend": "^0.1.1-alpha.20",
+    "@backstage/plugin-techdocs-backend": "^0.1.1-alpha.20",
    "@octokit/rest": "^18.0.0",
    "dockerode": "^3.2.0",
    "express": "^4.17.1",
@@ -40,7 +42,7 @@
    "winston": "^3.2.1"
  },
  "devDependencies": {
-    "@backstage/cli": "^0.1.1-alpha.19",
+    "@backstage/cli": "^0.1.1-alpha.20",
    "@types/dockerode": "^2.5.32",
    "@types/express": "^4.17.6",
    "@types/express-serve-static-core": "^4.17.5",
@@ -40,6 +40,7 @@ import sentry from './plugins/sentry';
 import proxy from './plugins/proxy';
 import techdocs from './plugins/techdocs';
 import graphql from './plugins/graphql';
+import app from './plugins/app';
 import { PluginEnvironment } from './types';

 function makeCreateEnv(loadedConfigs: AppConfig[]) {
@@ -71,6 +72,7 @@ async function main() {
  const sentryEnv = useHotMemoize(module, () => createEnv('sentry'));
  const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs'));
  const graphqlEnv = useHotMemoize(module, () => createEnv('graphql'));
+  const appEnv = useHotMemoize(module, () => createEnv('app'));

  const service = createServiceBuilder(module)
    .loadConfig(configReader)
@@ -82,8 +84,9 @@ async function main() {
    .addRouter('/auth', await auth(authEnv))
    .addRouter('/identity', await identity(identityEnv))
    .addRouter('/techdocs', await techdocs(techdocsEnv))
-    .addRouter('/proxy', await proxy(proxyEnv))
-    .addRouter('/graphql', await graphql(graphqlEnv));
+    .addRouter('/proxy', await proxy(proxyEnv, '/proxy'))
+    .addRouter('/graphql', await graphql(graphqlEnv))
+    .addRouter('', await app(appEnv));

  await service.start().catch(err => {
    console.log(err);
@@ -0,0 +1,25 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createRouter } from '@backstage/plugin-app-backend';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin({ logger }: PluginEnvironment) {
+  return await createRouter({
+    logger,
+    appPackageName: 'example-app',
+  });
+}
@@ -13,13 +13,14 @@
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
+
 // @ts-ignore
 import { createRouter } from '@backstage/plugin-proxy-backend';
 import { PluginEnvironment } from '../types';

-export default async function createPlugin({
-  logger,
-  config,
-}: PluginEnvironment) {
-  return await createRouter({ logger, config });
+export default async function createPlugin(
+  { logger, config }: PluginEnvironment,
+  pathPrefix: string,
+) {
+  return await createRouter({ logger, config, pathPrefix });
 }
--- a/Show More
+++ b/Show More