fix: conflicts

2020-10-27 09:47:26 +05:30
parent c5acbbb8c4 d89401df3c
commit 83c2f107f9
632 changed files with 9896 additions and 5491 deletions
@@ -0,0 +1,15 @@
+---
+'@backstage/core': minor
+'@backstage/core-api': minor
+---
+
+Updated the `GithubAuth.create` method to configure the default scope of the Github Auth Api. As a result the
+default scope is configurable when overwriting the Core Api in the app.
+
+```
+GithubAuth.create({
+  discoveryApi,
+  oauthRequestApi,
+  defaultScopes: ['read:user', 'repo'],
+}),
+```
@@ -0,0 +1,20 @@
+---
+'example-app': minor
+'@backstage/core': minor
+'@backstage/create-app': minor
+'@backstage/plugin-catalog': minor
+'@backstage/plugin-github-actions': minor
+'@backstage/plugin-jenkins': minor
+'@backstage/plugin-lighthouse': minor
+---
+
+The InfoCard variant `'height100'` is deprecated. Use variant `'gridItem'` instead.
+
+When the InfoCard is displayed as a grid item within a grid, you may want items to have the same height for all items.
+Set to the `'gridItem'` variant to display the InfoCard with full height suitable for Grid:
+`<InfoCard variant="gridItem">...</InfoCard>`
+
+Changed the InfoCards in '@backstage/plugin-github-actions', '@backstage/plugin-jenkins', '@backstage/plugin-lighthouse'
+to pass an optional variant to the corresponding card of the plugin.
+
+As a result the overview content of the EntityPage shows cards with full height suitable for Grid.
@@ -0,0 +1,12 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+The way that wiring together a catalog happens, has changed drastically. Now
+there is a new class `CatalogBuilder` that does almost all of the heavy lifting
+of how to augment/replace pieces of catalog functionality, such as adding
+support for custom entities or adding additional processors.
+
+As the builder was added, a lot of the static methods and builders for default
+setups have been removed from classes deep in the hierarchy. Instead, the
+builder contains the knowledge of what the defaults are.
@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': minor
+---
+
+Add the ability to import components from Bitbucket Server to the service catalog
@@ -0,0 +1,12 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+Filters passed to the `/entities` endpoint of the catalog has changed format.
+
+The old way was to pass things on the form `?a=b&c=d`; the new way is to pass
+things on the form `?filter=a=b,c=d`. See discussion in
+[#2910](https://github.com/spotify/backstage/issues/2910) for details.
+
+The comma separated items within a single filter have an AND between them. If
+multiple such filters are passed, they have an OR between those item groups.
@@ -0,0 +1,5 @@
+---
+'example-app': patch
+---
+
+Add Pull Request tab to components view.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog': minor
+---
+
+Add client side paging for catalog table
@@ -0,0 +1,13 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+- The `CatalogProcessor` API was updated to have `preProcessEntity` and
+  `postProcessEntity` methods, instead of just one `processEntity`. This makes
+  it easier to make processors that have several stages in one, and to make
+  different processors more position independent in the list of processors.
+- The `EntityPolicy` is now given directly to the `LocationReaders`, instead of
+  being enforced inside a policy. We have decided to separate out the act of
+  validating an entity to be outside of the processing flow, to make it
+  possible to apply more liberally and to evolve it as a separate concept.
+- Because of the above, the `EntityPolicyProcessor` has been removed.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-cost-insights': patch
+---
+
+export test utilities for mocking context
@@ -0,0 +1,12 @@
+---
+'@backstage/cli': minor
+---
+
+Adds a new `BACKSTAGE_CLI_BUILD_PARELLEL` environment variable to control
+parallelism for some build steps.
+
+This is useful in CI to help avoid out of memory issues when using `terser`. The
+`BACKSTAGE_CLI_BUILD_PARELLEL` environment variable can be set to
+`true | false | [integer]` to override the default behaviour. See
+[terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin#parallel)
+for more details.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-cost-insights': minor
+---
+
+Added getLastCompleteBillingDate to the CostInsightsApi to reason about completeness of billing data
@@ -0,0 +1,21 @@
+---
+'@backstage/backend-common': minor
+'@backstage/cli': minor
+'@backstage/config-loader': minor
+'example-backend': patch
+'@backstage/create-app': patch
+---
+
+**BREAKING CHANGE**
+
+The existing loading of additional config files like `app-config.development.yaml` using APP_ENV or NODE_ENV has been removed.
+Instead, the CLI and backend process now accept one or more `--config` flags to load config files.
+
+Without passing any flags, `app-config.yaml` and, if it exists, `app-config.local.yaml` will be loaded.
+If passing any `--config <path>` flags, only those files will be loaded, **NOT** the default `app-config.yaml` one.
+
+The old behaviour of for example `APP_ENV=development` can be replicated using the following flags:
+
+```bash
+--config ../../app-config.yaml --config ../../app-config.development.yaml
+```
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+handle the case where no entities are available to show
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+Add forwardRef to the SidebarItem
@@ -0,0 +1,8 @@
+---
+'@backstage/core': patch
+'@backstage/plugin-graphiql': patch
+'@backstage/plugin-tech-radar': patch
+'@backstage/plugin-techdocs': patch
+---
+
+add test case for Progress component
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder': patch
+---
+
+fix the accordion details design when job stage fail
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+fix the warning of all the core components test cases
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Fix CodeOwnersProcessor to handle non team users
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Allow templates to be located on non-default branch
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+Update ItemCard headers to pass color contrast standards.
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+rename stories folder top Chip
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+Remove "in default" in component name
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+update the test cases of CodeSnippet component
@@ -0,0 +1,25 @@
+---
+'@backstage/plugin-newrelic': minor
+---
+
+The New Relic plugin now uses the Backstage proxy to communicate with New Relic's API.
+
+Please update your `app-config.yaml` as follows:
+
+```yaml
+# Old Config
+newrelic:
+  api:
+    baseUrl: 'https://api.newrelic.com/v2'
+    key: NEW_RELIC_REST_API_KEY
+```
+
+```yaml
+# New Config
+proxy:
+  '/newrelic/apm/api':
+    target: https://api.newrelic.com/v2
+    headers:
+      X-Api-Key:
+        $env: NEW_RELIC_REST_API_KEY
+```
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+add test cases for Status components
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs-backend': patch
+---
+
+Replacing the hard coded `baseApiUrl` by reading the value from configuration to enable private GitHub setup for TechDocs.
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+update ItemCard component and it's story
@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-model': minor
+---
+
+Enable adding locations for config files that does not yet exist by adding a flag to api request
@@ -0,0 +1,10 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+Renamed the `LocationProcessor` class to `CatalogProcessor`.
+
+Likewise, renamed `LocationProcessorResult`, `LocationProcessorLocationResult`,
+`LocationProcessorDataResult`, `LocationProcessorEntityResult`,
+`LocationProcessorErrorResult`, and `LocationProcessorEmit` to their `Catalog*`
+counterparts.
@@ -0,0 +1,10 @@
+---
+'@backstage/plugin-cost-insights': minor
+---
+
+- getProjectDailyCost and getGroupDailyCost no longer accept a metric as a parameter
+- getDailyMetricData added to API for fetching daily metric data for given interval
+- dailyCost removed as configurable metric
+- default field added to metric configuration for displaying comparison metric data in top panel
+- Metric.kind can no longer be null
+- MetricData type added
@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-scaffolder': patch
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+The new `scaffolder.github.baseUrl` config property allows to specify a custom base url for GitHub enterprise instances
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-cost-insights': minor
+---
+
+Remove product filters from query parameters
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-tech-radar': patch
+---
+
+fix the horizontal scrolling issue in the RadarPage component
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+make ErrorPage responsive + fix the test case
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Better presentation of authentication errors
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+give aria-label attribute to Status Ok, Warning and Error
@@ -0,0 +1,5 @@
+---
+'@backstage/core': patch
+---
+
+fix the responsive of page story
@@ -0,0 +1,8 @@
+---
+'@backstage/backend-common': minor
+'example-backend': patch
+'@backstage/cli': patch
+'@backstage/create-app': patch
+---
+
+Change loadBackendConfig to return the config directly
@@ -14,3 +14,4 @@
 /packages/techdocs-container                @spotify/techdocs-core
 /.github/workflows/techdocs.yml             @spotify/techdocs-core
 /.github/workflows/techdocs-pypi.yml        @spotify/techdocs-core
+/.changeset/cost-insights-*                 @spotify/silver-lining
@@ -68,6 +68,7 @@ graphviz
 Hackathons
 haproxy
 heroku
+Heroku
 horizontalpodautoscalers
 Hostname
 http
@@ -105,6 +106,7 @@ Monorepo
 monorepos
 msw
 namespace
+namespaces
 Namespaces
 neuro
 newrelic
@@ -196,6 +198,7 @@ validators
 Voi
 Wealthsimple
 Weaveworks
+Webpack
 xyz
 yaml
 Zalando
@@ -1,5 +1,11 @@
-.idea/
+# macOS
 .DS_Store
+
+# IntelliJ
+.idea/
+*.iml
+
+# Visual Studio Code
 .vscode/
 .vsls.json

@@ -6,3 +6,4 @@ coverage
 templates
 plugins/scaffolder-backend/sample-templates
 .vscode
+dist-types
@@ -6,6 +6,16 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re

 ## Next Release

+### @backstage/cli
+
+- Configuration files are no longer selected through `APP_ENV` or `NODE_ENV`. The default configuration files are `app-config.yaml` and, fix it exists, `app-config.local.yaml` in the repo root. To load a different set of files, use `--config <path>` arguments.
+
+### @backstage/backend-common
+
+- Configuration files are no longer selected through `APP_ENV` or `NODE_ENV`. The default configuration files are `app-config.yaml` and, fix it exists, `app-config.local.yaml` in the repo root. To load a different set of files, use `--config <path>` arguments.
+
+## v0.1.1-alpha.25
+
 > Collect changes for the next release below

 ### @backstage/cli
@@ -87,7 +87,7 @@ We use [changesets](https://github.com/atlassian/changesets) to help us prepare
 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)
-4. Add generated changset to Git
+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

@@ -1,27 +0,0 @@
-# Deploying Backstage
-
-## Heroku
-
-Deploying to heroku is relatively easy following these steps.
-
-First, make sure you have the [heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log into it as well as login into Heroku's [container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime).
-
-```bash
-$ heroku login
-$ heroku container:login
-```
-
-You _might_ also need to set your Heroku app's stack to `container`
-
-```bash
-$ heroku stack:set container -a <your-app>
-```
-
-We can now build/push the Docker image to Heroku's container registry and release it to the `web` worker.
-
-```bash
-$ heroku container:push web -a <your-app>
-$ heroku container:release web -a <your-app>
-```
-
-With that, you should have Backstage up and running!
@@ -1,13 +0,0 @@
-app:
-  baseUrl: http://localhost:3000
-
-backend:
-  baseUrl: http://localhost:7000
-  listen:
-    port: 7000
-  cors:
-    origin: http://localhost:3000
-    methods: [GET, POST, PUT, DELETE]
-    credentials: true
-  csp:
-    connect-src: ["'self'", 'http:', 'https:']
@@ -1,6 +1,7 @@
 app:
  title: Backstage Example App
-  baseUrl: http://localhost:7000
+  baseUrl: http://localhost:3000
+  googleAnalyticsTrackingId: # UA-000000-0

 backend:
  baseUrl: http://localhost:7000
@@ -9,8 +10,12 @@ backend:
  database:
    client: sqlite3
    connection: ':memory:'
+  cors:
+    origin: http://localhost:3000
+    methods: [GET, POST, PUT, DELETE]
+    credentials: true
  csp:
-    connect-src: ["'self'", 'https:']
+    connect-src: ["'self'", 'http:', 'https:']

 # See README.md in the proxy-backend plugin for information on the configuration format
 proxy:
@@ -34,8 +39,14 @@ proxy:
        $env: TRAVISCI_AUTH_TOKEN
      travis-api-version: 3

+  '/newrelic/apm/api':
+    target: https://api.newrelic.com/v2
+    headers:
+      X-Api-Key:
+        $env: NEW_RELIC_REST_API_KEY
+
 organization:
-  name: Spotify
+  name: My Company

 techdocs:
  storageUrl: http://localhost:7000/api/techdocs/static/docs
@@ -44,23 +55,20 @@ techdocs:
    techdocs: 'docker'

 sentry:
-  organization: spotify
+  organization: my-company

 rollbar:
-  organization: spotify
+  organization: my-company
  accountToken:
    $env: ROLLBAR_ACCOUNT_TOKEN

-newrelic:
-  api:
-    baseUrl: 'https://api.newrelic.com/v2'
-    key: NEW_RELIC_REST_API_KEY
-
 lighthouse:
  baseUrl: http://localhost:3003

 kubernetes:
-  clusterLocatorMethod: 'configMultiTenant'
+  serviceLocatorMethod: 'multiTenant'
+  clusterLocatorMethods:
+    - 'config'
  clusters: []

 integrations:
@@ -142,9 +150,13 @@ catalog:
    # Backstage example templates
    - type: url
      target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml
+    # Backstage example groups and users
+    - type: url
+      target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/acme-corp.yaml

 scaffolder:
  github:
+    host: https://github.com
    token:
      $env: GITHUB_TOKEN
    visibility: public # or 'internal' or 'private'
@@ -236,10 +248,11 @@ costInsights:
      name: Big Query
      icon: search
  metrics:
-    dailyCost:
-      name: Your Company's Daily Cost
    DAU:
-      name: Cost Per DAU
+      name: Daily Active Users
+      default: true
+    MSC:
+      name: Monthly Subscribers
 homepage:
  clocks:
    - label: UTC
@@ -7,6 +7,7 @@ metadata:
  annotations:
    github.com/project-slug: spotify/backstage
    backstage.io/techdocs-ref: github:https://github.com/spotify/backstage.git
+    lighthouse.com/website-url: https://backstage.io
 spec:
  type: library
  owner: Spotify
@@ -5,7 +5,7 @@ type: application

 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
-version: 0.1.0
+version: 0.1.1

 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application.
@@ -62,13 +62,30 @@ backstage-ingress   *       123.1.2.3       80      17m

 > **NOTE**: this is not a production ready deployment.

-## Caveats
-
-The current implementation does not generate certificates for the ingress which means the browser will alert that the
-site is insecure and using self-signed certificates.
-
 ## Customization

+### Issue certificates
+
+These charts can install or reuse a `clusterIssuer` to generate certificates for the backstage `ingress`. To do that:
+
+1. [Install][install-cert-manager] or make sure [cert-manager][cert-manager] is installed in the cluster.
+2. Enable the issuer in the charts. This will first check if there is a `letsencrypt` issuer already deployed in your
+   cluster and deploy one if it doesn't exist.
+
+To enable it you need to provide a valid email address in the chart's values:
+
+```
+issuer:
+  email: me@example.com
+  clusterIssuer: "letsencrypt-prod"
+```
+
+By default, the charts use `letsencrypt-staging` so in the above example we instruct helm to use the production issuer
+instead.
+
+[cert-manager]: https://cert-manager.io/docs/
+[install-cert-manager]: https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm
+
 ### Custom PostgreSQL instance

 Configuring a connection to an existing PostgreSQL instance is possible through the chart's values.
@@ -18,4 +18,6 @@ stringData:
  GITHUB_TOKEN: {{ .Values.auth.githubToken }}
  GITLAB_TOKEN: {{ .Values.auth.gitlabToken }}
  AZURE_TOKEN: {{ .Values.auth.azure.api.token }}
+  NEW_RELIC_REST_API_KEY: {{ .Values.auth.newRelicRestApiKey }}
+  TRAVISCI_AUTH_TOKEN: {{ .Values.auth.travisciAuthToken }}
 {{- end }}
@@ -13,6 +13,7 @@ metadata:
 data:
  APP_CONFIG_app_baseUrl: {{ .Values.appConfig.app.baseUrl | quote | quote }}
  APP_CONFIG_app_title: {{ .Values.appConfig.app.title | quote | quote }}
+  APP_CONFIG_app_googleAnalyticsTrackingId: {{ .Values.appConfig.app.googleAnalyticsTrackingId | quote | quote }}
  APP_CONFIG_backend_baseUrl: {{ .Values.appConfig.backend.baseUrl | quote | quote }}
  APP_CONFIG_backend_cors_origin: {{ .Values.appConfig.backend.cors.origin | quote | quote }}
  APP_CONFIG_techdocs_storageUrl: {{ .Values.appConfig.techdocs.storageUrl | quote | quote }}
@@ -5,16 +5,25 @@ apiVersion: networking.k8s.io/v1beta1
 kind: Ingress
 metadata:
  name: {{ include "backstage.fullname" . }}-ingress
-  {{- with .Values.ingress.annotations }}
  annotations:
+    {{- if .Values.issuer.email }}
+    cert-manager.io/cluster-issuer: {{ .Values.issuer.clusterIssuer }}
+    {{- end }}
+    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
    nginx.ingress.kubernetes.io/configuration-snippet: |
      if ($scheme = https) {
      add_header  Strict-Transport-Security "max-age=0;";
      }
-  {{- toYaml . | nindent 4 }}
-  {{- end }}
+    {{- toYaml .Values.ingress.annotations | nindent 4 }}
 spec:
+  tls:
+    - secretName: {{ include "backstage.fullname" . }}-tls
+      hosts:
+        - {{ $frontendUrl.host }}
+        - {{ $backendUrl.host }}
+        - {{ $lighthouseUrl.host }}
+
  rules:
    - host: {{ $frontendUrl.host }}
      http:
@@ -56,17 +65,22 @@ apiVersion: networking.k8s.io/v1beta1
 kind: Ingress
 metadata:
  name: {{ include "backstage.fullname" . }}-ingress-lighthouse
-  {{- with .Values.ingress.annotations }}
  annotations:
+    {{- if .Values.issuer.email }}
+    cert-manager.io/cluster-issuer: {{ .Values.issuer.clusterIssuer }}
+    {{- end }}
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
    nginx.ingress.kubernetes.io/configuration-snippet: |
      if ($scheme = https) {
      add_header  Strict-Transport-Security "max-age=0;";
      }
-  {{- toYaml . | nindent 4 }}
-  {{- end }}
+    {{- toYaml .Values.ingress.annotations | nindent 4 }}
 spec:
+  tls:
+    - secretName: {{ include "backstage.fullname" . }}-tls
+      hosts:
+        - {{ $lighthouseUrl.host }}
  rules:
    - host: {{ $frontendUrl.host }}
      http:
@@ -0,0 +1,19 @@
+{{- if (and (.Capabilities.APIVersions.Has "cert-manager.io/v1alpha2") .Values.issuer.email )  -}}
+{{/*  Only install issuer if it doesn't already exist in the cluster */}}
+{{- if not ( lookup "cert-manager.io/v1alpha2" "ClusterIssuer"  "" .Values.issuer.clusterIssuer  ) }}
+apiVersion: cert-manager.io/v1alpha2
+kind: ClusterIssuer
+metadata:
+  name: {{ .Values.issuer.clusterIssuer }}
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: {{ required "expected a valid .Values.issuer.email to enable ClusterIssuer" .Values.issuer.email }}
+    privateKeySecretRef:
+      name: {{ required "expected .Values.issuer.cluster-issuer to not be empty (letsencrypt-prod | letsencrypt-staging)" .Values.issuer.clusterIssuer }}
+    solvers:
+    - http01:
+        ingress:
+          class: nginx
+{{- end -}}
+{{- end -}}
@@ -61,6 +61,10 @@ ingress:
  annotations:
    kubernetes.io/ingress.class: nginx

+issuer:
+  email:
+  clusterIssuer: 'letsencrypt-staging'
+
 global:
  postgresql:
    postgresqlUsername: backend-user
@@ -82,6 +86,7 @@ appConfig:
  app:
    baseUrl: https://demo.example.com
    title: Backstage
+    googleAnalyticsTrackingId:
  backend:
    baseUrl: https://demo.example.com
    listen:
@@ -243,3 +248,5 @@ auth:
  # Used by the scaffolder to create GitHub repos. Must have 'repo' scope.
  githubToken: g
  gitlabToken: g
+  newRelicRestApiKey: r
+  travisciAuthToken: fake-travis-ci-auth-token
@@ -9,7 +9,6 @@ import {
  InfoCard,
  Header,
  Page,
-  pageTheme,
  Content,
  ContentHeader,
  HeaderLabel,
@@ -25,7 +24,7 @@ const ExampleComponent: FC<{}> = () => {
  const profile = identityApi.getProfile();

  return (
-    <Page theme={pageTheme.tool}>
+    <Page themeId="tool">
      <Header
        title="Welcome to github-playground!"
        subtitle="Optional subtitle"
@@ -0,0 +1,42 @@
+# Plain Kubernetes Deployment
+
+This directory contains an example of a simple Kubernetes deployment of Backstage. It is not intended to serve as a complete production deployment, but as a starting point for setting one up.
+
+## Usage
+
+You can try the deployment out as is. The easiest way is to use [Docker Desktop](https://www.docker.com/products/docker-desktop) with [Kubernetes](https://docs.docker.com/get-started/kube-deploy/).
+
+From a fresh clone of this repo, run the following in the root:
+
+```bash
+yarn install
+
+yarn docker-build
+
+kubectl apply -f contrib/kubernetes/plain_single_backend_deplyoment/deployment.yaml
+```
+
+You can use the following commands to monitor the deployment:
+
+```bash
+# List all resources in the backstage namespace
+kubectl -n backstage get all
+
+# Inspect the status of the deployment resource
+kubectl -n backstage describe deployment backstage-backend
+
+# Inspect the status of the pod running the backstage backend
+kubectl -n backstage describe pod -l app=backstage,component=backend
+```
+
+Once the deployment is up and running, you can use the following to set up a proxy to reach the backend locally:
+
+```bash
+kubectl proxy
+```
+
+With the proxy up and running, you should be able to navigate to [http://localhost:8001/api/v1/namespaces/backstage/services/backstage-backend:http/proxy](http://localhost:8001/api/v1/namespaces/backstage/services/backstage-backend:http/proxy) and see Backstage. Note that you'll end up on a 404 page, but hitting the home icon in the sidebar should take you to the catalog page where you can see a few example services.
+
+## Caveats
+
+This deployment is for demonstration purposes only, for a production deployment you will need to set up at least a persistent database and some form of ingress. If your organization doesn't already have established patterns for these, you could look at options of managed PostgreSQL instances from cloud providers, or something like Zalando's [postgres-operator](https://github.com/zalando/postgres-operator). For ingress there are also [plenty of options](https://ramitsurana.gitbook.io/awesome-kubernetes/docs/projects/projects#load-balancing), where `nginx` is a popular choice to get started.
@@ -0,0 +1,107 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: backstage
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: backstage-backend
+  namespace: backstage
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: backstage
+      component: backend
+  template:
+    metadata:
+      labels:
+        app: backstage
+        component: backend
+    spec:
+      containers:
+        - name: backend
+          # This image is built with `yarn docker-build` in the repo root.
+          # Replace this with your own image to deploy your own Backstage app.
+          image: example-backend:latest
+          imagePullPolicy: Never
+
+          command: [node, packages/backend]
+          args: [--config, app-config.yaml, --config, k8s-config.yaml]
+
+          env:
+            # We set this to development to make the backend start with incomplete configuration. In a production
+            # deployment you will want to make sure that you have a full configuration, and remove any plugins that
+            # you are not using.
+            - name: NODE_ENV
+              value: development
+
+              # This makes it possible for the app to reach the backend when serving through `kubectl proxy`
+              # If you expose the service using for example an ingress controller, you should
+              # switch this out or remove it.
+              #
+              # Note that we're not setting app.baseUrl here, as setting the base path is not working at the moment.
+              # Further work is needed around the routing in the frontend or react-router before we can support that.
+            - name: APP_CONFIG_backend_baseUrl
+              value: http://localhost:8001/api/v1/namespaces/backstage/services/backstage-backend:http/proxy
+
+          ports:
+            - name: http
+              containerPort: 7000
+
+          volumeMounts:
+            - name: config-volume
+              mountPath: /usr/src/app/k8s-config.yaml
+              subPath: k8s-config.yaml
+
+          resources:
+            limits:
+              cpu: 1
+              memory: 0.5Gi
+
+          readinessProbe:
+            httpGet:
+              port: 7000
+              path: /healthcheck
+          livenessProbe:
+            httpGet:
+              port: 7000
+              path: /healthcheck
+
+      volumes:
+        - name: config-volume
+          configMap:
+            name: backstage-config
+            items:
+              - key: app-config
+                path: k8s-config.yaml
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: backstage-config
+  namespace: backstage
+data:
+  # Note that the config here is only applied to the backend. The frontend config is applied at build time.
+  # To override frontend config in this deployment, use `APP_CONFIG_` env vars.
+  app-config: |
+    app:
+      baseUrl: http://localhost:8001/api/v1/namespaces/backstage/services/backstage-backend:http/proxy
+    backend:
+      baseUrl: http://localhost:8001/api/v1/namespaces/backstage/services/backstage-backend:http/proxy
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: backstage-backend
+  namespace: backstage
+spec:
+  selector:
+    app: backstage
+    component: backend
+  ports:
+    - name: http
+      port: 80
+      targetPort: http
@@ -178,8 +178,7 @@ Spotify will maintain the open source core, but we envision different parts of
 the project being maintained by various companies and contributors. We also
 envision a large, diverse ecosystem of open source plugins, which would be
 maintained by their original authors/contributors or by the community. When it
-comes to
-[deployment](https://github.com/spotify/backstage/blob/master/DEPLOYMENT.md),
+comes to [deployment](https://backstage.io/docs/getting-started/deployment-k8s),
 the system integrator (typically, the infrastructure team in your organization)
 maintains Backstage in your own environment.

@@ -187,7 +186,7 @@ maintains Backstage in your own environment.

 No, this is not a service offering. We build the piece of software, and someone
 in your infrastructure team is responsible for
-[deploying](https://github.com/spotify/backstage/blob/master/DEPLOYMENT.md) and
+[deploying](https://backstage.io/docs/getting-started/deployment-k8s) and
 maintaining it.

 ### How secure is Backstage?
@@ -230,8 +229,3 @@ write an open source plugin for Backstage, like this
 See all the ways you can
 [contribute here](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md).
 We'd love to have you as part of the community.
-
-### Can I join the Backstage team?
-
-If you're interested in being part of the Backstage team, reach out to
-[fossopportunities@spotify.com](mailto:fossopportunities@spotify.com)
@@ -20,7 +20,7 @@ Each of these methods is hosted at an endpoint `/auth/[provider]/method`, where
 ```

 For more information on how these methods are used and for which purpose, refer
-to the documentation [here](oauth.md).
+to the [OAuth documentation](oauth.md).

 For details on the parameters, input and output conditions for each method,
 refer to the type documentation under
@@ -38,7 +38,7 @@ Currently OAuth is assumed to be the de facto authentication mechanism for
 Backstage based applications.

 Backstage comes with a "batteries-included" set of supported commonly used OAuth
-providers: Okta, Github, Google, Gitlab, and a generic OAuth2 provider.
+providers: Okta, GitHub, Google, GitLab, and a generic OAuth2 provider.

 All of these use the authorization flow of OAuth2 to implement authentication.

@@ -15,11 +15,11 @@ allowing for customization.

 ## Supplying Configuration

-Configuration is stored in `app-config.yaml` files, with support for suffixes
-such as `app-config.production.yaml` to override values for specific
-environments. The configuration files themselves contain plain YAML, but with
-support for loading in secrets from various sources using for example `$env` and
-`$file` keys.
+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.

 It is also possible to supply configuration through environment variables, for
 example `APP_CONFIG_app_baseUrl=https://staging.example.com`. However these
@@ -55,20 +55,28 @@ picked up by the serve tasks of `@backstage/cli` for local development, and are
 injected by the entrypoint of the nginx container serving the frontend in a
 production build.

-## File Resolution
+## Configuration Files

 It is possible to have multiple configuration files, both to support different
 environments, but also to define configuration that is local to specific
-packages.
+packages. The configuration files to load are selected using a `--config <path>`
+flag, and it is possible to load any number of files. Paths are relative to the
+working directory of the executed process, for example `package/backend`. This
+means that to select a config file in the repo root when running the backend,
+you would use `--config ../../my-config.yaml`.

-All `app-config.yaml` files inside the monorepo root and package root are
-considered, as are files with additional `local` and environment affixes such as
-`development`, for example `app-config.local.yaml`,
-`app-config.production.yaml`, and `app-config.development.local.yaml`. Which
-environment config files are loaded is determined by the `APP_ENV` environment
-variable, or `NODE_ENV` if it is not set. Local configuration files are always
-loaded, but are meant for local development overrides and should typically be
-`.gitignore`'d.
+If no `config` flags are specified, the default behavior is to load
+`app-config.yaml` and, if it exists, `app-config.local.yaml` from the repo root.
+In the provided project setup, `app-config.local.yaml` is `.gitignore`'d, making
+it a good place to add config overrides and secrets for local development.
+
+Note that if any config flags are provided, the default `app-config.yaml` files
+are NOT loaded. To include them you need to explicitly include them with a flag,
+for example:
+
+```
+yarn start --config ../../app-config.yaml --config ../../app-config.staging.yaml
+```

 All loaded configuration files are merged together using the following rules:

@@ -84,10 +92,10 @@ order:

 - Configuration from the `APP_CONFIG_` environment variables has the highest
  priority, followed by files.
- Files inside package directories have higher priority than those in the root
-  directory.
- Files with environment affixes have higher priority than ones without.
- Files with the `local` affix have higher priority than ones without.
+- Files loaded with config flags are ordered by priority, where the last flag
+  has the highest priority.
+- If no config flags are provided, `app-config.local.yaml` has higher priority
+  than `app-config.yaml`.

 ## Secrets

@@ -1,5 +1,5 @@
 ---
-id: software-catalog-configuration
+id: configuration
 title: Catalog Configuration
 description: Documentation on Software Catalog Configuration
 ---
@@ -12,7 +12,10 @@ This both applies to objects given to and returned from the software catalog
 API, as well as to the descriptor files that the software catalog can ingest
 natively. In the API request/response cycle, a JSON representation is used,
 while the descriptor files are on YAML format to be more easily maintainable by
-humans. However, the structure and semantics is the same in both cases.
+humans. However, the structure and semantics are the same in both cases.
+
+Although it's possible to name catalog entity descriptor files however you wish,
+we recommend that you name them `catalog-info.yaml`.

 ## Contents

@@ -110,7 +113,7 @@ data.
 Backstage specific entities have an `apiVersion` that is prefixed with
 `backstage.io/`, to distinguish them from other types of object that share the
 same type of structure. This may be relevant when co-hosting these
-specifications with e.g. kubernetes object manifests, or when an organization
+specifications with e.g. Kubernetes object manifests, or when an organization
 adds their own specific kinds of entity to the catalog.

 Early versions of the catalog will be using alpha/beta versions, e.g.
@@ -19,7 +19,7 @@ are then harvested and visualized in Backstage.

 ## How it works

-Backstage and the Backstage Service Catalog makes it easy for one team to manage
+Backstage and the Backstage Service Catalog make it easy for one team to manage
 10 services — and makes it possible for your company to manage thousands of
 them.

@@ -5,8 +5,8 @@ description: Documentation on Adding your own Templates
 ---

 Templates are stored in the **Service Catalog** under a kind `Template`. The
-minimum that the template skeleton needs is a `template.yaml` but it would be
-good to also have some files in there that can be templated in.
+minimum that is needed to define a template is a `template.yaml` file, but it
+would be good to also have some files in there that can be templated in.

 A simple `template.yaml` definition might look something like this:

@@ -61,7 +61,7 @@ support to load the location will also need to be added to the Catalog.

 You can add the template files to the catalog through
 [static location configuration](../software-catalog/configuration.md#static-location-configuration),
-for example
+for example:

 ```yaml
 catalog:
@@ -100,11 +100,11 @@ curl \
  --location \
  --request POST 'localhost:7000/api/catalog/locations' \
  --header 'Content-Type: application/json' \
-  --data-raw "{\"type\": \"github\", \"target\": \"https://${YOUR GITHUB REPO}blob/master/${PATH TO FOLDER}/template.yaml\"}"
+  --data-raw "{\"type\": \"github\", \"target\": \"https://${GITHUB URL}/${YOUR GITHUB ORG/REPO}/blob/master/${PATH TO FOLDER}/template.yaml\"}"
 ```

-This should then have added the catalog, and also should now be listed under the
-create page at http://localhost:3000/create.
+This should then have been added the catalog, and be listed under the create
+page at http://localhost:3000/create.

 The `type` field which is chosen in the request to add the `template.yaml` to
 the Service Catalog here, will become the `PreparerKey` which will be used to
@@ -15,10 +15,10 @@ location protocols:
 - `github://`

 These two are added to the `PreparersBuilder` and then passed into the
-`createRouter` function of the `@spotify/plugin-scaffolder-backend`
+`createRouter` function of the `@spotify/plugin-scaffolder-backend`.

-A full example backend can be found
-[here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts),
+A full example backend can be found in
+[`scaffolder.ts`](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts),
 but it looks something like the following

 ```ts
@@ -56,7 +56,7 @@ when added to the service catalog. You can see more about this `PreparerKey`
 here in [Register your own template](../adding-templates.md)

 **note:** Currently the catalog supports loading definitions from GitHub + Local
-Files, which translate into the two `PreparerKeys` `file` and `github`. To load
+Files, which translate into the two `PreparerKeys`: `file` and `github`. To load
 from other places, not only will there need to be another preparer, but the
 support to load the location will also need to be added to the Catalog.

@@ -39,17 +39,17 @@ internally.
 ![Enter some variables](../../assets/software-templates/template-picked.png)

 After filling in these variables, you'll get some more fields to fill out which
-are required for backstage usage: the owner, (which is a `user` in the backstage
+are required for backstage usage: the owner (which is a `user` in the backstage
 system), the `storePath` (which right now must be a GitHub Organisation or
-GitHub user), a non-existing github repository name in the format
-`organisation/reponame`, and a GitHub team or user account which should be
+GitHub user and a non-existing GitHub repository name in the format
+`organisation/reponame`), and a GitHub team or user account which should be
 granted admin access to the repository.

 ![Enter backstage vars](../../assets/software-templates/template-picked-2.png)

 ### Run!

-Once you've entered values and confirmed, you'll then get a modal with live
+Once you've entered values and confirmed, you'll then get a popup box with live
 progress of what is currently happening with the creation of your template.

 ![Templating Running](../../assets/software-templates/running.png)
@@ -70,6 +70,6 @@ you to the registered component in the catalog:

 ![Catalog](../../assets/software-templates/go-to-catalog.png)

-And then you'll also be able to see it in the Catalog View table
+And then you'll also be able to see it in the Catalog View table:

 ![Catalog](../../assets/software-templates/added-to-the-catalog-list.png)
@@ -211,22 +211,16 @@ docs on creating private GitHub access tokens is available
 Note that the need for private GitHub access tokens will be replaced with GitHub
 Apps integration further down the line.

-#### Github
+#### GitHub

-The Github access token is retrieved from environment variables via the config.
+The GitHub access token is retrieved from environment variables via the config.
 The config file needs to specify what environment variable the token is
 retrieved from. Your config should have the following objects.

 You can configure who can see the new repositories that the scaffolder creates
 by specifying `visibility` option. Valid options are `public`, `private` and
-`internal`. `internal` options is for GitHub Enterprise clients, which means
-public within the organization.
-
-#### Gitlab
-
-For Gitlab, we currently support the configuration of the GitLab publisher and
-allows to configure the private access token and the base URL of a GitLab
-instance:
+`internal`. The `internal` option is for GitHub Enterprise clients, which means
+public within the enterprise.

 ```yaml
 scaffolder:
@@ -234,6 +228,16 @@ scaffolder:
    token:
      $env: GITHUB_TOKEN
    visibility: public # or 'internal' or 'private'
+```
+
+#### GitLab
+
+For GitLab, we currently support the configuration of the GitLab publisher and
+allows to configure the private access token and the base URL of a GitLab
+instance:
+
+```yaml
+scaffolder:
  gitlab:
    api:
      baseUrl: https://gitlab.com
@@ -82,7 +82,9 @@ for companies to adopt. This involves (something like) the following work items.
 - “Solidify” work and “Mkdocs stabilization” work that has come out of our Q3
  end-to-end work.
 - Improve/simplify the get up and running process.
- Introduce doc template Software Templates.
+- Introduce new documentation templates.
+- Extend the already existing docs-template to have options of different
+  documentation types.
 - Enable companies to choose their own storage (S3 for example).
 - Enable companies to choose their own source code hosting provider (GitHub,
  GitLab, and so).
@@ -19,12 +19,20 @@ This section will guide you through:

 ## Create a basic documentation setup

+If you have an existing repository that you'd like to add documentation to, skip
+to the
+[Manually add documentation setup](#manually-add-documentation-setup-to-already-existing-repository)
+section below. Otherwise, continue reading to start a documentation repo from
+scratch.
+
 ### Use the documentation template

 Your working Backstage instance should by default have a documentation template
 added. If not, follow these
 [instructions](../software-templates/installation.md#adding-templates) to add
-the documentation template.
+the documentation template. The template creates a component with only TechDocs
+configuration and default markdown files as below mentioned in manual
+documentation setup, and is otherwise empty.

 ![Documentation Template](../../assets/techdocs/documentation-template.png)

@@ -35,9 +43,11 @@ setup for free.

 Prerequisities:

- `catalog-info.yml` file registered to Backstage.
+- An existing component
+  [registered in backstage](../software-catalog/index.md#adding-components-to-the-catalog)
+  (e.g. via a `catalog-info.yaml` file).

-Create a `mkdocs.yml` file in the root of the repository with the following
+Create an `mkdocs.yml` file in the root of your repository with the following
 content:

 ```yaml
@@ -50,8 +60,8 @@ plugins:
  - techdocs-core
 ```

-Update your `catalog-info.yaml` file in the root of the repository with the
-following content:
+Update your component's entity description by adding the following lines to its
+`catalog-info.yaml` in the root of its repository:

 ```yaml
 metadata:
@@ -59,7 +69,7 @@ metadata:
    backstage.io/techdocs-ref: dir:./
 ```

-Create a `/docs` folder in the root of the project with at least a `index.md`
+Create a `/docs` folder in the root of the project with at least an `index.md`
 file. _(If you add more markdown files, make sure to update the nav in the
 mkdocs.yml file to get a proper navigation for your documentation.)_

@@ -58,7 +58,7 @@ The default storage and request URLs:
 ```yaml
 techdocs:
  storageUrl: http://localhost:7000/api/techdocs/static/docs
-  requestUrl: http://localhost:7000/api/techdocs/docs
+  requestUrl: http://localhost:7000/api/techdocs/
 ```

 If you want `techdocs-backend` to manage building and publishing, you want
@@ -13,7 +13,7 @@ need to run Backstage in your own environment.
 ## Create an app

 To create a Backstage app, you will need to have
-[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
+[Node.js](https://nodejs.org/en/download/) Active LTS Release installed
 (currently v12).

 Backstage provides a utility for creating new apps. It guides you through the
@@ -124,3 +124,21 @@ the root directory:
 ```bash
 yarn workspace backend start
 ```
+
+### Troubleshooting
+
+#### Cannot find module
+
+You may encounter an error similar to below:
+
+```
+internal/modules/cjs/loader.js:968
+  throw err;
+  ^
+
+Error: Cannot find module '../build/Debug/nodegit.node'
+```
+
+This can occur if an npm dependency is not completely installed. Because some
+dependencies run a post-install script, ensure that both your npm and yarn
+configs have the `ignore-scripts` flag set to `false`.
@@ -2,17 +2,18 @@
 id: deployment-helm
 title: Helm
 description: Documentation on Kubernetes and Helm Deployment
+sidebar_label: Kubernetes and Helm
 ---

 # Helm charts

-An example Backstage app can be deployed in Kubernetes using the [Backstage Helm
-charts][backstage-helm-charts]
+An example Backstage app can be deployed in Kubernetes using the
+[Backstage Helm charts](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage).

-First, choose a DNS name where backstage will be hosted create a yaml file for
-your custom configuration.
+First, choose a DNS name where Backstage will be hosted, and create a YAML file
+for your custom configuration.

-```
+```yaml
 appConfig:
  app:
    baseUrl: https://backstage.mydomain.com
@@ -26,12 +27,11 @@ appConfig:
  techdocs:
    storageUrl: https://backstage.mydomain.com/api/techdocs/static/docs
    requestUrl: https://backstage.mydomain.com/api/techdocs
-
 ```

 Then use it to run:

-```
+```bash
 git clone https://github.com/spotify/backstage.git
 cd contrib/chart/backstage
 helm dependency update
@@ -61,9 +61,4 @@ backstage-ingress   *       123.1.2.3       80      17m
 > **NOTE**: this is not a production ready deployment.

 For more information on how to customize the deployment check the
-[README][charts-readme].
-
-[backstage-helm-charts]:
-  (https://github.com/spotify/backstage/tree/master/contrib/chart/backstage)
-[charts-readme]:
-  (https://github.com/spotify/backstage/tree/master/contrib/chart/backstage/README.md)
+[README](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage/README.md).
@@ -4,4 +4,10 @@ title: Kubernetes
 description: Documentation on Kubernetes and K8s Deployment
 ---

-Coming soon!
+Backstage itself provides tooling up to the point of building Docker images.
+Beyond that point we do not have an opinionated way to deploy Backstage within
+Kubernetes, as each cluster has its own unique set of tooling and patterns.
+
+We do provide examples to help you get started though. Check out
+[this example](https://github.com/spotify/backstage/tree/master/contrib/kubernetes/plain_single_backend_deplyoment/)
+for a basic single-deployment setup.
@@ -17,3 +17,33 @@ $ docker run --rm -it -p 7000:7000 -e APP_ENV=production -e NODE_ENV=development
 ```

 Then open http://localhost/ on your browser.
+
+## Heroku
+
+Deploying to Heroku is relatively easy following these steps.
+
+First, make sure you have the
+[Heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log
+into it as well as login into Heroku's
+[container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime).
+
+```bash
+$ heroku login
+$ heroku container:login
+```
+
+You _might_ also need to set your Heroku app's stack to `container`.
+
+```bash
+$ heroku stack:set container -a <your-app>
+```
+
+We can now build/push the Docker image to Heroku's container registry and
+release it to the `web` worker.
+
+```bash
+$ heroku container:push web -a <your-app>
+$ heroku container:release web -a <your-app>
+```
+
+With that, you should have Backstage up and running!
@@ -23,8 +23,8 @@ Requests towards this repo.

 Backstage provides the `@backstage/create-app` package to scaffold standalone
 instances of Backstage. You will need to have
-[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
-(currently v12), [yarn](https://classic.yarnpkg.com/en/docs/install) and
+[Node.js](https://nodejs.org/en/download/) Active LTS Release installed
+(currently v12), [Yarn](https://classic.yarnpkg.com/en/docs/install) and
 [Python](https://www.python.org/downloads/) (although you likely have it
 already). You will also need to have
 [Docker](https://docs.docker.com/engine/install/) installed to use some features
@@ -38,8 +38,8 @@ npx @backstage/create-app
 ```

 You will be taken through a wizard to create your app, and the output should
-look something like this. You can read more about this process
-[here](https://backstage.io/docs/getting-started/create-an-app).
+look something like this. You can read more about this process in
+[Create an app](https://backstage.io/docs/getting-started/create-an-app).

 ### Contributing to Backstage

@@ -1,7 +0,0 @@
---
-id: installation
-title: Installation
-description: Documentation on Installation
---
-
-Coming soon!
@@ -8,7 +8,7 @@ description: Documentation on How to run Backstage Locally

 - Node.js

-First make sure you are using NodeJS with an Active LTS Release, currently v12.
+First make sure you are using Node.js with an Active LTS Release, currently v12.
 This is made easy with a version manager such as
 [nvm](https://github.com/nvm-sh/nvm) which allows for version switching.

@@ -23,10 +23,10 @@ node --version
 > v12.18.3
 ```

- yarn
+- Yarn

 Please refer to the
-[installation instructions for yarn](https://classic.yarnpkg.com/en/docs/install/).
+[installation instructions for Yarn](https://classic.yarnpkg.com/en/docs/install/).

 - Docker

@@ -24,7 +24,7 @@ different ways.
 ## Overview

 The following diagram shows how Backstage might look when deployed inside a
-company which uses the Tech Radar plugin, the Lighthouse plugin, the Circle CI
+company which uses the Tech Radar plugin, the Lighthouse plugin, the CircleCI
 plugin and the service catalog.

 There are 3 main components in this architecture:
@@ -48,14 +48,14 @@ management. [[live demo](https://backstage-demo.roadie.io/)]
 ![UI with different components highlighted](../assets/architecture-overview/core-vs-plugin-components-highlighted.png)

 Each plugin typically makes itself available in the UI on a dedicated URL. For
-example, the lighthouse plugin is registered with the UI on `/lighthouse`.
+example, the Lighthouse plugin is registered with the UI on `/lighthouse`.
 [[live demo](https://backstage-demo.roadie.io/lighthouse)]

 ![The lighthouse plugin UI](../assets/architecture-overview/lighthouse-plugin.png)

-The Circle CI plugin is available on `/circleci`.
+The CircleCI plugin is available on `/circleci`.

-![Circle CI Plugin UI](../assets/architecture-overview/circle-ci.png)
+![CircleCI Plugin UI](../assets/architecture-overview/circle-ci.png)

 ## Plugins and plugin backends

@@ -76,7 +76,7 @@ Plugins can be enabled, and passed configuration in `apis.ts`. For example,
 [here](https://github.com/spotify/backstage/blob/master/packages/app/src/apis.ts)
 is that file in the Backstage sample app.

-This is how the lighthouse plugin would be enabled in a typical Backstage
+This is how the Lighthouse plugin would be enabled in a typical Backstage
 application:

 ```tsx
@@ -108,7 +108,7 @@ Architecturally, plugins can take three forms:
 #### Standalone plugins

 Standalone plugins run entirely in the browser.
-[The tech radar plugin](https://backstage-demo.roadie.io/tech-radar), for
+[The Tech Radar plugin](https://backstage-demo.roadie.io/tech-radar), for
 example, simply renders hard-coded information. It doesn't make any API requests
 to other services.

@@ -124,9 +124,9 @@ simple.
 Service backed plugins make API requests to a service which is within the
 purview of the organisation running Backstage.

-The lighthouse plugin, for example, makes requests to the
+The Lighthouse plugin, for example, makes requests to the
 [lighthouse-audit-service](https://github.com/spotify/lighthouse-audit-service).
-The lighthouse-audit-service is a microservice which runs a copy of Google's
+The `lighthouse-audit-service` is a microservice which runs a copy of Google's
 [Lighthouse library](https://github.com/GoogleChrome/lighthouse/) and stores the
 results in a PostgreSQL database.

@@ -144,43 +144,42 @@ Third-party backed plugins are similar to service backed plugins. The main
 difference is that the service which backs the plugin is hosted outside of the
 ecosystem of the company hosting Backstage.

-The Circle CI plugin is an example of a third-party backed plugin. Circle CI is
-a SaaS service which can be used without any knowledge of Backstage. It has an
-API which a Backstage plugin consumes to display content.
+The CircleCI plugin is an example of a third-party backed plugin. CircleCI is a
+SaaS service which can be used without any knowledge of Backstage. It has an API
+which a Backstage plugin consumes to display content.

-Requests which go to Circle CI from the users browser are passed through a proxy
+Requests which go to CircleCI from the users browser are passed through a proxy
 service that Backstage provides. Without this, the requests would be blocked by
 Cross Origin Resource Sharing policies which prevent a browser page served at
 [https://example.com](https://example.com) from serving resources hosted at
 https://circleci.com.

-![CircleCi plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png)
+![CircleCI plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png)

 ## Databases

-As we have seen, both the lighthouse-audit-service and catalog-backend require a
-database to work with.
+As we have seen, both the `lighthouse-audit-service` and `catalog-backend`
+require a database to work with.

-At the time of writing, the lighthouse-audit-service requires PostgreSQL to work
-with. The service catalog backend uses an in-memory Sqlite3 instance. This is a
-development oriented setup and there are plans to support other databases in the
-future.
+At the time of writing, the `lighthouse-audit-service` requires PostgreSQL to
+work with. The service catalog backend uses an in-memory Sqlite3 instance. This
+is a development-oriented setup and there are plans to support other databases
+in the future.

-To learn more about the future of databases and Backstage, see the following two
+To learn more about the future of databases and Backstage, see the following
 GitHub issues.

-[Knex + Plugins (Multiple vs Single Database) · Issue #1598 · spotify/backstage](https://github.com/spotify/backstage/issues/1598)
-
-[Update migrations to support postgres by dariddler · Pull Request #1527 · spotify/backstage](https://github.com/spotify/backstage/pull/1527#discussion_r450374145)
+- [Knex + Plugins (Multiple vs Single Database) · Issue #1598 · spotify/backstage](https://github.com/spotify/backstage/issues/1598)
+- [Update migrations to support postgres by dariddler · Pull Request #1527 · spotify/backstage](https://github.com/spotify/backstage/pull/1527#discussion_r450374145)

 ## Containerization

 The example Backstage architecture shown above would Dockerize into three
-separate docker images.
+separate Docker images.

 1. The frontend container
 2. The backend container
-3. The lighthouse audit service container
+3. The Lighthouse audit service container

 ![Boxes around the architecture to indicate how it is containerised](../assets/architecture-overview/containerised.png)

@@ -204,7 +203,7 @@ yarn run docker-build
 This will create a container called `example-backend`.

 The lighthouse-audit-service container is already publicly available in Docker
-Hub and can be downloaded and ran with
+Hub and can be downloaded and run with

 ```bash
 docker run spotify/lighthouse-audit-service:latest
@@ -47,40 +47,29 @@ guidelines to get started.

 ### Ongoing work 🚧

- **[Plugins for managing micro services end-2-end](https://github.com/spotify/backstage/milestone/14)** -
+- **[Plugins for managing micro services end-2-end](https://github.com/spotify/backstage/milestone/14)**
  Out of the box Backstage will ship with a set of plugins (Overview, CI, API
  and Docs) that will demonstrate how a user can manage a micro service and
  follow a change all the way out in production. Completing this work will make
  it much easier to see how a plugin can be built that integrates with the
  Backstage Service Catalog.

- **[Kubernetes support](https://github.com/spotify/backstage/milestone/20)** -
-  Native support for Kubernetes, making it easier for developers to see and
-  manage their services running in k8s.
-
- **[Helm charts](https://github.com/spotify/backstage/issues/2540)** - Provide
-  Helm charts for easy deployments of Backstage and its subsystems on
-  Kubernetes.
+- **[Users and teams](https://github.com/spotify/backstage/issues/1807)**
+  Ownership is a central concept in Backstage. It should be easy to import your
+  existing organizational data, such as users and groups/teams, into Backstage.
+  A user the logs into Backstage should see software components owned by the
+  team(s) they are in.

 - **[Backstage platform is stable](https://github.com/spotify/backstage/milestone/19)** -
  The platform APIs and features are stable and can be depended on for
  production use. After this plugins will require little to no maintenance.

- Further improvements to platform documentation
+* **[Improved Kubernetes plugin](https://github.com/spotify/backstage/issues/2857)** -
+  Native support for Kubernetes, making it easier for developers to see and
+  manage their services running in k8s.

-### Plugins
-
-Building and maintaining [plugins](https://backstage.io/plugins) is the work of
-the entire Backstage community.
-
-A list of plugins that are in development is
-[available here](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+label%3Aplugin+sort%3Areactions-%2B1-desc).
-We strongly recommend to upvote 👍 plugins you are interested in. This helps us
-and the community prioritize what plugins to build.
-
-Are you missing a plugin for your favorite tool? Please
-[suggest a new one](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME).
-Chances are that someone will jump in and help build it.
+- Further improvements to platform documentation. Examples include a Golden Path
+  for plugin development.

 ### Future work 🔮

@@ -107,8 +96,24 @@ Chances are that someone will jump in and help build it.
  query. Plugins can easily query this API as well as extend the model where
  needed.

+### Plugins
+
+Building and maintaining [plugins](https://backstage.io/plugins) is the work of
+the entire Backstage community.
+
+A list of plugins that are in development is
+[available here](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+label%3Aplugin+sort%3Areactions-%2B1-desc).
+We strongly recommend to upvote 👍 plugins you are interested in. This helps us
+and the community prioritize what plugins to build.
+
+Are you missing a plugin for your favorite tool? Please
+[suggest a new one](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME).
+Chances are that someone will jump in and help build it.
+
 ### Completed milestones ✅

+- [Kubernetes plugin - v1](https://github.com/spotify/backstage/tree/master/plugins/kubernetes)
+- [Helm charts](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage)
 - [Backstage Design System 💅](https://backstage.io/blog/2020/09/30/backstage-design-system)
 - [Cost Insights plugin 💸](https://engineering.atspotify.com/2020/09/29/managing-clouds-from-the-ground-up-cost-engineering-at-spotify/)
 - [Donate Backstage to the CNCF 🎉](https://backstage.io/blog/2020/09/23/backstage-cncf-sandbox)
@@ -88,7 +88,7 @@ The proxy is powered by the `http-proxy-middleware` package. See
 [Proxying](proxying.md) for a full description of its configuration options.

 Internally at Spotify, the proxy option has been the overwhelmingly most popular
-choice for plugin makers. Since we have DNS based service discovery in place and
+choice for plugin makers. Since we have DNS-based service discovery in place and
 a microservices framework that made it trivial to expose plain HTTP, it has been
 a matter of just adding a few lines of Backstage config to get the benefit of
 being easily and robustly reachable from users' web browsers as well.
@@ -73,7 +73,7 @@ export const plugin = createPlugin({
 ```

 This is where the plugin is created and where it hooks into the app by declaring
-what component should be shown on what url. See reference docs for
+what component should be shown on what URL. See reference docs for
 [createPlugin](../reference/createPlugin.md) or
 [router](../reference/createPlugin-router.md).

@@ -101,11 +101,11 @@ Backstage CLI.

 ## Talking to the outside world

-If your plugin needs to communicate with services outside the backstage
+If your plugin needs to communicate with services outside the Backstage
 environment you will probably face challenges like CORS policies and/or
 backend-side authorization. To smooth this process out you can use proxy -
-either the one you already have (like nginx/haproxy/etc) or the proxy-backend
-plugin that we provide for the backstage backend.
+either the one you already have (like Nginx, HAProxy, etc.) or the proxy-backend
+plugin that we provide for the Backstage backend.
 [Read more](https://github.com/spotify/backstage/blob/master/plugins/proxy-backend/README.md)

 [Back to Getting Started](../README.md)
@@ -248,15 +248,15 @@ Testing an API involves verifying four things:

 ### Mocking API Calls

-[Mocking in jest](https://facebook.github.io/jest/docs/en/mock-functions.html)
+[Mocking in Jest](https://facebook.github.io/jest/docs/en/mock-functions.html)
 involves wrapping existing functions (like an API call function) with an
 alternative.

 For example:

-**./Api.js**
+**`./MyApi.js`**

-```
+```js
 export {
  fetchSomethingFromServer: () => {
    // Live production call to a URI. Must be avoided during testing!
@@ -265,9 +265,9 @@ export {
 };
 ```

-**./\_\_mocks\_\_/Api.js**
+**`./\_\_mocks\_\_/MyApi.js`**

-```
+```js
 export {
  fetchSomethingFromServer: () => {
    // Simulate a production call, but avoid jest and just use a promise
@@ -276,16 +276,16 @@ export {
 }
 ```

-**./Api.test.js**
+**`./MyApi.test.js`**

-```
+```js
 /* eslint-disable import/first */

 jest.mock('./MyApi'); // Instruct Jest to swap all future imports of './MyApi.js' to './__mocks__/MyApi.js'

 import MyApi from './MyApi'; // Will actually return the contents of the file in the __mocks__ folder now

-it ('loads data', (done) => {
+it('loads data', done => {
  MyApi.fetchSomethingFromServer().then(result => {
    expect(result).toBe('some result object simulating server data here');
    done();
@@ -0,0 +1,237 @@
+---
+id: project-structure
+title: Backstage Project Structure
+description:
+  Introduction to files and folders in the Backstage Project repository
+---
+
+Backstage is a complex project, and the GitHub repository contains many
+different files and folders. This document aims to clarify what purpose of those
+files and folders are.
+
+## General purpose files and folders
+
+In the project root, there are a set of files and folders which are not part of
+the project as such, and may or may not be familiar to someone looking through
+the code.
+
+- [`.changeset/`](https://github.com/spotify/backstage/tree/master/.changeset) -
+  This folder contains files outlining which changes occurred in the project
+  since the last release. These files are added manually, but managed by
+  [changesets](https://github.com/atlassian/changesets) and will be removed at
+  every new release. They are essentially building-blocks of a CHANGELOG.
+
+- [`.github/`](https://github.com/spotify/backstage/tree/master/.github) -
+  Standard GitHub folder. It contains - amongst other things - our workflow
+  definitions and templates. Worth noting is the
+  [styles](https://github.com/spotify/backstage/tree/master/.github/styles)
+  folder which is used for a markdown spellchecker.
+
+- [`.yarn/`](https://github.com/spotify/backstage/tree/master/.yarn) - Backstage
+  ships with it's own `yarn` implementation. This allows us to have better
+  control over our `yarn.lock` file and hopefully avoid problems due to yarn
+  versioning differences.
+
+- [`docker/`](https://github.com/spotify/backstage/tree/master/docker) - Files
+  related to our root Dockerfile. We are planning to refactor this, so expect
+  this folder to be moved in the future.
+
+- [`contrib/`](https://github.com/spotify/backstage/tree/master/contrib) -
+  Collection of examples or resources provided by the community. We really
+  appreciate contributions in here and encourage them being kept up to date.
+
+- [`docs/`](https://github.com/spotify/backstage/tree/master/docs) - This is
+  where we keep all of our documentation Markdown files. These ends up on
+  http://backstage.io/docs. Just keep in mind that changes to the
+  [`sidebars.json`](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json)
+  file may be needed as sections are added/removed.
+
+- [`.editorconfig`](https://github.com/spotify/backstage/tree/master/.editorconfig) -
+  A configuration file used by most common code editors.
+
+- [`.imgbotconfig`](https://github.com/spotify/backstage/tree/master/.imgbotconfig) -
+  Configuration for a [bot](https://imgbot.net/)
+
+## Monorepo packages
+
+Every folder in both `packages/` and `plugins/` is within our monorepo setup, as
+defined in
+[`package.json`](https://github.com/spotify/backstage/blob/master/package.json):
+
+```json
+ "workspaces": {
+    "packages": [
+      "packages/*",
+      "plugins/*"
+    ]
+  },
+```
+
+Let's look at them individually.
+
+### `packages/`
+
+These are all the packages that we use within the project. [Plugins](#plugins)
+are separated out into their own folder, see further down.
+
+- [`app/`](https://github.com/spotify/backstage/tree/master/packages/app) - This
+  is our take on how an App could look like, bringing together a set of packages
+  and plugins into a working Backstage App. This is not a published package, and
+  the main goals are to provide a demo of what an App could look like and to
+  enable local development.
+
+- [`backend/`](https://github.com/spotify/backstage/tree/master/packages/backend) -
+  Every standalone Backstage project will have both an `app` _and_ a `backend`
+  package. The `backend` uses plugins to construct a working backend that the
+  frontend (`app`) can use.
+
+- [`backend-common/`](https://github.com/spotify/backstage/tree/master/packages/backend-common) -
+  There are no "core" packages in the backend. Instead we have `backend-common`
+  which contains helper middleware and other utils.
+
+- [`catalog-model/`](https://github.com/spotify/backstage/tree/master/packages/catalog-model) -
+  You can consider this to be a library for working with the catalog of sorts.
+  It contains the definition of an
+  [Entity](https://backstage.io/docs/features/software-catalog/references#docsNav),
+  as well as validation and other logic related to it. This package can be used
+  in both the frontend and the backend.
+
+- [`cli/`](https://github.com/spotify/backstage/tree/master/packages/cli) - One
+  of the biggest packages in our project, the `cli` is used to build, serve,
+  diff, create-plugins and more. In the early days of this project, we started
+  out with calling tools directly - such as `eslint` - through `package.json`.
+  But as it was tricky to have a good development experience around that when we
+  change named tooling, we opted for wrapping those in our own cli. That way
+  everything looks the same in `package.json`. Much like
+  [react-scripts](https://github.com/facebook/create-react-app/tree/master/packages/react-scripts).
+
+- [`cli-common/`](https://github.com/spotify/backstage/tree/master/packages/cli-common) -
+  This package mainly handles path resolving. It is a separate package to reduce
+  bugs in [cli](https://github.com/spotify/backstage/tree/master/packages/cli).
+  We also want as few dependencies as possible to reduce download time when
+  running the cli which is another reason this is a separate package.
+
+- [`config/`](https://github.com/spotify/backstage/tree/master/packages/config) -
+  The way we read configuration data. This package can take a bunch of config
+  objects and merge them together.
+  [app-config.yaml](https://github.com/spotify/backstage/blob/master/app-config.yaml)
+  is an example of an config object.
+
+- [`config-loader/`](https://github.com/spotify/backstage/tree/master/packages/config-loader) -
+  This package is used to read config objects. It does not know how to merge,
+  but only reads files and passes them on to the config. As this part is only
+  used by the backend, we chose to separate `config` and `config-loader` into
+  two different packages.
+
+- [`core/`](https://github.com/spotify/backstage/tree/master/packages/core) -
+  This package contains our visual React components, some of which you can find
+  in
+  [plugin examples](https://backstage.io/storybook/?path=/story/plugins-examples--plugin-with-data).
+  Apart from that it re-exports everything from [`core-api`] so that users only
+  need to rely on one package.
+
+- [`core-api/`](https://github.com/spotify/backstage/tree/master/packages/core-api) -
+  This package contains APIs and definitions of such. It is it's own package
+  because we needed to split our `test-utils` package. It's an implementation
+  detail that we try to hide from our users, and no one should have to depend on
+  it directly.
+
+- [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) -
+  This package contains specific testing facilities used when testing
+  `core-api`.
+
+- [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) -
+  This package contains more general purpose testing facilities for testing a
+  Backstage App.
+
+- [`create-app/`](https://github.com/spotify/backstage/tree/master/packages/create-app) -
+  An CLI to specifically scaffold a new Backstage App. It does so by using a
+  [template](https://github.com/spotify/backstage/tree/master/packages/create-app/templates/default-app).
+
+- [`dev-utils/`](https://github.com/spotify/backstage/tree/master/packages/dev-utils) -
+  Helps you setup a plugin for isolated development so that it can be served
+  separately.
+
+- [`docgen/`](https://github.com/spotify/backstage/tree/master/packages/docgen) -
+  Uses the
+  [Typescript Compiler API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API)
+  to read out definitions and generate documentation for it.
+
+- [`e2e-test/`](https://github.com/spotify/backstage/tree/master/packages/e2e-test) -
+  Another CLI that can be run to try out what would happen if you built all the
+  packages, publish them, created a new app, and the run it. CI uses this for
+  e2e-tests.
+
+- [`storybook/`](https://github.com/spotify/backstage/tree/master/packages/storybook) -
+  This folder contains only the storybook config. Stories are within the core
+  package. The Backstage Storybook is found
+  [here](https://backstage.io/storybook)
+
+- [`techdocs-cli/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) -
+  Used for verifying TechDocs locally.
+
+- [`techdocs-container/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-container) -
+  Used by the `techdocs-cli`
+
+- [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core)
+
+- [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils)
+
+- [`theme/`](https://github.com/spotify/backstage/tree/master/packages/theme) -
+  Holds the Backstage Theme.
+
+### `plugins/`
+
+Most of the functionality of a Backstage App comes from plugins. Even core
+features can be plugins, take the
+[catalog](https://github.com/spotify/backstage/tree/master/plugins/catalog) as
+an example.
+
+We can categorize plugins into three different types; **Frontend**, **Backend**
+and **GraphQL**. We differentiate these types of plugins when we name them, with
+a dash-suffix. `-backend` means it’s a backend plugin and so on.
+
+One reason for splitting a plugin is because of to it's dependencies. Another
+reason is for clear separation of concerns.
+
+Take a look at our [Plugin Gallery](https://backstage.io/plugins) or browse
+through the
+[`plugins/`](https://github.com/spotify/backstage/tree/master/plugins) folder.
+
+## Packages outside of the monorepo
+
+For convenience we include packages in our project that are not part of our
+monorepo setup.
+
+- [`microsite/`](https://github.com/spotify/backstage/blob/master/microsite) -
+  This folder contains the source code for backstage.io. It is built with
+  [Docusaurus](https://docusaurus.io/). This folder is not part of the monorepo
+  due to dependency reasons. Look at the
+  [README](https://github.com/spotify/backstage/blob/master/microsite/README.md)
+  for instructions on how to run it locally.
+
+## Root files specifically used by the `app`
+
+These files are kept in the root of the project mostly by historical reasons.
+Some of these files may be subject to be moved out of the root sometime in the
+future.
+
+- [`.npmrc`](https://github.com/spotify/backstage/tree/master/.npmrc) - It's
+  common for companies to have their own npm registry, this files makes sure
+  that this folder use the public registry.
+
+- [`.vale.ini`](https://github.com/spotify/backstage/tree/master/.vale.ini) -
+  [Spell checker](https://github.com/errata-ai/vale) for Markdown files.
+
+- [`.yarnrc`](https://github.com/spotify/backstage/tree/master/.yarnrc) -
+  Enforces "our" version of Yarn.
+
+- [`app-config.yaml`](https://github.com/spotify/backstage/tree/master/app-config.yaml) -
+  Configuration for the app, both frontend and backend.
+
+- [`catalog-info.yaml`](https://github.com/spotify/backstage/tree/master/catalog-info.yaml) -
+  Description of Backstage in the Backstage Entity format.
+
+- [`lerna.json`](https://github.com/spotify/backstage/tree/master/lerna.json) -
+  [Lerna](https://github.com/lerna/lerna) monorepo config. We are using
+  `yarn workspaces`, so this will only be used for executing scripts.
@@ -179,7 +179,7 @@ const onSave = async () => {
 ```

 Now it's much simpler for users to change the theme tune, as they no longer need
-to go look up a track ID and edit a yaml file. Instead, they can now stay inside
+to go look up a track ID and edit a YAML file. Instead, they can now stay inside
 Backstage and search for the track and request the change from there. In
 addition, the requested change can be reviewed by the regular process of each
 organization.
@@ -239,12 +239,12 @@ hits merge.
 # 8. Attack of the Clones

 Sam just released v1.8.4 of the plugin, and at this point it's so popular that a
-couple of other plugins has started depending on the `sam.wise/spotify-track-id`
-annotation. One such plugin being the `spotify-album-art` plugin that can
-display the album art of the theme tune as the background of the entity header.
-Sam thinks it's all pretty cool, but doesn't like that the annotation that was
-once an internal concern of the plugin is now becoming a standard in the
-community.
+couple of other plugins have started depending on the
+`sam.wise/spotify-track-id` annotation. One such plugin being the
+`spotify-album-art` plugin that can display the album art of the theme tune as
+the background of the entity header. Sam thinks it's all pretty cool, but
+doesn't like that the annotation that was once an internal concern of the plugin
+is now becoming a standard in the community.

 In order to standardize the annotation in Backstage, Sam submits a Pull Request
 to the Backstage Core repo. The request suggests a new well-known metadata
@@ -7,11 +7,11 @@ title: Monorepo App Setup With Authentication

 <br />

-> This document takes you through setting up a backstage app that runs in your
+> This document takes you through setting up a Backstage app that runs in your
 > own environment. It starts with a skeleton install and verifying of the
 > monorepo's functionality. Next, GitHub authentication is added and tested.
 >
-> This document assumes you have NodeJS 12 active along with Yarn and Python.
+> This document assumes you have Node.js 12 active along with Yarn and Python.
 > Please note, that at the time of this writing, the current version is
 > 0.1.1-alpha.21. This guide can still be used with future versions, just,
 > verify as you go. If you run into issues, you can compare your setup with mine
@@ -20,7 +20,7 @@ title: Adding Custom Plugin to Existing Monorepo App
 > functionality, extend the Sidebar to make our life easy. Finally, we add
 > custom code to display GitHub repository information.
 >
-> This document assumes you have NodeJS 12 active along with Yarn and Python.
+> This document assumes you have Node.js 12 active along with Yarn and Python.
 > Please note, that at the time of this writing, the current version is
 > 0.1.1-alpha.21. This guide can still be used with future versions, just,
 > verify as you go. If you run into issues, you can compare your setup with mine
@@ -161,7 +161,7 @@ export default ExampleFetchComponent;

 # The Graph Model

-GitHub has a graphql API available for interacting. Let's start by adding our
+GitHub has a GraphQL API available for interacting. Let's start by adding our
 basic repository query

 1. Add the query const statement outside ExampleFetchComponent
@@ -0,0 +1,79 @@
+---
+title: New Cost Insights plugin: The engineer’s solution to taming cloud costs
+author: Janisa Anandamohan
+authorURL: https://twitter.com/janisa_a
+---
+
+How did Spotify save millions on cloud costs within a matter of months?? We made cost optimization just another part of the daily development process. Our newly open sourced [Cost Insights plugin](https://github.com/spotify/backstage/tree/master/plugins/cost-insights) makes a team’s cloud costs visible — and actionable — right inside Backstage. So engineers can see the impact of their cloud usage (down to a product and resource level) and make optimizations wherever and whenever it makes sense. By managing cloud costs from the ground up, you can make smarter decisions that let you continue to build and scale quickly, without wasting resources.
+
+<iframe width="780" height="440" src="https://www.youtube.com/embed/YLAd5hdXR_Q" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+Are we turning engineers into accountants? Nope, we’re just letting engineers do what they do best, in the place that feels natural to them: inside Backstage.
+
+<!--truncate-->
+
+## Why put a cost management tool in the hands of engineers?
+
+Engineers are closest to the metal in terms of knowing why a specific feature, product, or service is using cloud resources. So they’re in the best position to understand how costs impact ongoing development (and vice versa).
+
+If you manage costs top-down from a 10,000-foot view of your cloud infrastructure, you’re likely making decisions far removed from products, especially in larger organizations. Set a broad cost-cutting goal, and you could be creating unintended consequences — curtailing spending at the expense of growth or experimentation.
+
+## Ground-level intelligence, data-driven solutions
+
+Our hypothesis at Spotify was, if you bring spending data into an engineer’s everyday development workflow, they’ll naturally look for cost optimizations just like they look for any other optimization. And the cost optimizations will be more efficient and effective, because the decisions are informed at the ground level.
+
+The problem is that most cloud platforms don’t provide cost data at a granular enough level to make those decisions. And the bigger your organization (say, two-thousand-microservices and four-thousand-data-pipelines big, like Spotify), then the less you can attribute these large, fuzzy numbers to the right team, let alone a shipping product or internal service.
+
+That’s where Cost Insights comes in. Instead of making cost management and product development separate departments on the org chart, Backstage brings them together — with a level of detail and specificity engineers relate and respond to.
+
+## How to turn dollars into sense
+
+It’s not enough to make costs visible. To be useful, the numbers need to be relevant, relatable, and actionable. In other words, not just cost information, but insights. There are several ways the plugin puts data from your cloud provider in a more helpful context.
+
+### Use business metrics to evaluate costs
+
+Cost Insights will show you trends at a glance and also let you compare costs quarter over quarter. More importantly, you can also evaluate costs against business metrics that you care most about. In the example below, should the upward slope shown in the first screen be cause for worry? Perhaps not — if you switch views, you’ll see that cost per daily average user (DAU) is actually going down. Exactly what you hope to see as you scale.
+
+![Comparing costs to DAU](assets/20-10-22/cost-insights-1-dau.gif)
+_(Note: Screens are examples; they do not show real data.)_
+
+### Illustrate costs with relatable, real-world comparisons
+
+In addition to dollar amounts, Cost Insights allows teams to visualize and convert cost overages into more relatable terms. In the example below, we equate the growth in costs for virtual machine instances (100% increase) to developer time spent (about 1 engineer). We use this particular comparison in the plugin because we found it resonated with our own engineers — providing a useful perspective for spending increases. You can configure what the “cost of an engineer” means to your organization. Or engineers can build in their own comparisons — cups of coffee, carbon offset credits, electric luxury vehicles — whatever makes costs more tangible for them.
+
+![Cost growth as engineering time](assets/20-10-22/cost-insights-2-engineer.png)
+_(Note: Screens are examples; they do not show real data.)_
+
+### Tie spending to specific products and resources
+
+The more detailed the cost data, the more relevant, actionable, and helpful it is. Cost Insights allows you to attribute costs to products and resources in a way that makes sense to your engineers. For example, here we see a breakdown of data processing costs by individual pipelines. This allows your team to target optimizations more precisely.
+
+![Data Processing costs by pipeline](assets/20-10-22/cost-insights-3-data.png)
+_(Note: Screens are examples; they do not show real data.)_
+
+## Driving down costs without slowing down development
+
+When it comes to cutting costs, we actually want to guard against over-optimization. Growth and costs can go hand in hand. The trick is knowing when one is out of balance and needs addressing. Our product highlights when there’s been a large increase in spending, so that engineers are thinking about cost only when they must and aren’t distracted from their set goals and priorities.
+
+Engineers can then determine for themselves if the time invested in an optimization was valuable compared to the costs saved. Cost Insights puts the decision in our engineers’ hands for them to choose when to focus on growth efforts and when to focus on cost. Control, as ever, remains with our developers, where we think it belongs.
+
+## Getting started
+
+You can begin working with the Cost Insights plugin today on [GitHub](https://github.com/spotify/backstage/tree/master/plugins/cost-insights). We include an example client with static data in the expected format. The `CostInsightsApi` should talk with a cloud billing backend that aggregates billing data from your cloud provider.
+
+The current release of Cost Insights includes:
+
+- Daily cost graph by team or billing account
+- Cost comparisons against configurable business metrics (including an option for Daily Active Users)
+- Insights panels — configurable for the cloud products your company uses
+- Cost alerts and recommendations
+- Selectable time periods for month-over-month or quarter-over-quarter comparisons
+- Conversion of cost growth into “cost of average engineer” to help optimization trade-off decisions
+
+Our hope is to help other companies translate their cloud cost in a relatable way for their engineers to better understand their impact and accurately identify their opportunities for optimizations.
+
+And if you’re interested in contributing to our outstanding issues, you can find them in the issues queue, filtered under the [‘cost-insights’ label](https://github.com/spotify/backstage/labels/cost-insights).
+
+## Ready for DevSecCostOpsPlus (and whatever’s next)
+
+There’s DevOps, there’s DevSecOps, and then there’s Backstage: one frontend for all your infrastructure. From building, testing, and deploying to monitoring and security — Backstage helps you manage your entire tech organization and provides a seamless developer experience for engineers, from end to end to end. And now that also extends to cost management for your cloud infrastructure and tooling. Happy building and [happy optimizing](https://github.com/spotify/backstage/tree/master/plugins/cost-insights).
@@ -0,0 +1,9 @@
+---
+title: AWS Lambda
+author: roadie.io
+authorUrl: https://roadie.io
+category: Monitoring
+description: View AWS Lambda functions for your components in Backstage.
+documentation: https://roadie.io/backstage/plugins/aws-lambda
+iconUrl: https://roadie.io/static/77f62f79e27ae8565496e4df7eef8be5/45f2b/logo.png
+npmPackageName: '@roadiehq/backstage-plugin-aws-lambda'
@@ -0,0 +1,9 @@
+---
+title: Security Insights
+author: roadie.io
+authorUrl: https://roadie.io/
+category: Security
+description: View Security Insights for your components in Backstage.
+documentation: https://roadie.io/backstage/plugins/security-insights
+iconUrl: https://roadie.io/static/7f13bb8d861d8dedc5112fb939d215f9/351f2/GitHub-Mark-Light-120px-plus.png
+npmPackageName: '@roadiehq/backstage-plugin-security-insights'
@@ -15,7 +15,7 @@
  },
  "devDependencies": {
    "@spotify/prettier-config": "^8.0.0",
-    "docusaurus": "^2.0.0-alpha.65",
+    "docusaurus": "^2.0.0-alpha.66",
    "js-yaml": "^3.14.0",
    "prettier": "^2.0.5"
  },
@@ -78,7 +78,41 @@ const Background = props => {
        </Block.Container>
      </Block>

-      <Block className="stripe-bottom bg-black-grey">
+      <Block className="stripe bg-black-grey">
+        <Block.Container style={{ justifyContent: 'flex-start' }}>
+          <Block.TextBox>
+            <Block.Title>Control cloud costs</Block.Title>
+            <Block.Paragraph>
+              How do you control cloud costs while maintaining the speed and
+              independence of your development teams? With the{' '}
+              <a href="https://backstage.io/plugins">Cost Insights plugin</a>{' '}
+              for Backstage, managing cloud costs becomes just another part of
+              an engineer’s daily development process. They get a clear view of
+              their spending — and can decide for themselves how they want to
+              optimize it. Learn more about the{' '}
+              <a href="https://backstage.io/blog/2020/10/22/cost-insights-plugin">
+                Cost Insights plugin
+              </a>
+              .
+            </Block.Paragraph>
+            <Block.LinkButton href="https://youtu.be/YLAd5hdXR_Q">
+              Watch now
+            </Block.LinkButton>
+          </Block.TextBox>
+          <Block.MediaFrame>
+            <iframe
+              width="560"
+              height="315"
+              src="https://www.youtube.com/embed/YLAd5hdXR_Q"
+              frameborder="0"
+              allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
+              allowfullscreen
+            ></iframe>
+          </Block.MediaFrame>
+        </Block.Container>
+      </Block>
+
+      <Block className="stripe bg-black">
        <Block.Container style={{ justifyContent: 'flex-start' }}>
          <Block.TextBox>
            <Block.Title id="techdocs-demo">
@@ -96,7 +130,7 @@ const Background = props => {
              </a>
              .
            </Block.Paragraph>
-            <Block.LinkButton href={'https://youtu.be/mOLCgdPw1iA'}>
+            <Block.LinkButton href="https://youtu.be/mOLCgdPw1iA">
              Watch now
            </Block.LinkButton>
          </Block.TextBox>
@@ -16,9 +16,8 @@ const {
 const pluginsDirectory = require('path').join(process.cwd(), 'data/plugins');
 const pluginMetadata = fs
  .readdirSync(pluginsDirectory)
-  .map(file =>
-    yaml.safeLoad(fs.readFileSync(`./data/plugins/${file}`, 'utf8')),
-  );
+  .map(file => yaml.safeLoad(fs.readFileSync(`./data/plugins/${file}`, 'utf8')))
+  .sort((a, b) => a.title.toLowerCase().localeCompare(b.title.toLowerCase()));
 const truncate = text =>
  text.length > 170 ? text.substr(0, 170) + '...' : text;

@@ -44,7 +43,7 @@ const Plugins = () => (
        </span>
      </div>
      <BulletLine style={{ width: '100% ' }} />
-      <Container wrapped className="grid">
+      <Container wrapped className="PluginGrid">
        {pluginMetadata.map(
          ({
            iconUrl,
@@ -57,26 +56,25 @@ const Plugins = () => (
          }) => (
            <div className="PluginCard">
              <div className="PluginCardHeader">
-                <img src={iconUrl || defaultIconUrl} alt={title} />
-                <h2 className="PluginCardTitle">{title}</h2>
-                <p className="Author">
-                  by <a href={authorUrl}>{author}</a>
-                </p>
-                <span className="ChipOutlined">{category}</span>
+                <div className="PluginCardImage">
+                  <img src={iconUrl || defaultIconUrl} alt={title} />
+                </div>
+                <div className="PluginCardInfo">
+                  <h3 className="PluginCardTitle">{title}</h3>
+                  <p className="PluginCardAuthor">
+                    by <a href={authorUrl}>{author}</a>
+                  </p>
+                  <span className="PluginCardChipOutlined">{category}</span>
+                </div>
              </div>
              <div className="PluginCardBody">
                <p>{truncate(description)}</p>
              </div>
-              <Container className="PluginCardFooter">
-                <span>
-                  <a
-                    className="PluginCardLink ButtonFilled"
-                    href={documentation}
-                  >
-                    Explore
-                  </a>
-                </span>
-              </Container>
+              <div className="PluginCardFooter">
+                <a className="ButtonFilled" href={documentation}>
+                  Explore
+                </a>
+              </div>
            </div>
          ),
        )}
@@ -28,6 +28,7 @@
        "label": "Deployment",
        "ids": [
          "getting-started/deployment-k8s",
+          "getting-started/deployment-helm",
          "getting-started/deployment-other"
        ]
      }
@@ -163,7 +164,7 @@
      "architecture-decisions/adrs-adr009"
    ],
    "Contribute": ["../CONTRIBUTING"],
-    "Support": ["overview/support"],
+    "Support": ["support/support", "support/project-structure"],
    "FAQ": ["FAQ"]
  }
 }
@@ -60,7 +60,7 @@ const siteConfig = {
  /* path to images for header/footer */
  // headerIcon: "img/android-chrome-192x192.png",
  footerIcon: 'img/android-chrome-192x192.png',
-  favicon: 'img/favicon.svg',
+  favicon: 'img/favicon.ico',

  /* Colors for website */
  colors: {
--- a/Show More
+++ b/Show More