diff --git a/.changeset/breezy-carrots-hunt.md b/.changeset/breezy-carrots-hunt.md
new file mode 100644
index 0000000000..0075009a2d
--- /dev/null
+++ b/.changeset/breezy-carrots-hunt.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-explore': patch
+---
+
+Add "Organization" tab with a diagram
diff --git a/.changeset/calm-insects-melt.md b/.changeset/calm-insects-melt.md
new file mode 100644
index 0000000000..4b17764c33
--- /dev/null
+++ b/.changeset/calm-insects-melt.md
@@ -0,0 +1,7 @@
+---
+'@backstage/cli': patch
+'@backstage/create-app': patch
+'@backstage/plugin-catalog-graphql': patch
+---
+
+chore: bump `ts-node` versions to 9.1.1
diff --git a/.changeset/cyan-beans-marry.md b/.changeset/cyan-beans-marry.md
new file mode 100644
index 0000000000..99d7ad47ce
--- /dev/null
+++ b/.changeset/cyan-beans-marry.md
@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-model': patch
+---
+
+Renamed parameters to input in template schema
diff --git a/.changeset/dry-elephants-doubt.md b/.changeset/dry-elephants-doubt.md
deleted file mode 100644
index 7a9ccc9892..0000000000
--- a/.changeset/dry-elephants-doubt.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/plugin-github-deployments': patch
----
-
-Adds extraColumns field to GitHub Deployments card
diff --git a/.changeset/fair-carrots-tell.md b/.changeset/fair-carrots-tell.md
deleted file mode 100644
index 62dce5c3ce..0000000000
--- a/.changeset/fair-carrots-tell.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/cli': patch
----
-
-Add `config:docs` command that opens up reference documentation for the local configuration schema in a browser.
diff --git a/.changeset/fluffy-suns-repair.md b/.changeset/fluffy-suns-repair.md
deleted file mode 100644
index 6f45905219..0000000000
--- a/.changeset/fluffy-suns-repair.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/plugin-scaffolder': patch
----
-
-Respect top-level UI schema keys in scaffolder forms. Allows more advanced RJSF features such as explicit field ordering.
diff --git a/.changeset/fresh-cheetahs-rush.md b/.changeset/fresh-cheetahs-rush.md
deleted file mode 100644
index fe8a9caafb..0000000000
--- a/.changeset/fresh-cheetahs-rush.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/cli': patch
----
-
-No longer add newly created plugins to `plugins.ts` in the app, as it is no longer needed.
diff --git a/.changeset/good-glasses-build.md b/.changeset/good-glasses-build.md
deleted file mode 100644
index 3d506d3e43..0000000000
--- a/.changeset/good-glasses-build.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-'@backstage/core-api': patch
-'@backstage/core': patch
----
-
-Add support for discovering plugins through the app element tree, removing the need to register them explicitly.
diff --git a/.changeset/grumpy-goats-refuse.md b/.changeset/grumpy-goats-refuse.md
new file mode 100644
index 0000000000..8dc2e390fc
--- /dev/null
+++ b/.changeset/grumpy-goats-refuse.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder': patch
+---
+
+Show error on task page if task does not exist.
diff --git a/.changeset/moody-pigs-repeat.md b/.changeset/moody-pigs-repeat.md
deleted file mode 100644
index 396fa80281..0000000000
--- a/.changeset/moody-pigs-repeat.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/core': patch
----
-
-Exported SignInProviderConfig to strongly type SignInPage providers
diff --git a/.changeset/ninety-pots-guess.md b/.changeset/ninety-pots-guess.md
new file mode 100644
index 0000000000..4b9a770c29
--- /dev/null
+++ b/.changeset/ninety-pots-guess.md
@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+update plugins created to use react-use 17.2.4
diff --git a/.changeset/quiet-badgers-cheer.md b/.changeset/quiet-badgers-cheer.md
deleted file mode 100644
index e22bf9492c..0000000000
--- a/.changeset/quiet-badgers-cheer.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-'@backstage/create-app': patch
----
-
-Removed `plugins.ts` from the app, as plugins are now discovered through the react tree.
-
-To apply this change to an existing app, simply delete `packages/app/src/plugins.ts` along with the import and usage in `packages/app/src/App.tsx`.
-
-Note that there are a few plugins that require explicit registration, in which case you would need to keep them in `plugins.ts`. The set of plugins that need explicit registration is any plugin that doesn't have a component extension that gets rendered as part of the app element tree. An example of such a plugin in the main Backstage repo is `@backstage/plugin-badges`. In the case of the badges plugin this is because there is not yet a component-based API for adding context menu items to the entity layout.
-
-If you have plugins that still rely on route registration through the `register` method of `createPlugin`, these need to be kept in `plugins.ts` as well. However, it is recommended to migrate these to export an extensions component instead.
diff --git a/.changeset/real-apples-visit.md b/.changeset/real-apples-visit.md
deleted file mode 100644
index b5165f633b..0000000000
--- a/.changeset/real-apples-visit.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/plugin-catalog-backend': patch
----
-
-GithubDiscoveryProcessor now excludes archived repositories so they won't be added to Backstage.
diff --git a/.changeset/rude-items-bow.md b/.changeset/rude-items-bow.md
deleted file mode 100644
index 69b76d821e..0000000000
--- a/.changeset/rude-items-bow.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/plugin-kubernetes-backend': patch
----
-
-Kubernetes client TLS verification is now configurable and defaults to true
diff --git a/.changeset/short-bobcats-mate.md b/.changeset/short-bobcats-mate.md
new file mode 100644
index 0000000000..d63e7058a9
--- /dev/null
+++ b/.changeset/short-bobcats-mate.md
@@ -0,0 +1,7 @@
+---
+'@backstage/core': patch
+'@backstage/plugin-api-docs': patch
+---
+
+Fix state persisted in the URL make search input in the table toolbar lose their
+focus.
diff --git a/.changeset/six-turtles-sip.md b/.changeset/six-turtles-sip.md
deleted file mode 100644
index e71b04e64d..0000000000
--- a/.changeset/six-turtles-sip.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-'@backstage/backend-common': patch
----
-
-Support configuration of file storage for SQLite databases. Every plugin has its
-own database file at the specified path.
diff --git a/.changeset/sour-plums-enjoy.md b/.changeset/sour-plums-enjoy.md
deleted file mode 100644
index ef68166255..0000000000
--- a/.changeset/sour-plums-enjoy.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-'@backstage/create-app': patch
----
-
-Fix system diagram card to be on the system page
-
-To apply the same fix to an existing application, in `EntityPage.tsx` simply move the `` for the `/diagram` path from the `groupPage` down into the `systemPage` element.
diff --git a/.changeset/stale-carpets-poke.md b/.changeset/stale-carpets-poke.md
deleted file mode 100644
index 4f39e57b71..0000000000
--- a/.changeset/stale-carpets-poke.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-'@backstage/plugin-catalog-backend': patch
----
-
-Externalize repository processing for BitbucketDiscoveryProcessor.
-
-Add an extension point where you can customize how a matched Bitbucket repository should
-be processed. This can for example be used if you want to generate the catalog-info.yaml
-automatically based on other files in a repository, while taking advantage of the
-build-in repository crawling functionality.
-
-`BitbucketDiscoveryProcessor.fromConfig` now takes an optional parameter `options.parser` where
-you can customize the logic for each repository found. The default parser has the same
-behaviour as before, where it emits an optional location for the matched repository
-and lets the other processors take care of further processing.
-
-```typescript
-const customRepositoryParser: BitbucketRepositoryParser = async function* customRepositoryParser({
- client,
- repository,
-}) {
- // Custom logic for interpret the matching repository.
- // See defaultRepositoryParser for an example
-};
-
-const processor = BitbucketDiscoveryProcessor.fromConfig(env.config, {
- parser: customRepositoryParser,
- logger: env.logger,
-});
-```
diff --git a/.changeset/stale-chefs-retire.md b/.changeset/stale-chefs-retire.md
deleted file mode 100644
index e43c20062a..0000000000
--- a/.changeset/stale-chefs-retire.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/core': patch
----
-
-Adding close button on support menu
diff --git a/.changeset/techdocs-swift-mugs-invent.md b/.changeset/techdocs-swift-mugs-invent.md
deleted file mode 100644
index 912089fb3c..0000000000
--- a/.changeset/techdocs-swift-mugs-invent.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@backstage/plugin-techdocs': patch
----
-
-Add a test id to the shadow root element of the Reader to access it easily in e2e tests
diff --git a/.changeset/ten-paws-ring.md b/.changeset/ten-paws-ring.md
new file mode 100644
index 0000000000..8ed2158f6c
--- /dev/null
+++ b/.changeset/ten-paws-ring.md
@@ -0,0 +1,44 @@
+---
+'@backstage/core': patch
+'@backstage/core-api': patch
+'@backstage/integration-react': patch
+'@backstage/plugin-api-docs': patch
+'@backstage/plugin-badges': patch
+'@backstage/plugin-bitrise': patch
+'@backstage/plugin-catalog': patch
+'@backstage/plugin-catalog-import': patch
+'@backstage/plugin-catalog-react': patch
+'@backstage/plugin-circleci': patch
+'@backstage/plugin-cloudbuild': patch
+'@backstage/plugin-code-coverage': patch
+'@backstage/plugin-config-schema': patch
+'@backstage/plugin-cost-insights': patch
+'@backstage/plugin-explore': patch
+'@backstage/plugin-fossa': patch
+'@backstage/plugin-gcp-projects': patch
+'@backstage/plugin-github-actions': patch
+'@backstage/plugin-github-deployments': patch
+'@backstage/plugin-gitops-profiles': patch
+'@backstage/plugin-graphiql': patch
+'@backstage/plugin-jenkins': patch
+'@backstage/plugin-kafka': patch
+'@backstage/plugin-kubernetes': patch
+'@backstage/plugin-lighthouse': patch
+'@backstage/plugin-newrelic': patch
+'@backstage/plugin-org': patch
+'@backstage/plugin-pagerduty': patch
+'@backstage/plugin-register-component': patch
+'@backstage/plugin-rollbar': patch
+'@backstage/plugin-scaffolder': patch
+'@backstage/plugin-search': patch
+'@backstage/plugin-sentry': patch
+'@backstage/plugin-sonarqube': patch
+'@backstage/plugin-splunk-on-call': patch
+'@backstage/plugin-tech-radar': patch
+'@backstage/plugin-techdocs': patch
+'@backstage/plugin-todo': patch
+'@backstage/plugin-user-settings': patch
+'@backstage/plugin-welcome': patch
+---
+
+chore: bump `react-use` dependency in all packages
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 4e21603c63..b07519824b 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -8,12 +8,16 @@
/docs/features/techdocs @backstage/techdocs-core
/docs/features/search @backstage/techdocs-core
/docs/assets/search @backstage/techdocs-core
+/plugins/code-coverage @alde @nissayeva
+/plugins/code-coverage-backend @alde @nissayeva
/plugins/cost-insights @backstage/silver-lining
/plugins/cloudbuild @trivago/ebarrios
/plugins/search @backstage/techdocs-core
/plugins/search-* @backstage/techdocs-core
/plugins/techdocs @backstage/techdocs-core
/plugins/techdocs-backend @backstage/techdocs-core
+/packages/search-common @backstage/techdocs-core
/packages/techdocs-common @backstage/techdocs-core
/.changeset/cost-insights-* @backstage/silver-lining
+/.changeset/search-* @backstage/techdocs-core
/.changeset/techdocs-* @backstage/techdocs-core
diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt
index 226af9bf0a..694226b8cc 100644
--- a/.github/styles/vocab.txt
+++ b/.github/styles/vocab.txt
@@ -10,16 +10,20 @@ Chai
Changesets
Chanwit
Cloudformation
+Cobertura
Codecov
Codehilite
Config
+Datadog
Debounce
Discoverability
Dockerfile
+dockerfiles
Dockerize
Docusaurus
Env
Expedia
+Fargate
Figma
Firekube
Fiverr
@@ -31,13 +35,16 @@ Hackathons
Heroku
Hostname
Iain
+JaCoCo
JavaScript
Kaewkasi
Knex
Leasot
Lerna
+LocalStack
Luxon
Minikube
+Minio
Mkdocs
Monorepo
Namespaces
@@ -75,6 +82,7 @@ Tolerations
WWW
Weaveworks
Webpack
+XML
Zalando
Zhou
abc
diff --git a/.github/workflows/chromatic-storybook-test.yml b/.github/workflows/chromatic-storybook-test.yml
index bb14e1c38b..89df848c76 100644
--- a/.github/workflows/chromatic-storybook-test.yml
+++ b/.github/workflows/chromatic-storybook-test.yml
@@ -48,5 +48,7 @@ jobs:
- uses: chromaui/action@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
+ # projetToken intentionally shared to allow collaborators to run Chromatic on forks
+ # https://www.chromatic.com/docs/custom-ci-provider#run-chromatic-on-external-forks-of-open-source-projects
projectToken: 9tzak77m9nj
storybookBuildDir: 'packages/storybook/dist'
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2337a70e2c..0a6d0f8589 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -85,6 +85,9 @@ jobs:
- name: type checking and declarations
run: yarn tsc:full
+ - name: check api reports
+ run: yarn build:api-reports:only --ci
+
- name: build changed packages
if: ${{ steps.yarn-lock.outcome == 'success' }}
run: yarn lerna -- run build --since origin/master --include-dependencies
diff --git a/.prettierignore b/.prettierignore
index c4e675a5d7..e60d54a466 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -4,6 +4,7 @@ microsite
coverage
*.hbs
templates
+api-report.md
plugins/scaffolder-backend/sample-templates
.vscode
dist-types
diff --git a/app-config.yaml b/app-config.yaml
index afbda40852..3c4f2d7ea5 100644
--- a/app-config.yaml
+++ b/app-config.yaml
@@ -2,6 +2,12 @@ app:
title: Backstage Example App
baseUrl: http://localhost:3000
googleAnalyticsTrackingId: # UA-000000-0
+ #datadogRum:
+ # clientToken: '123456789'
+ # applicationId: qwerty
+ # site: # datadoghq.eu default = datadoghq.com
+ # env: # optional
+
support:
url: https://github.com/backstage/backstage/issues # Used by common ErrorPage
items: # Used by common SupportButton component
diff --git a/contrib/chart/backstage/README.md b/contrib/chart/backstage/README.md
index 7d04a2cf1e..40bb2666bc 100644
--- a/contrib/chart/backstage/README.md
+++ b/contrib/chart/backstage/README.md
@@ -129,6 +129,16 @@ For the CA, create a `configMap` named `--postgres-ca`
kubectl create configmap my-company-backstage-postgres-ca --from-file=ca.crt"
```
+or disable CA mount
+
+```yaml
+backend:
+ postgresCertMountEnabled: false
+
+lighthouse:
+ postgresCertMountEnabled: false
+```
+
> Where the release name contains the chart name "backstage" then only the release name will be used.
Now install the helm chart:
diff --git a/contrib/chart/backstage/templates/_helpers.tpl b/contrib/chart/backstage/templates/_helpers.tpl
index 5d49ba6975..123d4dba5b 100644
--- a/contrib/chart/backstage/templates/_helpers.tpl
+++ b/contrib/chart/backstage/templates/_helpers.tpl
@@ -214,7 +214,7 @@ Postgres port for the backend
{{- .Values.postgresql.service.port }}
{{- else if .Values.appConfig.backend.database.connection.port -}}
{{- .Values.appConfig.backend.database.connection.port }}
-{{ else }}
+{{- else -}}
5432
{{- end -}}
{{- end -}}
diff --git a/contrib/chart/backstage/templates/backend-deployment.yaml b/contrib/chart/backstage/templates/backend-deployment.yaml
index 144fc93e62..0fa6b7fbe2 100644
--- a/contrib/chart/backstage/templates/backend-deployment.yaml
+++ b/contrib/chart/backstage/templates/backend-deployment.yaml
@@ -26,6 +26,13 @@ spec:
{{- end}}
containers:
- name: {{ .Chart.Name }}-backend
+ command: ["node"]
+ args:
+ - "packages/backend"
+ - "--config"
+ - "app-config.yaml"
+ - "--config"
+ - {{ printf "/usr/src/app/%s" (include "backstage.appConfigFilename" .) | quote }}
image: {{ .Values.backend.image.repository }}:{{ .Values.backend.image.tag }}
imagePullPolicy: {{ .Values.backend.image.pullPolicy }}
ports:
@@ -49,16 +56,20 @@ spec:
name: {{ include "backend.postgresql.passwordSecret" .}}
key: postgresql-password
volumeMounts:
+ {{- if .Values.backend.postgresCertMountEnabled }}
- name: postgres-ca
mountPath: {{ include "backstage.backend.postgresCaDir" . }}
+ {{- end }}
- name: app-config
mountPath: {{ printf "/usr/src/app/%s" (include "backstage.appConfigFilename" .) }}
subPath: {{ include "backstage.appConfigFilename" . }}
volumes:
+ {{- if .Values.backend.postgresCertMountEnabled }}
- name: postgres-ca
configMap:
name: {{ include "backstage.fullname" . }}-postgres-ca
+ {{- end }}
- name: app-config
configMap:
name: {{ include "backstage.fullname" . }}-app-config
@@ -83,5 +94,5 @@ spec:
app: backstage
component: backend
- type: ClusterIP
+ type: {{ .Values.backend.serviceType }}
{{- end }}
diff --git a/contrib/chart/backstage/templates/frontend-deployment.yaml b/contrib/chart/backstage/templates/frontend-deployment.yaml
index 9c674cc160..04983513a6 100644
--- a/contrib/chart/backstage/templates/frontend-deployment.yaml
+++ b/contrib/chart/backstage/templates/frontend-deployment.yaml
@@ -1,3 +1,4 @@
+{{- if .Values.frontend.enabled }}
apiVersion: apps/v1
kind: Deployment
metadata:
@@ -46,7 +47,6 @@ spec:
{{- if .Values.global.nodeSelector }}
nodeSelector: {{- toYaml .Values.global.nodeSelector | nindent 8 }}
{{- end }}
-{{- if .Values.frontend.enabled }}
---
apiVersion: v1
kind: Service
@@ -62,5 +62,5 @@ spec:
app: backstage
component: frontend
- type: ClusterIP
+ type: {{ .Values.frontend.serviceType }}
{{- end }}
diff --git a/contrib/chart/backstage/templates/lighthouse-config.yaml b/contrib/chart/backstage/templates/lighthouse-config.yaml
index fdf4bd8b06..7b8cad42dc 100644
--- a/contrib/chart/backstage/templates/lighthouse-config.yaml
+++ b/contrib/chart/backstage/templates/lighthouse-config.yaml
@@ -1,3 +1,4 @@
+{{- if .Values.lighthouse.enabled }}
apiVersion: v1
kind: ConfigMap
metadata:
@@ -7,4 +8,5 @@ data:
PGUSER: {{ include "lighthouse.postgresql.user" . | quote }}
PGPORT: {{ include "lighthouse.postgresql.port" . | quote }}
PGHOST: {{ include "lighthouse.postgresql.host" . | quote }}
- PGPATH_TO_CA: {{ include "backstage.lighthouse.postgresCaFilename" . | quote }}
\ No newline at end of file
+ PGPATH_TO_CA: {{ include "backstage.lighthouse.postgresCaFilename" . | quote }}
+{{- end }}
\ No newline at end of file
diff --git a/contrib/chart/backstage/templates/lighthouse-deployment.yaml b/contrib/chart/backstage/templates/lighthouse-deployment.yaml
index d6e1ce19dd..849c48d7a6 100644
--- a/contrib/chart/backstage/templates/lighthouse-deployment.yaml
+++ b/contrib/chart/backstage/templates/lighthouse-deployment.yaml
@@ -51,14 +51,18 @@ spec:
name: {{ include "lighthouse.postgresql.passwordSecret" . }}
key: postgresql-password
+ {{- if .Values.lighthouse.postgresCertMountEnabled }}
volumeMounts:
- name: postgres-ca
mountPath: {{ include "backstage.lighthouse.postgresCaDir" . }}
+ {{- end }}
+ {{- if .Values.lighthouse.postgresCertMountEnabled }}
volumes:
- name: postgres-ca
configMap:
name: {{ include "backstage.fullname" . }}-postgres-ca
+ {{- end }}
{{- if .Values.global.nodeSelector }}
nodeSelector: {{- toYaml .Values.global.nodeSelector | nindent 8 }}
@@ -78,5 +82,5 @@ spec:
app: backstage
component: lighthouse-audit-service
- type: ClusterIP
+ type: {{ .Values.lighthouse.serviceType }}
{{- end }}
diff --git a/contrib/chart/backstage/templates/postgresql-password-backend-secret.yaml b/contrib/chart/backstage/templates/postgresql-password-backend-secret.yaml
new file mode 100644
index 0000000000..a71cef7b21
--- /dev/null
+++ b/contrib/chart/backstage/templates/postgresql-password-backend-secret.yaml
@@ -0,0 +1,15 @@
+{{- if not .Values.postgresql.enabled }}
+---
+apiVersion: v1
+kind: Secret
+type: Opaque
+metadata:
+ name: {{ include "backend.postgresql.passwordSecret" . }}
+ labels:
+ release: {{ .Release.Name }}
+ annotations:
+ "helm.sh/hook": "pre-install,pre-upgrade"
+ "helm.sh/hook-delete-policy": "before-hook-creation"
+data:
+ postgresql-password: {{ .Values.appConfig.backend.database.connection.password | b64enc }}
+{{- end }}
diff --git a/contrib/chart/backstage/templates/postgresql-password-secret.yaml b/contrib/chart/backstage/templates/postgresql-password-lighthouse-secret.yaml
similarity index 51%
rename from contrib/chart/backstage/templates/postgresql-password-secret.yaml
rename to contrib/chart/backstage/templates/postgresql-password-lighthouse-secret.yaml
index e53369adb9..e7374e70db 100644
--- a/contrib/chart/backstage/templates/postgresql-password-secret.yaml
+++ b/contrib/chart/backstage/templates/postgresql-password-lighthouse-secret.yaml
@@ -1,18 +1,4 @@
-{{- if not .Values.postgresql.enabled }}
----
-apiVersion: v1
-kind: Secret
-type: Opaque
-metadata:
- name: {{ include "backend.postgresql.passwordSecret" . }}
- labels:
- release: {{ .Release.Name }}
- annotations:
- "helm.sh/hook": "pre-install,pre-upgrade"
- "helm.sh/hook-delete-policy": "before-hook-creation"
-data:
- postgresql-password: {{ .Values.appConfig.backend.database.connection.password | b64enc }}
-{{- end }}
+{{- if .Values.lighthouse.enabled }}
{{- if not .Values.postgresql.enabled }}
---
apiVersion: v1
@@ -28,3 +14,4 @@ metadata:
data:
postgresql-password: {{ .Values.lighthouse.database.connection.password | b64enc }}
{{- end }}
+{{- end }}
diff --git a/contrib/chart/backstage/values.yaml b/contrib/chart/backstage/values.yaml
index bd80bc22b6..9f70dac6dc 100644
--- a/contrib/chart/backstage/values.yaml
+++ b/contrib/chart/backstage/values.yaml
@@ -3,13 +3,14 @@
# Declare variables to be passed into your templates.
frontend:
- enabled: true
+ enabled: false
replicaCount: 1
image:
repository: martinaif/backstage-k8s-demo-frontend
tag: test1
pullPolicy: IfNotPresent
containerPort: 80
+ serviceType: ClusterIP
resources:
requests:
memory: 128Mi
@@ -23,9 +24,11 @@ backend:
replicaCount: 1
image:
repository: martinaif/backstage-k8s-demo-backend
- tag: test1
+ tag: 20210423T1550
pullPolicy: IfNotPresent
containerPort: 7000
+ serviceType: ClusterIP
+ postgresCertMountEnabled: true
resources:
requests:
memory: 512Mi
@@ -40,6 +43,8 @@ lighthouse:
tag: latest
pullPolicy: IfNotPresent
containerPort: 3003
+ serviceType: ClusterIP
+ postgresCertMountEnabled: true
resources:
requests:
memory: 128Mi
diff --git a/contrib/docker/frontend-with-nginx/Dockerfile b/contrib/docker/frontend-with-nginx/Dockerfile
deleted file mode 100644
index a444c9de83..0000000000
--- a/contrib/docker/frontend-with-nginx/Dockerfile
+++ /dev/null
@@ -1,18 +0,0 @@
-FROM nginx:mainline
-
-# The purpose of this image is to serve the frontend app content separately.
-# By default the Backstage backend uses the app-backend plugin to serve the
-# app from the backend itself, but it may be desirable to move the frontend
-# content serving to a separate deployment, in which case this image can be used.
-
-# This dockerfile requires the app to be built on the host first, as it
-# simply copies in the build output into the image.
-
-RUN apt-get update && apt-get -y install jq && rm -rf /var/lib/apt/lists/*
-
-COPY packages/app/dist /usr/share/nginx/html
-COPY docker/default.conf.template /etc/nginx/conf.d/default.conf.template
-COPY docker/run.sh /usr/local/bin/run.sh
-CMD run.sh
-
-ENV PORT 80
diff --git a/contrib/docker/frontend-with-nginx/Dockerfile.dockerbuild b/contrib/docker/frontend-with-nginx/Dockerfile.dockerbuild
new file mode 100644
index 0000000000..41f931544f
--- /dev/null
+++ b/contrib/docker/frontend-with-nginx/Dockerfile.dockerbuild
@@ -0,0 +1,58 @@
+# The purpose of this image is to serve the frontend app content separately.
+# By default the Backstage backend uses the app-backend plugin to serve the
+# app from the backend itself, but it may be desirable to move the frontend
+# content serving to a separate deployment, in which case this image can be
+# used.
+
+# This dockerfile also performs the build first inside docker. This may come
+# with a build time impact, but is sometimes desirable. If you want to run the
+# build on the host instead, use the file simply named Dockerfile in this folder
+# instead.
+
+# USAGE:
+#
+# - Copy this file and the "docker" folder from this directory to your project
+# root
+#
+# - Update your .dockerignore, make sure that the source folders are not
+# excluded, but do exclude node_modules and build artifacts:
+#
+# .git
+# node_modules
+# packages/*/dist
+# packages/*/node_modules
+# plugins/*/dist
+# plugins/*/node_modules
+#
+# - Update the copy of this file to add configuration arguments to the "build"
+# command, for example:
+#
+# RUN yarn workspace app build --config --config ...
+#
+# - In your project root, run:
+#
+# docker build -t backstage-frontend -f Dockerfile.dockerbuild .
+
+
+
+FROM node:14-buster AS build
+
+RUN mkdir /app
+COPY . /app
+WORKDIR /app
+
+RUN yarn install
+RUN yarn workspace app build
+
+
+
+FROM nginx:mainline
+
+RUN apt-get update && apt-get -y install jq && rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /app/packages/app/dist /usr/share/nginx/html
+COPY docker/default.conf.template /etc/nginx/templates/default.conf.template
+
+COPY docker/inject-config.sh /docker-entrypoint.d/40-inject-config.sh
+
+ENV PORT 80
diff --git a/contrib/docker/frontend-with-nginx/Dockerfile.hostbuild b/contrib/docker/frontend-with-nginx/Dockerfile.hostbuild
new file mode 100644
index 0000000000..1e0134017f
--- /dev/null
+++ b/contrib/docker/frontend-with-nginx/Dockerfile.hostbuild
@@ -0,0 +1,41 @@
+# The purpose of this image is to serve the frontend app content separately.
+# By default the Backstage backend uses the app-backend plugin to serve the
+# app from the backend itself, but it may be desirable to move the frontend
+# content serving to a separate deployment, in which case this image can be
+# used.
+
+# This dockerfile requires the app to be built on the host first, as it
+# simply copies in the build output into the image. If you want to also perform
+# the build itself inside docker, use Dockerfile.build in this folder instead.
+
+
+# USAGE:
+#
+# - Copy this file and the "docker" folder from this directory to your project
+# root
+#
+# - Add the following line to your .dockerignore to make sure that the built
+# frontend actually can be transferred into the docker image:
+#
+# !packages/app/dist
+#
+# - In your project root, run:
+#
+# yarn install
+# yarn tsc
+# yarn build --config --config ...
+# docker build -t backstage-frontend -f Dockerfile.hostbuild .
+
+
+
+FROM nginx:mainline
+
+RUN apt-get update && apt-get -y install jq && rm -rf /var/lib/apt/lists/*
+
+COPY packages/app/dist /usr/share/nginx/html
+COPY docker/default.conf.template /etc/nginx/templates/default.conf.template
+
+COPY docker/inject-config.sh /docker-entrypoint.d/40-inject-config.sh
+
+ENV PORT 80
+
diff --git a/contrib/docker/frontend-with-nginx/README.md b/contrib/docker/frontend-with-nginx/README.md
new file mode 100644
index 0000000000..eae70b8bba
--- /dev/null
+++ b/contrib/docker/frontend-with-nginx/README.md
@@ -0,0 +1,16 @@
+# Frontend with NGINX
+
+This folder contains Docker images that let you run the Backstage frontend as
+a separate image, rather than having it served through the `app-backend` plugin
+from the backend.
+
+Note that when running the frontend like this, the app configuration becomes
+embedded into the actual static JavaScript files at build time. This means that
+you will have to supply the list of configuration files as part of the command
+line at build.
+
+## Usage
+
+There are two variants: one that builds inside Docker, and one that builds on
+the host. See the comments at the top of the individual dockerfiles for usage
+instructions.
diff --git a/contrib/docker/frontend-with-nginx/docker/run.sh b/contrib/docker/frontend-with-nginx/docker/inject-config.sh
similarity index 80%
rename from contrib/docker/frontend-with-nginx/docker/run.sh
rename to contrib/docker/frontend-with-nginx/docker/inject-config.sh
index fdb1742a07..a0cea96ff3 100755
--- a/contrib/docker/frontend-with-nginx/docker/run.sh
+++ b/contrib/docker/frontend-with-nginx/docker/inject-config.sh
@@ -2,13 +2,6 @@
set -Eeuo pipefail
-# Run nginx as root
-sed -i 's/user nginx.*$//' /etc/nginx/nginx.conf
-
-# Write selected env vars to nginx config
-envsubst '$PORT' < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf
-
-# Inject runtime config into the client
function inject_config() {
# Read runtime config from env in the same way as the @backstage/config-loader package
local config
@@ -41,4 +34,3 @@ function inject_config() {
inject_config
-exec nginx -g 'daemon off;'
diff --git a/contrib/docker/multi-stage-frontend/Dockerfile b/contrib/docker/multi-stage-frontend/Dockerfile
deleted file mode 100644
index 3190687c52..0000000000
--- a/contrib/docker/multi-stage-frontend/Dockerfile
+++ /dev/null
@@ -1,23 +0,0 @@
-FROM node:12-buster AS build
-
-RUN mkdir /app
-COPY . /app
-WORKDIR /app
-
-RUN yarn install
-RUN yarn workspace example-app build
-
-# Contruct backstage-frontend image
-FROM nginx:mainline
-
-RUN apt-get update && apt-get -y install jq && rm -rf /var/lib/apt/lists/*
-
-# Copy from build stage
-COPY --from=build /app/packages/app/dist /usr/share/nginx/html
-
-COPY docker/default.conf.template /etc/nginx/conf.d/default.conf.template
-COPY docker/run.sh /usr/local/bin/run.sh
-
-CMD run.sh
-
-ENV PORT 80
diff --git a/contrib/docker/multi-stage-frontend/README.md b/contrib/docker/multi-stage-frontend/README.md
deleted file mode 100644
index b6ae4fdc6c..0000000000
--- a/contrib/docker/multi-stage-frontend/README.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Standalone Dockerfile for frontend
-
-This directory contains the resources which will help you build backstage without any requirements
-other than docker itself. It uses a multi-stage Dockerfile to build and ship backstage.
-
-## Usage
-
-You can simply run the following command to build backstage.
-
-```
-# Make sure you are in the root directory of backstage then run
-docker build -t backstage-frontend -f ./contrib/docker/multi-stage-frontend/Dockerfile .
-```
-
-After a successful build, You can simply run backstage frontend with the following command.
-
-```
-docker run -it --rm -p 3080:80 backstage-frontend
-```
diff --git a/contrib/docs/tutorials/aws-fargate-deployment.md b/contrib/docs/tutorials/aws-fargate-deployment.md
new file mode 100644
index 0000000000..bc530441c6
--- /dev/null
+++ b/contrib/docs/tutorials/aws-fargate-deployment.md
@@ -0,0 +1,16 @@
+# Deploying Backstage with AWS Fargate and Aurora
+
+There are any number of ways to deploy backstage containers on AWS. One of the
+simplest from a management and ops perspective is to leverage AWS Fargate and
+Aurora PostgreSQL, where both the container orchestration and database clusters
+are AWS managed services.
+
+However, to use them properly there are a large number of supporting resources
+(VPCs, Security Groups, Load Balancers, Certificate, etc) required. One approach
+is to use [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/) to
+simplify and automate the creation of the entire infrastructure stack along with
+automating the build and deploy of the container.
+
+Check out the [Backstage On AWS](https://github.com/rbogle/backstage-on-aws)
+repository, for a ready to use CDK application for deploying your custom
+Backstage app onto AWS ECS Fargate and Aurora.
diff --git a/contrib/kubernetes/basic_kubernetes_example_with_helm/backstage/templates/service.yaml b/contrib/kubernetes/basic_kubernetes_example_with_helm/backstage/templates/service.yaml
index 77a113ae5c..e74bfe0b8d 100644
--- a/contrib/kubernetes/basic_kubernetes_example_with_helm/backstage/templates/service.yaml
+++ b/contrib/kubernetes/basic_kubernetes_example_with_helm/backstage/templates/service.yaml
@@ -16,7 +16,7 @@ spec:
app.kubernetes.io/name: {{ include "backstage.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}
-{{- if .Values.app.enabled }}
+{{- if .Values.backend.enabled }}
---
apiVersion: v1
kind: Service
diff --git a/contrib/terraform/techdocs-s3-storage/readme.md b/contrib/terraform/techdocs-s3-storage/readme.md
new file mode 100644
index 0000000000..9615cc8d13
--- /dev/null
+++ b/contrib/terraform/techdocs-s3-storage/readme.md
@@ -0,0 +1 @@
+This terraform file should create a S3 bucket and setup IAM with a user with an inline policy which gives the user access to the bucket. After you have created the bucket, user and policy you should go to the user in the AWS console and create an access key. This access key should be used as the env variables in step 3a [here](https://backstage.io/docs/features/techdocs/using-cloud-storage#configuring-aws-s3-bucket-with-techdocs).
diff --git a/contrib/terraform/techdocs-s3-storage/terraform.tf b/contrib/terraform/techdocs-s3-storage/terraform.tf
new file mode 100644
index 0000000000..f256663f43
--- /dev/null
+++ b/contrib/terraform/techdocs-s3-storage/terraform.tf
@@ -0,0 +1,81 @@
+#==========================
+# Variables
+#==========================
+
+variable "backstage_bucket" {
+ default = "backstage_bucket_for_my_corp"
+}
+
+variable "backstage_iam" {
+ default = "backstage"
+}
+
+variable "shared_managed_tag" {
+ default = "terraform_for_my_corp"
+}
+
+#==========================
+# Bucket
+#==========================
+
+resource "aws_s3_bucket" "backstage" {
+ bucket = var.backstage_bucket
+ acl = "private"
+ provider = aws
+
+ lifecycle {
+ prevent_destroy = true
+ }
+
+ server_side_encryption_configuration {
+ rule {
+ apply_server_side_encryption_by_default {
+ sse_algorithm = "AES256"
+ }
+ }
+ }
+
+ tags = {
+ Name = var.backstage_bucket
+ "Managed By Terraform" = var.shared_managed_tag
+ }
+}
+
+resource "aws_s3_bucket_public_access_block" "backstage" {
+ bucket = aws_s3_bucket.backstage.id
+
+ block_public_acls = true
+ block_public_policy = true
+ ignore_public_acls = true
+ restrict_public_buckets = true
+}
+
+
+#==========================
+# IAM
+#==========================
+
+resource "aws_iam_user" "backstage" {
+ name = var.backstage_iam
+}
+
+resource "aws_iam_user_policy" "backstage" {
+ name = var.backstage_iam
+ user = aws_iam_user.backstage.name
+ policy = data.aws_iam_policy_document.backstage_policy.json
+}
+
+data "aws_iam_policy_document" "backstage_policy" {
+ statement {
+ actions = [
+ "s3:PutObject",
+ "s3:GetObject",
+ "s3:ListBucket"
+ ]
+ effect = "Allow"
+ resources = [
+ "${aws_s3_bucket.backstage.arn}",
+ "${aws_s3_bucket.backstage.arn}/*",
+ ]
+ }
+}
diff --git a/cypress/src/integration/integrations.ts b/cypress/src/integration/integrations.ts
new file mode 100644
index 0000000000..5ee077502a
--- /dev/null
+++ b/cypress/src/integration/integrations.ts
@@ -0,0 +1,76 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+///
+import 'os';
+
+describe('Integrations', () => {
+ describe('ReadTree', () => {
+ it('should work for github', () => {
+ cy.loginAsGuest();
+
+ cy.request('POST', '/api/catalog/locations', {
+ target:
+ 'https://github.com/backstage-verification/test-repo/blob/main/**/*',
+ type: 'url',
+ });
+
+ cy.visit('/catalog');
+ cy.contains('All').click();
+ cy.get('table').should('contain', 'github-repo');
+ cy.get('table').should('contain', 'github-repo-nested');
+ });
+
+ // it('should work for azure', () => {
+ // cy.loginAsGuest();
+
+ // cy.request('POST', '/api/catalog/locations', {
+ // target:
+ // 'https://dev.azure.com/backstage-verification/_git/test-repo?path=*',
+ // type: 'url',
+ // });
+ // });
+
+ it('should work for gitlab', () => {
+ cy.loginAsGuest();
+
+ cy.request('POST', '/api/catalog/locations', {
+ target:
+ 'https://gitlab.com/backstage-verification/test-repo/-/tree/master/**/*',
+ type: 'url',
+ });
+
+ cy.visit('/catalog');
+ cy.contains('All').click();
+ cy.get('table').should('contain', 'gitlab-repo');
+ cy.get('table').should('contain', 'gitlab-repo-nested');
+ });
+
+ it('should work for bitbucket', () => {
+ cy.loginAsGuest();
+
+ cy.request('POST', '/api/catalog/locations', {
+ target:
+ 'https://bitbucket.org/backstage-verification/test-repo/src/master/**/*',
+ type: 'url',
+ });
+
+ cy.visit('/catalog');
+ cy.contains('All').click();
+ cy.get('table').should('contain', 'bitbucket-repo');
+ cy.get('table').should('contain', 'bitbucket-repo-nested');
+ });
+ });
+});
diff --git a/docs/cli/commands.md b/docs/cli/commands.md
index 324d17463c..a99d4cd9d0 100644
--- a/docs/cli/commands.md
+++ b/docs/cli/commands.md
@@ -111,6 +111,7 @@ Usage: backstage-cli app:build
Options:
--stats Write bundle stats to output directory
+ --lax Do not require environment variables to be set
--config <path> Config files to load instead of app-config.yaml (default: [])
-h, --help display help for command
```
@@ -486,6 +487,7 @@ Usage: backstage-cli config:print [options]
Options:
--package <name> Only load config schema that applies to the given package
+ --lax Do not require environment variables to be set
--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]
@@ -506,6 +508,7 @@ Usage: backstage-cli config:check [options]
Options:
--package <name> Only load config schema that applies to the given package
+ --lax Do not require environment variables to be set
--config <path> Config files to load instead of app-config.yaml (default: [])
-h, --help display help for command
```
diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md
index ef178b2977..383cf0615a 100644
--- a/docs/deployment/docker.md
+++ b/docs/deployment/docker.md
@@ -232,7 +232,7 @@ package, which is done as follows:
Once the `app-backend` is removed from the backend, you can use your favorite
static file serving method for serving the frontend. An example of how to set up
an NGINX image is available in the
-[contrib folder in the main repo](https://github.com/backstage/backstage/blob/master/contrib/docker/frontend-with-nginx/Dockerfile)
+[contrib folder in the main repo](https://github.com/backstage/backstage/blob/master/contrib/docker/frontend-with-nginx)
Note that if you're building a separate docker build of the frontend you
probably need to adjust `.dockerignore` appropriately. Most likely by making
diff --git a/docs/deployment/helm.md b/docs/deployment/helm.md
index fd36aeb81f..cbfcb1bc57 100644
--- a/docs/deployment/helm.md
+++ b/docs/deployment/helm.md
@@ -1,12 +1,10 @@
---
id: helm
-title: Deploying Backstage with Helm
+title: Deploying with Helm
description: How to deploy Backstage with Helm and Kubernetes
sidebar_label: Helm
---
-# Helm charts
-
An example Backstage app can be deployed in Kubernetes using the
[Backstage Helm charts](https://github.com/backstage/backstage/tree/master/contrib/chart/backstage).
diff --git a/docs/deployment/index.md b/docs/deployment/index.md
index db4ceca6f1..86ad03d1ae 100644
--- a/docs/deployment/index.md
+++ b/docs/deployment/index.md
@@ -30,7 +30,9 @@ There is also an example of deploying on [Heroku](heroku.md), which only
requires the first two steps.
An example of deploying Backstage with a [Helm chart](helm.md), a common pattern
-in AWS, is also available.
+in AWS, is also available. There is also a contrib guide to deploying Backstage
+with
+[AWS Fargate and Aurora PostgreSQL](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/aws-fargate-deployment.md)
Please consider contributing other deployment guides if you get Backstage set up
on common infrastructure, it would be a great benefit to the community.
diff --git a/docs/deployment/k8s.md b/docs/deployment/k8s.md
index 9dbf447740..2c52e0e308 100644
--- a/docs/deployment/k8s.md
+++ b/docs/deployment/k8s.md
@@ -357,6 +357,16 @@ spec:
name: postgres-secrets
- secretRef:
name: backstage-secrets
+# Uncomment if health checks are enabled in your app:
+# https://backstage.io/docs/plugins/observability#health-checks
+# readinessProbe:
+# httpGet:
+# port: 7000
+# path: /healthcheck
+# livenessProbe:
+# httpGet:
+# port: 7000
+# path: /healthcheck
```
For production deployments, the `image` reference will usually be a full URL to
diff --git a/docs/features/kubernetes/configuration.md b/docs/features/kubernetes/configuration.md
index 8222fbb400..5dbad9cf4a 100644
--- a/docs/features/kubernetes/configuration.md
+++ b/docs/features/kubernetes/configuration.md
@@ -78,6 +78,7 @@ cluster. Valid values are:
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
+| `aws` | This will use AWS credentials to access resources in EKS clusters |
##### `clusters.\*.skipTLSVerify`
diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md
index fed24c58d6..36bb724be6 100644
--- a/docs/features/kubernetes/installation.md
+++ b/docs/features/kubernetes/installation.md
@@ -8,52 +8,36 @@ 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, read the
-[Getting Started](../../getting-started/index.md).
+[Getting Started](../../getting-started/index.md) guide.
## 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
+The first step is to add the Kubernetes frontend 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/
+# From your Backstage root directory
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`:
+Once the package has been installed, you need to import the plugin in your app
+by adding the "Kubernetes" tab to the respective catalog pages.
```tsx
-import { Router as KubernetesRouter } from '@backstage/plugin-kubernetes';
+// In packages/app/src/components/catalog/EntityPage.tsx
+import { EntityKubernetesContent } from '@backstage/plugin-kubernetes';
-// ...
-
-const ServiceEntityPage = ({ entity }: { entity: Entity }) => (
-
- // ...
- }
- />
- // ...
-
-);
+// You can add the tab to any number of pages, the service page is shown as an
+// example here
+const serviceEntityPage = (
+
+ {/* other tabs... */}
+
+
+
```
That's it! But now, we need the Kubernetes Backend plugin for the frontend to
@@ -65,17 +49,16 @@ Navigate to `packages/backend` of your Backstage app, and install the
`@backstage/plugin-kubernetes-backend` package.
```bash
-cd my-backstage-app/
+# From your Backstage root directory
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`:
+add the following:
```typescript
+// In packages/backend/src/plugins/kubernetes.ts
import { createRouter } from '@backstage/plugin-kubernetes-backend';
import { PluginEnvironment } from '../types';
@@ -91,18 +74,15 @@ 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
+// In packages/backend/src/index.ts
import kubernetes from './plugins/kubernetes';
-
// ...
-
-const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes'));
-
-// ...
-
-apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv));
+async function main() {
+ // ...
+ 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
diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md
index 1afdff418a..320b82d0ad 100644
--- a/docs/features/software-catalog/configuration.md
+++ b/docs/features/software-catalog/configuration.md
@@ -37,6 +37,13 @@ The locations added through static configuration cannot be removed through the
catalog locations API. To remove these locations, you must remove them from the
configuration.
+Syntax errors or other types of errors present in `catalog-info.yaml` files will
+be logged for investigation. Errors do not cause processing to abort.
+
+When multiple `catalog-info.yaml` files with the same `metadata.name` property
+are discovered, one will be processed and all others will be skipped. This
+action is logged for further investigation.
+
### Integration Processors
Integrations may simply provide a mechanism to handle `url` location type for an
@@ -111,8 +118,7 @@ catalog:
> deleting entities will not work in this mode.**
A common use case for this configuration is when organizations have a remote
-source that should be mirrored into backstage. If we want backstage to be a
-mirror of this remote source we cannot allow users to also register entities
-with e.g.
+source that should be mirrored into Backstage. To make Backstage a mirror of
+this remote source, users cannot also register new entities with e.g. the
[catalog-import](https://github.com/backstage/backstage/tree/master/plugins/catalog-import)
plugin.
diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md
index f4e1f86dd8..eb087a9c5f 100644
--- a/docs/features/software-catalog/descriptor-format.md
+++ b/docs/features/software-catalog/descriptor-format.md
@@ -44,7 +44,7 @@ metadata:
name: artist-web
description: The place to be, for great artists
labels:
- system: public-websites
+ example.com/custom: custom_label_value
annotations:
example.com/service-discovery: artistweb
circleci.com/project-slug: github/example-org/artist-website
@@ -58,6 +58,7 @@ spec:
type: website
lifecycle: production
owner: artist-relations-team
+ system: public-websites
```
This is the same entity as returned in JSON from the software catalog API:
@@ -76,7 +77,7 @@ This is the same entity as returned in JSON from the software catalog API:
"etag": "ZjU2MWRkZWUtMmMxZS00YTZiLWFmMWMtOTE1NGNiZDdlYzNk",
"generation": 1,
"labels": {
- "system": "public-websites"
+ "example.com/custom": "custom_label_value"
},
"links": [{
"url": "https://admin.example-org.com",
@@ -90,7 +91,8 @@ This is the same entity as returned in JSON from the software catalog API:
"spec": {
"lifecycle": "production",
"owner": "artist-relations-team",
- "type": "website"
+ "type": "website",
+ "system": "public-websites"
}
}
```
@@ -639,22 +641,11 @@ A list of strings that can be associated with the template, e.g.
This list will also be used in the frontend to display to the user so you can
potentially search and group templates by these tags.
-### `spec.type` [optional]
+### `spec.type` [required]
-The type of component as a string, e.g. `website`. This field is optional but
-recommended.
-
-The software catalog accepts any type value, but an organization should take
-great care to establish a proper taxonomy for these. Tools including Backstage
-itself may read this field and behave differently depending on its value. For
-example, a website type component may present tooling in the Backstage interface
-that is specific to just websites.
-
-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
+The type of component created by the template, e.g. `website`. This is used for
+filtering templates, and should ideally match the Component
+[spec.type](#spectype-required) created by the template.
### `spec.parameters` [required]
diff --git a/docs/features/software-catalog/installation.md b/docs/features/software-catalog/installation.md
index ff8dfbda68..0b622fb093 100644
--- a/docs/features/software-catalog/installation.md
+++ b/docs/features/software-catalog/installation.md
@@ -18,20 +18,15 @@ The catalog frontend plugin should be installed in your `app` package, which is
created as a part of `@backstage/create-app`. To install the package, run:
```bash
+# From your Backstage root directory
cd packages/app
yarn add @backstage/plugin-catalog
```
### Adding the Plugin to your `packages/app`
-Add the following entry to the head of your `packages/app/src/plugins.ts`:
-
-```ts
-export { catalogPlugin } from '@backstage/plugin-catalog';
-```
-
-Next we need to install the two pages that the catalog plugin provides. You can
-choose any name for these routes, but we recommend the following:
+Add the two pages that the catalog plugin provides to your app. You can choose
+any name for these routes, but we recommend the following:
```tsx
// packages/app/src/App.tsx
@@ -109,6 +104,7 @@ The catalog backend should be installed in your `backend` package, which is
created as a part of `@backstage/create-app`. To install the package, run:
```bash
+# From your Backstage root directory
cd packages/backend
yarn add @backstage/plugin-catalog-backend
```
diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md
index 0053c14b79..67b92bd941 100644
--- a/docs/features/software-catalog/well-known-annotations.md
+++ b/docs/features/software-catalog/well-known-annotations.md
@@ -273,6 +273,20 @@ project within your organization.
Specifying this annotation may enable SonarQube related features in Backstage
for that entity.
+### backstage.io/code-coverage
+
+```yaml
+# Example:
+metadata:
+ annotations:
+ backstage.io/code-coverage: scm-only
+```
+
+The value of this annotation controls the code-coverage backstage plugin. If set
+to `scm-only`, the plugin will only take into account files stored in source
+control (e.g. ignoring generated code). If set to `enabled`, all files covered
+by a coverage report will be taken into account.
+
## Deprecated Annotations
The following annotations are deprecated, and only listed here to aid in
diff --git a/docs/features/software-templates/installation.md b/docs/features/software-templates/installation.md
index 105b7e5f96..ad7e6d1062 100644
--- a/docs/features/software-templates/installation.md
+++ b/docs/features/software-templates/installation.md
@@ -20,20 +20,15 @@ The scaffolder frontend plugin should be installed in your `app` package, which
is created as a part of `@backstage/create-app`. To install the package, run:
```bash
+# From your Backstage root directory
cd packages/app
yarn add @backstage/plugin-scaffolder
```
### Adding the Plugin to your `packages/app`
-Add the following entry to the head of your `packages/app/src/plugins.ts`:
-
-```ts
-export { scaffolderPlugin } from '@backstage/plugin-scaffolder';
-```
-
-Next we need to install the root page that the Scaffolder plugin provides. You
-can choose any path for the route, but we recommend the following:
+Add the root page that the Scaffolder plugin provides to your app. You can
+choose any path for the route, but we recommend the following:
```tsx
import { ScaffolderPage } from '@backstage/plugin-scaffolder';
@@ -63,6 +58,7 @@ The scaffolder backend should be installed in your `backend` package, which is
created as a part of `@backstage/create-app`. To install the package, run:
```bash
+# From your Backstage root directory
cd packages/backend
yarn add @backstage/plugin-scaffolder-backend
```
@@ -74,6 +70,10 @@ creating a file called `packages/backend/src/plugins/scaffolder.ts` with the
following contents to get you up and running quickly.
```ts
+import {
+ DockerContainerRunner,
+ SingleHostDiscovery,
+} from '@backstage/backend-common';
import {
CookieCutter,
createRouter,
@@ -82,7 +82,6 @@ import {
CreateReactAppTemplater,
Templaters,
} from '@backstage/plugin-scaffolder-backend';
-import { SingleHostDiscovery } from '@backstage/backend-common';
import type { PluginEnvironment } from '../types';
import Docker from 'dockerode';
import { CatalogClient } from '@backstage/catalog-client';
@@ -93,8 +92,11 @@ export default async function createPlugin({
database,
reader,
}: PluginEnvironment) {
- const cookiecutterTemplater = new CookieCutter();
- const craTemplater = new CreateReactAppTemplater();
+ const dockerClient = new Docker();
+ const containerRunner = new DockerContainerRunner({ dockerClient });
+
+ const cookiecutterTemplater = new CookieCutter({ containerRunner });
+ const craTemplater = new CreateReactAppTemplater({ containerRunner });
const templaters = new Templaters();
templaters.register('cookiecutter', cookiecutterTemplater);
@@ -103,8 +105,6 @@ export default async function createPlugin({
const preparers = await Preparers.fromConfig(config, { logger });
const publishers = await Publishers.fromConfig(config, { logger });
- const dockerClient = new Docker();
-
const discovery = SingleHostDiscovery.fromConfig(config);
const catalogClient = new CatalogClient({ discoveryApi: discovery });
@@ -114,7 +114,6 @@ export default async function createPlugin({
publishers,
logger,
config,
- dockerClient,
database,
catalogClient,
reader,
@@ -265,9 +264,9 @@ the templates at [localhost:3000/create](http://localhost:3000/create) now!
Software Templates use
[Cookiecutter](https://github.com/cookiecutter/cookiecutter) as templating
library. By default it will use the
-[spotify/backstage-cookiecutter](<[spotify/backstage-cookiecutter](https://github.com/backstage/backstage/blob/37e35b910afc7d1270855aed0ec4718aba366c91/plugins/scaffolder-backend/scripts/Cookiecutter.dockerfile)>)
+[spotify/backstage-cookiecutter](https://github.com/backstage/backstage/blob/37e35b910afc7d1270855aed0ec4718aba366c91/plugins/scaffolder-backend/scripts/Cookiecutter.dockerfile)
docker image.
-If you are running backstage from a Docker container and you want to avoid
+If you are running Backstage from a Docker container and you want to avoid
calling a container inside a container, you can set up Cookiecutter in your own
image, this will use the local installation instead.
diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md
index ff145ee5af..90dd603c8f 100644
--- a/docs/features/software-templates/writing-custom-actions.md
+++ b/docs/features/software-templates/writing-custom-actions.md
@@ -106,7 +106,6 @@ return await createRouter({
publishers,
logger,
config,
- dockerClient,
database,
catalogClient,
reader,
@@ -124,7 +123,6 @@ return await createRouter({
publishers,
logger,
config,
- dockerClient,
database,
catalogClient,
reader,
@@ -136,11 +134,9 @@ return await createRouter({
want to have those as well as your new one, you'll need to do the following:
```ts
-
-import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend`;
+import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend';
const builtInActions = createBuiltinActions({
- dockerClient,
integrations,
catalogClient,
templaters,
@@ -155,7 +151,6 @@ return await createRouter({
publishers,
logger,
config,
- dockerClient,
database,
catalogClient,
reader,
diff --git a/docs/features/techdocs/FAQ.md b/docs/features/techdocs/FAQ.md
index 5ce71ebfad..117471f749 100644
--- a/docs/features/techdocs/FAQ.md
+++ b/docs/features/techdocs/FAQ.md
@@ -45,3 +45,15 @@ metadata annotation is used in the build process of TechDocs. But when
annotation should still be present in entity descriptor file (e.g.
`catalog-info.yaml`) for Backstage to know that TechDocs is enabled for the
entity.
+
+#### Is it possible for users to suggest changes or provide feedback on a TechDocs page?
+
+This is supported for TechDocs sites whose source code is hosted in either
+GitHub or GitLab. In order to add "edit this page" and "leave feedback" buttons
+on a TechDocs page, be sure that you have `repo_url` and `edit_uri` values in
+your `mkdocs.yml` files per
+[MkDocs instructions](https://www.mkdocs.org/user-guide/configuration).
+
+If the host name of your source code hosting URL does not include `github` or
+`gitlab`, an `integrations` entry in your `app-config.yaml` pointed at your
+source code provider is also needed (only the `host` key is necessary).
diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md
index c7876f3874..aa38dd42b1 100644
--- a/docs/features/techdocs/configuration.md
+++ b/docs/features/techdocs/configuration.md
@@ -78,6 +78,11 @@ techdocs:
# https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#constructor-property
endpoint: ${AWS_ENDPOINT}
+ # (Optional) Whether to use path style URLs when communicating with S3.
+ # Defaults to false.
+ # This allows providers like LocalStack, Minio and Wasabi (and possibly others) to be used to host tech docs.
+ s3ForcePathStyle: false
+
# Required when techdocs.publisher.type is set to 'azureBlobStorage'. Skip otherwise.
azureBlobStorage:
diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md
index a9844ef528..0dec7ec24e 100644
--- a/docs/features/techdocs/configuring-ci-cd.md
+++ b/docs/features/techdocs/configuring-ci-cd.md
@@ -148,6 +148,23 @@ jobs:
- uses: actions/setup-node@v2
- uses: actions/setup-python@v2
+ # the 2 steps below can be removed if you aren't using plantuml in your documentation
+ - name: setup java
+ uses: actions/setup-java@v2
+ with:
+ distribution: 'zulu'
+ java-version: '11'
+ - name: download, validate, install plantuml and its dependencies
+ run: |
+ curl -o plantuml.jar -L http://sourceforge.net/projects/plantuml/files/plantuml.1.2021.4.jar/download
+ echo "be498123d20eaea95a94b174d770ef94adfdca18 plantuml.jar" | sha1sum -c -
+ mv plantuml.jar /opt/plantuml.jar
+ mkdir -p "$HOME/.local/bin"
+ echo $'#!/bin/sh\n\njava -jar '/opt/plantuml.jar' ${@}' >> "$HOME/.local/bin/plantuml"
+ chmod +x "$HOME/.local/bin/plantuml"
+ echo "$HOME/.local/bin" >> $GITHUB_PATH
+ sudo apt-get install -y graphviz
+
- name: Install techdocs-cli
run: sudo npm install -g @techdocs/cli
diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md
index a96e881849..51f07d5cde 100644
--- a/docs/features/techdocs/getting-started.md
+++ b/docs/features/techdocs/getting-started.md
@@ -22,21 +22,15 @@ Navigate to your new Backstage application directory. And then to your
`packages/app` directory, and install the `@backstage/plugin-techdocs` package.
```bash
-cd my-backstage-app/
+# From your Backstage root directory
cd packages/app
yarn add @backstage/plugin-techdocs
```
Once the package has been installed, you need to import the plugin in your app.
-Add the following to `packages/app/src/plugins.ts`:
-
-```typescript
-export { plugin as TechDocs } from '@backstage/plugin-techdocs';
-```
-
-Now we can add a route for the TechDocs page. In `packages/app/src/App.tsx`,
-import TechDocsPage and add the following to `FlatRoutes`:
+In `packages/app/src/App.tsx`, import `TechDocsPage` and add the following to
+`FlatRoutes`:
```tsx
import { TechDocsPage } from '@backstage/plugin-techdocs';
@@ -60,7 +54,7 @@ Navigate to `packages/backend` of your Backstage app, and install the
`@backstage/plugin-techdocs-backend` package.
```bash
-cd my-backstage-app/
+# From your Backstage root directory
cd packages/backend
yarn add @backstage/plugin-techdocs-backend
```
@@ -69,6 +63,7 @@ Create a file called `techdocs.ts` inside `packages/backend/src/plugins/` and
add the following
```typescript
+import { DockerContainerRunner } from '@backstage/backend-common';
import {
createRouter,
Generators,
@@ -90,9 +85,14 @@ export default async function createPlugin({
reader,
});
+ // Docker client (conditionally) used by the generators, based on techdocs.generators config.
+ const dockerClient = new Docker();
+ const containerRunner = new DockerContainerRunner({ dockerClient });
+
// Generators are used for generating documentation sites.
const generators = await Generators.fromConfig(config, {
logger,
+ containerRunner,
});
// Publisher is used for
@@ -103,14 +103,13 @@ export default async function createPlugin({
discovery,
});
- // Docker client (conditionally) used by the generators, based on techdocs.generators config.
- const dockerClient = new Docker();
+ // checks if the publisher is working and logs the result
+ await publisher.getReadiness();
return await createRouter({
preparers,
generators,
publisher,
- dockerClient,
logger,
config,
discovery,
diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md
index 2cb769b0e3..6c64e83a76 100644
--- a/docs/features/techdocs/how-to-guides.md
+++ b/docs/features/techdocs/how-to-guides.md
@@ -82,3 +82,84 @@ Caveat: Currently TechDocs sites built using URL Reader will be cached for 30
minutes which means they will not be re-built if new changes are made within 30
minutes. This cache invalidation will be replaced by commit timestamp based
implementation very soon.
+
+## How to use a custom TechDocs home page?
+
+### 1st way: TechDocsCustomHome with a custom configuration
+
+As an example, in your main App.tsx:
+
+```tsx
+import {
+ TechDocsCustomHome,
+ PanelType,
+ TechDocsReaderPage,
+} from '@backstage/plugin-techdocs';
+import { Entity } from '@backstage/catalog-model';
+
+const tabsConfig = [
+ {
+ label: 'Custom Tab',
+ panels: [
+ {
+ title: 'Custom Documents Cards 1',
+ description:
+ 'Explore your internal technical ecosystem through documentation.',
+ panelType: 'DocsCardGrid' as PanelType,
+ // optional, is applied to a container of the panel (excludes header of panel)
+ panelCSS: { maxHeight: '400px', overflow:'auto' },
+ filterPredicate: (entity: Entity) => !!entity.metadata.annotations?.['customCardAnnotationOne'];
+ },
+ {
+ title: 'Custom Documents Cards 2',
+ description:
+ 'Explore your internal technical ecosystem through documentation.',
+ panelType: 'DocsCardGrid' as PanelType,
+ panelCSS: { maxHeight: '400px', overflow:'auto' },
+ filterPredicate: (entity: Entity) => !!entity.metadata.annotations?.['customCardAnnotationTwo'];
+ },
+ ],
+ },
+ {
+ label: 'Overview',
+ panels: [
+ {
+ title: 'Overview',
+ description:
+ 'Explore your internal technical ecosystem through documentation.',
+ panelType: 'DocsTable' as PanelType,
+ filterPredicate: () => true,
+ },
+ ],
+ },
+];
+
+const routes = (
+
+ }
+ />
+ }
+ />
+
+```
+
+An example of tabsConfig that corresponds to the default documentation home page
+can be found at `plugins/techdocs/src/home/components/TechDocsHome.tsx`.
+
+Currently `panelType` has DocsCardGrid and DocsTable available. We currently
+recommend that DocsCardGrid can be optionally vertically stacked by setting a
+maxHeight using `panelCSS`, and DocsTable to be in a tab by itself.
+
+### 2nd way: Custom home page plugin
+
+A custom home page plugin can be built that uses the components extensions
+DocsCardGrid and DocsTable, exported from @backstage/techdocs. They both take a
+array of documentation entities ( i.e.have a 'backstage.io/techdocs-ref'
+annotation ) as an 'entities' attribute.
+
+For a reference to the React structure of the default home page, please refer to
+`plugins/techdocs/src/home/components/TechDocsCustomHome.tsx`.
diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md
index d5a3a68425..62ee4867c8 100644
--- a/docs/features/techdocs/using-cloud-storage.md
+++ b/docs/features/techdocs/using-cloud-storage.md
@@ -119,6 +119,7 @@ techdocs:
Create a dedicated AWS S3 bucket for the storage of TechDocs sites.
[Refer to the official documentation](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html).
+[Terraform example](https://github.com/backstage/backstage/blob/master/contrib/terraform/techdocs-s3-storage/terraform.tf).
TechDocs will publish documentation to this bucket and will fetch files from
here to serve documentation in Backstage. Note that the bucket names are
@@ -135,13 +136,29 @@ techdocs:
bucketName: 'name-of-techdocs-storage-bucket'
```
-**3a. (Recommended) Setup authentication the AWS way, using environment
+**3. Create minimal AWS IAM policies to manage TechDocs**
+
+To _write_ TechDocs into the S3 bucket the IAM policy needs to have at a minimum
+permissions to:
+
+- `s3:ListBucket` to retrieve bucket metadata
+- `s3:PutObject` to upload files to the bucket
+
+To _read_ TechDocs from the S3 bucket the IAM policy needs to have at a minimum
+permissions to:
+
+- `s3:ListBucket` - To retrieve bucket metadata
+- `s3:GetObject` - To retrieve files from the bucket
+
+**4a. (Recommended) Setup authentication the AWS way, using environment
variables**
You should follow the
[AWS security best practices guide for authentication](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html).
-TechDocs needs access to read files and metadata of the S3 bucket.
+TechDocs needs access to read files and metadata of the S3 bucket. So if you are
+creating a policy for a user you want to make sure it is granted access to
+ListBucket, GetObject and PutObject.
If the environment variables
@@ -166,7 +183,7 @@ more in
The AWS Region of the bucket is optional since TechDocs uses AWS SDK V2 and not
V3.
-**3b. Authentication using app-config.yaml**
+**4b. Authentication using app-config.yaml**
AWS credentials and region can be provided to the AWS SDK via `app-config.yaml`.
If the configs below are present, they will be used over existing `AWS_*`
@@ -187,7 +204,7 @@ techdocs:
Refer to the
[official AWS documentation for obtaining the credentials](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/getting-your-credentials.html).
-**3c. Authentication using an assumed role** Users with multiple AWS accounts
+**4c. Authentication using an assumed role** Users with multiple AWS accounts
may want to use a role for S3 storage that is in a different AWS account. Using
the `roleArn` parameter as seen below, you can instruct the TechDocs publisher
to assume a role before accessing S3.
@@ -207,7 +224,7 @@ Note: Assuming a role requires that primary credentials are already configured
at `AWS.config.credentials`. Read more about
[assuming roles in AWS](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html).
-**4. That's it!**
+**5. That's it!**
Your Backstage app is now ready to use AWS S3 for TechDocs, to store and read
the static generated documentation files. When you start the backend of the app,
diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md
index 181f541929..4dbc6bfa48 100644
--- a/docs/getting-started/app-custom-theme.md
+++ b/docs/getting-started/app-custom-theme.md
@@ -135,3 +135,31 @@ const themeOptions = createThemeOptions({
},
});
```
+
+## Custom Logo
+
+In addition to a custom theme, you can also customize the logo displayed at the
+far top left of the site.
+
+In your frontend app, locate `src/components/Root/` folder. You'll find two
+components:
+
+- `LogoFull.tsx` - A larger logo used when the Sidebar navigation is opened.
+- `LogoIcon.tsx` - A smaller logo used when the sidebar navigation is closed.
+
+To replace the images, you can simply replace the relevant code in those
+components with raw SVG definitions.
+
+You can also use another web image format such as PNG by importing it. To do
+this, place your new image into a new subdirectory such as
+`src/components/Root/logo/my-company-logo.png`, and then add this code:
+
+```jsx
+import MyCustomLogoFull from './logo/my-company-logo.png';
+
+//...
+
+const LogoFull = () => {
+ return ;
+};
+```
diff --git a/docs/getting-started/configure-app-with-plugins.md b/docs/getting-started/configure-app-with-plugins.md
index b2f3a37d90..746b4bd940 100644
--- a/docs/getting-started/configure-app-with-plugins.md
+++ b/docs/getting-started/configure-app-with-plugins.md
@@ -27,14 +27,7 @@ package.json. Backstage Apps are set up as monorepos with
[yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). Since
CircleCI is a frontend UI plugin, it goes in `app` rather than `backend`.
-2. Add the plugin itself to the App:
-
-```js
-// packages/app/src/plugins.ts
-export { plugin as CircleCi } from '@backstage/plugin-circleci';
-```
-
-3. Register the plugin in the entity pages:
+2. Add the `EntityCircleCIContent` extension to the entity pages in the app:
```diff
// packages/app/src/components/catalog/EntityPage.tsx
diff --git a/docs/integrations/datadog-rum/installation.md b/docs/integrations/datadog-rum/installation.md
new file mode 100644
index 0000000000..f96298a33b
--- /dev/null
+++ b/docs/integrations/datadog-rum/installation.md
@@ -0,0 +1,34 @@
+---
+id: installation
+title: Datadog RUM Installation
+sidebar_label: Installation
+# prettier-ignore
+description: Adding Datadog Real User Monitoring (RUM) to Your App
+---
+
+Datadog Real User Monitoring (RUM) allows you to visualize and analyze the
+real-time performance and user journeys of your application's individual users.
+This is an option to profile and monitor the user experience of your Backstage
+installation.
+
+There is a basic [Datadog RUM](https://docs.datadoghq.com/real_user_monitoring/)
+integration built into Backstage. You can enable it by adding the following to
+your `app-config.yaml`:
+
+```yaml
+app:
+ datadogRum:
+ clientToken: '123456789'
+ applicationId: qwerty
+ # site: datadoghq.eu
+ # env: 'staging'
+```
+
+The `clientToken` and `applicationId` are generated from the Datadog RUM page
+following
+[these instructions](https://docs.datadoghq.com/real_user_monitoring/browser/).
+
+There are two optional arguments:
+
+- `site`: The Datadog site of your organization; defaults to `datadoghq.com`
+- `env`: The application environment for Datadog events (no default)
diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md
index f2f2bc72c8..316f066614 100644
--- a/docs/overview/architecture-overview.md
+++ b/docs/overview/architecture-overview.md
@@ -67,33 +67,41 @@ is available at
### Installing plugins
-Plugins are typically loaded by the UI in your Backstage applications
-`plugins.ts` file. For example,
-[here](https://github.com/backstage/backstage/blob/master/packages/app/src/plugins.ts)
-is that file in the Backstage sample app.
+Plugins are typically installed as React components in your Backstage
+application. For example,
+[here](https://github.com/backstage/backstage/blob/master/packages/app/src/App.tsx)
+is a file that imports many full-page plugins in the Backstage sample app.
-Plugins can be enabled, and passed configuration in `apis.ts`. For example,
-[here](https://github.com/backstage/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
-application:
+An example of one of these plugin components is the `CatalogIndexPage`, which is
+a full-page view that allows you to browse entities in the Backstage catalog. It
+is installed in the app by importing it and adding it as an element like this:
```tsx
-import { ApiHolder, ApiRegistry } from '@backstage/core';
-import {
- lighthouseApiRef,
- LighthouseRestApi,
-} from '@backstage/plugin-lighthouse';
+import { CatalogIndexPage } from '@backstage/plugin-catalog';
-const builder = ApiRegistry.builder();
+...
-export const lighthouseApi = new LighthouseRestApi(/* URL of the lighthouse microservice! */);
-builder.add(lighthouseApiRef, lighthouseApi);
-
-export default builder.build() as ApiHolder;
+const routes = (
+
+ ...
+ } />
+ ...
+
+);
```
+Note that we use `"/catalog"` as our path to this plugin page, but we can choose
+any route we want for the page, as long as it doesn't collide with the routes
+that we choose for the other plugins in the app.
+
+These components that are exported from plugins are referred to as "Plugin
+Extension Components", or "Extension Components". They are regular React
+components, but in addition to being able to be rendered by React, they also
+contain various pieces of metadata that is used to wire together the entire app.
+Extension components are created using `create*Extension` methods, which you can
+read more about in the
+[composability documentation](../plugins/composability.md).
+
As of this moment, there is no config based install procedure for plugins. Some
code changes are required.
diff --git a/docs/overview/logos.md b/docs/overview/logos.md
index 4c0c345f36..9421b7f31e 100644
--- a/docs/overview/logos.md
+++ b/docs/overview/logos.md
@@ -6,37 +6,37 @@ description: Guidelines for how to use the Backstage logos and icons
---
Guidelines for how to use the Backstage logo and icon can be found
-[here](/logo_assets/Backstage_Identity_Assets_Overview.pdf). The assets below
-are all in `.svg` format. Other formats are available in the
+[here](https://backstage.io/logo_assets/Backstage_Identity_Assets_Overview.pdf).
+The assets below are all in `.svg` format. Other formats are available in the
[repository](https://github.com/backstage/backstage/tree/master/microsite/static/logo_assets).
## Backstage logo
-
-
+
+
-
-
+
+
-
-
+
+
## Backstage icon