Merge branch 'master' of github.com:backstage/backstage into blam/tubgoat

* 'master' of github.com:backstage/backstage: (1353 commits)
  chore: change the wording slightly
  chore: review comments
  chore: prettier makes pretty
  Update docs/features/software-templates/installation.md
  chore: fix spelling mistake
  chore: fixing spelling of docs
  chore: reworking the files so that it's moved to docs instea
  chore: fix the config key for scaffolderr
  chore: updating docs reference to integrations condfig
  chore: fix newline on new file
  chore: Added example multi-stage with the new backstage bundle command
  Remove heading from the adr template
  Updated version changes to be minor
  Updated changeset with breaking changes documentation
  chore(deps-dev): bump @types/mini-css-extract-plugin from 0.9.1 to 1.2.2
  chore(deps): bump @octokit/request from 5.4.12 to 5.4.13
  Update comments, use MUI's capitalize
  Change category from Feedback to Data Display
  Fix typo
  Tweak wording
  ...

.changeset/beige-queens-crash.md

@@ -1,13 +0,0 @@
----
-'@backstage/create-app': patch
----
-
-Optimized the `yarn install` step in the backend `Dockerfile`.
-
-To apply these changes to an existing app, make the following changes to `packages/backend/Dockerfile`:
-
-Replace the `RUN yarn install ...` line with the following:
-
-```bash
-RUN yarn install --frozen-lockfile --production --network-timeout 300000 && rm -rf "$(yarn cache dir)"
-```

.changeset/chatty-cooks-begin.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-kubernetes': patch
+'@backstage/plugin-kubernetes-backend': patch
+---
+
+Add AWS auth provider for Kubernetes

.changeset/chilly-chefs-protect.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-api-docs': patch
----
-
-Update swagger-ui-react to 3.37.2

.changeset/clean-rocks-ring.md

@@ -0,0 +1,18 @@
+---
+'@backstage/cli': minor
+---
+
+We've bumped the `@eslint-typescript` packages to the latest, which now add some additional rules that might cause lint failures.
+The main one which could become an issue is the [no-use-before-define](https://eslint.org/docs/rules/no-use-before-define) rule.
+
+Every plugin and app has the ability to override these rules if you want to ignore them for now.
+
+You can reset back to the default behaviour by using the following in your own `.eslint.js`
+
+```js
+rules: {
+  'no-use-before-define': 'off'
+}
+```
+
+Because of the nature of this change, we're unable to provide a grace period for the update :(

.changeset/cost-insights-curvy-dingos-live.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-cost-insights': patch
+---
+
+Allow expand functionality to top panel product chart tooltip.

.changeset/cost-insights-cyan-nails-film.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-cost-insights': patch
----
-
-Add breakdown view to the Cost Overview panel

.changeset/cost-insights-yellow-trees-love.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-cost-insights': minor
+---
+
+Add support for additional breakdowns of daily cost data.
+This changes the type of Cost.groupedCosts returned by CostInsightsApi.getGroupDailyCost.

.changeset/famous-items-travel.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-techdocs-backend': patch
----
-
-Update URL auth format for Gitlab clone

.changeset/fast-flowers-tickle.md

@@ -0,0 +1,31 @@
+---
+'@backstage/plugin-kafka': minor
+'@backstage/plugin-kafka-backend': minor
+---
+
+Added support for multiple Kafka clusters and multiple consumers per component.
+Note that this introduces several breaking changes.
+
+1. Configuration in `app-config.yaml` has changed to support the ability to configure multiple clusters. This means you are required to update the configs in the following way:
+
+```diff
+kafka:
+   clientId: backstage
+-  brokers:
+-    - localhost:9092
++  clusters:
++    - name: prod
++      brokers:
++        - localhost:9092
+```
+
+2. Configuration of services has changed as well to support multiple clusters:
+
+```diff
+  annotations:
+-    kafka.apache.org/consumer-groups: consumer
++    kafka.apache.org/consumer-groups: prod/consumer
+```
+
+3. Kafka Backend API has changed, so querying offsets of a consumer group is now done with the following query path:
+   `/consumers/${clusterId}/${consumerGroup}/offsets`

.changeset/five-games-grin.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Add `--lax` option to `config:print` and `config:check`, which causes all environment variables to be assumed to be set.

.changeset/forty-jobs-occur.md

@@ -0,0 +1,8 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+Add `EntityRefLinks` that shows one or multiple entity ref links.
+
+Change the about card and catalog table to use `EntityRefLinks` due to the
+nature of relations to support multiple relations per type.

.changeset/four-plants-happen.md

@@ -1,6 +0,0 @@
----
-'@backstage/plugin-sentry': patch
-'@backstage/plugin-welcome': patch
----
-
-Refactor route registration to remove deprecating code

.changeset/green-boats-attend.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Support supplying a custom catalog descriptor file parser

.changeset/grumpy-crews-build.md

@@ -1,9 +0,0 @@
----
-'@backstage/config-loader': minor
----
-
-Fix typo of "visibility" in config schema reference
-
-If you have defined a config element named `visiblity`, you
-will need to fix the spelling to `visibility`. For more info,
-see https://backstage.io/docs/conf/defining#visibility.

.changeset/happy-crabs-punch.md

@@ -0,0 +1,12 @@
+---
+'@backstage/config-loader': patch
+---
+
+Added support for environment variable substitutions in string configuration values using a `${VAR}` placeholder. All environment variables must be available, or the entire expression will be evaluated to `undefined`. To escape a substitution, use `$${...}`, which will end up as `${...}`.
+
+For example:
+
+```yaml
+app:
+  baseUrl: https://${BASE_HOST}
+```

.changeset/healthy-cameras-suffer.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-kubernetes': patch
+---
+
+Improve error reporting for plugin misconfiguration.

.changeset/honest-jokes-rush.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Use .text instead of .json for ALB key response

.changeset/light-bulldogs-guess.md

@@ -1,5 +0,0 @@
----
-'@backstage/backend-common': patch
----
-
-Allow the `backend.listen.port` config to be both a number or a string.

.changeset/light-nails-crash.md

@@ -1,5 +0,0 @@
----
-'@backstage/cli': patch
----
-
-Bump versions of `esbuild` and `rollup-plugin-esbuild`

.changeset/loud-terms-kiss.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-sonarqube': patch
+---
+
+Ask the SonarQube server for all support metrics prior to querying them for a project.

.changeset/lucky-guests-mate.md

@@ -0,0 +1,5 @@
+---
+'@backstage/config-loader': minor
+---
+
+Removed support for the deprecated `$data` placeholder.

.changeset/new-nails-thank.md

@@ -1,7 +0,0 @@
----
-'@backstage/plugin-proxy-backend': patch
----
-
-Filter the headers that are sent from the proxied-targed back to the frontend to not forwarded unwanted authentication or
-monitoring contexts from other origins (like `Set-Cookie` with e.g. a google analytics context). The implementation reuses
-the `allowedHeaders` configuration that now controls both directions `frontend->target` and `target->frontend`.

.changeset/perfect-dryers-sell.md

@@ -1,13 +0,0 @@
----
-'@backstage/create-app': patch
----
-
-Removed `"resolutions"` entry for `esbuild` in the root `package.json` in order to use the version specified by `@backstage/cli`.
-
-To apply this change to an existing app, remove the following from your root `package.json`:
-
-```json
-"resolutions": {
-  "esbuild": "0.6.3"
-},
-```

.changeset/slow-insects-fail.md

@@ -1,5 +0,0 @@
----
-'@backstage/create-app': patch
----
-
-Add [API docs plugin](https://github.com/backstage/backstage/tree/master/plugins/api-docs) to new apps being created through the CLI.

.changeset/smart-turkeys-bathe.md

@@ -1,28 +0,0 @@
----
-'@backstage/plugin-catalog-backend': minor
-'@backstage/plugin-catalog-import': minor
-'@backstage/catalog-model': patch
-'@backstage/plugin-scaffolder': patch
----
-
-Add Analyze location endpoint to catalog backend. Add catalog-import plugin and replace import-component with it. To start using Analyze location endpoint, you have add it to the `createRouter` function options in the `\backstage\packages\backend\src\plugins\catalog.ts` file:
-
-```ts
-export default async function createPlugin(env: PluginEnvironment) {
-  const builder = new CatalogBuilder(env);
-  const {
-    entitiesCatalog,
-    locationsCatalog,
-    higherOrderOperation,
-    locationAnalyzer, //<--
-  } = await builder.build();
-
-  return await createRouter({
-    entitiesCatalog,
-    locationsCatalog,
-    higherOrderOperation,
-    locationAnalyzer, //<--
-    logger: env.logger,
-  });
-}
-```

.changeset/sour-eels-dream.md

@@ -1,7 +0,0 @@
----
-'@backstage/plugin-catalog-backend': patch
----
-
-Gracefully handle missing codeowners.
-
-The CodeOwnersProcessor now also takes a logger as a parameter.

.changeset/stupid-taxis-sneeze.md

@@ -1,7 +0,0 @@
----
-'@backstage/cli': minor
-'@backstage/plugin-cost-insights': patch
----
-
-sort product panels and navigation menu by greatest cost
-update tsconfig.json to use ES2020 api

.changeset/techdocs-dirty-rivers-hope.md

@@ -0,0 +1,5 @@
+---
+'@backstage/techdocs-common': patch
+---
+
+Add rate limiter for concurrent execution of file uploads in AWS and Google publishers

.changeset/tender-parrots-itch.md

@@ -0,0 +1,5 @@
+---
+'@backstage/config-loader': minor
+---
+
+Enable further processing of configuration files included using the `$include` placeholder. Meaning that for example for example `$env` includes will be processed as usual in included files.

.changeset/tidy-actors-repair.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-techdocs': patch
----
-
-Use type EntityName from catalog-model for entities

.changeset/twenty-trees-travel.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-catalog': patch
----
-
-Use the OWNED_BY relation and compare it to the users MEMBER_OF relation. The user entity is searched by name, based on the userId of the identity.

.changeset/weak-roses-search.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-proxy-backend': patch
----
-
-Add configuration schema for the commonly used properties

.github/CODEOWNERS

@@ -6,9 +6,12 @@
 
 *                                           @backstage/maintainers
 /docs/features/techdocs                     @backstage/techdocs-core
+/docs/features/search                       @backstage/techdocs-core
 /plugins/cost-insights                      @backstage/silver-lining
 /plugins/cloudbuild                         @trivago/ebarrios
-/plugins/techdocs                           @backstage/techdocs-core
 /plugins/search                             @backstage/techdocs-core
+/plugins/techdocs                           @backstage/techdocs-core
 /plugins/techdocs-backend                   @backstage/techdocs-core
+/packages/techdocs-common                   @backstage/techdocs-core
 /.changeset/cost-insights-*                 @backstage/silver-lining
+/.changeset/techdocs-*                      @backstage/techdocs-core

.github/styles/vocab.txt

@@ -1,4 +1,5 @@
 abc
+adamdmharvey
 andrewthauer
 Apdex
 api
@@ -7,6 +8,8 @@ apis
 args
 asciidoc
 async
+Autoscaling
+autoscaling
 Avro
 backrub
 Balachandran
@@ -23,6 +26,7 @@ changesets
 Changesets
 chanwit
 Chanwit
+ci
 cisphobia
 cissexist
 classname
@@ -34,6 +38,8 @@ Codecov
 codehilite
 Codehilite
 codeowners
+composability
+composable
 config
 Config
 configmaps
@@ -42,10 +48,13 @@ const
 cookiecutter
 css
 dariddler
+dataflow
 deadnaming
 destructured
 dev
+devops
 devs
+dhenneke
 discoverability
 Discoverability
 dls
@@ -54,32 +63,40 @@ Dockerfile
 Dockerize
 dockerode
 Docusaurus
+Dominik
+dtuite
 dzolotusky
-eg
 Ek
+etag
 env
 Env
+esbuild
 eslint
+Expedia
 facto
 failover
 Figma
 Firekube
+Fiverr
 freben
 Fredrik
-github
-Github
-gitlab
-Gitlab
+Georgoulas
+gitbeaker
+GitHub
+GitLab
 Grafana
+GraphQL
 graphql
 graphviz
 Gustavsson
 Hackathons
 haproxy
-heroku
+Henneke
 Heroku
 horizontalpodautoscalers
 Hostname
+hotspots
+html
 http
 https
 Iain
@@ -88,8 +105,8 @@ incentivised
 inlined
 inlinehilite
 interop
-javascript
-Javascript
+Ioannis
+JavaScript
 jq
 js
 json
@@ -98,9 +115,11 @@ Kaewkasi
 Knex
 kubectl
 kubernetes
+Kumar
 learnings
 lerna
 Lerna
+Luxon
 magiclink
 mailto
 maintainership
@@ -110,6 +129,7 @@ microsite
 middleware
 minikube
 Minikube
+misconfiguration
 misgendering
 mkdocs
 Mkdocs
@@ -125,28 +145,33 @@ neuro
 newrelic
 nginx
 Niklas
+nodegit
 nohoist
 nonces
+noop
 npm
+nvarchar
 nvm
-oauth
-Oauth
+OAuth
+octokit
 oidc
 Okta
 Oldsberg
 onboarding
 Onboarding
 pagerduty
+parallelization
 Patrik
 Phoen
 plantuml
 Pomaceous
 postgres
+postpack
 pre
 prebaked
 preconfigured
+prepack
 Preprarer
-Prerequisities
 productional
 Protobuf
 proxying
@@ -168,6 +193,8 @@ rollbar
 Rollbar
 Rollup
 Rosaceae
+routable
+Routable
 rst
 rsync
 rugvip
@@ -180,12 +207,14 @@ semlas
 semver
 Serverless
 Sinon
-smartsymobls
+Sneha
 Snyk
+sourcemaps
 sparklines
 Spotifiers
 spotify
 Spotify
+sqlite
 squidfunk
 src
 stefanalund
@@ -198,13 +227,13 @@ talkdesk
 Talkdesk
 tasklist
 techdocs
+Telenor
 templated
 templater
 Templater
 templaters
 Templaters
 Thauer
-theres
 toc
 tolerations
 Tolerations
@@ -213,12 +242,17 @@ toolsets
 tooltip
 tooltips
 touchpoints
+transpiled
+transpilation
+Tuite
 ui
+unmanaged
 untracked
 upvote
 url
 utils
 validators
+varchar
 Voi
 Wealthsimple
 Weaveworks

.github/workflows/codeql-analysis.yml

@@ -11,6 +11,11 @@ on:
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [master]
+    # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#scanning-pull-requests
+    paths-ignore:
+      - '**/*.md'
+      - '**/*.yml'
+      - '**/*.yaml'
   schedule:
     - cron: '0 8 * * 6'
 
@@ -36,11 +41,6 @@ jobs:
           # a pull request then we can checkout the head.
           fetch-depth: 2
 
-      # If this run was triggered by a pull request event, then checkout
-      # the head of the pull request instead of the merge commit.
-      - run: git checkout HEAD^2
-        if: ${{ github.event_name == 'pull_request' }}
-
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v1

.github/workflows/fossa.yml

@@ -0,0 +1,44 @@
+name: FOSSA
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2.3.4
+
+        # We use this to modify the generated .fossa.yml
+      - name: Install yq
+        run: sudo snap install yq
+
+      - name: Install Fossa
+        run: "curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash"
+
+      - name: Configure Fossa
+        # The --option flag for fossa init does not work yet, see https://github.com/fossas/fossa-cli/issues/614
+        run: |
+          fossa init
+          yq eval -i '.analyze.modules[].options.strategy = "yarn-list"' .fossa.yml
+
+          # This deletes entries for template and example packages found within packages and plugins
+          # Seems like yq has a bug that causes only a subset of all matches to be deleted each run
+          yq eval -i 'del(.analyze.modules[] | select(.path == "*/*/**"))' .fossa.yml
+          yq eval -i 'del(.analyze.modules[] | select(.path == "*/*/**"))' .fossa.yml
+          yq eval -i 'del(.analyze.modules[] | select(.path == "*/*/**"))' .fossa.yml
+          yq eval -i 'del(.analyze.modules[] | select(.path == "*/*/**"))' .fossa.yml
+          yq eval -i 'del(.analyze.modules[] | select(.path == "*/*/**"))' .fossa.yml
+
+      - name: Show config
+        run: cat .fossa.yml
+
+      - name: Fossa Analyze
+        env:
+          # FOSSA Push-Only API Token
+          FOSSA_API_KEY: 9ee7e8893660832a7387dcc32377fb61
+        run: fossa analyze --branch "$GITHUB_REF"

.github/workflows/master-win.yml

@@ -51,10 +51,13 @@ jobs:
       - name: test
         run: yarn lerna -- run test
 
+      # credit: https://github.com/appleboy/discord-action/issues/3#issuecomment-731426861
       - name: Discord notification
         if: ${{ failure() }}
-        uses: Ilshidur/action-discord@0.2.0
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-        with:
-          args: 'Windows master build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'
+        run: |
+          $MESSAGE=@"
+          {\"content\": \"Windows master build failed https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}\"}
+          "@
+          C:\msys64\usr\bin\curl.exe -i -H "Accept: application/json" -H "Content-Type:application/json" -X POST $env:DISCORD_WEBHOOK --data $MESSAGE

.github/workflows/master.yml

@@ -8,6 +8,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
 
+    outputs:
+      needs_release: ${{ steps.release_check.outputs.needs_release }}
+
     strategy:
       matrix:
         node-version: [12.x, 14.x]
@@ -47,6 +50,15 @@ jobs:
         run: yarn install --frozen-lockfile
       # End of yarn setup
 
+      - name: Fetch previous commit for release check
+        run: git fetch origin '${{ github.event.before }}'
+
+      - name: Check if release
+        id: release_check
+        run: node scripts/check-if-release.js
+        env:
+          COMMIT_SHA_BEFORE: '${{ github.event.before }}'
+
       - name: validate config
         run: yarn backstage-cli config:check
 
@@ -70,21 +82,6 @@ jobs:
           bash <(curl -s https://codecov.io/bash) -f packages/core/coverage/* -F core
           bash <(curl -s https://codecov.io/bash) -f packages/core-api/coverage/* -F core-api
 
-      # Publishes current version of packages that are not already present in the registry
-      - name: publish
-        if: matrix.node-version == '12.x'
-        run: yarn lerna -- publish from-package --yes
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      # Tags the commit with the version in the core package if the tag doesn't exist
-      - uses: Klemensas/action-autotag@1.2.3
-        if: matrix.node-version == '12.x'
-        with:
-          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
-          package_root: 'packages/core'
-          tag_prefix: 'v'
-
       - name: Discord notification
         if: ${{ failure() }}
         uses: Ilshidur/action-discord@0.2.0
@@ -92,3 +89,86 @@ jobs:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         with:
           args: 'Master build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'
+
+  # A separate release build that is only run for commits that are the result of merging the "Version Packages" PR
+  # We can't re-use the output from the above step, but we'll have a guaranteed node_modules cache and
+  # only run the build steps that are necessary for publishing
+  release:
+    needs: build
+
+    if: needs.build.outputs.needs_release == 'true'
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.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: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-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 type declarations
+        run: yarn tsc:full
+
+      - name: build packages
+        run: yarn lerna -- run --ignore example-app build
+
+      # Publishes current version of packages that are not already present in the registry
+      - name: publish
+        run: yarn lerna -- publish from-package --yes
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Creates the next available tag with format "release-<year>-<month>-<day>[.<n>]"
+      - name: Create a release tag
+        id: create_tag
+        run: node scripts/create-release-tag.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
+
+      # Convert the newly created tag into a release with changelog information
+      - name: Create release on GitHub
+        run: node scripts/create-github-release.js ${{ steps.create_tag.outputs.tag_name }} 1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
+
+      # Notify everyone about this great new release :D
+      - name: Discord notification
+        uses: Ilshidur/action-discord@0.2.0
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_RELEASE_WEBHOOK }}
+          TAG_NAME: ${{ steps.create_tag.outputs.tag_name }}
+        with:
+          args: 'A new release has been published! https://github.com/backstage/backstage/releases/tag/{{TAG_NAME}}'

.github/workflows/microsite-build-check.yml

@@ -13,7 +13,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x]
+        node-version: [14.x]
 
     env:
       CI: true
@@ -27,6 +27,9 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
+      - name: verify doc links
+        run: node scripts/verify-links.js
+
         # Skip caching of microsite dependencies, it keeps the global cache size
         # smaller, which make Windows builds a lot faster for the rest of the project.
       - name: yarn install

.github/workflows/microsite-with-storybook-deploy.yml

@@ -17,7 +17,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x]
+        node-version: [14.x]
 
     env:
       CI: true
@@ -55,7 +55,7 @@ jobs:
         run: ls microsite/build/backstage && ls microsite/build/backstage/storybook
 
       - name: Deploy both microsite and storybook to gh-pages
-        uses: JamesIves/github-pages-deploy-action@3.4.2
+        uses: JamesIves/github-pages-deploy-action@3.7.1
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           BRANCH: gh-pages

.github/workflows/nightly.yml

@@ -55,6 +55,7 @@ jobs:
 
       - name: tsc
         run: yarn tsc
+
       - name: build
         run: yarn build
 
@@ -62,7 +63,7 @@ jobs:
       - name: prepare nightly release
         run: yarn changeset version --snapshot nightly
 
-      # Publishes the nightly release to NPM, by using tag we make sure the release is
+      # Publishes the nightly release to npm, by using tag we make sure the release is
       # not flagged as the latest release, which means that people will not get this
       # version of the package unless requested explicitly
       - name: publish nightly release

.github/workflows/techdocs-project-board.yml

@@ -1,7 +1,7 @@
 name: Automatically add new TechDocs Issues and PRs to the GitHub project board
 # Development of TechDocs in Backstage is managed by this Kanban board - https://github.com/orgs/backstage/projects/1
 # New issues and PRs with TechDocs in their title or docs-like-code label will be added to the board.
-# Caveat: New PRs created from forks will not be added since GitHub actions don't share credentials with forks.
+# Caveat: New PRs created from forks will not be added since GitHub Actions don't share credentials with forks.
 
 on:
   issues:
@@ -9,17 +9,17 @@ on:
   pull_request:
     types: [opened, reopened, labeled, edited]
 
-env:
-  MY_GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
-
 jobs:
   assign_issue_or_pr_to_project:
     runs-on: ubuntu-latest
     name: Triage
+    env:
+      MY_GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
     steps:
       - name: Assign new issue to Incoming based on its title.
         uses: srggrs/assign-one-project-github-action@1.2.0
         if: |
+          env.MY_GITHUB_TOKEN != null &&
           contains(github.event.issue.title, 'TechDocs') ||
           contains(github.event.issue.title, 'techdocs') ||
           contains(github.event.issue.title, 'Techdocs')
@@ -30,6 +30,7 @@ jobs:
       - name: Assign new issue to Incoming based on its label.
         uses: srggrs/assign-one-project-github-action@1.2.0
         if: |
+          env.MY_GITHUB_TOKEN != null &&
           contains(github.event.issue.labels.*.name, 'docs-like-code')
         with:
           project: 'https://github.com/orgs/backstage/projects/1'
@@ -38,6 +39,7 @@ jobs:
       - name: Assign new PR to Incoming based on its title.
         uses: srggrs/assign-one-project-github-action@1.2.0
         if: |
+          env.MY_GITHUB_TOKEN != null &&
           contains(github.event.pull_request.title, 'TechDocs') ||
           contains(github.event.pull_request.title, 'techdocs') ||
           contains(github.event.pull_request.title, 'Techdocs')
@@ -48,6 +50,7 @@ jobs:
       - name: Assign new PR to Incoming based on its label.
         uses: srggrs/assign-one-project-github-action@1.2.0
         if: |
+          env.MY_GITHUB_TOKEN != null &&
           contains(github.event.pull_request.labels.*.name, 'docs-like-code')
         with:
           project: 'https://github.com/orgs/backstage/projects/1'

.gitignore

@@ -130,3 +130,6 @@ site
 
 # Local configuration files
 *.local.yaml
+
+# Sensitive credentials
+*-credentials.yaml

ADOPTERS.md

@@ -1,15 +1,21 @@
-| 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                                     |
-| [Grab](https://www.grab.com)                 | [@althafh](https://github.com/althafh)                       | Initial work as a unified interface for all of Grab's internal tooling                           |
+| Organization                                  | Contact                                                                                                                                               | Description of Use                                                                                                                     |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [Spotify](https://www.spotify.com)            | [@leemills83](https://github.com/leemills83)                                                                                                          | 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                                                                           |
+| [Grab](https://www.grab.com)                  | [@althafh](https://github.com/althafh)                                                                                                                | Initial work as a unified interface for all of Grab's internal tooling                                                                 |
+| [Telenor Sweden](https://www.telenor.se)      | [@O5ten](https://github.com/O5ten)                                                                                                                    | Building a developer portal for scaffolding projects towards our unified build environment and microservice stacks                     |
+| [Fiverr](https://www.fiverr.com)              | [@nirga](https://github.com/nirga)                                                                                                                    | Unifying separate tools that developers are using today (i.e. monitoring, dead letter queues management, etc.) into a single platform. |
+| [Zalando SE](https://www.zalando.de)          | [@leviferreira](https://github.com/leviferreira)                                                                                                      | Building V2 of the Internal Development Portal.                                                                                        |
+| [LegalZoom](https://legalzoom.com)            | [@backjo](https://github.com/backjo)                                                                                                                  | Developer portal - hub for all engineering projects and metadata.                                                                      |
+| [Expedia Group](https://www.expediagroup.com) | [Mike Turner](mailto:miturner@expediagroup.com), [Sneha Kumar](mailto:snkumar@expediagroup.com), [@guillermomanzo](https://github.com/guillermomanzo) | EG Common Developer Toolkit                                                                                                            |
+| [Paddle.com](https://paddle.com)              | [Ioannis Georgoulas](https://github.com/geototti21)                                                                                                   | Developer portal (Tech Docs, Service Catalog, Internal Tooling), we use vanilla Backstage FE and custom BE implementation in Go        |

CHANGELOG.md

@@ -1,13 +1,9 @@
 # Backstage Changelog
 
-This is a best-effort changelog where we manually collect breaking changes. It is not an exhaustive list of all changes or even features added.
+This changelog is no longer being updated and will be removed in the future, as each package now has its own changelog instead. It was a best-effort changelog where we manually collected breaking changes during the `v0.1.1-alpha.<n>` releases.
 
 If you encounter issues while upgrading to a newer version, don't hesitate to reach out on [Discord](https://discord.gg/EBHEGzX) or [open an issue](https://github.com/backstage/backstage/issues/new/choose)!
 
-## Next Release
-
-> Collect changes for the next release below
-
 ## v0.1.1-alpha.26
 
 ### @backstage/cli

CODE_OF_CONDUCT.md

@@ -18,7 +18,7 @@ Harassment includes, but is not limited to:
 - Offensive comments related to gender, gender identity and expression, sexual orientation, disability, mental illness, neuro(a)typicality, physical appearance, body size, race, age, regional discrimination, political or religious affiliation
 - Unwelcome comments regarding a person’s lifestyle choices and practices, including those related to food, health, parenting, drugs, and employment
 - Deliberate misgendering. This includes deadnaming or persistently using a pronoun that does not correctly reflect a person's gender identity. You must address people by the name they give you when not addressing them by their username or handle
-- Physical contact and simulated physical contact (eg, textual descriptions like “_hug_” or “_backrub_”) without consent or after a request to stop
+- Physical contact and simulated physical contact (e.g., textual descriptions like “_hug_” or “_backrub_”) without consent or after a request to stop
 - Threats of violence, both physical and psychological
 - Incitement of violence towards any individual, including encouraging a person to commit suicide or to engage in self-harm
 - Deliberate intimidation

CONTRIBUTING.md

@@ -6,19 +6,19 @@ Therefore we want to create strong community of contributors -- all working toge
 
 Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. ❤️
 
-Backstage is released under the Apache2.0 License, and original creations contributed to this repo are accepted under the same license.
+Backstage is released under the Apache 2.0 License, and original creations contributed to this repo are accepted under the same license.
 
-# Types of Contributions
+## Types of Contributions
 
-## Report bugs
+### Report bugs
 
 No one likes bugs. Report bugs as an issue [here](https://github.com/backstage/backstage/issues/new?template=bug_template.md).
 
-## Fix bugs or build new features
+### Fix bugs or build new features
 
 Look through the GitHub issues for [bugs](https://github.com/backstage/backstage/labels/bugs), [good first issues](https://github.com/backstage/backstage/labels/good%20first%20issue) or [help wanted](https://github.com/backstage/backstage/labels/help%20wanted).
 
-## Build a plugin
+### Build a plugin
 
 The value of Backstage grows with every new plugin that gets added. Wouldn't it be fantastic if there was a plugin for every infrastructure project out there? We think so. And we would love your help.
 
@@ -26,27 +26,27 @@ A great reference example of a plugin can be found on [our blog](https://backsta
 
 What kind of plugins should/could be created? Some inspiration from the 120+ plugins that we have developed inside Spotify can be found [here](https://backstage.io/demos), but we will keep a running list of suggestions labeled with [[plugin]](https://github.com/backstage/backstage/labels/plugin).
 
-## Suggesting a plugin
+### Suggesting a plugin
 
 If you start developing a plugin that you aim to release as open source, we suggest that you create a [new Issue](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development.
 
 You can also use this process if you have an idea for a good plugin but you hope that someone else will pick up the work.
 
-## Adding Non-code Contributions
+### Adding Non-code Contributions
 
 Since there is such a large landscape of possible development, build, and deployment environments, we welcome community contributions in these areas in the [`/contrib`](https://github.com/backstage/backstage/tree/master/contrib) folder of the project. This is an excellent place to put things that help out the community at large, but which may not fit within the scope of the core product to support natively. Here, you will find Helm charts, alternative Docker images, and much more.
 
-## Write Documentation
+### Write Documentation
 
 The current documentation is very limited. Help us make the `/docs` folder come alive.
 
-## Contribute to Storybook
+### Contribute to Storybook
 
 We think the best way to ensure different plugins provide a consistent experience is through a solid set of reusable UI/UX components. Backstage uses [Storybook](http://backstage.io/storybook).
 
 Either help us [create new components](https://github.com/backstage/backstage/labels/help%20wanted) or improve stories for the existing ones (look for files with `*.stories.tsx`).
 
-## Submit Feedback
+### Submit Feedback
 
 The best way to send feedback is to file [an issue](https://github.com/backstage/backstage/issues).
 
@@ -58,47 +58,59 @@ If you are proposing a feature:
 - Remember that this is a volunteer-driven project, and that contributions
   are welcome :)
 
-## Add your company to ADOPTERS
+### Add your company to ADOPTERS
 
 Have you started using Backstage? Adding your company to [ADOPTERS](ADOPTERS.md) really helps the project.
 
-# Get Started!
+## Get Started!
 
 So...feel ready to jump in? Let's do this. 👏🏻💯
 
 Start by reading our [Getting Started](https://backstage.io/docs/getting-started/) page. If you need help, just jump into our [Discord chatroom](https://discord.gg/MUpMjP2).
 
-# Coding Guidelines
+## Coding Guidelines
 
 All code is formatted with `prettier` using the configuration in the repo. If possible we recommend configuring your editor to format automatically, but you can also use the `yarn prettier --write <file>` command to format files.
 
+A consistent coding style is included via [EditorConfig](https://editorconfig.org/) with the file [`.editorconfig`](.editorconfig) at the root of the repo. Depending on your editor of choice, it will either support it out of the box or you can [download a plugin](https://editorconfig.org/#download) for the config to be applied.
+
 If you're contributing to the backend or CLI tooling, be mindful of cross-platform support. [This](https://shapeshed.com/writing-cross-platform-node/) blog post is a good guide of what to keep in mind when writing cross-platform NodeJS.
 
 Also be sure to skim through our [ADRs](https://github.com/backstage/backstage/tree/master/docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for.
 
 If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command.
 
-# Creating Changesets
+## Creating Changesets
 
-We use [changesets](https://github.com/atlassian/changesets) to help us prepare releases. It helps us make sure that every package affected by a change gets a proper version number and an entry in its `CHANGELOG.md`. To make the process of generating releases easy. it helps when contributors include changesets with their pull requests.
+We use [changesets](https://github.com/atlassian/changesets) to help us prepare releases. They help us make sure that every package affected by a change gets a proper version number and an entry in its `CHANGELOG.md`. To make the process of generating releases easy, it helps when contributors include changesets with their pull requests.
 
-## To create a changeset
+### When to use a changeset?
+
+Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage stability index](https://backstage.io/docs/overview/stability-index) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs.
+
+In general, changesets are not needed for the documentation, build utilities, contributed samples in `contrib/`, or the [example `packages/app`](packages/app).
+
+### How to create a changeset
 
 1. Run `yarn changeset`
 2. Select which packages you want to include a changeset for
-3. Select impact of change that you're introducing (minor, major or patch)
+3. Select impact of change that you're introducing (patch, minor, or major)
 4. Add generated changeset to Git
 5. Push the commit with your changeset to the branch associated with your PR
-6. Accept our gratitude for making the release process easier on the maintainer
+6. Accept our gratitude for making the release process easier on the maintainers
 
-For more information, checkout [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in changesets repository.
+For more information, checkout [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in the changesets repository.
 
-# Code of Conduct
+## Merging to Master
+
+For those contributors who have earned write access to the repository, when a pull request is approved, in general we prefer the author of the PR to perform the merge themselves. This allows them to own accountability for the change and they likely know best how or when to address pending fixes or additional follow-ups. In this way, we all help contribute to the project's successful outcomes.
+
+## Code of Conduct
 
 This project adheres to the [Spotify FOSS Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.
 
 [code-of-conduct]: https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md
 
-# Security Issues?
+## Security Issues?
 
 See [SECURITY](SECURITY.md).

OWNERS.md

@@ -22,3 +22,6 @@ People that have made significant contributions to the project and earned write
 
 - Andrew Thauer - Wealthsimple (GitHub: [andrewthauer](https://github.com/andrewthauer))
 - Oliver Sand - SDA SE (GitHub: [Fox32](https://github.com/Fox32))
+- David Tuite - Roadie (GitHub: [dtuite](https://github.com/dtuite))
+- Adam Harvey - DXC Technology (GitHub: [adamdmharvey](https://github.com/adamdmharvey))
+- Dominik Henneke - SDA SE (GitHub: [dhenneke](https://github.com/dhenneke))

README.md

@@ -10,13 +10,9 @@
 [![Codecov](https://img.shields.io/codecov/c/github/backstage/backstage)](https://codecov.io/gh/backstage/backstage)
 [![](https://img.shields.io/npm/v/@backstage/core?label=Version)](https://github.com/backstage/backstage/releases)
 
-> We recently moved from `spotify/backstage`, update your remotes!
->
-> `git remote set-url origin git@github.com:backstage/backstage.git`
-
 ## What is Backstage?
 
-[Backstage](https://backstage.io/) is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure. So your product teams can ship high-quality code quickly — without compromising autonomy.
+[Backstage](https://backstage.io/) is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly — without compromising autonomy.
 
 Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.
 
@@ -43,7 +39,7 @@ Check out [the documentation](https://backstage.io/docs/getting-started) on how
 
 - [Main documentation](https://backstage.io/docs)
 - [Service Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview)
-- [Architecture](https://backstage.io/docs/overview/architecture-terminology) ([Decisions](https://backstage.io/docs/architecture-decisions/adrs-overview))
+- [Architecture](https://backstage.io/docs/overview/architecture-overview) ([Decisions](https://backstage.io/docs/architecture-decisions/adrs-overview))
 - [Designing for Backstage](https://backstage.io/docs/dls/design)
 - [Storybook - UI components](https://backstage.io/storybook)
 
@@ -61,6 +57,6 @@ Check out [the documentation](https://backstage.io/docs/getting-started) on how
 
 ## License
 
-Copyright 2020 © Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
+Copyright 2020-2021 © Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
 
 Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

app-config.yaml

@@ -16,6 +16,10 @@ backend:
     credentials: true
   csp:
     connect-src: ["'self'", 'http:', 'https:']
+  reading:
+    allow:
+      - host: example.com
+      - host: '*.mozilla.org'
   # workingDirectory: /tmp # Use this to configure a working directory for the scaffolder, defaults to the OS temp-dir
 
 # See README.md in the proxy-backend plugin for information on the configuration format
@@ -46,20 +50,37 @@ proxy:
       X-Api-Key:
         $env: NEW_RELIC_REST_API_KEY
 
+  '/pagerduty':
+    target: https://api.pagerduty.com
+    headers:
+      Authorization:
+        $env: PAGERDUTY_TOKEN
+
   '/buildkite/api':
     target: https://api.buildkite.com/v2/
     headers:
       Authorization:
         $env: BUILDKITE_TOKEN
 
+  '/sentry/api':
+    target: https://sentry.io/api/
+    allowedMethods: ['GET']
+    headers:
+      Authorization:
+        $env: SENTRY_TOKEN
+
 organization:
   name: My Company
 
+# Reference documentation http://backstage.io/docs/features/techdocs/configuration
 techdocs:
-  storageUrl: http://localhost:7000/api/techdocs/static/docs
   requestUrl: http://localhost:7000/api/techdocs
+  storageUrl: http://localhost:7000/api/techdocs/static/docs
+  builder: 'local' # Alternatives - 'external'
   generators:
-    techdocs: 'docker'
+    techdocs: 'docker' # Alternatives - 'local'
+  publisher:
+    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
 
 sentry:
   organization: my-company
@@ -78,6 +99,13 @@ kubernetes:
     - 'config'
   clusters: []
 
+kafka:
+  clientId: backstage
+  clusters:
+    - name: cluster
+      brokers:
+        - localhost:9092
+
 integrations:
   github:
     - host: github.com
@@ -110,7 +138,16 @@ integrations:
 
 catalog:
   rules:
-    - allow: [Component, API, Group, User, Template, Location]
+    - allow:
+        - Component
+        - API
+        - Resource
+        - Group
+        - User
+        - Template
+        - System
+        - Domain
+        - Location
 
   processors:
     githubOrg:
@@ -120,7 +157,7 @@ catalog:
             $env: GITHUB_TOKEN
         #### Example for how to add your GitHub Enterprise instance using the API:
         # - target: https://ghe.example.net
-        #   apiBaseUrl: https://ghe.example.net/api/v3
+        #   apiBaseUrl: https://ghe.example.net/api
         #   token:
         #     $env: GHE_TOKEN
     ldapOrg:
@@ -155,24 +192,46 @@ catalog:
       #    groupFilter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')
 
   locations:
+    # Add a location here to ingest it, for example from an URL:
+    #
+    #     - type: url
+    #       target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-components.yaml
+    #
+    # For local development you can use a file location instead:
+    #
+    #     - type: file
+    #       target: ../catalog-model/examples/all-components.yaml
+    #
+    # File locations are relative to the current working directory of the
+    # backend, for example packages/backend/.
+
     # Backstage example components
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-components.yaml
+    - type: file
+      target: ../catalog-model/examples/all-components.yaml
     # Example component for github-actions
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/plugins/github-actions/examples/sample.yaml
-    # Example component for techdocs
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml
+    - type: file
+      target: ../../plugins/github-actions/examples/sample.yaml
+    # Example component for TechDocs
+    - type: file
+      target: ../../plugins/techdocs-backend/examples/documented-component/catalog-info.yaml
     # Backstage example APIs
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml
+    - type: file
+      target: ../catalog-model/examples/all-apis.yaml
+    # Backstage example resources
+    - type: file
+      target: ../catalog-model/examples/all-resources.yaml
+    # Backstage example systems
+    - type: file
+      target: ../catalog-model/examples/all-systems.yaml
+    # Backstage example domains
+    - type: file
+      target: ../catalog-model/examples/all-domains.yaml
     # Backstage example templates
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml
+    - type: file
+      target: ../../plugins/scaffolder-backend/sample-templates/all-templates.yaml
     # Backstage example groups and users
-    - type: url
-      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/acme-corp.yaml
+    - type: file
+      target: ../catalog-model/examples/acme-corp.yaml
 
 scaffolder:
   github:
@@ -189,7 +248,16 @@ scaffolder:
     api:
       token:
         $env: AZURE_TOKEN
+  bitbucket:
+    api:
+      host: https://bitbucket.org
+      username:
+        $env: BITBUCKET_USERNAME
+      token:
+        $env: BITBUCKET_TOKEN
+
 auth:
+  environment: development
   ### Providing an auth.session.secret will enable session support in the auth-backend
   # session:
   #   secret: custom session secret
@@ -290,6 +358,9 @@ costInsights:
     bigQuery:
       name: BigQuery
       icon: search
+    events:
+      name: Events
+      icon: data
   metrics:
     DAU:
       name: Daily Active Users
@@ -306,3 +377,5 @@ homepage:
       timezone: 'Europe/Stockholm'
     - label: TYO
       timezone: 'Asia/Tokyo'
+pagerduty:
+  eventsBaseUrl: 'https://events.pagerduty.com/v2'

catalog-info.yaml

@@ -6,7 +6,7 @@ metadata:
     Backstage is an open-source developer portal that puts the developer experience first.
   annotations:
     github.com/project-slug: backstage/backstage
-    backstage.io/techdocs-ref: github:https://github.com/backstage/backstage.git
+    backstage.io/techdocs-ref: url:https://github.com/backstage/backstage
     lighthouse.com/website-url: https://backstage.io
 spec:
   type: library

contrib/chart/backstage/templates/backend-secret.yaml

@@ -20,4 +20,5 @@ stringData:
   AZURE_TOKEN: {{ .Values.auth.azure.api.token }}
   NEW_RELIC_REST_API_KEY: {{ .Values.auth.newRelicRestApiKey }}
   TRAVISCI_AUTH_TOKEN: {{ .Values.auth.travisciAuthToken }}
+  PAGERDUTY_TOKEN: {{ .Values.auth.pagerdutyToken }}
 {{- end }}

contrib/chart/backstage/values.yaml

@@ -250,3 +250,4 @@ auth:
   gitlabToken: g
   newRelicRestApiKey: r
   travisciAuthToken: fake-travis-ci-auth-token
+  pagerdutyToken: h

contrib/docker/frontend-with-nginx/Dockerfile

@@ -8,8 +8,6 @@ FROM nginx:mainline
 # This dockerfile requires the app to be built on the host first, as it
 # simply copies in the build output into the image.
 
-# The safest way to build this image is to use `yarn docker-build:app`
-
 RUN apt-get update && apt-get -y install jq && rm -rf /var/lib/apt/lists/*
 
 COPY packages/app/dist /usr/share/nginx/html

contrib/docs/tutorials/authenticate-api-requests.md

@@ -0,0 +1,52 @@
+# Authenticate API requests
+
+The Backstage backend APIs are by default available without authentication. To avoid evil-doers from accessing or modifying data, one might use a network protection mechanism such as a firewall or an authenticating reverse proxy. For Backstage instances that are available on the Internet one can instead use the experimental IdentityClient as outlined below.
+
+API requests from frontend plugins include an authorization header with a Backstage identity token acquired when the user logs in. By adding a middleware that verifies said token to be valid and signed by Backstage, non-authenticated requests can be blocked with a 401 Unauthorized response.
+
+Note that this means Backstage will stop working for guests, as no token is issued for them.
+
+Caveat: as of writing this, Backstage does not refresh the identity token so eventually users will get a 401 response on API calls (not on loading the web page as only the API calls are authenticated) and have to logout/login again to get a new token.
+
+```typescript
+// packages/backend/src/index.ts from a create-app deployment
+
+import { Request, Response, NextFunction } from 'express';
+import { IdentityClient } from '@backstage/plugin-auth-backend';
+
+// ...
+
+async function main() {
+  // ...
+
+  const discovery = SingleHostDiscovery.fromConfig(config);
+  const identity = new IdentityClient({
+    discovery,
+    issuer: await discovery.getExternalBaseUrl('auth'),
+  });
+  const authMiddleware = async (
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ) => {
+    try {
+      const token = IdentityClient.getBearerToken(req.headers.authorization);
+      req.user = await identity.authenticate(token);
+      next();
+    } catch (error) {
+      res.status(401).send(`Unauthorized`);
+    }
+  };
+
+  const apiRouter = Router();
+  // The auth route must be publically available as it is used during login
+  apiRouter.use('/auth', await auth(authEnv));
+  // Only authenticated requests are allowed to the routes below
+  apiRouter.use('/catalog', authMiddleware, await catalog(catalogEnv));
+  apiRouter.use('/techdocs', authMiddleware, await techdocs(techdocsEnv));
+  apiRouter.use('/proxy', authMiddleware, await proxy(proxyEnv));
+  apiRouter.use(authMiddleware, notFoundHandler());
+
+  // ...
+}
+```

contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md

@@ -3,7 +3,7 @@
 ExampleComponent.tsx reference
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { Typography, Grid } from '@material-ui/core';
 import {
   InfoCard,
@@ -14,11 +14,11 @@ import {
   HeaderLabel,
   SupportButton,
   identityApiRef,
+  useApi,
 } from '@backstage/core';
-import { useApi } from '@backstage/core-api';
 import ExampleFetchComponent from '../ExampleFetchComponent';
 
-const ExampleComponent: FC<{}> = () => {
+const ExampleComponent = () => {
   const identityApi = useApi(identityApiRef);
   const userId = identityApi.getUserId();
   const profile = identityApi.getProfile();

contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md

@@ -3,7 +3,7 @@
 ExampleFetchComponent.tsx reference
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { useAsync } from 'react-use';
 import Alert from '@material-ui/lab/Alert';
 import {
@@ -11,8 +11,8 @@ import {
   TableColumn,
   Progress,
   githubAuthApiRef,
+  useApi,
 } from '@backstage/core';
-import { useApi } from '@backstage/core-api';
 import { graphql } from '@octokit/graphql';
 
 const query = `{
@@ -57,7 +57,7 @@ type DenseTableProps = {
   viewer: Viewer;
 };
 
-export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
+export const DenseTable = ({ viewer }: DenseTableProps) => {
   const columns: TableColumn[] = [
     { title: 'Name', field: 'name' },
     { title: 'Created', field: 'createdAt' },
@@ -76,7 +76,7 @@ export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
   );
 };
 
-const ExampleFetchComponent: FC<{}> = () => {
+const ExampleFetchComponent = () => {
   const auth = useApi(githubAuthApiRef);
 
   const { value, loading, error } = useAsync(async (): Promise<any> => {

docs/FAQ.md

@@ -117,6 +117,62 @@ through the proxy.
 Learn more about [the different components](overview/what-is-backstage.md) that
 make up Backstage.
 
+### How do I keep my Backstage app up to date?
+
+In many ways one can view Backstage as a library rather than an application or
+service. The `@backstage/create-app` tool that is used to create your own
+Backstage app is similar to
+[`create-react-app`](https://github.com/facebook/create-react-app) in that it
+gives you a starting point. The code you get is meant to be evolved, and most of
+the functionality you get out of the box is brought in via npm dependencies.
+Keeping your app up to date generally means keeping your dependencies up to
+date. The Backstage CLI provides a command to help you with that. Simply run
+`yarn backstage-cli versions:bump` at the root of your repo, and the latest
+versions of all Backstage packages will be installed.
+
+While staying up to date with new releases and changes will keep your app up to
+date, it can often be convenient to use the changes done to the
+`@backstage/create-app` template as another method to stay up to date. For that
+purpose, any changes done to the template are documented along with upgrade
+instructions in the
+[changelog](https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md)
+of the `@backstage/create-app` package.
+
+### Why can't I dynamically install plugins without modifications the app?
+
+This decision is part of the core architecture and development flow of
+Backstage. Plugins have a lot of freedom in what they provide and how they are
+integrated into the app, and it would therefore add a lot of complexity to allow
+plugins to be integrated via configuration the same way as they can be
+integrated with code.
+
+By bundling all plugins and their dependencies into one app bundle it is also
+possible to do significant optimizations to the app load time by allowing
+plugins to share dependencies between each other when possible. This contributes
+to Backstage being fast, which is an important part of the user and developer
+experience.
+
+### Why are there no published Docker images or helm charts for Backstage?
+
+As mentioned above, Backstage is not a packaged service that you can use out of
+the box. In order to get started with Backstage you need to use the
+`@backstage/create-app` package to create and customize your own Backstage app.
+
+In order to build a Docker image from your own app, you can use the
+`yarn build-image` command which is included out of the box in the app template.
+By default this image will bundle up both the frontend and the backend into a
+single image that you can deploy using your favorite tooling.
+
+There are also some examples that can help you deploy Backstage to kubernetes in
+the
+[contrib](https://github.com/backstage/backstage/tree/master/contrib/kubernetes)
+folder.
+
+It is possible that example images will be provided in the future, which can be
+used to quickly try out a small subset of the functionality of Backstage, but
+these would not be able to provide much more functionality on top of what you
+can see on a demo site.
+
 ### Do I have to write plugins in TypeScript?
 
 No, you can use JavaScript if you prefer. We want to keep the Backstage core

docs/api/utility-apis.md

@@ -33,10 +33,10 @@ hook exported by `@backstage/core`, or the `withApis` HOC if you prefer class
 components. For example, the `ErrorApi` can be accessed like this:
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { useApi, errorApiRef } from '@backstage/core';
 
-export const MyComponent: FC<{}> = () => {
+export const MyComponent = () => {
   const errorApi = useApi(errorApiRef);
 
   // Signal to the app that something went wrong, and display the error to the user.

docs/architecture-decisions/adr000-template.md

@@ -0,0 +1,22 @@
+---
+id: adrs-adr000
+title: ADR000: [TITLE]
+description: Architecture Decision Record (ADR) for [TITLE] [DESCRIPTION]
+---
+
+<!-- These documents have names that are short noun phrases. For example, "ADR001: Deployment on Ruby on Rails 3.0.10" or "ADR009: LDAP for Multitenant Integration" -->
+
+## Context
+
+<!--
+This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. -->
+
+## Decision
+
+<!-- This section describes our response to these forces. It is stated in full sentences, with active voice. "We will ..." -->
+
+## Consequences
+
+<!-- This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. -->
+
+<!-- This template is taken from a blog post by Michael Nygard http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions -->

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

@@ -4,12 +4,16 @@ title: ADR001: Architecture Decision Record (ADR) log
 description: Architecture Decision Record (ADR) logs as a reference point for the team
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-04-26 | Open   |
+## Decision
 
-## Decision: A decision was made to store ADRs in a log in the project repository
+A decision was made to store ADRs in a log in the project repository
 
-## Discussion: There is a need to store big decisions made in a log as a reference point for the team, help with onboarding new members and give context to others interested in the project.
+## Discussion
 
-## Risks: People stop adding ADRs to the log and context gets lost
+There is a need to store big decisions made in a log as a reference point for
+the team, help with onboarding new members and give context to others interested
+in the project.
+
+## Risks
+
+People stop adding ADRs to the log and context gets lost

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

@@ -4,10 +4,6 @@ title: ADR002: Default Software Catalog File Format
 description: Architecture Decision Record (ADR) log on Default Software Catalog File Format
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-05-17 | Open   |
-
 ## Background
 
 Backstage comes with a software catalog functionality, that you can use to track

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

@@ -4,10 +4,6 @@ title: ADR003: Avoid Default Exports and Prefer Named Exports
 description: Architecture Decision Record (ADR) log on Avoid Default Exports and Prefer Named Exports
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-05-19 | Open   |
-
 ## Context
 
 When CommonJS was the primary authoring format, the best practice was to export

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

@@ -4,10 +4,6 @@ title: ADR004: Module Export Structure
 description: Architecture Decision Record (ADR) log on Module Export Structure
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-05-27 | Open   |
-
 ## Context
 
 With a growing number of exports of packages like `@backstage/core`, it is

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

@@ -4,10 +4,6 @@ title: ADR005: Catalog Core Entities
 description: Architecture Decision Record (ADR) log on Catalog Core Entities
 ---
 
-| Created    | Status |
-| ---------- | ------ |
-| 2020-05-29 | Open   |
-
 ## Context
 
 We want to standardize on a few core entities that we are tracking in the
@@ -58,7 +54,7 @@ discover existing functionality in the ecosystem.
 APIs are implemented by components and make their boundaries explicit. They
 might be defined using an RPC IDL (e.g. in Protobuf, GraphQL or similar), a data
 schema (e.g. in Avro, TFRecord or similar), or as code interfaces (e.g.
-framework APIs in Swift, Kotlin, Java, C++, Typescript etc). In any case, APIs
+framework APIs in Swift, Kotlin, Java, C++, TypeScript etc). 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.
 

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

@@ -6,7 +6,7 @@ description: Architecture Decision Record (ADR) log on Avoid React.FC and React.
 
 ## Context
 
-Facebook has removed `React.FC` from their base template for a Typescript
+Facebook has removed `React.FC` from their base template for a TypeScript
 project. The reason for this was that it was found to be an unnecessary feature
 with next to no benefits in combination with a few downsides.
 
@@ -43,6 +43,15 @@ const GoodComponent = ({ text, children }: GoodProps) => (
     {children}
   </div>
 );
+
+/* Or as a shorthand, if no specifc child type is required */
+type GoodProps = PropsWithChildren<{ text: string }>;
+const GoodComponent = ({ text, children }: GoodProps) => (
+  <div>
+    <div>{text}</div>
+    {children}
+  </div>
+);
 ```
 
 ## Consequences

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

@@ -0,0 +1,36 @@
+---
+id: adrs-adr010
+title: ADR010: Use the Luxon Date Library
+description: Architecture Decision Record (ADR) for Luxon Date Library
+---
+
+## Context
+
+Date formatting (e.g. `a day ago`) and calculations are common within Backstage.
+Some of these useful features are not supported by the standard JavaScript
+`Date` object. The popular [Moment.js](https://momentjs.com/) library has been
+commonly used to fill this gap but suffers from large bundle sizes and mutable
+state issues. On top of this, `momentjs` is
+[being sunset](https://momentjs.com/docs/#/-project-status/) and the project
+recommends using one of the more modern alternative libraries.
+
+See
+[[RFC] Standardized Date & Time Library](https://github.com/backstage/backstage/issues/3401).
+
+## Decision
+
+We will use [Luxon](https://moment.github.io/luxon/index.html) as the standard
+date library within Backstage.
+
+`Luxon` provides a similar feature set and API to `Moment.js`, but improves on
+its design through immutability and the usage of modern JavaScript APIs (e.g.
+`Intl`). This results in smaller bundle sizes while providing a full feature set
+and avoids the need for using additional libraries for common date & time tasks.
+
+## Consequences
+
+- All core packages and plugins within Backstage should use `Luxon` for any date
+  manipulation or formatting that cannot be easily accomplished with the native
+  JavaScript `Date` object.
+- Using a single date library avoids having to learn multiple library APIs
+- Having a single date library will reduce bundle sizes

docs/architecture-decisions/index.md

@@ -18,8 +18,9 @@ Records should be stored under the `architecture-decisions` directory.
 
 ### Creating an ADR
 
-- Copy `0000-template.md` to `docs/architecture-decisions/0000-my-decision.md`
-  (my-decision should be descriptive. Do not assign an ADR number.)
+- Copy `docs/architecture-decisions/adr000-template.md` to
+  `docs/architecture-decisions/adr000-my-decision.md` (my-decision should be
+  descriptive. Do not assign an ADR number.)
 - Fill in the ADR following the guidelines in the template
 - Submit a pull request
 - Address and integrate feedback from the community

docs/assets/search/architecture.drawio.svg

@@ -0,0 +1,541 @@
+<svg host="65bd71144e" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="789px" height="766px" viewBox="-0.5 -0.5 789 766" content="&lt;mxfile host=&quot;bd2205bb-07f8-4b61-b1c1-5174fe4ebe37&quot; modified=&quot;2021-01-14T13:46:42.842Z&quot; agent=&quot;5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Code/1.52.0 Chrome/83.0.4103.122 Electron/9.3.5 Safari/537.36&quot; etag=&quot;jW9IV2PM6529z9FP4d6-&quot; version=&quot;13.10.0&quot; type=&quot;embed&quot;&gt;&lt;diagram id=&quot;AOZgdlUmH_6GT6Gt5u4e&quot; name=&quot;Page-1&quot;&gt;7V1bc6M4Fv41rpp5CMVNAh4TJ5ntre7qbGdqdvqRYMWmG4MXcGLvrx8JSYAuNtgG59JJV3VASALOd3R0zqcjMnGmy80febhafMlmKJnY5mwzca4ntu3ZPv6fFGxpAXQALZjn8YwWWU3Bffx/xApNVrqOZ6gQKpZZlpTxSiyMsjRFUSmUhXmePYvVHrNEvOsqnCOl4D4KE7X0v/GsXNBSH5hN+b9QPF/wO1smu/IQRj/nebZO2f0mtvNY/dDLy5D3xeoXi3CWPbeKnJuJM82zrKRHy80UJUS0XGy03e2Oq/Vz5ygt+zSALm3xFCZrxB+5erByy4XxvIhLdL8KI3L+jPGeOFeLcpngMwsfhsWKQvAYbxDu9uoxTpJplmR51dyxral5CXB5UebZT9S6YpoQAp+0yNKyVQ6m5B8uZ8+G8hJtdr6gVYsNayPKlqjMt7gKawACpnlME90goOfPDa6Wy9BYtDHlhSHTpXnddyNPfMBEukO8zjsXrwteUryepUgTzfBAZqdZXi6yeZaGyU1TelWNTiLJaxOfNXU+Z9mKyfwHKssts0rhusxERNAmLv8mzQ0PsNPvrUvXG9Z1dbJlJ0UZ5uUlMU24IM1SxMtuY/J6tEE64zWiJCyKOKKFrIp1AshELPshxlLM1nnEanlMcfETzhGr5us1IUdJWMZPYvc6VFnTuyzGN641CHKjuuVzBxC7oI/AWjW6gSUVblvVVqRCsfs+ninfx5RUjfbYKF79jr100Q1+saFucaDOMtTXf20vp9HzZuluzOW/s23w14/igrsZ+2QuDvcuBJJ4nuLjBD2WI8hfM+gUSHrL37FcRf62P5b8gf3O1Vt2FF6DegONzGFCNHMWP+HDeVm9Oy16yOUSfFOh3nsdGTVU3AnxXUOHnqVBLxgNPJ1n/QGeatbEadlRcbP5yBRGnTcAcO7pRm2PzFpSZg7fLCwWFWbWyLZMHA9QI1Oos2TOADLtMSXjoHdFDqNtEmMlzu1uDX6g6v75oS6oA+2v6xJ3gzge1Gu3wGvTcwCB4TsiLhpggG84rgqND05Hxla1/XK1wgV3WJYVIXI5IU4xDJdE+pUV+patS1S9OntA+L91xsxTgcI8WrSLTJSgJRORdyX2ZBhG1fttXUwNm3etLZZ1Bku5FFUiRxjr8KGqQGwgCdQ4+i2bF+HnQRjPKwJVHIXJJbuwjGezKiBkkQO+DbiagGv90BV1hhWKRnhE5XEk30TVG8fWDGh7gPFsaygMt+K5cPiKlca+XSXreZxeUHW4IFdwzPoBoOS8i9OcZWpsss4/GQRC1Y/8Wi6wTPHQr7ArVDfktz9RtLjOInwJ929OwzJMsjluXp3elNHvwyHM3JK3jK/igro+YYcUF1Q37Q4x69rwEG+TCGJC2HMui8aE13R1y6oXnJ/nZVb7cg9Hlt7v1/RvZc3AqqELTrSD3/K8WotO0g6NU7bHhn/YbhFBS0LQ1oeXurE9hPnWhpeuo6B0RuqbHxPe2zQ4C65nvrHg823diJzQVpQ8J+dNu+qsocwHG65taht4tKxNbQPmcks0+alk98EcdSAGCI4XtBWls74V2JJitThttbVMKEJLsTZUcAr53tmX7XpiRztY/COIdj3borLv3MW54g4pc3bwwTmdm3dhAmX31Q56cs+j2T/HUgC/Z5OXeZPOCSGAcb5JwgILneJ6nyU5OwrDe3qEysj4AFsC2wuMoP3jCth7fJ5rY++cFXs1JFWx/4SRmOfYWGdkxH8Ot8QYfOC8Z1C7nmto3JpgJGi5ypzZg+HeSO1vMB8GdrsjrRX8Zn2+vYgvZAcILpLXw0e6Q3mMpUj0akz/hw/ftv/jjeP/KG6CvIYJLM+wRlrwd2XSjDlLu1wYuT5gQunnTMlvZpuB0c+XGsoFAi87niTv/qDRtCsfRhtt2PuH0lhRg6sZNc4oo+ZQRfel+NSC3l5Fl+sDb08mjNpa5jMss5eaqyGDPN4OsAVHjJnv0AXbNfzx9Ox9uUfbfJr/jC4cHW0mDaIO7ul1kU0StB7oO6PLKB4zo+tFfHpe1KsSMZQlrMhXlyQyxGq1Vrz8Zu9FvLIG6xZKtAoMgTzfDidj3Zr2MUw65bqxAEzSnbOTIX/D+NUZ5Rw/rQnS5lGNNUSALgmbSr5Yhakga44VkdAFDfzIorhn2KsN/l3JyCRh4wULBcnVatlBgflvfCVdLx8qEip7JLfhQSqOMtdJWbTwpw+yA/+3F6beVj8DWQTTFzTK185p5lhRqqfAcdYU8/4Z5k1k2zjf3wXf+6S49lyZ544m85xmxJzgV/feUABeFO1D4pwW3Ca0xeArCLwO0HcQDgftUWA1mg0Kp4RfQ6gJTec7+6KNJZgnHhUOta9AQ3Z2zl7MHSFzUz5/+K3KBzQp4S0d/15PatKMFxw8302z5QprRNp/XnvT+eJ1Oh3HHUBlVoJQ46fCAczUi05KRy3+SnSrPRTb+nq2TDkahgiaeh0a1yI50lYGx7fb2tVZ34L+oCbMU+OnO4xVnfGZPhTkF1/DkROJ/kT5krx9tYaLgcUTliZhjV4uFyhVr31D5TonpvIbd7w1o+dz+ICSiTavqNuPlh1y1a9OSPdXddZyS+9YnHiEtWLbn9l9J7XD29ZUait2mjHTsHzGF9brQPTsRKr/AgqdAkOm9rLHxwKdyurxQTdQaF4vI17efeobnfNsdiz0MElQks3zcElUoOVdCddabldXYls18903gd2rmgEt2czwPWLtuEyXlgwHiMtc3d6ol+VNTttdedw2mCFCXA++pDchBj3Hxjz16tO54x2iEuwdgzM6Gy5UnY1XEf4Alpgz2Lbq3YnNH+HPSxp/VzT+buDrkmLHioDAyxI14pcfajt1EC/XZbLeEhsDNGwMOBdpt4ffZz5gJ79vmWS8K95gtECzdUII/HfoCkoc/UnWAJq+IacFOLoNMCwSFeyBO4QOdMYBnToQ6FTgj5BlEV9n0XopWfdTFu2Gt+6D4ukEEp4Wl3B7r6qlggmGALNHVsZb3UN8WpDgBYYlBuuOG2jXVw1fs4sYKDlpR8Hjv5V44U1NobptKXAIj15x2YGt32YyQtYVf6tT5mZLZ5ix4LEMkM4yN7zfV2K5v6AynIVl+EsYbuBLnAw25Bq3XLdVwx+ASoC6bKQBpuGKjjNv0tmK6mTvvabvCVs3UCdlzQckRpqUoY5wGwDa/6xR9ZJ3eRahoojTeV8w1bSYIfl6KaWmxfNYmq+3DIozcA0QiEBrxvBY+zJgZ7bbcUB/wvP/5gPoAz85NtamOqhLyz0J5cNWWt6HNgz6gaAeX6odSxu8weftw7ThfUwC5/6w7lgzgNdJqB0Ebu2u8YIvYVp9dcJkRqBG+kFpUnt40xxV7j4h7r+hZfZUH68S4s4JcQDLFcDdx1idRnMOxaWfV8UUqAQO4PstzxAG8HjyvAzBcClDvRf1mgUBu3+i7uQofsA7lU4/anUPmKIW7f1qstoaQm3rLqKh8zGg3NFweyu9Tib5IONHlgXjBNU26WaDIvpJPT7nPeYZSW/al+X0K1kuV2IwgK1xgzQxrn94jItPm7+0QFWl+WsWzs0/&lt;/diagram&gt;&lt;/mxfile&gt;" style="background-color: rgb(255, 255, 255);">
+    <defs/>
+    <g>
+        <rect x="560" y="484" width="140" height="140" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <rect x="420" y="484" width="140" height="140" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <path d="M 664.5 595 L 664.5 705 L 595.54 705" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 590.29 705 L 597.29 701.5 L 595.54 705 L 597.29 708.5 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <rect x="420" y="110" width="140" height="140" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <rect x="420" y="299" width="280" height="140" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <rect x="560" y="110" width="140" height="140" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <rect x="90" y="469.25" width="110" height="90" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 108px; height: 1px; padding-top: 514px; margin-left: 92px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: left; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <div>
+                                    <br/>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="92" y="518" fill="#5C5C5C" font-family="Helvetica" font-size="12px">
+                    &#xa;
+                </text>
+            </switch>
+        </g>
+        <rect x="5" y="20" width="295" height="170" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 293px; height: 1px; padding-top: 105px; margin-left: 7px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: left; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <div>
+                                    <br/>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="7" y="109" fill="#5C5C5C" font-family="Helvetica" font-size="12px">
+                    &#xa;
+                </text>
+            </switch>
+        </g>
+        <rect x="20" y="50" width="260" height="130" fill="none" stroke="#006658" stroke-dasharray="3 3" pointer-events="all"/>
+        <path d="M 530.83 665 C 530.83 656.72 543.89 650 560 650 C 567.74 650 575.16 651.58 580.63 654.39 C 586.1 657.21 589.17 661.02 589.17 665 L 589.17 720 C 589.17 723.98 586.1 727.79 580.63 730.61 C 575.16 733.42 567.74 735 560 735 C 543.89 735 530.83 728.28 530.83 720 Z" fill="#21c0a5" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 589.17 665 C 589.17 668.98 586.1 672.79 580.63 675.61 C 575.16 678.42 567.74 680 560 680 C 543.89 680 530.83 673.28 530.83 665" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <rect x="0" y="0" width="320" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 10px; margin-left: 160px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                App Package: &lt;Route path="/search" element={&lt;... /&gt;} /&gt;
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="160" y="14" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    App Package: &lt;Route path="/search" element={&lt;... /&gt;}...
+                </text>
+            </switch>
+        </g>
+        <rect x="415" y="90" width="210" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 100px; margin-left: 520px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                @backstage/plugin-search-backend
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="520" y="104" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    @backstage/plugin-search-backend
+                </text>
+            </switch>
+        </g>
+        <rect x="90" y="433.75" width="160" height="30" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 1px; height: 1px; padding-top: 449px; margin-left: 92px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: left; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                Other Plugins
+                                <br/>
+                                (TechDocs, Catalog, Etc)
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="92" y="452" fill="#5C5C5C" font-family="Helvetica" font-size="12px">
+                    Other Plugins...
+                </text>
+            </switch>
+        </g>
+        <rect x="90" y="229.25" width="210" height="177.75" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 208px; height: 1px; padding-top: 318px; margin-left: 92px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: left; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <div>
+                                    <font color="#ffffff" size="1">
+                                        <br/>
+                                    </font>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="92" y="322" fill="#5C5C5C" font-family="Helvetica" font-size="12px"></text>
+            </switch>
+        </g>
+        <rect x="80" y="209.25" width="160" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 219px; margin-left: 160px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                @backstage/plugin-search
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="160" y="223" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    @backstage/plugin-search
+                </text>
+            </switch>
+        </g>
+        <path d="M 630 364.25 L 758 364.3 L 758 177.3 L 661.87 177.25" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 656.62 177.25 L 663.62 173.75 L 661.87 177.25 L 663.62 180.75 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <rect x="415" y="279" width="280" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 289px; margin-left: 555px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                Other Backend Plugin (TechDocs, Catalog, Etc)
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="555" y="293" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Other Backend Plugin (TechDocs, Catalog, Etc)
+                </text>
+            </switch>
+        </g>
+        <rect x="445" y="745" width="230" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 755px; margin-left: 560px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                Search Engine (Elastic, Solr, SaaS, etc.)
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="560" y="759" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Search Engine (Elastic, Solr, SaaS, et...
+                </text>
+            </switch>
+        </g>
+        <rect x="415" y="459.5" width="190" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 470px; margin-left: 510px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                Search Engine Integration Layer
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="510" y="473" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Search Engine Integration Layer
+                </text>
+            </switch>
+        </g>
+        <path d="M 458.13 178.25 L 400 178.3 L 400 559.8 L 443.63 559.77" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 463.38 178.25 L 456.38 181.76 L 458.13 178.25 L 456.38 174.76 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 448.88 559.77 L 441.88 563.27 L 443.63 559.77 L 441.88 556.27 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 655.5 151.75 L 780 151.8 L 780 555 L 690.87 555" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 685.62 555 L 692.62 551.5 L 690.87 555 L 692.62 558.5 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <rect x="80" y="60.5" width="190" height="10" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <rect x="30" y="60" width="40" height="70" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <rect x="80" y="90" width="190" height="65.5" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <rect x="229" y="160.5" width="40" height="10" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 166px; margin-left: 230px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font color="#ffffff">
+                                    1 2 3
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="249" y="169" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    1 2 3
+                </text>
+            </switch>
+        </g>
+        <rect x="73" y="70.5" width="100" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 81px; margin-left: 123px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #FFFFFF; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                <span style="font-size: 7.2px ; text-align: left">
+                                    X number of search results
+                                </span>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="123" y="84" fill="#FFFFFF" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    X number of sear...
+                </text>
+            </switch>
+        </g>
+        <path d="M 220 313.37 L 220 330.63" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 220 308.12 L 223.5 315.12 L 220 313.37 L 216.5 315.12 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 220 335.88 L 216.5 328.88 L 220 330.63 L 223.5 328.88 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 187 257.5 L 36.1 257.5 L 36.12 179.61" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <rect x="187" y="241" width="66" height="66" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 64px; height: 1px; padding-top: 274px; margin-left: 188px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <span style="color: rgb(255 , 255 , 255) ; font-size: 9px ; text-align: left">
+                                    Components
+                                </span>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="220" y="278" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Components
+                </text>
+            </switch>
+        </g>
+        <path d="M 276.37 367 L 360 367 L 360 152.8 L 458.13 152.75" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 271.12 367 L 278.12 363.5 L 276.37 367 L 278.12 370.5 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 463.38 152.75 L 456.38 156.25 L 458.13 152.75 L 456.38 149.25 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 220px; margin-left: 351px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">
+                                Pass Search
+                                <br/>
+                                Term and Filters
+                                <br/>
+                                and then
+                                <br/>
+                                Return Results
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="351" y="223" fill="#5C5C5C" font-family="Helvetica" font-size="11px" text-anchor="middle">
+                    Pass Search...
+                </text>
+            </switch>
+        </g>
+        <path d="M 160 397 L 180 337 L 280 337 L 260 397 Z" fill="#21c0a5" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 367px; margin-left: 161px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font color="#ffffff">
+                                    Search API
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="220" y="371" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Search API
+                </text>
+            </switch>
+        </g>
+        <rect x="5" y="20" width="295" height="20" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <path d="M 110 516.25 L 36.1 516.3 L 36.12 180" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <rect x="110" y="483.25" width="66" height="66" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 64px; height: 1px; padding-top: 516px; margin-left: 111px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <span style="color: rgb(255 , 255 , 255) ; font-size: 9px ; text-align: left">
+                                    Components
+                                </span>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="143" y="520" fill="#5C5C5C" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Components
+                </text>
+            </switch>
+        </g>
+        <path d="M 635 198.75 L 630 198.8 L 630 190" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 573.5 239.75 L 593.5 198.75 L 655.5 198.75 L 635.5 239.75 Z" fill="#21c0a5" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 80px; height: 1px; padding-top: 219px; margin-left: 575px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #FFFFFF; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font style="font-size: 10px">
+                                    Scheduler
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="615" y="223" fill="#FFFFFF" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Scheduler
+                </text>
+            </switch>
+        </g>
+        <rect x="604.5" y="139" width="51" height="51" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 49px; height: 1px; padding-top: 165px; margin-left: 606px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #FFFFFF; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font style="font-size: 9px">
+                                    Gather Documents
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="630" y="168" fill="#FFFFFF" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Gather D...
+                </text>
+            </switch>
+        </g>
+        <path d="M 444.17 349.5 C 444.17 341.22 453.31 334.5 464.59 334.5 C 470.01 334.5 475.2 336.08 479.03 338.89 C 482.86 341.71 485.01 345.52 485.01 349.5 L 485.01 379 C 485.01 387.28 475.87 394 464.59 394 C 453.31 394 444.17 387.28 444.17 379 Z" fill="#21c0a5" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 485.01 349.5 C 485.01 357.78 475.87 364.5 464.59 364.5 C 453.31 364.5 444.17 357.78 444.17 349.5" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 550 364.25 L 517.5 364.3 L 485.01 364.3" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <rect x="550" y="324.25" width="80" height="80" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 364px; margin-left: 551px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #FFFFFF; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font style="font-size: 11px">
+                                    Collate Documents
+                                    <br/>
+                                    Or Metadata
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="590" y="368" fill="#FFFFFF" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Collate Docum...
+                </text>
+            </switch>
+        </g>
+        <rect x="464.5" y="140" width="51" height="51" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 49px; height: 1px; padding-top: 166px; margin-left: 466px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #FFFFFF; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font style="font-size: 9px">
+                                    API Endpoint
+                                    <br/>
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="490" y="169" fill="#FFFFFF" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    API Endp...
+                </text>
+            </switch>
+        </g>
+        <rect x="419.59" y="110" width="90" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 120px; margin-left: 465px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #FFFFFF; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                <font style="font-size: 9px">
+                                    Query Processing
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="465" y="123" fill="#FFFFFF" font-family="Helvetica" font-size="11px" text-anchor="middle">
+                    Query Processing
+                </text>
+            </switch>
+        </g>
+        <rect x="560" y="110" width="80" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 120px; margin-left: 600px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #FFFFFF; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                <font style="font-size: 9px">
+                                    Index Processing
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="600" y="123" fill="#FFFFFF" font-family="Helvetica" font-size="11px" text-anchor="middle">
+                    Index Processi...
+                </text>
+            </switch>
+        </g>
+        <rect x="560" y="484" width="80" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 494px; margin-left: 600px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                <font style="font-size: 9px" color="#ffffff">
+                                    Index Processing
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="600" y="497" fill="#5C5C5C" font-family="Helvetica" font-size="11px" text-anchor="middle">
+                    Index Processi...
+                </text>
+            </switch>
+        </g>
+        <rect x="420" y="484" width="90" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 494px; margin-left: 465px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                <font style="font-size: 9px" color="#ffffff">
+                                    Query Processing
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="465" y="497" fill="#5C5C5C" font-family="Helvetica" font-size="11px" text-anchor="middle">
+                    Query Processing
+                </text>
+            </switch>
+        </g>
+        <rect x="604.5" y="515" width="80" height="80" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 555px; margin-left: 606px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 9px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font color="#ffffff">
+                                    <b>
+                                        Manage Index
+                                    </b>
+                                    <br/>
+                                    Create, Remove, Replace Documents and Indices
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="645" y="558" fill="#5C5C5C" font-family="Helvetica" font-size="9px" text-anchor="middle">
+                    Manage Index...
+                </text>
+            </switch>
+        </g>
+        <path d="M 470.25 601.37 L 470.3 705 L 524.63 705" fill="none" stroke="#006658" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 470.25 596.12 L 473.75 603.12 L 470.25 601.37 L 466.75 603.12 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 529.88 705 L 522.88 708.5 L 524.63 705 L 522.88 701.5 Z" fill="#006658" stroke="#006658" stroke-miterlimit="10" pointer-events="all"/>
+        <rect x="450" y="514" width="81" height="81" fill="#21c0a5" stroke="#006658" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 79px; height: 1px; padding-top: 555px; margin-left: 451px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 9px; font-family: Helvetica; color: #5C5C5C; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font color="#ffffff">
+                                    Compile and Execute Query from Term and Filters
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="491" y="557" fill="#5C5C5C" font-family="Helvetica" font-size="9px" text-anchor="middle">
+                    Compile and Execut...
+                </text>
+            </switch>
+        </g>
+    </g>
+    <switch>
+        <g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/>
+        <a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank">
+            <text text-anchor="middle" font-size="10px" x="50%" y="100%">
+                Viewer does not support full SVG 1.1
+            </text>
+        </a>
+    </switch>
+</svg>

docs/assets/techdocs/aws-s3.drawio.svg

@@ -0,0 +1,144 @@
+<svg host="65bd71144e" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="605px" height="362px" viewBox="-0.5 -0.5 605 362" content="&lt;mxfile host=&quot;046c5cfb-a3a2-464c-a595-f674d31136ed&quot; modified=&quot;2020-12-26T01:33:35.255Z&quot; agent=&quot;5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Code/1.52.1 Chrome/83.0.4103.122 Electron/9.3.5 Safari/537.36&quot; etag=&quot;nIR1gVsObWk5MHRRKeB7&quot; version=&quot;13.10.0&quot; type=&quot;embed&quot;&gt;&lt;diagram id=&quot;fZcCmqQ9Q5JzR6r55YHy&quot; name=&quot;Page-1&quot;&gt;7VhNc5swEP01HJtBiA/7iI3dHtqT20lzlIUCajCishzb/fVdQBhkSOLWjtPJ9JJo367Qat/TImzh6Wr3UZIi/SJillmOHe8sHFmO43sI/pbAXgPBuAYSyeMasltgwX+xGkQNuuExW2ushpQQmeKFCVKR54wqAyNSiq0Zdi+y2AAKkrAesKAk66O3PFapRn3bbh2fGE9SvfS4cSwJfUik2OR6PcvBczQPZ7PavSLNs3T8OiWx2HYgPLPwVAqh6tFqN2VZWVqzbPMnvIe8JcvVKRM8nccjyTasSblKTO2bYmxTrtiiILS0t8C3hSepWmVgIRje8yybikxIsHORQ9BkraR4YA0INXC9YDKOwKNXY1Kx3ZMpo0MhQF9MrJiSewjRE5xRPUNLy3Frc9vy5Nu4xtIORdjXWyVaG8nhyW19YKBLNFwu1+9VR0iVikTkJPssRKFr8oMptdeyJhslzIqxHVffYWzr8V0Hj3YdR7RvjBwSrabceI151/W10yqrnReH5XFoqQFkzsv9Vf6aqEbi6FnqKlWzWM+s68Di3jk6ohFqJTaS6ijNiyIyYTrK9YbZliwjij+ajz+Lu6DHXZn+Qpu6PuYuzyAX/SPkDlHZp/1ydLpXohMPNC4/U2VDEpByl2f/50Y0jg/rirgQApBf7FonjBL9v3rKsgHCeMXzBoWslm2k/W3NZMdVr9x4j8RmKuuFprp+YIqmLxLZ7b2Ah6MojKZ6px0cRdjzgkNSA6z2OvLT7ddFRv9Fdr8Bo8DtN+Cxd4Ez7FyN9dsFBIeUAmtqmP3TaIeyqiNuDTr10R14i5KMJzmYFMgCmeFJSRKHS0qoHSsex+Uyg2Iy5Wbo6RXVgbEhDuz3tYFQXxvOJd7N7rW08ZXRNBJ0/a6awll3Mhd5R5eyAeJfrSl41yJ+Aeq2JxsKPJzTEt4J6X7whpyPXuKcHjbd0lqWazmOu9AJ2nCHtNE95EvZoIXION3//atBMliXLKuAku/yellnUrlPfyMUgueqqq83sbxjgQx+pg1egC/RG4Lxjdkd0Aj3lNKIx/hkcy8glPEbC8VsF/+l8pxUkBOcIBVv6Ov+z6UCZvs7S+Xr/JaFZ78B&lt;/diagram&gt;&lt;/mxfile&gt;" style="background-color: rgb(241, 250, 238);">
+    <defs/>
+    <g>
+        <rect x="0" y="0" width="603" height="360" fill="none" stroke="#457b9d" pointer-events="all"/>
+        <path d="M 213 175 L 126 222" fill="none" stroke="#457b9d" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 387 175 L 474 222" fill="none" stroke="#457b9d" stroke-miterlimit="10" pointer-events="stroke"/>
+        <rect x="213" y="80" width="174" height="95" fill="#a8dadc" stroke="#457b9d" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 172px; height: 1px; padding-top: 128px; margin-left: 214px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #1D3557; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font style="font-size: 16px">
+                                    <b>
+                                        Admin
+                                    </b>
+                                    User
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="300" y="131" fill="#1D3557" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Admin User
+                </text>
+            </switch>
+        </g>
+        <rect x="5" y="12" width="111" height="20" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 109px; height: 1px; padding-top: 22px; margin-left: 6px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #1D3557; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font style="font-size: 16px">
+                                    <b>
+                                        AWS Account
+                                    </b>
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="61" y="26" fill="#1D3557" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    AWS Account
+                </text>
+            </switch>
+        </g>
+        <rect x="387" y="222" width="174" height="95" fill="#a8dadc" stroke="#457b9d" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 172px; height: 1px; padding-top: 270px; margin-left: 388px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #1D3557; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font style="font-size: 16px">
+                                    <b>
+                                        TechDocs
+                                    </b>
+                                    User
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="474" y="273" fill="#1D3557" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    TechDocs User
+                </text>
+            </switch>
+        </g>
+        <rect x="39" y="222" width="174" height="95" fill="#a8dadc" stroke="#457b9d" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 172px; height: 1px; padding-top: 270px; margin-left: 40px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #1D3557; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                <font style="font-size: 16px">
+                                    <b>
+                                        S3 Bucket
+                                    </b>
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="126" y="273" fill="#1D3557" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    S3 Bucket
+                </text>
+            </switch>
+        </g>
+        <rect x="451.5" y="159" width="46" height="34" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 176px; margin-left: 475px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                <font color="#457b9d" style="font-size: 14px">
+                                    User
+                                    <br/>
+                                    policy
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="475" y="180" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    User...
+                </text>
+            </switch>
+        </g>
+        <rect x="99.5" y="159" width="53" height="34" fill="none" stroke="none" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 176px; margin-left: 126px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: nowrap; ">
+                                <font color="#457b9d" style="font-size: 14px">
+                                    Bucket
+                                    <br/>
+                                    policy
+                                </font>
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="126" y="180" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    Bucket...
+                </text>
+            </switch>
+        </g>
+    </g>
+    <switch>
+        <g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/>
+        <a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank">
+            <text text-anchor="middle" font-size="10px" x="50%" y="100%">
+                Viewer does not support full SVG 1.1
+            </text>
+        </a>
+    </switch>
+</svg>

docs/auth/auth-backend-classes.md

@@ -61,6 +61,19 @@ If your authentication provider is any of the above mentioned providers, you can
 configure them by setting the right variables in `app-config.yaml` under the
 `auth` section.
 
+### SAML
+
+The SAML Provider is currently under development. Additional validation and
+profile handling is still required before use in production.
+
+To configure the SAML Auth provider, look at the configuration parameters
+supported by
+[Passport-SAML](https://github.com/node-saml/passport-saml#config-parameter-details)
+under the `auth.providers.saml` key
+
+For security reasons, validate that the response from the IdP is indeed signed
+by also providing the `cert` configuration.
+
 ### Configuration
 
 Each authentication provider (except SAML) needs five parameters: an OAuth
@@ -96,6 +109,11 @@ auth:
       development:
         clientId:
           $env:
+    saml:
+      entryPoint:
+        $env: AUTH_SAML_ENTRY_POINT
+      issuer:
+        $env: AUTH_SAML_ISSUER
             ...
 ```
 

docs/auth/index.md

@@ -93,6 +93,6 @@ sign-in methods.
 More details are provided in dedicated sections of the documentation.
 
 - [OAuth](./oauth.md): Description of the generic OAuth flow implemented by the
-  [auth-backend](../../plugins/auth-backend).
+  [auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend).
 - [Glossary](./glossary.md): Glossary of some common terms related to the auth
   flows.

docs/auth/oauth.md

@@ -1,9 +1,8 @@
 ---
 id: oauth
 title: OAuth and OpenID Connect
-description: This section describes how Backstage allows plugins to request
-OAuth Access Tokens and OpenID Connect ID Tokens on behalf of the user, to be
-used for auth to various third party APIs
+# prettier-ignore
+description: This section describes how Backstage allows plugins to request OAuth Access Tokens and OpenID Connect ID Tokens on behalf of the user, to be used for auth to various third party APIs
 ---
 
 This section describes how Backstage allows plugins to request OAuth Access

docs/cli/commands.md

@@ -0,0 +1,606 @@
+---
+id: commands
+title: Commands
+description: Descriptions of all commands available in the CLI.
+---
+
+This page lists all commands provided by the Backstage CLI, what they're for,
+and where to use them.
+
+The documentation for each command begins with specifying its scope, this
+indicates where the command should be used by selecting from the following list:
+
+- `app` - A frontend app package, such as `packages/app`.
+- `backend` - A backend package, such as `packages/backend`.
+- `frontend-plugin` - A frontend plugin package.
+- `backend-plugin` - A backend plugin package.
+- `root` - The monorepo root.
+- `any` - Any kind of package, but not the repo root.
+
+## help
+
+This command displays a help summary or detailed help screens for each command.
+Below is a cleaned up output of `yarn backstage-cli --help`.
+
+```text
+app:build                Build an app for a production release
+app:diff                 Diff an existing app with the creation template
+app:serve                Serve an app for local development
+
+backend:build            Build a backend plugin
+backend:bundle           Bundle the backend into a deployment archive
+backend:build-image      Bundles the package into a docker image
+backend:dev              Start local development server with HMR for the backend
+
+plugin:build             Build a plugin
+plugin:diff              Diff an existing plugin with the creation template
+plugin:serve             Serves the dev/ folder of a plugin
+
+build                    Build a package for publishing
+build-workspace          Builds a temporary dist workspace from the provided packages
+lint                     Lint a package
+test                     Run tests, forwarding args to Jest, defaulting to watch mode
+clean                    Delete cache directories
+
+create-plugin            Creates a new plugin in the current repository
+remove-plugin            Removes plugin in the current repository
+
+config:print             Print the app configuration for the current package
+config:check             Validate that the given configuration loads and matches schema
+
+versions:bump            Bump Backstage packages to the latest versions
+versions:check           Check Backstage package versioning
+
+prepack                  Prepares a package for packaging before publishing
+postpack                 Restores the changes made by the prepack command
+
+help [command]           display help for command
+```
+
+## app:build
+
+Scope: `app`
+
+Builds a bundle of static content from the app, which can then be served via any
+static web server such as `nginx`, or via the
+[`app-backend`](https://www.npmjs.com/package/@backstage/plugin-app-backend)
+plugin directly from a Backstage backend instance.
+
+The command also reads and injects static configuration into the bundle. It is
+important to note that when deploying using your own static content hosting
+solution, this will be the final configuration used in the frontend unless you
+for example hook in configuration loading from the backend. When using the
+`nginx` based Dockerfile in this repo along with its included run script,
+`APP_CONFIG_` environment variables will be injected into the frontend, and when
+serving using the `app-backend` plugin, the configuration is completely injected
+from the backend and the configuration at the time of calling this command will
+not be used.
+
+Note that even when injecting configuration at runtime, it is not possible to
+change the base path of the app. For example, if you at build time have
+`app.baseUrl` set to `http://dev-app.com/my-app`, you can change that to
+`https://prod-app.com/my-app`, but not to `https://prod-app.com`, as that would
+change the path.
+
+During the build, the following variables are set:
+
+```java
+process.env.NODE_ENV = 'production';
+process.env.BUILD_INFO = {
+  cliVersion: '0.4.0', // The version of the CLI package
+  gitVersion: 'v0.4.0-86-ge54815618', // output of `git describe --always`
+  packageVersion: '1.0.5', // The version of the app package itself
+  timestamp: 1678900000000, // Date.now() when the build started
+  commit: 'e548156182a973ed4b459e18533afc22c85ffff8', // output of `git rev-parse HEAD`
+};
+```
+
+Some CI environments do not properly report correct resource limits, potentially
+leading to errors such as `ENOMEM` during compilation. If you run into this
+issue you can limit the parallelization of the build process by setting the
+environment variable `BACKSTAGE_CLI_BUILD_PARALLEL`, which is forwarded to the
+[`terser-webpack-plugin`](https://github.com/webpack-contrib/terser-webpack-plugin#parallel).
+You can set it to `false` or `1` to completely disable parallelization, but
+usually a low value such as `2` is enough.
+
+```text
+Usage: backstage-cli app:build
+
+Options:
+  --stats          Write bundle stats to output directory
+  --config <path>  Config files to load instead of app-config.yaml (default: [])
+  -h, --help       display help for command
+```
+
+## app:diff
+
+Scope: `app`
+
+Diff an existing app with the template used in `@backstage/create-app`. This
+will verify that your app package has not diverged from the template, and can be
+useful to run after updating the version of `@backstage/cli` in your app.
+
+This command is experimental and may be removed in the future.
+
+```text
+Usage: backstage-cli app:diff
+
+Options:
+  --check     Fail if changes are required
+  --yes       Apply all changes
+  -h, --help  display help for command
+```
+
+## app:serve
+
+Scope: `app`
+
+Serve an app for local development. This starts up a local development server,
+using a bundling configuration that is quite similar to that of the `app:build`
+command, but with development features such as React Hot Module Replacement,
+faster sourcemaps, no minification, etc.
+
+The static configuration is injected into the frontend, but it does not support
+watching, meaning that changes in for example `app-config.yaml` are not
+reflected until the serve process is restarted.
+
+During the build, the following variables are set:
+
+```java
+process.env.NODE_ENV = 'development';
+process.env.BUILD_INFO = { /* See app:build */ };
+```
+
+The server listening configuration is controlled through the static
+configuration. The `app.baseUrl` determines the listening host and port, as well
+as whether HTTPS is used or not. It is also possible to override the listening
+host and port if needed by setting `app.listen.host` and `app.listen.port`.
+
+```text
+Usage: backstage-cli app:serve [options]
+
+Options:
+  --check          Enable type checking and linting
+  --config <path>  Config files to load instead of app-config.yaml (default: [])
+  -h, --help       display help for command
+```
+
+## backend:build
+
+Scope: `backend-plugin`
+
+This builds a backend package for publishing and use in production. The build
+output is written to `dist/`. Be sure to list any additional file that the
+package depends on at runtime in the `"files"` field inside `package.json`, a
+common example being the `migrations` directory.
+
+```text
+Usage: backstage-cli backend:build [options]
+
+Options:
+  -h, --help  display help for command
+```
+
+## backend:bundle
+
+Scope: `backend`
+
+Bundle the backend and all of its local dependencies into a deployment archive.
+The archive is written to `dist/bundle.tar.gz`, and contains the packaged
+version of all dependencies of the target package, along with the target package
+itself. The layout of the packages in the archive is the same as the directory
+layout in the target monorepo, and the bundle also contains the root
+`package.json` and `yarn.lock`.
+
+To use the bundle, extract it into a target directory, run
+`yarn install --production`, and then start the target backend package using for
+example `node package/backend`.
+
+The `dist/bundle.tar.gz` is accompanied by a `dist/skeleton.tar.gz`, which has
+the same layout, but only contains `package.json` files and `yarn.lock`. This
+can be used to run a `yarn install` in environments that will benefit from the
+caching that this enables, such as Docker image builds. To use the skeleton
+archive, simply extract it first, run install, and then extract the main bundle.
+
+The following is an example of a `Dockerfile` that can be used to package the
+output of `backstage-cli backend:bundle` into an image:
+
+```Dockerfile
+FROM node:14-buster
+WORKDIR /app
+
+ADD yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./
+RUN yarn install --production --network-timeout 600000 && rm -rf "$(yarn cache dir)"
+
+ADD packages/backend/dist/bundle.tar.gz app-config.yaml ./
+
+CMD node packages/backend
+```
+
+```text
+Usage: backstage-cli backend:bundle [options]
+
+Bundle the backend into a deployment archive
+
+Options:
+  --build-dependencies  Build all local package dependencies before bundling the backend
+  -h, --help            display help for command
+```
+
+## backend:build-image
+
+Scope: `backend`
+
+Builds a Docker image of the backend package, forwarding all unknown options to
+`docker image build`. For example:
+
+```bash
+yarn backstage-cli backend:build-image --build --tag my-backend-image
+```
+
+The image is built using the backend package along with all of its local package
+dependencies. It expects to find a `Dockerfile` at the root of the backend
+package, which will be used during the build.
+
+The Dockerfile is **NOT** executed within the package or repo itself. Because
+the packages in the repo itself are configured for development instead of
+production use, the final Docker build happens in a separate temporary
+directory, to which the backend package and dependencies have been copied. Only
+files listed within the `"files"` field within each package's `package.json` are
+copied over, along with the root `package.json`, `yarn.lock`, and any
+`app-config.*.yaml` files.
+
+During the build a `skeleton.tar` file is created and put at the repo root. This
+file contains the `package.json` of each included package, which together with
+the root `package.json` and `yarn.lock` can be used to run a cached
+`yarn install` before the full production builds of all the packages are copied
+over, providing a significant speedup if Docker build layer caching available.
+
+This command is experimental and we hope to be able to replace it with one that
+is less integrated directly with Docker, and also supports multi-stage Docker
+builds. It is possible to replicate most of what this command does by manually
+building each package, and then use the `build-workspace` to create the
+temporary workspace, and finally copy over any additional files to the workspace
+and execute the Docker build within it.
+
+```text
+Usage: backstage-cli backend:build-image [options]
+
+Options:
+  --build                 Build packages before packing them into the image
+  --backstage-cli-help    display help for command
+```
+
+## backend:dev
+
+Scope: `backend`, `backend-plugin`
+
+Starts a backend package in development mode, with watch mode enabled for all
+local dependencies.
+
+```text
+Usage: backstage-cli backend:dev [options]
+
+Options:
+  --check          Enable type checking and linting
+  --inspect        Enable debugger
+  --config <path>  Config files to load instead of app-config.yaml (default: [])
+  -h, --help       display help for command
+```
+
+## create-plugin
+
+Scope: `root`
+
+Creates a new plugin within the repository. This command is typically wrapped up
+in the root `package.json` to be executed with `yarn create-plugin`, using
+options that are appropriate for the organization that owns the app repo. A
+recommended scope for internal packages is `@internal`.
+
+```text
+Usage: backstage-cli create-plugin [options]
+
+Options:
+  --backend             Create plugin with the backend dependencies as default
+  --scope <scope>       npm scope
+  --npm-registry <URL>  npm registry URL
+  --no-private          Public npm package
+  -h, --help            display help for command
+```
+
+## remove-plugin
+
+Scope: `root`
+
+A utility to remove a plugin from a repo, essentially undoing everything that
+was done by `create-plugin`.
+
+This is primarily intended as a utility for manual tests and end to end testing
+scripts.
+
+```text
+Usage: backstage-cli remove-plugin [options]
+
+Options:
+  -h, --help  display help for command
+```
+
+## plugin:build
+
+Scope: `frontend-plugin`
+
+Build a frontend plugin for publishing to a package registry. There is no need
+to run this command during development or even in CI unless the package is being
+published. The `app:bundle` command does not use the output for this command
+when bundling local package dependencies.
+
+The output is written to a `dist/` folder. It also outputs type declarations for
+the plugin, and therefore requires `yarn tsc` to have been run first. The input
+type declarations are expected to be found within `dist-types/` at the root of
+the monorepo.
+
+```text
+Usage: backstage-cli plugin:build [options]
+
+Options:
+  -h, --help  display help for command
+```
+
+## plugin:serve
+
+Scope: `frontend-plugin`
+
+Serves a frontend plugin by itself for isolated development. The serve task
+itself is essentially identical to `app:serve`, but the entrypoint is instead
+set to the `dev/` folder within the plugin.
+
+The `dev/` folder typically contains a small wrapper script that hooks up any
+necessary mock APIs or other things that are needed for the plugin to function.
+The `@backstage/dev-utils` package provides utilities to that end.
+
+```text
+Usage: backstage-cli plugin:serve [options]
+
+Options:
+  --check          Enable type checking and linting
+  --config <path>  Config files to load instead of app-config.yaml (default: [])
+  -h, --help       display help for command
+```
+
+## plugin:diff
+
+Scope: `frontend-plugin`
+
+Compares a frontend plugin to the `create-plugin` template, making sure that it
+hasn't diverged from the template and recommending updates when it has. A good
+practice is to run this command after updating the version of the CLI in a
+project.
+
+```text
+Usage: backstage-cli plugin:diff [options]
+
+Options:
+  --check     Fail if changes are required
+  --yes       Apply all changes
+  -h, --help  display help for command
+```
+
+## build
+
+Scope: `any`
+
+Build a single package for publishing, just like the `plugin:build` and
+`backend:build` commands. This command is intended for standalone packages that
+aren't plugins, and for example support building of isomorphic packages for
+usage in both the frontend and backend.
+
+For frontend packages you'll want to include `esm` output, and for backend
+packages `cjs`. Whether to include `types` depends on if you need type
+declarations for the package, and also requires `yarn tsc` to have been run
+first.
+
+```text
+Usage: backstage-cli build [options]
+
+Options:
+  --outputs <formats>  List of formats to output [types,cjs,esm]
+  -h, --help           display help for command
+```
+
+## lint
+
+Scope: `any`
+
+Lint a package. In addition to the default `eslint` behavior, this command will
+include TypeScript files, treat warnings as errors, and default to linting the
+entire directory if no specific files are listed.
+
+```text
+Usage: backstage-cli lint [options]
+
+Options:
+  --format <format>  Lint report output format (default: "eslint-formatter-friendly")
+  --fix              Attempt to automatically fix violations
+  -h, --help         display help for command
+```
+
+## test
+
+Scope: `any`
+
+Run tests, forwarding all unknown options to Jest, and defaulting to watch mode.
+When executing the tests, `process.env.NODE_ENV` will be set to `"test"`.
+
+This command uses a default Jest configuration that is included in the CLI,
+which is set up with similar goals for speed, scale, and working within a
+monorepo. The configuration sets the `src` as the root directory, enforces the
+`.test.` infix for tests, and uses `src/setupTests.ts` as the test setup
+location.
+
+If needed, the configuration can be extended using a `"jest"` field in
+`package.json`, both within the target package and the monorepo root, with
+configuration in the target package taking precedence. Refer to the
+[Jest configuration documentation](https://jestjs.io/docs/en/configuration) for
+a full list of configuration options.
+
+In addition to the Jest configuration there's an optional `transformModules`
+option, which is an array of module names to include in transformations.
+Normally modules inside `node_modules` are not transformed, but there are cases
+were published packages are not transpiled far enough to be usable by Jest, in
+which case you need to enable transform of them.
+
+Another way to override the Jest configuration is to place a `jest.config.js` or
+`jest.config.ts` file in the package root. As opposed to the `package.json` way
+of overriding config, this completely removes the base config, and so you need
+to set it up from scratch.
+
+```text
+Usage: backstage-cli test [options]
+
+Options:
+  --backstage-cli-help    display help for command
+```
+
+## config:print
+
+Scope: `root`
+
+Print the static configuration, defaulting to reading `app-config.yaml` in the
+repo root, using schema collected from all local packages in the repo.
+
+For example, to validate that a given configuration value is visible in the
+frontend when building the `my-app` package, you can use the following:
+
+```bash
+yarn backstage-cli config:print --frontend --package my-app
+```
+
+```text
+Usage: backstage-cli config:print [options]
+
+Options:
+  --package <name>   Only load config schema that applies to the given package
+  --frontend         Print only the frontend configuration
+  --with-secrets     Include secrets in the printed configuration
+  --format <format>  Format to print the configuration in, either json or yaml [yaml]
+  --config <path>    Config files to load instead of app-config.yaml (default: [])
+  -h, --help         display help for command
+```
+
+## config:check
+
+Scope: `root`
+
+Validate that static configuration loads and matches schema, defaulting to
+reading `app-config.yaml` in the repo root and using schema collected from all
+local packages in the repo.
+
+```text
+Usage: backstage-cli config:check [options]
+
+Options:
+  --package <name>  Only load config schema that applies to the given package
+  --config <path>   Config files to load instead of app-config.yaml (default: [])
+  -h, --help        display help for command
+```
+
+## versions:bump
+
+Scope: `root`
+
+Bump all `@backstage` packages to the latest versions. This checks for updates
+in the package registry, and will update entries both in `yarn.lock` and
+`package.json` files when necessary.
+
+```text
+Usage: backstage-cli versions:bump [options]
+
+Options:
+  -h, --help  display help for command
+```
+
+## versions:check
+
+Scope: `root`
+
+Validate `@backstage` dependencies within the repo, making sure that there are
+no duplicates of packages that might lead to breakages. For example,
+`@backstage/core` must not be loaded in twice, so having two different versions
+of it installed will cause this command to exit with an error.
+
+By supplying the `--fix` flag the command will attempt to fix any conflict that
+can be resolved by editing `yarn.lock`, but will not attempt to search for
+remote updates or modify any `package.json` files.
+
+```text
+Usage: backstage-cli versions:check [options]
+
+Options:
+  --fix       Fix any auto-fixable versioning problems
+  -h, --help  display help for command
+```
+
+## prepack
+
+Scope: `any`
+
+This command should be added as `scripts.prepack` in all packages. It enables
+packaging- and publish-time overrides for fields inside `packages.json`.
+
+The checked in version of all packages in a Backstage monorepo are tailored for
+local development, and as such `main` and similar fields inside `package.json`
+point to development source, i.e. `src/index.ts`. Using this when publishing
+would lead to a broken package, since `src/` is not included in the published
+package and we instead need to point to files in the `dist/` directory. This
+command allows for those fields to be rewritten when needed, and does so by
+copying all fields within `publishConfig` to the top-level of each
+`package.json`, skipping `access`, `registry`, and `tag`.
+
+The need for this command may be removed in the future, as this exact method of
+overriding fields for publishing is already supported by some package managers.
+
+```text
+Usage: backstage-cli prepack [options]
+
+Options:
+  -h, --help  display help for command
+```
+
+## postpack
+
+Scope: `any`
+
+This should be added as `scripts.postpack` in all packages. It restores
+`package.json` to what it looked like before calling the `prepack` command.
+
+```text
+Usage: backstage-cli postpack [options]
+
+Options:
+  -h, --help  display help for command
+```
+
+## clean
+
+Scope: `any`
+
+Remove cache and output directories.
+
+```text
+Usage: backstage-cli clean [options]
+
+Options:
+  -h, --help  display help for command
+```
+
+## build-workspace
+
+Scope: `any`, `root`
+
+Builds a mirror of the workspace using the packaged production version of each
+package. This essentially calls `yarn pack` in each included package and unpacks
+the resulting archive in the target `workspace-dir`.
+
+```text
+Usage: backstage-cli build-workspace [options] <workspace-dir>
+```

docs/cli/index.md

@@ -0,0 +1,108 @@
+---
+id: index
+title: Overview
+description: Overview of the Backstage CLI
+---
+
+## Summary
+
+Backstage provides an opinionated set of tooling for both frontend and backend
+development. It is delivered through the
+[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) package and
+executed either directly through `yarn backstage-cli <command>` or within
+`package.json` scripts. When creating an app using
+[`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app)
+it contains package scripts for executing the most common commands.
+
+Under the hood the CLI uses [Webpack](https://webpack.js.org/) for bundling,
+[Rollup](https://rollupjs.org/) for building packages,
+[Jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for
+linting. It also includes custom tooling for working within Backstage apps, for
+example for keeping the app up to date and verifying static configuration.
+
+For a full list of CLI commands, see the [commands](./commands.md) page.
+
+## Introduction
+
+A goal of Backstage is to provide a delightful developer experience in and
+around the project. Creating new apps and plugins should be simple, iteration
+speed should be fast, and the overhead of maintaining custom tooling should be
+minimal. As a part of accomplishing this goal, Backstage provides its own set of
+opinionated tooling, delivered primarily through the
+[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) package.
+
+The `@backstage/cli` package provides a single executable script,
+`backstage-cli`, which you can run directly with `yarn` or within a script in
+`package.json`. If you have a Backstage app set up, you can try out the
+following command to print the top-level help page of the CLI:
+
+```text
+yarn backstage-cli --help
+```
+
+If you are familiar with [`create-react-app`](https://create-react-app.dev/) you
+may recognize the pattern of bundling tooling up as a CLI, as it uses a package
+called [`react-scripts`](https://www.npmjs.com/package/react-scripts) to bring
+most of the functionality into the created project. The Backstage equivalent of
+`create-react-app` is
+[`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app),
+and the equivalent of `react-scripts` is `@backstage/cli`. There are however a
+couple of key differences between the two. Most notably, Backstage apps are
+monorepos and the CLI is tailored for that environment. It provides tooling both
+for bundling and developing full end-user apps, but also for developing,
+building and publishing individual packages within the monorepo, as well as
+tooling that is more unique to Backstage, such as commands for working with
+static configuration.
+
+## Opinionated Tooling
+
+The Backstage CLI is highly opinionated in what tools are used and how they are
+configured. It is tailored for development in large TypeScript monorepos with
+hundreds of separate packages, but with the ability to have edits anywhere in
+the codebase reflected within a few seconds. The build output is also optimized
+for this setup, and aims to provide an excellent user experience with fast page
+load times in modern browsers, rather than a wide range of support.
+
+While the Backstage tooling is opinionated in how to develop and build packages,
+it is also possible to use your own tooling either partially or fully. For
+example, the CLI provides a command for building a plugin package for
+publishing, but the output is a quite standard combination of transpiled
+JavaScript and TypeScript type declarations. The usage of the command from the
+CLI can therefore easily be replaced with other tools if necessary.
+
+Just like `react-scripts`, the Backstage CLI does not provide many hooks for
+overriding or customizing the build process. This is to allow for evolution of
+the CLI without having to take a wide API surface into account. This allows us
+to quickly iterate and improve the tooling, as well as to more easily keep
+dependencies up to date.
+
+## Opinions & Goals
+
+In no particular order, this is a list of opinions and goals that guide the
+design and development of the Backstage CLI:
+
+- All you need for development is `yarn start`, there should be no need to
+  manually build packages or run other separate tasks.
+- Development experience comes first. The toolchain is optimized for keeping
+  development smooth, rather than making it easy to for example build and
+  publish packages.
+- Type checking and linting is left for text editors and Continuous Integration.
+  Most text editors provide tooling for these checks, and running them a second
+  time during compilation slows down iteration speed and consumes more system
+  resources.
+- Backstage is run in modern browsers. We keep transpilation lightweight and
+  rely on modern technologies such as HTTP/2 to optimize frontend speed.
+
+## Glossary
+
+- **Package** - A package in the Node.js ecosystem, often published to a package
+  registry such as [NPM](https://www.npmjs.com/).
+- **Monorepo** - A project layout that consists of multiple packages within a
+  single project, where packages are able to have local dependencies on each
+  other. Often enabled through tooling such as [lerna](https://lerna.js.org/)
+  and [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)
+- **Local Package** - One of the packages within a monorepo. These package may
+  or may not also be published to a package registry.
+- **Bundle** - A collection of the deployment artifacts. The output of the
+  bundling process, which brings a collection of packages into a single
+  collection of deployment artifacts.

docs/conf/defining.md

@@ -36,6 +36,10 @@ export interface Config {
      * @visibility frontend
      */
     baseUrl: string;
+
+    // Use @items.<name> to assign annotations to primitive array items
+    /** @items.visibility frontend */
+    myItems: string[];
   };
 }
 ```
@@ -83,6 +87,12 @@ object will be available in the frontend. The full ancestry does not need to
 have correctly defined visibilities however, so it is enough to only for example
 declare the visibility of a leaf node of `type: "string"`.
 
+| `visibility` |                                                                    |
+| ------------ | ------------------------------------------------------------------ |
+| `frontend`   | Visible in frontend and backend                                    |
+| `backend`    | (Default) Only in backend                                          |
+| `secret`     | Only in backend and may be excluded from logs for security reasons |
+
 ## Validation
 
 Schemas can be validated using the `backstage-cli config:check` command. If you

docs/conf/index.md

@@ -18,8 +18,8 @@ allowing for customization.
 Configuration is stored in YAML files where the defaults are `app-config.yaml`
 and `app-config.local.yaml` for local overrides. Other sets of files can by
 loaded by passing `--config <path>` flags. The configuration files themselves
-contain plain YAML, but with support for loading in secrets from various sources
-using for example `$env` and `$file` keys.
+contain plain YAML, but with support for loading in data and secrets from
+various sources using for example `$env` and `$file` keys.
 
 It is also possible to supply configuration through environment variables, for
 example `APP_CONFIG_app_baseUrl=https://staging.example.com`. However these

docs/conf/writing.md

@@ -97,13 +97,13 @@ order:
 - If no config flags are provided, `app-config.local.yaml` has higher priority
   than `app-config.yaml`.
 
-## Secrets and Dynamic Data
+## Includes and Dynamic Data
 
-Secrets are supported via special data loading keys that are prefixed with `$`,
-which in turn provide a number of different ways to read in secrets. To load a
-configuration value as a secret, supply an object with one of the special secret
-keys, for example `$env` or `$file`. A full list of supported secret keys can be
-found below. For example, the following will read the config key
+Includes are supported via special data loading keys that are prefixed with `$`,
+which in turn provide a number of different ways to read in data. To load in an
+external configuration value, supply an object with one of the special include
+keys, for example `$env` or `$file`. A full list of supported include keys can
+be found below. For example, the following will read the config key
 `backend.mySecretKey` from the environment variable `MY_SECRET_KEY`:
 
 ```yaml
@@ -114,43 +114,42 @@ backend:
 
 With the above configuration, calling `config.getString('backend.mySecretKey')`
 will return the value of the environment variable `MY_SECRET_KEY` when the
-backend started up. All secrets are loaded at startup, so changing the contents
-of secret files or environment variables will not be reflected at runtime.
+backend started up. All includes are loaded at startup, so changing the contents
+of files or environment variables will not be reflected at runtime.
 
-As hinted at, secrets can be loaded from a bunch of different sources, and can
-be extended with more. Below is a list of the currently supported methods for
-loading secrets.
+Below is a list of the currently supported methods for loading includes.
 
-### Env Secrets
+### Env Includes
 
-This reads a secret from an environment variable. For example, the following
-config loads the secret from the `MY_SECRET` env var.
+This reads a string value from an environment variable. For example, the
+following configuration loads the string value from the `MY_SECRET` environment
+variable.
 
 ```yaml
 $env: MY_SECRET
 ```
 
-### File Secrets
+### File Includes
 
-This reads a secret from the entire contents of a file. The file path is
-relative to the `app-config.yaml` the defines the secrets. For example, the
-following reads the contents of `my-secret.txt` relative to the config file
-itself:
+This reads a string value from the entire contents of a text file. The file path
+is relative to the source config file. For example, the following reads the
+contents of `my-secret.txt` relative to the config file itself:
 
 ```yaml
 $file: ./my-secret.txt
 ```
 
-### Data File Secrets
+### Including Files
 
-This reads secrets from a path within a JSON-like data file. The file path
-behaves similar to file secrets, but with the addition of a url fragment that is
-used to point to a specific value inside the file. Supported file extensions are
-`.json`, `.yaml`, and `.yml`. For example, the following would read out
-`my-secret-key` from `my-secrets.json`:
+The `$include` keyword can be used to load configuration values from an external
+file. It's able to load and parse data from `.json`, `.yml`, and `.yaml` files.
+It's also possible to include a url fragment (`#`) to point to a value at the
+given path in the file, using a dot-separated list of keys.
+
+For example, the following would read `my-secret-key` from `my-secrets.json`:
 
 ```yaml
-$data: ./my-secrets.json#deployment.key
+$include: ./my-secrets.json#deployment.key
 ```
 
 Example `my-secrets.json` file:
@@ -162,3 +161,19 @@ Example `my-secrets.json` file:
   }
 }
 ```
+
+## Environment Variable Substitution
+
+Configuration files support environment variable substitution via a `${MY_VAR}`
+syntax. For example:
+
+```yaml
+app:
+  baseUrl: https://${HOST}
+```
+
+Note that all environment variables must be available, or the entire
+configuration value will evaluate to `undefined`.
+
+The substitution syntax can be escaped using `$${...}`, which will be resolved
+as `${...}`.

docs/dls/figma.md

@@ -1,8 +1,8 @@
 ---
 id: figma
 title: Figma
-description: Documentation on using Figma to build your own plugins for
-Backstage
+# prettier-ignore
+description: Documentation on using Figma to build your own plugins for Backstage
 ---
 
 We have a [Figma component library](https://www.figma.com/@backstage) that you

docs/features/kubernetes/configuration.md

@@ -0,0 +1,130 @@
+---
+id: configuration
+title: Configuring Kubernetes integration
+sidebar_label: Configuration
+# prettier-ignore
+description: Configuring the Kubernetes integration for Backstage expose your entity's objects
+---
+
+Configuring the Backstage Kubernetes integration involves two steps:
+
+1. Enabling the backend to collect objects from your Kubernetes cluster(s).
+2. Surfacing your Kubernetes objects in catalog entities
+
+## Configuring Kubernetes Clusters
+
+The following is a full example entry in `app-config.yaml`:
+
+```yaml
+kubernetes:
+  serviceLocatorMethod: 'multiTenant'
+  clusterLocatorMethods:
+    - 'config'
+  clusters:
+    - url: http://127.0.0.1:9999
+      name: minikube
+      authProvider: 'serviceAccount'
+      serviceAccountToken:
+        $env: K8S_MINIKUBE_TOKEN
+    - url: http://127.0.0.2:9999
+      name: gke-cluster-1
+      authProvider: 'google'
+```
+
+### `serviceLocatorMethod`
+
+This configures how to determine which clusters a component is running in.
+
+Currently, the only valid value is:
+
+- `multiTenant` - This configuration assumes that all components run on all the
+  provided clusters.
+
+### `clusterLocatorMethods`
+
+This is an array used to determine where to retrieve cluster configuration from.
+
+Currently, the only valid cluster locator method is:
+
+- `config` - This cluster locator method will read cluster information from your
+  app-config (see below).
+
+### `clusters`
+
+Used by the `config` cluster locator method to construct Kubernetes clients.
+
+### `clusters.\*.url`
+
+The base URL to the Kubernetes control plane. Can be found by using the
+"Kubernetes master" result from running the `kubectl cluster-info` command.
+
+### `clusters.\*.name`
+
+A name to represent this cluster, this must be unique within the `clusters`
+array. Users will see this value in the Service Catalog Kubernetes plugin.
+
+### `clusters.\*.authProvider`
+
+This determines how the Kubernetes client authenticates with the Kubernetes
+cluster. Valid values are:
+
+| Value            | Description                                                                                                                                                                                                                       |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `serviceAccount` | This will use a Kubernetes [service account](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set. |
+| `google`         | This will use a user's Google auth token from the [Google auth plugin](https://backstage.io/docs/auth/) to access the Kubernetes API.                                                                                             |
+
+### `clusters.\*.serviceAccount` (optional)
+
+The service account token to be used when using the `serviceAccount` auth
+provider.
+
+### Role Based Access Control
+
+The current RBAC permissions required are read-only cluster wide, for the
+following objects:
+
+- pods
+- services
+- configmaps
+- deployments
+- replicasets
+- horizontalpodautoscalers
+- ingresses
+
+## Surfacing your Kubernetes components as part of an entity
+
+There are two ways to surface your Kubernetes components as part of an entity.
+The label selector takes precedence over the annotation/service id.
+
+### Common `backstage.io/kubernetes-id` label
+
+#### Adding the entity annotation
+
+In order for Backstage to detect that an entity has Kubernetes components, the
+following annotation should be added to the entity's `catalog-info.yaml`:
+
+```yaml
+annotations:
+  'backstage.io/kubernetes-id': dice-roller
+```
+
+#### Labeling Kubernetes components
+
+In order for Kubernetes components to show up in the service catalog as a part
+of an entity, Kubernetes components themselves can have the following label:
+
+```yaml
+'backstage.io/kubernetes-id': <BACKSTAGE_ENTITY_NAME>
+```
+
+### Label selector query annotation
+
+You can write your own custom label selector query that Backstage will use to
+lookup the objects (similar to `kubectl --selector="your query here"`). Review
+the
+[labels and selectors Kubernetes documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
+for more info.
+
+```yaml
+'backstage.io/kubernetes-label-selector': 'app=my-app,component=front-end'
+```

docs/features/kubernetes/index.md

@@ -0,0 +1,30 @@
+---
+id: overview
+title: Kubernetes
+sidebar_label: Overview
+description: Monitoring Kubernetes based services with the service catalog
+---
+
+Kubernetes in Backstage is a tool that's designed around the needs of service
+owners, not cluster admins. Now developers can easily check the health of their
+services no matter how or where those services are deployed — whether it's on a
+local host for testing or in production on dozens of clusters around the world.
+
+It will elevate the visibility of errors where identified, and provide drill
+down about the deployments, pods, and other objects for a service.
+
+![Kubernetes plugin screenshot](../../assets/features/kubernetes/backstage-k8s-2-deployments.png)
+
+The feature is made up of two plugins:
+[`@backstage/plugin-kubernetes`](https://github.com/backstage/backstage/tree/master/plugins/kubernetes)
+and
+[`@backstage/plugin-kubernetes-backend`](https://github.com/backstage/backstage/tree/master/plugins/kubernetes-backend).
+
+The frontend plugin exposes information to the end user in a digestible way,
+while the backend wraps the mechanics to connect to Kubernetes clusters to
+collect the relevant information.
+
+## Let's use it!
+
+To get started, first you must [install the Kubernetes plugins](installation.md)
+and then [configure them](configuration.md).

docs/features/kubernetes/installation.md

@@ -0,0 +1,119 @@
+---
+id: installation
+title: Installation
+description: Installing Kubernetes plugin into Backstage
+---
+
+The Kubernetes feature is a plugin to Backstage, and it is exposed as a tab when
+viewing entities in the software catalog.
+
+If you haven't setup Backstage already, start
+[here](../../getting-started/index.md).
+
+## Adding the Kubernetes frontend plugin
+
+The first step is to add the frontend Kubernetes plugin to your Backstage
+application. Navigate to your new Backstage application directory. And then to
+your `packages/app` directory, and install the `@backstage/plugin-kubernetes`
+package.
+
+```bash
+cd my-backstage-app/
+cd packages/app
+yarn add @backstage/plugin-kubernetes
+```
+
+Once the package has been installed, you need to import the plugin in your app.
+Add the following to `packages/app/src/plugins.ts`:
+
+`plugins.ts`:
+
+```typescript
+export { plugin as Kubernetes } from '@backstage/plugin-kubernetes';
+```
+
+Now, add the "Kubernetes" tab to the catalog entity page. In
+`packages/app/src/components/catalog/EntityPage.tsx`, you'll add a router to get
+to the tab, and add the tab itself.
+
+`EntityPage.tsx`:
+
+```tsx
+import { Router as KubernetesRouter } from '@backstage/plugin-kubernetes';
+
+// ...
+
+const ServiceEntityPage = ({ entity }: { entity: Entity }) => (
+  <EntityPageLayout>
+    // ...
+    <EntityPageLayout.Content
+      path="/kubernetes/*"
+      title="Kubernetes"
+      element={<KubernetesRouter entity={entity} />}
+    />
+    // ...
+  </EntityPageLayout>
+);
+```
+
+That's it! But now, we need the Kubernetes Backend plugin for the frontend to
+work.
+
+## Adding Kubernetes Backend plugin
+
+Navigate to `packages/backend` of your Backstage app, and install the
+`@backstage/plugin-kubernetes-backend` package.
+
+```bash
+cd my-backstage-app/
+cd packages/backend
+yarn add @backstage/plugin-kubernetes-backend
+```
+
+Create a file called `kubernetes.ts` inside `packages/backend/src/plugins/` and
+add the following
+
+`kubernetes.ts`:
+
+```typescript
+import { createRouter } from '@backstage/plugin-kubernetes-backend';
+import { PluginEnvironment } from '../types';
+
+export default async function createPlugin({
+  logger,
+  config,
+}: PluginEnvironment) {
+  return await createRouter({ logger, config });
+}
+```
+
+And import the plugin to `packages/backend/src/index.ts`. There are three lines
+of code you'll need to add, and they should be added near similar code in your
+existing Backstage backend.
+
+`index.ts`:
+
+```typescript
+import kubernetes from './plugins/kubernetes';
+
+// ...
+
+const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes'));
+
+// ...
+
+apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv));
+```
+
+That's it! The Kubernetes frontend and backend have now been added to your
+Backstage app.
+
+## Running Backstage locally
+
+Start the frontend and the backend app by
+[running backstage locally](../../getting-started/running-backstage-locally.md).
+
+## Configuration
+
+After installing the plugins in the code, you'll need to then
+[configure them](configuration.md).

docs/features/search/README.md

@@ -0,0 +1,100 @@
+---
+id: search-overview
+title: Search Documentation
+sidebar_label: Overview
+# prettier-ignore
+description: Backstage Search lets you find the right information you are looking for in the Backstage ecosystem.
+---
+
+# Backstage Search
+
+## What is it?
+
+Backstage Search lets you find the right information you are looking for in the
+Backstage ecosystem.
+
+## Features
+
+- A federated, faceted search, searching across all entities registered in your
+  Backstage instance.
+
+- A search that lets you plug in your own search engine of choice.
+
+- A standardized search API where you can choose to index other plugins data.
+
+## Project roadmap
+
+| Version                 | Description                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Backstage Search V.0 ✅ | Search Frontend letting you search through the entities of the software catalog. [See V.0 Use Cases.](#backstage-search-v0)                                         |
+| Backstage Search V.1 ⌛ | Basic “out-of-the-box” in-memory indexing process of entities, and their metadata, registered to the Software Catalog. [See V.1 Use Cases.](#backstage-search-v1)   |
+| Backstage Search V.2 ⌛ | Search Backend responsible for the indexing process of entities, and their metadata, registered to the Software Catalog. [See V.2 Use Cases.](#backstage-search-v2) |
+| Backstage Search V.3 ⌛ | Standardized Search API lets you index other plugins data to the search engine of choice. [See V.3 Use Cases.](#backstage-search-v3)                                |
+
+## Use Cases
+
+#### Backstage Search V.0
+
+- As a software engineer I should be able to navigate to a search page and
+  search for entities registered in the Software Catalog.
+- As a software engineer I should be able to use the search input field in the
+  sidebar to search for entities registered in the Software Catalog.
+- As a software engineer I should be able to see the number of results my search
+  returned.
+- As a software engineer I should be able to filter on metadata (kind,
+  lifecycle) when I’ve performed a search.
+- As a software engineer I should be able to hide the filters if I don’t need to
+  use them.
+
+#### Backstage Search V.1
+
+- As a software engineer I should be able to get a match of a search on all
+  entity metadata (e.g. owner, name, description, kind).
+- As an integrator I should not have to plug in any search engine, instead I can
+  use the out of the box in-memory indexing process to index entities and their
+  metadata registered in the Software Catalog.
+
+#### Backstage Search V.2
+
+- As an integrator I should be able to spin up an instance of ElasticSearch.
+- As an integrator I should be able to define a ElasticSearch cluster in my
+  app_config.yaml where my data gets indexed to.
+
+more to come...
+
+#### Backstage Search V.3
+
+- As a contributor I should be able to integrate plugin data to the indexing
+  process of Backstage Search by using the standardized API.
+- As a software engineer I should be able to search for all content (for
+  example, entities, metadata, documentation) in backstage search.
+
+more to come...
+
+## Search Engines Supported
+
+See [Backstage Search Architecture](architecture.md) to get an overview of how
+the search engines are used.
+
+| Search Engine | Support Status |
+| ------------- | -------------- |
+| ElasticSearch | Not yet ❌     |
+
+[Reach out to us](#feedback) if you want to chat about support for more search
+engines.
+
+## Tech Stack
+
+| Stack           | Location                 |
+| --------------- | ------------------------ |
+| Frontend Plugin | @backstage/plugin-search |
+| Backend Plugin  | ⌛                       |
+
+## Feedback
+
+For any questions of feedback, reach out to us in the `#search` channel of our
+[Discord chatroom](https://github.com/backstage/backstage#community).
+
+We are still looking for feedback to improve the architecture to fit your
+use-case, see
+[this open issue](https://github.com/backstage/backstage/issues/4078).

docs/features/search/architecture.md

@@ -0,0 +1,39 @@
+---
+id: architecture
+title: Search Architecture
+description: Documentation on Search Architecture
+---
+
+# Search Architecture
+
+> _This is a proposed architecture which has not been implemented yet. We are
+> still looking for feedback to improve the architecture to fit your use-case,
+> see [this open issue](https://github.com/backstage/backstage/issues/4078)._
+
+Below you can explore the Search Architecture. Our aim with this architecture is
+to support a wide variety of search engines, while providing a simple developer
+experience for plugin developers, and a good out-of-the-box experience for
+Backstage end-users.
+
+<img data-zoomable src="../../assets/search/architecture.drawio.svg" alt="Search Architecture" />
+
+At a base-level, we want to support the following:
+
+- We aim to enable the capability to search across the entire Backstage
+  ecosystem by decoupling search from content management.
+- We aim to enable the capability to deploy Backstage using any search engine,
+  by providing an integration and translation layer between the core search
+  plugin and search engine specific logic that can be extended for different
+  search engines. We may also introduce the ability to replace the backend API
+  endpoint with a custom endpoint for simpler customization.
+
+More advanced use-cases we hope to support with this architecture include:
+
+- It should be easy for any plugin to expose new content to search. (e.g. entity
+  metadata, documentation from TechDocs)
+- It should be easy for any plugin to append relevant metadata to existing
+  content in search. (e.g. location (path) for TechDocs page)
+- It should be easy to refine search queries (e.g. ranking, scoring, etc.)
+- It should be easy to customize the search UI
+- It should be easy to add search functionality to any Backstage plugin or
+  deployment

docs/features/software-catalog/configuration.md

@@ -60,7 +60,7 @@ data from. Each entry is a structure with up to four elements:
   and raw. If it is not supplied, anonymous access will be used.
 - `apiBaseUrl` (optional): If you want to communicate using the APIv3 method
   with this provider, specify the base URL for its endpoint here, with no
-  trailing slash. Specifically when the target is github, you can leave it out
+  trailing slash. Specifically when the target is GitHub, you can leave it out
   to be inferred automatically. For a GitHub Enterprise installation, it is
   commonly at `https://api.<host>` or `https://<host>/api/v3`.
 - `rawBaseUrl` (optional): If you want to communicate using the raw HTTP method

docs/features/software-catalog/descriptor-format.md

@@ -31,6 +31,7 @@ we recommend that you name them `catalog-info.yaml`.
 - [Kind: Resource](#kind-resource)
 - [Kind: System](#kind-system)
 - [Kind: Domain](#kind-domain)
+- [Kind: Location](#kind-location)
 
 ## Overall Shape Of An Entity
 
@@ -59,7 +60,7 @@ software catalog API.
   },
   "spec": {
     "lifecycle": "production",
-    "owner": "artist-relations@example.com",
+    "owner": "artist-relations-team",
     "type": "website"
   }
 }
@@ -83,7 +84,7 @@ metadata:
 spec:
   type: website
   lifecycle: production
-  owner: artist-relations@example.com
+  owner: artist-relations-team
 ```
 
 The root fields `apiVersion`, `kind`, `metadata`, and `spec` are part of the
@@ -130,6 +131,19 @@ spec:
     $text: https://petstore.swagger.io/v2/swagger.json
 ```
 
+Note that to be able to read from targets that are outside of the normal
+integration points such as `github.com`, you'll need to explicitly allow it by
+adding an entry in the `backend.reading.allow` list. For example:
+
+```yml
+backend:
+  baseUrl: ...
+  reading:
+    allow:
+      - host: example.com
+      - host: '*.examples.org'
+```
+
 ## Common to All Kinds: The Envelope
 
 The root envelope object has the following structure.
@@ -267,7 +281,7 @@ identical in use to
 
 Their purpose is mainly, but not limited, to reference into external systems.
 This could for example be a reference to the git ref the entity was ingested
-from, to monitoring and logging systems, to pagerduty schedules, etc. Users may
+from, to monitoring and logging systems, to PagerDuty schedules, etc. Users may
 add these to descriptor YAML files, but in addition to this automated systems
 may also add annotations, either during ingestion into the catalog, or at a
 later time.
@@ -380,7 +394,8 @@ metadata:
 spec:
   type: website
   lifecycle: production
-  owner: artist-relations@example.com
+  owner: artist-relations-team
+  system: artist-engagement-portal
   providesApis:
     - artist-api
 ```
@@ -406,7 +421,7 @@ The current set of well-known and common values for this field is:
 
 - `service` - a backend service, typically exposing an API
 - `website` - a website
-- `library` - a software library, such as an NPM module or a Java library
+- `library` - a software library, such as an npm module or a Java library
 
 ### `spec.lifecycle` [required]
 
@@ -426,8 +441,8 @@ The current set of well-known and common values for this field is:
 
 ### `spec.owner` [required]
 
-The owner of the component, e.g. `artist-relations@example.com`. This field is
-required.
+An [entity reference](#string-references) to the owner of the component, e.g.
+`artist-relations-team`. This field is required.
 
 In Backstage, the owner of a component is the singular entity (commonly a team)
 that bears ultimate responsibility for the component, and has the authority and
@@ -439,40 +454,45 @@ not to be used by automated processes to for example assign authorization in
 runtime systems. There may be others that also develop or otherwise touch the
 component, but there will always be one ultimate owner.
 
-Apart from being a string, the software catalog leaves the format of this field
-open to implementers to choose. Most commonly, it is set to the ID or email of a
-group of people in an organizational structure.
+| [`kind`](#apiversion-and-kind-required)                | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                              |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default`   | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
 
-### `spec.implementsApis` [optional]
+### `spec.system` [optional]
 
-**NOTE**: This field was marked for deprecation on Nov 25nd, 2020. It will be
-removed entirely from the model on Dec 14th, 2020 in the repository and will not
-be present in released packages following the next release after that. Please
-update your code to not consume this field before the removal date.
+An [entity reference](#string-references) to the system that the component
+belongs to, e.g. `artist-engagement-portal`. This field is optional.
 
-Links APIs that are implemented by the component, e.g. `artist-api`. This field
-is optional.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                            |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`System`](#kind-system) (default)      | Same as this entity, typically `default`   | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
 
-The software catalog expects a list of one or more strings that references the
-names of other entities of the `kind` `API`.
+### `spec.subcomponentOf` [optional]
 
-This field has the same behavior as `spec.providesApis`.
+An [entity reference](#string-references) to another component of which the
+component is a part, e.g. `spotify-ios-app`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required)  | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                            |
+| ---------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`Component`](#kind-component) (default) | Same as this entity, typically `default`   | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
 
 ### `spec.providesApis` [optional]
 
-Links APIs that are provided by the component, e.g. `artist-api`. This field is
-optional.
+An array of [entity references](#string-references) to the APIs that are
+provided by the component, e.g. `artist-api`. This field is optional.
 
-The software catalog expects a list of one or more strings that references the
-names of other entities of the `kind` `API`.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                                                  |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| [`API`](#kind-api) (default)            | Same as this entity, typically `default`   | [`providesApi`, and reverse `apiProvidedBy`](well-known-relations.md#providesapi-and-apiprovidedby) |
 
 ### `spec.consumesApis` [optional]
 
-Links APIs that are consumed by the component, e.g. `artist-api`. This field is
-optional.
+An array of [entity references](#string-references) to the APIs that are
+consumed by the component, e.g. `artist-api`. This field is optional.
 
-The software catalog expects a list of one or more strings that references the
-names of other entities of the `kind` `API`.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                                                  |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| [`API`](#kind-api) (default)            | Same as this entity, typically `default`   | [`consumesApi`, and reverse `apiConsumedBy`](well-known-relations.md#consumesapi-and-apiconsumedby) |
 
 ## Kind: Template
 
@@ -557,7 +577,7 @@ The current set of well-known and common values for this field is:
 
 - `service` - a backend service, typically exposing an API
 - `website` - a website
-- `library` - a software library, such as an NPM module or a Java library
+- `library` - a software library, such as an npm module or a Java library
 
 ### `spec.templater` [required]
 
@@ -611,7 +631,8 @@ metadata:
 spec:
   type: openapi
   lifecycle: production
-  owner: artist-relations@example.com
+  owner: artist-relations-team
+  system: artist-engagement-portal
   definition: |
     openapi: "3.0.0"
     info:
@@ -677,8 +698,8 @@ The current set of well-known and common values for this field is:
 
 ### `spec.owner` [required]
 
-The owner of the API, e.g. `artist-relations@example.com`. This field is
-required.
+An [entity reference](#string-references) to the owner of the component, e.g.
+`artist-relations-team`. This field is required.
 
 In Backstage, the owner of an API is the singular entity (commonly a team) that
 bears ultimate responsibility for the API, and has the authority and capability
@@ -690,9 +711,18 @@ processes to for example assign authorization in runtime systems. There may be
 others that also develop or otherwise touch the API, but there will always be
 one ultimate owner.
 
-Apart from being a string, the software catalog leaves the format of this field
-open to implementers to choose. Most commonly, it is set to the ID or email of a
-group of people in an organizational structure.
+| [`kind`](#apiversion-and-kind-required)                | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                              |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default`   | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
+
+### `spec.system` [optional]
+
+An [entity reference](#string-references) to the system that the API belongs to,
+e.g. `artist-engagement-portal`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                            |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`System`](#kind-system) (default)      | Same as this entity, typically `default`   | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
 
 ### `spec.definition` [required]
 
@@ -722,10 +752,12 @@ metadata:
   description: The infra business unit
 spec:
   type: business-unit
+  profile:
+    displayName: Infrastructure
+    email: infrastructure@example.com
+    picture: https://example.com/groups/bu-infrastructure.jpeg
   parent: ops
-  ancestors: [ops, global-synergies, acme-corp]
   children: [backstage, other]
-  descendants: [backstage, other, team-a, team-b, team-c, team-d]
 ```
 
 In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
@@ -748,6 +780,14 @@ Some common values for this field could be:
 - `product-area`
 - `root` - as a common virtual root of the hierarchy, if desired
 
+### `spec.profile` [optional]
+
+Optional profile information about the group, mainly for display purposes. All
+fields of this structure are also optional. The email would be a group email of
+some form, that the group may wish to be used for contacting them. The picture
+is expected to be a URL pointing to an image that's representative of the group,
+and that a browser could fetch and render on a group page or similar.
+
 ### `spec.parent` [optional]
 
 The immediate parent group in the hierarchy, if any. Not all groups must have a
@@ -755,30 +795,11 @@ parent; the catalog supports multi-root hierarchies. Groups may however not have
 more than one parent.
 
 This field is an
-[entity reference](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-this field points to a group in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of that group.
+[entity reference](https://backstage.io/docs/features/software-catalog/references).
 
-### `spec.ancestors` [required]
-
-**NOTE**: This field was marked for deprecation on Nov 22nd, 2020. It will be
-removed entirely from the model on Dec 6th, 2020 in the repository and will not
-be present in released packages following the next release after that. Please
-update your code to not consume this field before the removal date.
-
-The recursive list of parents up the hierarchy, by stepping through parents one
-by one. The list must be present, but may be empty if `parent` is not present.
-The first entry in the list is equal to `parent`, and then the following ones
-are progressively farther up the hierarchy.
-
-The entries of this array are
-[entity references](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-these entries point to groups in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of those groups.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                                |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default)        | Same as this entity, typically `default`   | [`childOf`, and reverse `parentOf`](well-known-relations.md#parentof-and-childof) |
 
 ### `spec.children` [required]
 
@@ -788,30 +809,11 @@ no child groups. The items are not guaranteed to be ordered in any particular
 way.
 
 The entries of this array are
-[entity references](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-these entries point to groups in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of those groups.
+[entity references](https://backstage.io/docs/features/software-catalog/references).
 
-### `spec.descendants` [required]
-
-**NOTE**: This field was marked for deprecation on Nov 22nd, 2020. It will be
-removed entirely from the model on Dec 6th, 2020 in the repository and will not
-be present in released packages following the next release after that. Please
-update your code to not consume this field before the removal date.
-
-The immediate and recursive child groups of this group in the hierarchy
-(children, and children's children, etc.). The list must be present, but may be
-empty if there are no child groups. The items are not guaranteed to be ordered
-in any particular way.
-
-The entries of this array are
-[entity references](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-these entries point to groups in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of those groups.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                                    |
+| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default)        | Same as this entity, typically `default`   | [`hasMember`, and reverse `memberOf`](well-known-relations.md#memberof-and-hasmember) |
 
 ## Kind: User
 
@@ -867,20 +869,252 @@ user is not member of any groups. The items are not guaranteed to be ordered in
 any particular way.
 
 The entries of this array are
-[entity references](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-these entries point to groups in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of those groups.
+[entity references](https://backstage.io/docs/features/software-catalog/references).
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                                    |
+| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default)        | Same as this entity, typically `default`   | [`memberOf`, and reverse `hasMember`](well-known-relations.md#memberof-and-hasmember) |
 
 ## Kind: Resource
 
-This kind is not yet defined, but is reserved [for future use](system-model.md).
+Describes the following entity kind:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `Resource`              |
+
+A resource describes the infrastructure a system needs to operate, like BigTable
+databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with
+components and systems allows to visualize resource footprint, and create
+tooling around them.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Resource
+metadata:
+  name: artists-db
+  description: Stores artist details
+spec:
+  type: database
+  owner: artist-relations-team
+  system: artist-engagement-portal
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `Resource`, respectively.
+
+### `spec.owner` [required]
+
+An [entity reference](#string-references) to the owner of the resource, e.g.
+`artist-relations-team`. This field is required.
+
+In Backstage, the owner of a resource is the singular entity (commonly a team)
+that bears ultimate responsibility for the resource, and has the authority and
+capability to develop and maintain it. They will be the point of contact if
+something goes wrong, or if features are to be requested. The main purpose of
+this field is for display purposes in Backstage, so that people looking at
+catalog items can get an understanding of to whom this resource belongs. It is
+not to be used by automated processes to for example assign authorization in
+runtime systems. There may be others that also manage or otherwise touch the
+resource, but there will always be one ultimate owner.
+
+| [`kind`](#apiversion-and-kind-required)                | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                              |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default`   | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
+
+### `spec.type` [required]
+
+The type of resource as a string, e.g. `database`. This field is required. There
+is currently no enforced set of values for this field, so it is left up to the
+adopting organization to choose a nomenclature that matches the resources used
+in their tech stack.
+
+Some common values for this field could be:
+
+- `database`
+- `s3-bucket`
+- `cluster`
+
+### `spec.system` [optional]
+
+An [entity reference](#string-references) to the system that the resource
+belongs to, e.g. `artist-engagement-portal`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                            |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`System`](#kind-system) (default)      | Same as this entity, typically `default`   | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
 
 ## Kind: System
 
-This kind is not yet defined, but is reserved [for future use](system-model.md).
+Describes the following entity kind:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `System`                |
+
+A system is a collection of resources and components. The system may expose or
+consume one or several APIs. It is viewed as abstraction level that provides
+potential consumers insights into exposed features without needing a too
+detailed view into the details of all components. This also gives the owning
+team the possibility to decide about published artifacts and APIs.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+  name: artist-engagement-portal
+  description: Handy tools to keep artists in the loop
+spec:
+  owner: artist-relations-team
+  domain: artists
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `System`, respectively.
+
+### `spec.owner` [required]
+
+An [entity reference](#string-references) to the owner of the system, e.g.
+`artist-relations-team`. This field is required.
+
+In Backstage, the owner of a system is the singular entity (commonly a team)
+that bears ultimate responsibility for the system, and has the authority and
+capability to develop and maintain it. They will be the point of contact if
+something goes wrong, or if features are to be requested. The main purpose of
+this field is for display purposes in Backstage, so that people looking at
+catalog items can get an understanding of to whom this system belongs. It is not
+to be used by automated processes to for example assign authorization in runtime
+systems. There may be others that also develop or otherwise touch the system,
+but there will always be one ultimate owner.
+
+| [`kind`](#apiversion-and-kind-required)                | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                              |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default`   | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
+
+### `spec.domain` [optional]
+
+An [entity reference](#string-references) to the domain that the system belongs
+to, e.g. `artists`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                            |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`Domain`](#kind-domain) (default)      | Same as this entity, typically `default`   | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
 
 ## Kind: Domain
 
-This kind is not yet defined, but is reserved [for future use](system-model.md).
+Describes the following entity kind:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `Domain`                |
+
+A Domain groups a collection of systems that share terminology, domain models,
+business purpose, or documentation, i.e. form a bounded context.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Domain
+metadata:
+  name: artists
+  description: Everything about artists
+spec:
+  owner: artist-relations-team
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `Domain`, respectively.
+
+### `spec.owner` [required]
+
+An [entity reference](#string-references) to the owner of the domain, e.g.
+`artist-relations-team`. This field is required.
+
+In Backstage, the owner of a domain is the singular entity (commonly a team)
+that bears ultimate responsibility for the domain, and has the authority and
+capability to develop and maintain it. They will be the point of contact if
+something goes wrong, or if features are to be requested. The main purpose of
+this field is for display purposes in Backstage, so that people looking at
+catalog items can get an understanding of to whom this domain belongs. It is not
+to be used by automated processes to for example assign authorization in runtime
+systems. There may be others that also develop or otherwise touch the domain,
+but there will always be one ultimate owner.
+
+| [`kind`](#apiversion-and-kind-required)                | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                              |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default`   | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
+
+## Kind: Location
+
+Describes the following entity kind:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `Location`              |
+
+A location is a marker that references other places to look for catalog data.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Location
+metadata:
+  name: org-data
+spec:
+  type: url
+  targets:
+    - http://github.com/myorg/myproject/org-data-dump/catalog-info-staff.yaml
+    - http://github.com/myorg/myproject/org-data-dump/catalog-info-consultants.yaml
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `Location`, respectively.
+
+### `spec.type` [optional]
+
+The single location type, that's common to the targets specified in the spec. If
+it is left out, it is inherited from the location type that originally read the
+entity data. For example, if you have a `url` type location, that when read
+results in a `Location` kind entity with no `spec.type`, then the referenced
+targets in the entity will implicitly also be of `url` type. This is useful
+because you can define a hierarchy of things in a directory structure using
+relative target paths (see below), and it will work out no matter if it's
+consumed locally on disk from a `file` location, or as uploaded on a VCS.
+
+### `spec.target` [optional]
+
+A single target as a string. Can be either an absolute path/URL (depending on
+the type), or a relative path such as `./details/catalog-info.yaml` which is
+resolved relative to the location of this Location entity itself.
+
+### `spec.targets` [optional]
+
+A list of targets as strings. They can all be either absolute paths/URLs
+(depending on the type), or relative paths such as `./details/catalog-info.yaml`
+which are resolved relative to the location of this Location entity itself.

docs/features/software-catalog/external-integrations.md

@@ -94,7 +94,7 @@ The recommended way of instantiating the catalog backend classes is to use the
 as illustrated in the
 [example backend here](https://github.com/backstage/backstage/blob/master/packages/backend/src/plugins/catalog.ts).
 We will create a new
-[`CatalogProcessor`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/ingestion/types.ts)
+[`CatalogProcessor`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/ingestion/processors/types.ts)
 subclass that can be added to this catalog builder.
 
 It is up to you where you put the code for this new processor class. For quick

docs/features/software-catalog/system-model.md

@@ -23,7 +23,7 @@ We model software in the Backstage catalogue using these three core entities
 - **Resources** are physical or virtual infrastructure needed to operate a
   component
 
-![](../../assets/software-catalog/software-model-core-entities.png)
+![](../../assets/software-catalog/software-model-core-entities.drawio.svg)
 
 ### Component
 
@@ -44,8 +44,8 @@ Backstage model and the primary way to discover existing functionality in the
 ecosystem.
 
 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
+might be defined using an RPC IDL (e.g., Protobuf, GraphQL, ...), a data schema
+(e.g., 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.
 
@@ -73,6 +73,8 @@ these entities using the following (optional) concepts:
   function
 - **Domains** relate entities and systems to part of the business
 
+![](../../assets/software-catalog/software-model-entities.drawio.svg)
+
 ### System
 
 With increasing complexity in software, systems form an important abstraction
@@ -107,10 +109,6 @@ 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
-
-Backstage currently supports Components and APIs.
-
 ## Links
 
 - [Original RFC](https://github.com/backstage/backstage/issues/390)

docs/features/software-catalog/well-known-annotations.md

@@ -22,7 +22,7 @@ use.
 # Example:
 metadata:
   annotations:
-    backstage.io/managed-by-location: github:http://github.com/backstage/backstage/catalog-info.yaml
+    backstage.io/managed-by-location: url:http://github.com/backstage/backstage/blob/master/catalog-info.yaml
 ```
 
 The value of this annotation is a so called location reference string, that
@@ -30,8 +30,8 @@ points to the source from which the entity was originally fetched. This
 annotation is added automatically by the catalog as it fetches the data from a
 registered location, and is not meant to normally be written by humans. The
 annotation may point to any type of generic location that the catalog supports,
-so it cannot be relied on to always be specifically of type `github`, nor that
-it even represents a single file. Note also that a single location can be the
+so it cannot be relied on to always be specifically of type `url`, nor that it
+even represents a single file. Note also that a single location can be the
 source of many entities, so it represents a many-to-one relationship.
 
 The format of the value is `<type>:<target>`. Note that the target may also
@@ -40,13 +40,30 @@ expecting a two-item array out of it. The format of the target part is
 type-dependent and could conceivably even be an empty string, but the separator
 colon is always present.
 
+### backstage.io/managed-by-origin-location
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    backstage.io/managed-by-origin-location: url:http://github.com/backstage/backstage/blob/master/catalog-info.yaml
+```
+
+The value of this annotation is a location reference string (see above). It
+points to the location, whose registration lead to the creation of the entity.
+In most cases, the `backstage.io/managed-by-location` and
+`backstage.io/managed-by-origin-location` will be equal. They will be different
+if the original location delegates to another location. A common case is, that a
+location is registered as `bootstrap:bootstrap` which means that it is part of
+the `app-config.yaml` of a Backstage installation.
+
 ### backstage.io/techdocs-ref
 
 ```yaml
 # Example:
 metadata:
   annotations:
-    backstage.io/techdocs-ref: github:https://github.com/backstage/backstage.git
+    backstage.io/techdocs-ref: url:https://github.com/backstage/backstage/tree/master
 ```
 
 The value of this annotation is a location reference string (see above). If this

docs/features/software-catalog/well-known-relations.md

@@ -48,11 +48,10 @@ where present.
 ### `providesApi` and `apiProvidedBy`
 
 A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
-[Component](descriptor-format.md#kind-component) or
-[System](descriptor-format.md#kind-system).
+[Component](descriptor-format.md#kind-component).
 
-These relations express that a component or system exposes an API - meaning that
-it hosts callable endpoints from which you can consume that API.
+These relations express that a component exposes an API - meaning that it hosts
+callable endpoints from which you can consume that API.
 
 This relation is commonly generated based on `spec.providesApis` of the
 component or system in question.
@@ -60,11 +59,10 @@ component or system in question.
 ### `consumesApi` and `apiConsumedBy`
 
 A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
-[Component](descriptor-format.md#kind-component) or
-[System](descriptor-format.md#kind-system).
+[Component](descriptor-format.md#kind-component).
 
-These relations express that a component or system consumes an API - meaning
-that it depends on endpoints of the API.
+These relations express that a component consumes an API - meaning that it
+depends on endpoints of the API.
 
 This relation is commonly generated based on `spec.consumesApis` of the
 component or system in question.
@@ -91,3 +89,18 @@ A membership relation, typically for [Users](descriptor-format.md#kind-user) in
 [Groups](descriptor-format.md#kind-group).
 
 This relation is commonly based on `spec.memberOf`.
+
+### `partOf` and `hasPart`
+
+A relation with a [Domain](descriptor-format.md#kind-domain),
+[System](descriptor-format.md#kind-system) or
+[Component](descriptor-format.md#kind-component) entity, typically from a
+[Component](descriptor-format.md#kind-component),
+[API](descriptor-format.md#kind-api), or
+[System](descriptor-format.md#kind-system).
+
+These relations express that a component belongs to a larger component; a
+component, API or resource belongs to a system; or that a system is grouped
+under a domain.
+
+This relation is commonly based on `spec.system` or `spec.domain`.

docs/features/software-templates/extending/create-your-own-publisher.md

@@ -57,7 +57,7 @@ That type looks like the following:
 export type PublisherBase = {
   publish(opts: {
     entity: TemplateEntityV1alpha1;
-    values: RequiredTemplateValues & Record<string, JsonValue>;
+    values: TemplaterValues;
     directory: string;
   }): Promise<{ remoteUrl: string }>;
 };

docs/features/software-templates/extending/create-your-own-templater.md

@@ -61,7 +61,7 @@ That type looks like the following:
 ```ts
 export type TemplaterRunOptions = {
   directory: string;
-  values: RequiredTemplateValues & Record<string, JsonValue>;
+  values: TemplaterValues;
   logStream?: Writable;
   dockerClient: Docker;
 };
@@ -86,10 +86,11 @@ follows:
 
 _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
-downloads the folder and does everything using an AMI if you want. It's entirely
-up to you!
+to a minimum for running backstage scaffolder, but you don't _have_ to use
+Docker. You can `pip install cookiecutter` to run it locally in your backend.
+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!
 
 Now it's up to you to implement the `run` function, and then return a
 `TemplaterRunResult` which is `{ resultDir: string }`.

docs/features/software-templates/index.md

@@ -2,8 +2,8 @@
 id: software-templates-index
 title: Backstage Software Templates
 sidebar_label: Overview
-description: The Software Templates part of Backstage is a tool that can help
-you create Components inside Backstage
+# prettier-ignore
+description: The Software Templates part of Backstage is a tool that can help you create Components inside Backstage
 ---
 
 The Software Templates part of Backstage is a tool that can help you create