paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 41 Packages Projects Releases Wiki Activity

Merge pull request #17 from backstage/master

Browse Source 
Sync fork
This commit is contained in:
Esteban Barrios
2021-01-06 11:48:26 +01:00
committed by GitHub
parent fb02ff807d 51cae2ceb4
commit 4054e41a74
1188 changed files with 48581 additions and 11937 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/bitbucket-scaffolder.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-scaffolder-backend': patch
---
Add scaffolding support for Bitbucket Cloud and Server.
.changeset/chilly-dodos-drop.md
+6
View File
@@ -0,0 +1,6 @@
---
'@backstage/techdocs-common': patch
'@backstage/plugin-techdocs-backend': patch
---
1. Added option to use AWS S3 as a choice to store the static generated files for TechDocs.
.changeset/cost-insights-strange-rings-smile.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-cost-insights': patch
---
remove excessive margin from cost overview banner
.changeset/cost-insights-ten-carpets-return.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-cost-insights': minor
---
remove cost insights currency feature flag
.changeset/cost-insights-wild-cars-wait.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-cost-insights': patch
---
Fix savings/excess display calculation
.changeset/cuddly-files-argue.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/create-app': patch
---
Replace `register-component` plugin with new `catalog-import` plugin
.changeset/cyan-lizards-confess.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/backend-common': patch
---
Fix HTTPS certificate generation and add new config switch, enabling it simply by setting `backend.https = true`. Also introduces caching of generated certificates in order to avoid having to add a browser override every time the backend is restarted.
.changeset/dry-dolls-run.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/cli': patch
---
Use consistent file extensions for JS output when building packages.
.changeset/early-spies-grow.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog-backend': patch
---
Fixed a bug where the catalog would read back all entities when adding a location that already exists.
.changeset/famous-shrimps-double.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-scaffolder': patch
---
Bug fix: User can retry creating a new component if an error occurs, without having to reload the page.
.changeset/fifty-yaks-behave.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/techdocs-common': patch
---
Fix for `integration.github.apiBaseUrl` configuration not properly overriding apiBaseUrl used by techdocs
.changeset/flat-suns-call.md
+17
View File
@@ -0,0 +1,17 @@
---
'@backstage/plugin-auth-backend': patch
---
Add support for the majority of the Core configurations for Passport-SAML.
These configuration keys are supported:
- entryPoint
- issuer
- cert
- privateKey
- decryptionPvk
- signatureAlgorithm
- digestAlgorithm
As part of this change, there is also a fix to the redirection behaviour when doing load balancing and HTTPS termination - the application's baseUrl is used to generate the callback URL. For properly configured Backstage installations, no changes are necessary, and the baseUrl is respected.
.changeset/friendly-numbers-accept.md
+20
View File
@@ -0,0 +1,20 @@
---
'@backstage/config-loader': patch
---
Deprecate `$data` and replace it with `$include` which allows for any type of json value to be read from external files. In addition, `$include` can be used without a path, which causes the value at the root of the file to be loaded.
Most usages of `$data` can be directly replaced with `$include`, except if the referenced value is not a string, in which case the value needs to be changed. For example:
```yaml
# app-config.yaml
foo:
$data: foo.yaml#myValue # replacing with $include will turn the value into a number
$data: bar.yaml#myValue # replacing with $include is safe
# foo.yaml
myValue: 0xf00
# bar.yaml
myValue: bar
```
.changeset/heavy-shirts-nail.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog-backend': patch
---
Change `location_update_log` columns from `nvarchar(255)` to `text`
.changeset/hip-experts-dance.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-catalog-backend': patch
---
An entity A, that exists in the catalog, can no longer be overwritten by registering a different location that also tries to supply an entity with the same kind+namespace+name. Writes of that new entity will instead be rejected with a log message similar to `Rejecting write of entity Component:default/artist-lookup from file:/Users/freben/dev/github/backstage/packages/catalog-model/examples/components/artist-lookup-component.yaml because entity existed from github:https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml`
.changeset/hungry-mice-clap.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-sentry': patch
---
Port to new composability API by exporting new `EntitySentryContent` and `EntitySentryCard` component extensions.
.changeset/kind-buses-change.md
+7
View File
@@ -0,0 +1,7 @@
---
'@backstage/backend-common': patch
'@backstage/techdocs-common': patch
'@backstage/plugin-scaffolder-backend': patch
---
Moving the Git actions to isomorphic-git instead of the node binding version of nodegit
.changeset/large-guests-compete.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog': patch
---
Remove the unused dependency to `@backstage/plugin-techdocs`.
.changeset/loud-vans-pretend.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-search': patch
---
Fix Material-UI warning for search filtering
.changeset/mighty-plums-wave.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/backend-common': patch
---
Tweaked development log formatter to include extra fields at the end of each log line
.changeset/nasty-colts-tell.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/cli': patch
---
Add `backend:bundle` command for bundling a backend package with dependencies into a deployment archive.
.changeset/new-horses-protect.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog-backend': patch
---
Add processor for ingesting AWS accounts from AWS Organizations
.changeset/odd-camels-begin.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/backend-common': minor
---
Refactored UrlReader.readTree to be required and accept (url, options)
.changeset/ninety-gifts-guess.md → .changeset/odd-eyes-beg.md
+1 -1
View File
@@ -3,4 +3,4 @@
'@backstage/integration': patch
---
Added the integration package
Provide support for on-prem azure devops
.changeset/six-experts-destroy.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-scaffolder-backend': patch
---
Add config schema for Bitbucket scaffolder
.changeset/swift-ears-fetch.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-pagerduty': patch
---
Optimize empty state image size.
.changeset/tough-jars-share.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-tech-radar': patch
---
Updated example data in `README`.
.github/CODEOWNERS
+2
View File
@@ -8,6 +8,8 @@
/docs/features/techdocs @backstage/techdocs-core
/plugins/cost-insights @backstage/silver-lining
/plugins/cloudbuild @trivago/ebarrios
/plugins/search @backstage/techdocs-core
/plugins/techdocs @backstage/techdocs-core
/plugins/techdocs-backend @backstage/techdocs-core
/packages/techdocs-common @backstage/techdocs-core
/.changeset/cost-insights-* @backstage/silver-lining
.github/styles/vocab.txt
+53 -16
View File
@@ -1,4 +1,6 @@
abc
adamdmharvey
andrewthauer
Apdex
api
Api
@@ -9,27 +11,33 @@ async
Avro
backrub
Balachandran
benjdlambert
Bigtable
Billett
Blackbox
bool
boolean
builtins
Chai
changeset
changesets
Changesets
changset
chanwit
Chanwit
ci
cisphobia
cissexist
classname
cli
cloudbuild
cncf
codeblocks
Codecov
codehilite
Codehilite
codeowners
composability
composable
config
Config
configmaps
@@ -38,10 +46,13 @@ const
cookiecutter
css
dariddler
dataflow
deadnaming
destructured
dev
devops
devs
dhenneke
discoverability
Discoverability
dls
@@ -50,7 +61,9 @@ Dockerfile
Dockerize
dockerode
Docusaurus
eg
Dominik
dtuite
dzolotusky
Ek
env
Env
@@ -59,23 +72,30 @@ facto
failover
Figma
Firekube
Fiverr
freben
Fredrik
github
Github
GitHub
gitlab
Gitlab
GitLab
Grafana
graphql
graphviz
Gustavsson
Hackathons
haproxy
Henneke
heroku
Heroku
horizontalpodautoscalers
Hostname
http
https
Iain
img
incentivised
inlined
inlinehilite
interop
javascript
@@ -92,8 +112,8 @@ learnings
lerna
Lerna
magiclink
Maintainership
mailto
maintainership
Malus
md
microsite
@@ -110,31 +130,37 @@ msw
namespace
namespaces
Namespaces
namespacing
neuro
newrelic
nginx
Niklas
nodegit
nohoist
nonces
npm
nvarchar
nvm
oauth
Oauth
OAuth
oidc
Okta
Oldsberg
onboarding
Onboarding
pagerduty
parallelization
Patrik
Phoen
plantuml
Pomaceous
postgres
postpack
pre
prebaked
preconfigured
prepack
Preprarer
Prerequisities
productional
Protobuf
proxying
@@ -158,58 +184,69 @@ Rollup
Rosaceae
rst
rsync
rugvip
ruleset
sam
scaffolded
scaffolder
Scaffolder
semlas
semver
Serverless
Sinon
smartsymobls
Snyk
sourcemaps
sparklines
Spotifiers
spotify
Spotify
sqlite
squidfunk
src
stefanalund
subkey
subtree
superfences
Superfences
superset
talkdesk
Talkdesk
tasklist
techdocs
Telenor
templated
templater
Templater
templaters
Templaters
Thauer
theres
toc
tolerations
Tolerations
toolchain
toolsets
tooltip
tooltips
touchpoints
transpiled
transpilation
Tuite
ui
untracked
upvote
url
utils
validators
varchar
Voi
Wealthsimple
Weaveworks
Webpack
www
WWW
xyz
yaml
Zalando
Zhou
Billett
cloudbuild
Grafana
Iain
Snyk
www
WWW
Zolotusky
zoomable
.github/workflows/changeset.yml
+1 -1
View File
@@ -19,4 +19,4 @@ jobs:
# Calls out to `changeset version`, but also runs prettier
version: yarn release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
.github/workflows/ci.yml
+3
View File
@@ -72,6 +72,9 @@ jobs:
- name: prettier
run: yarn prettier:check
- name: validate config
run: yarn backstage-cli config:check
- name: lint
run: yarn lerna -- run lint --since origin/master
.github/workflows/codeql-analysis.yml
+5 -5
View File
@@ -11,6 +11,11 @@ on:
pull_request:
# The branches below must be a subset of the branches above
branches: [master]
# https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#scanning-pull-requests
paths-ignore:
- '**/*.md'
- '**/*.yml'
- '**/*.yaml'
schedule:
- cron: '0 8 * * 6'
@@ -36,11 +41,6 @@ jobs:
# a pull request then we can checkout the head.
fetch-depth: 2
# If this run was triggered by a pull request event, then checkout
# the head of the pull request instead of the merge commit.
- run: git checkout HEAD^2
if: ${{ github.event_name == 'pull_request' }}
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v1
.github/workflows/e2e-win.yml
+1 -1
View File
@@ -32,7 +32,7 @@ jobs:
with:
node-version: ${{ matrix.node-version }}
- name: Add msbuild to PATH
uses: microsoft/setup-msbuild@v1.0.1
uses: microsoft/setup-msbuild@v1.0.2
- name: yarn install
run: yarn install --frozen-lockfile
.github/workflows/master-win.yml
+6 -3
View File
@@ -51,10 +51,13 @@ jobs:
- name: test
run: yarn lerna -- run test
# credit: https://github.com/appleboy/discord-action/issues/3#issuecomment-731426861
- name: Discord notification
if: ${{ failure() }}
uses: Ilshidur/action-discord@0.2.0
env:
DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
with:
args: 'Windows master build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'
run: |
$MESSAGE=@"
{\"content\": \"Windows master build failed https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}\"}
"@
C:\msys64\usr\bin\curl.exe -i -H "Accept: application/json" -H "Content-Type:application/json" -X POST $env:DISCORD_WEBHOOK --data $MESSAGE
.github/workflows/master.yml
+85 -15
View File
@@ -47,6 +47,9 @@ jobs:
run: yarn install --frozen-lockfile
# End of yarn setup
- name: validate config
run: yarn backstage-cli config:check
- name: lint
run: yarn lerna -- run lint
@@ -67,21 +70,6 @@ jobs:
bash <(curl -s https://codecov.io/bash) -f packages/core/coverage/* -F core
bash <(curl -s https://codecov.io/bash) -f packages/core-api/coverage/* -F core-api
# Publishes current version of packages that are not already present in the registry
- name: publish
if: matrix.node-version == '12.x'
run: yarn lerna -- publish from-package --yes
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
# Tags the commit with the version in the core package if the tag doesn't exist
- uses: Klemensas/action-autotag@1.2.3
if: matrix.node-version == '12.x'
with:
GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
package_root: 'packages/core'
tag_prefix: 'v'
- name: Discord notification
if: ${{ failure() }}
uses: Ilshidur/action-discord@0.2.0
@@ -89,3 +77,85 @@ jobs:
DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
with:
args: 'Master build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'
# A separate release build that is only run for commits that are the result of merging the "Version Packages" PR
# We can't re-use the output from the above step, but we'll have a guaranteed node_modules cache and
# only run the build steps that are necessary for publishing
release:
if: ${{ endsWith(github.event.head_commit.message, 'from backstage/changeset-release/master\n\nVersion Packages') }}
needs: build
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [14.x]
env:
CI: 'true'
NODE_OPTIONS: --max-old-space-size=4096
steps:
- uses: actions/checkout@v2
# Beginning of yarn setup, keep in sync between all workflows, see ci.yml
- name: use node.js ${{ matrix.node-version }}
uses: actions/setup-node@v1
with:
node-version: ${{ matrix.node-version }}
registry-url: https://registry.npmjs.org/ # Needed for auth
- name: cache all node_modules
id: cache-modules
uses: actions/cache@v2
with:
path: '**/node_modules'
key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
- name: find location of global yarn cache
id: yarn-cache
if: steps.cache-modules.outputs.cache-hit != 'true'
run: echo "::set-output name=dir::$(yarn cache dir)"
- name: cache global yarn cache
uses: actions/cache@v2
if: steps.cache-modules.outputs.cache-hit != 'true'
with:
path: ${{ steps.yarn-cache.outputs.dir }}
key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
restore-keys: |
${{ runner.os }}-yarn-
- name: yarn install
run: yarn install --frozen-lockfile
# End of yarn setup
- name: build type declarations
run: yarn tsc:full
- name: build packages
run: yarn lerna -- run --ignore example-app build
# Publishes current version of packages that are not already present in the registry
- name: publish
run: yarn lerna -- publish from-package --yes
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
# Creates the next available tag with format "release-<year>-<month>-<day>[.<n>]"
- name: Create a release tag
id: create_tag
run: node scripts/create-release-tag.js
env:
GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
# Convert the newly created tag into a release with changelog information
- name: Create release on GitHub
run: node scripts/create-github-release.js ${{ steps.create_tag.outputs.tag_name }} 1
env:
GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
# Notify everyone about this great new release :D
- name: Discord notification
uses: Ilshidur/action-discord@0.2.0
env:
DISCORD_WEBHOOK: ${{ secrets.DISCORD_RELEASE_WEBHOOK }}
TAG_NAME: ${{ steps.create_tag.outputs.tag_name }}
with:
args: 'A new release has been published! https://github.com/backstage/backstage/releases/tag/{{TAG_NAME}}'
.github/workflows/nightly.yml
+1 -1
View File
@@ -62,7 +62,7 @@ jobs:
- name: prepare nightly release
run: yarn changeset version --snapshot nightly
# Publishes the nightly release to NPM, by using tag we make sure the release is
# Publishes the nightly release to npm, by using tag we make sure the release is
# not flagged as the latest release, which means that people will not get this
# version of the package unless requested explicitly
- name: publish nightly release
.github/workflows/techdocs-project-board.yml
+1 -1
View File
@@ -1,7 +1,7 @@
name: Automatically add new TechDocs Issues and PRs to the GitHub project board
# Development of TechDocs in Backstage is managed by this Kanban board - https://github.com/orgs/backstage/projects/1
# New issues and PRs with TechDocs in their title or docs-like-code label will be added to the board.
# Caveat: New PRs created from forks will not be added since GitHub actions don't share credentials with forks.
# Caveat: New PRs created from forks will not be added since GitHub Actions don't share credentials with forks.
on:
issues:
.gitignore
+1
View File
@@ -96,6 +96,7 @@ typings/
.nuxt
dist
dist-types
dist-workspace
# Gatsby files
.cache/
.yarnrc
+1 -1
View File
@@ -6,4 +6,4 @@ registry "https://registry.npmjs.org/"
disable-self-update-check true
lastUpdateCheck 1580389148099
yarn-path ".yarn/releases/yarn-1.22.1.js"
network-timeout 600000
network-timeout 300000
ADOPTERS.md
+19 -15
View File
@@ -1,15 +1,19 @@
| Organization | Contact | Description of Use |
| -------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| [Spotify](https://www.spotify.com) | [@stefanalund](https://github.com/stefanalund) | Main interface towards all of Spotify's infrastructure and technical documentation. |
| [bol.com](https://www.bol.com) | [@RoyJacobs](https://github.com/RoyJacobs) | Initial work being done to unify platform tooling. |
| [DFDS](https://www.dfds.com) | [@carlsendk](https://github.com/carlsendk) | V2 self-service platform. |
| [Roadie](https://roadie.io) | [@dtuite](https://github.com/dtuite) | Hosted, managed Backstage with easy set-up |
| [Roku](https://www.roku.com) | [@timurista](https://github.com/timurista) | Initial work on Cloud engineering service platform. |
| [SDA SE](https://sda.se) | [@Fox32](https://github.com/Fox32) | Central place for developing and sharing services in our insurance ecosystem. |
| [H-E-B](https://www.heb.com) | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform. |
| [American Airlines](https://www.aa.com) | [@paulpach](https://github.com/paulpach) | Central place for developers to develop and maintain applications |
| [Kiwi.com](https://kiwi.com) | [@aexvir](https://github.com/aexvir) | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry. |
| [Voi](https://www.voiscooters.com/) | [@K-Phoen](https://github.com/K-Phoen) | Developer portal, main gateway to our infrastructure, documentation and internal tooling. |
| [Talkdesk](https://www.talkdesk.com) | [@jaime-talkdesk](https://github.com/jaime-talkdesk) | Initial work for Engineering Portal and Self Provisioning to R&D |
| [Wealthsimple](https://www.wealthsimple.com) | [@andrewthauer](https://github.com/andrewthauer) | Developer portal, service catalog, documentation and tooling |
| [Grab](https://www.grab.com) | [@althafh](https://github.com/althafh) | Initial work as a unified interface for all of Grab's internal tooling |
| Organization | Contact | Description of Use |
| -------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| [Spotify](https://www.spotify.com) | [@leemills83](https://github.com/leemills83) | Main interface towards all of Spotify's infrastructure and technical documentation. |
| [bol.com](https://www.bol.com) | [@RoyJacobs](https://github.com/RoyJacobs) | Initial work being done to unify platform tooling. |
| [DFDS](https://www.dfds.com) | [@carlsendk](https://github.com/carlsendk) | V2 self-service platform. |
| [Roadie](https://roadie.io) | [@dtuite](https://github.com/dtuite) | Hosted, managed Backstage with easy set-up |
| [Roku](https://www.roku.com) | [@timurista](https://github.com/timurista) | Initial work on Cloud engineering service platform. |
| [SDA SE](https://sda.se) | [@Fox32](https://github.com/Fox32) | Central place for developing and sharing services in our insurance ecosystem. |
| [H-E-B](https://www.heb.com) | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform. |
| [American Airlines](https://www.aa.com) | [@paulpach](https://github.com/paulpach) | Central place for developers to develop and maintain applications |
| [Kiwi.com](https://kiwi.com) | [@aexvir](https://github.com/aexvir) | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry. |
| [Voi](https://www.voiscooters.com/) | [@K-Phoen](https://github.com/K-Phoen) | Developer portal, main gateway to our infrastructure, documentation and internal tooling. |
| [Talkdesk](https://www.talkdesk.com) | [@jaime-talkdesk](https://github.com/jaime-talkdesk) | Initial work for Engineering Portal and Self Provisioning to R&D |
| [Wealthsimple](https://www.wealthsimple.com) | [@andrewthauer](https://github.com/andrewthauer) | Developer portal, service catalog, documentation and tooling |
| [Grab](https://www.grab.com) | [@althafh](https://github.com/althafh) | Initial work as a unified interface for all of Grab's internal tooling |
| [Telenor Sweden](https://www.telenor.se) | [@O5ten](https://github.com/O5ten) | Building a developer portal for scaffolding projects towards our unified build environment and microservice stacks |
| [Fiverr](https://www.fiverr.com) | [@nirga](https://github.com/nirga) | Unifying separate tools that developers are using today (i.e. monitoring, dead letter queues management, etc.) into a single platform. |
| [Zalando SE](https://www.zalando.de) | [@leviferreira](https://github.com/leviferreira) | Building V2 of the Internal Development Portal. |
| [LegalZoom](https://legalzoom.com) | [@backjo](https://github.com/backjo) | Developer portal - hub for all engineering projects and metadata. |
CHANGELOG.md
+1 -5
View File
@@ -1,13 +1,9 @@
# Backstage Changelog
This is a best-effort changelog where we manually collect breaking changes. It is not an exhaustive list of all changes or even features added.
This changelog is no longer being updated and will be removed in the future, as each package now has its own changelog instead. It was a best-effort changelog where we manually collected breaking changes during the `v0.1.1-alpha.<n>` releases.
If you encounter issues while upgrading to a newer version, don't hesitate to reach out on [Discord](https://discord.gg/EBHEGzX) or [open an issue](https://github.com/backstage/backstage/issues/new/choose)!
## Next Release
> Collect changes for the next release below
## v0.1.1-alpha.26
### @backstage/cli
CODE_OF_CONDUCT.md
+1 -1
View File
@@ -18,7 +18,7 @@ Harassment includes, but is not limited to:
- Offensive comments related to gender, gender identity and expression, sexual orientation, disability, mental illness, neuro(a)typicality, physical appearance, body size, race, age, regional discrimination, political or religious affiliation
- Unwelcome comments regarding a person’s lifestyle choices and practices, including those related to food, health, parenting, drugs, and employment
- Deliberate misgendering. This includes deadnaming or persistently using a pronoun that does not correctly reflect a person's gender identity. You must address people by the name they give you when not addressing them by their username or handle
- Physical contact and simulated physical contact (eg, textual descriptions like “_hug_” or “_backrub_”) without consent or after a request to stop
- Physical contact and simulated physical contact (e.g., textual descriptions like “_hug_” or “_backrub_”) without consent or after a request to stop
- Threats of violence, both physical and psychological
- Incitement of violence towards any individual, including encouraging a person to commit suicide or to engage in self-harm
- Deliberate intimidation
CONTRIBUTING.md
+33 -21
View File
@@ -6,19 +6,19 @@ Therefore we want to create strong community of contributors -- all working toge
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. ❤️
Backstage is released under the Apache2.0 License, and original creations contributed to this repo are accepted under the same license.
Backstage is released under the Apache 2.0 License, and original creations contributed to this repo are accepted under the same license.
# Types of Contributions
## Types of Contributions
## Report bugs
### Report bugs
No one likes bugs. Report bugs as an issue [here](https://github.com/backstage/backstage/issues/new?template=bug_template.md).
## Fix bugs or build new features
### Fix bugs or build new features
Look through the GitHub issues for [bugs](https://github.com/backstage/backstage/labels/bugs), [good first issues](https://github.com/backstage/backstage/labels/good%20first%20issue) or [help wanted](https://github.com/backstage/backstage/labels/help%20wanted).
## Build a plugin
### Build a plugin
The value of Backstage grows with every new plugin that gets added. Wouldn't it be fantastic if there was a plugin for every infrastructure project out there? We think so. And we would love your help.
@@ -26,27 +26,27 @@ A great reference example of a plugin can be found on [our blog](https://backsta
What kind of plugins should/could be created? Some inspiration from the 120+ plugins that we have developed inside Spotify can be found [here](https://backstage.io/demos), but we will keep a running list of suggestions labeled with [[plugin]](https://github.com/backstage/backstage/labels/plugin).
## Suggesting a plugin
### Suggesting a plugin
If you start developing a plugin that you aim to release as open source, we suggest that you create a [new Issue](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development.
You can also use this process if you have an idea for a good plugin but you hope that someone else will pick up the work.
## Adding Non-code Contributions
### Adding Non-code Contributions
Since there is such a large landscape of possible development, build, and deployment environments, we welcome community contributions in these areas in the [`/contrib`](https://github.com/backstage/backstage/tree/master/contrib) folder of the project. This is an excellent place to put things that help out the community at large, but which may not fit within the scope of the core product to support natively. Here, you will find Helm charts, alternative Docker images, and much more.
## Write Documentation
### Write Documentation
The current documentation is very limited. Help us make the `/docs` folder come alive.
## Contribute to Storybook
### Contribute to Storybook
We think the best way to ensure different plugins provide a consistent experience is through a solid set of reusable UI/UX components. Backstage uses [Storybook](http://backstage.io/storybook).
Either help us [create new components](https://github.com/backstage/backstage/labels/help%20wanted) or improve stories for the existing ones (look for files with `*.stories.tsx`).
## Submit Feedback
### Submit Feedback
The best way to send feedback is to file [an issue](https://github.com/backstage/backstage/issues).
@@ -58,47 +58,59 @@ If you are proposing a feature:
- Remember that this is a volunteer-driven project, and that contributions
are welcome :)
## Add your company to ADOPTERS
### Add your company to ADOPTERS
Have you started using Backstage? Adding your company to [ADOPTERS](ADOPTERS.md) really helps the project.
# Get Started!
## Get Started!
So...feel ready to jump in? Let's do this. 👏🏻💯
Start by reading our [Getting Started](https://backstage.io/docs/getting-started/) page. If you need help, just jump into our [Discord chatroom](https://discord.gg/MUpMjP2).
# Coding Guidelines
## Coding Guidelines
All code is formatted with `prettier` using the configuration in the repo. If possible we recommend configuring your editor to format automatically, but you can also use the `yarn prettier --write <file>` command to format files.
A consistent coding style is included via [EditorConfig](https://editorconfig.org/) with the file [`.editorconfig`](.editorconfig) at the root of the repo. Depending on your editor of choice, it will either support it out of the box or you can [download a plugin](https://editorconfig.org/#download) for the config to be applied.
If you're contributing to the backend or CLI tooling, be mindful of cross-platform support. [This](https://shapeshed.com/writing-cross-platform-node/) blog post is a good guide of what to keep in mind when writing cross-platform NodeJS.
Also be sure to skim through our [ADRs](https://github.com/backstage/backstage/tree/master/docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for.
If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command.
# Creating Changesets
## Creating Changesets
We use [changesets](https://github.com/atlassian/changesets) to help us prepare releases. It helps us make sure that every package affected by a change gets a proper version number and an entry in its `CHANGELOG.md`. To make the process of generating releases easy. it helps when contributors include changesets with their pull requests.
We use [changesets](https://github.com/atlassian/changesets) to help us prepare releases. They help us make sure that every package affected by a change gets a proper version number and an entry in its `CHANGELOG.md`. To make the process of generating releases easy, it helps when contributors include changesets with their pull requests.
## To create a changeset
### When to use a changeset?
Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage stability index](https://backstage.io/docs/overview/stability-index) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs.
In general, changesets are not needed for the documentation, build utilities, contributed samples in `contrib/`, or the [example `packages/app`](packages/app).
### How to create a changeset
1. Run `yarn changeset`
2. Select which packages you want to include a changeset for
3. Select impact of change that you're introducing (minor, major or patch)
3. Select impact of change that you're introducing (patch, minor, or major)
4. Add generated changeset to Git
5. Push the commit with your changeset to the branch associated with your PR
6. Accept our gratitude for making the release process easier on the maintainer
6. Accept our gratitude for making the release process easier on the maintainers
For more information, checkout [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in changesets repository.
For more information, checkout [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in the changesets repository.
# Code of Conduct
## Merging to Master
For those contributors who have earned write access to the repository, when a pull request is approved, in general we prefer the author of the PR to perform the merge themselves. This allows them to own accountability for the change and they likely know best how or when to address pending fixes or additional follow-ups. In this way, we all help contribute to the project's successful outcomes.
## Code of Conduct
This project adheres to the [Spotify FOSS Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.
[code-of-conduct]: https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md
# Security Issues?
## Security Issues?
See [SECURITY](SECURITY.md).
GOVERNANCE.md
+31 -38
View File
@@ -1,52 +1,45 @@
# Backstage Governance
# Process for becoming a maintainer
This document defines project governance for the project.
## a) Your organization is not yet a maintainer
## Maintainers
- Express interest to the sponsors that your organization is interested in becoming a maintainer. Becoming a maintainer generally means that you are going to be spending substantial time on Backstage for the foreseeable future. You should have domain expertise and be extremely proficient in TypeScript.
- We will expect you to start contributing increasingly complicated PRs, under the guidance of the existing maintainers.
- We may ask you to do some PRs from our backlog.
- As you gain experience with the code base and our standards, we will ask you to do code reviews for incoming PRs.
- After a period of approximately 2-3 months of working together and making sure we see eye to eye, the existing sponsors and maintainers will confer and decide whether to grant maintainer status or not. We make no guarantees on the length of time this will take, but 2-3 months is the approximate goal.
Backstage Maintainers have write access to the Backstage GitHub repository https://github.com/backstage/backstage. The current maintainers can be found in [MAINTAINERS](MAINTAINERS.md).
This privilege is granted with some expectation of responsibility: maintainers are people who care about the Backstage project and want to help it grow and improve. A maintainer is not just someone who can make changes, but someone who has demonstrated his or her ability to collaborate with the team, get the most knowledgeable people to review code, contribute high-quality code, and follow through to fix issues (in code or tests).
A maintainer is a contributor to the Backstage project's success and a citizen helping the project succeed.
## Becoming a Maintainer
## b) Your organization is currently a maintainer
To become a maintainer you need to demonstrate the following:
- commitment to the project
- participate in discussions, contributions, code reviews for 3 months or more,
- perform code reviews for 10 non-trivial pull requests,
- contribute 10 non-trivial pull requests and have them merged into master,
- ability to write good code,
- ability to collaborate with the team,
- understanding of how the team works (policies, processes for testing and code review, etc),
- understanding of the project's code base and coding style.
- First decide whether your organization really needs more people with maintainer access. Valid reasons are "blast radius", a large organization that is working on multiple unrelated projects, etc.
- Contact a sponsor for your organization and express interest.
- Start doing PRs and code reviews under the guidance of your maintainer.
- After a period of 1-2 months the existing sponsors will discuss granting maintainer access.
- Maintainer access can be upgraded to sponsor access after another conference of the existing sponsors.
## Changes in Maintainership
# Maintainer responsibilities
A new maintainer must be proposed by an existing maintainer by opening an issue (with title `Maintainer Nomination`) to the Backstage GitHub repository (https://github.com/backstage/backstage) containing the following information:
- Monitor email aliases.
- Monitor Discord (delayed response is perfectly acceptable).
- Triage GitHub issues and perform pull request reviews for other maintainers and the community.
- Triage build issues - file issues for known flaky builds or bugs, and either fix or find someone to fix any master build breakages.
- During GitHub issue triage, apply all applicable ([labels](https://github.com/backstage/backstage/labels)) to each new issue. Labels are extremely useful for future issue follow up. Which labels to apply is somewhat subjective so just use your best judgment. A few of the most important labels that are not self explanatory are:
- good first issue: Mark any issue that can reasonably be accomplished by a new contributor with this label.
- help wanted: Unless it is immediately obvious that someone is going to work on an issue (and if so assign it), mark it help wanted.
- Make sure that ongoing PRs are moving forward at the right pace or closing them.
- Participate when called upon in the security release process. Note that although this should be a rare occurrence, if a serious vulnerability is found, the process may take up to several full days of work to implement. This reality should be taken into account when discussing time commitment obligations with employers.
- In general, continue to be willing to spend at least 25% of one's time working on Backstage (~1.25 business days per week).
- We currently maintain an "on-call" rotation within the maintainers. Each on-call is 1 week. Although all maintainers are welcome to perform all of the above tasks, it is the on-call maintainer's responsibility to triage incoming issues/questions and marshal ongoing work forward. To reiterate, it is not the responsibility of the on-call maintainer to answer all questions and do all reviews, but it is their responsibility to make sure that everything is being actively covered by someone.
- nominee's first and last name,
- nominee's email address and GitHub user name,
- an explanation of why the nominee should be a maintainer,
- a list of links to non-trivial pull requests (top 10) authored by the nominee.
# When does a maintainer lose maintainer status
Maintainers can be removed by a 2/3 majority vote.
If a maintainer is no longer interested or cannot perform the maintainer duties listed above, they should volunteer to be moved to emeritus status. In extreme cases this can also occur by a vote of the sponsors and maintainers per the voting process below.
## Approving PRs
# Conflict resolution and voting
PRs may be merged after receiving at least one approval from a maintainer.
In general, we prefer that technical issues and maintainer membership are amicably worked out between the persons involved. If a dispute cannot be decided independently, the sponsors and maintainers can be called in to decide an issue. If the sponsors and maintainers themselves cannot decide an issue, the issue will be resolved by voting. The voting process is a simple majority in which each sponsor receives two votes and each maintainer receives one vote.
## GitHub Project Administration
# Adding new projects to the Backstage GitHub organization
Maintainers will be added to the collaborators list of the Backstage repository with "Write" access.
## Changes in Governance
All changes in Governance require a 2/3 majority vote.
## Other Changes
Unless specified above, all other changes to the project require a 2/3 majority vote.
Additionally, any maintainer may request that any change require a 2/3 majority vote.
New projects will be added to the Backstage organization via GitHub issue discussion in one of the existing projects in the organization. Once sufficient discussion has taken place (~3-5 business days but depending on the volume of conversation), the maintainers of the project where the issue was opened (since different projects in the organization may have different maintainers) will decide whether the new project should be added. See the section above on voting if the maintainers cannot easily decide.
MAINTAINERS.md
-21
View File
@@ -1,21 +0,0 @@
# Maintainers
- See [CONTRIBUTING.md](CONTRIBUTING.md) for general contribution guidelines.
## Current Maintainers 🏓
- Stefan Ålund - Spotify (GitHub: @stefanalund, Discord: @stalund)
- Patrik Oldsberg - Spotify (GitHub: @Rugvip, Discord: @Rugvip)
- Fredrik Adelöw - Spotify (GitHub: @freben, Discord: @freben)
- Ben Lambert - Spotify (GitHub: @benjdlambert, Discord: @blam)
## Plugin maintainers 🧩
Teams and individuals that maintain a plugin (or another non-core module of the code) can get write access to that part of the repo using CODEOWNERS.
## Hall of Fame 👏
People that have made significant contributions to the project and earned write access:
- Andrew Thauer - Wealthsimple (GitHub: @andrewthauer)
- Oliver Sand - SDA SE (GitHub: @Fox32)
OWNERS.md
+27
View File
@@ -0,0 +1,27 @@
- See [CONTRIBUTING.md](CONTRIBUTING.md) for general contribution guidelines.
- See [GOVERNANCE.md](GOVERNANCE.md) for governance guidelines and responsibilities.
This page lists all active sponsors and maintainers.
# Sponsors
- Niklas Gustavsson ([protocol7](https://github.com/protocol7)) (ngn@spotify.com)
- Dave Zolotusky ([dzolotusky](https://github.com/dzolotusky)) (dzolo@spotify.com)
- Lee Mills ([leemills83](https://github.com/leemills83)) (leem@spotify.com)
# Maintainers
- Patrik Oldsberg ([rugvip](https://github.com/rugvip)) (Discord: @Rugvip)
- Fredrik Adelöw ([freben](https://github.com/freben)) (Discord: @freben)
- Ben Lambert ([benjdlambert](https://github.com/benjdlambert)) (Discord: @blam)
- Stefan Ålund ([stefanalund](https://github.com/stefanalund)) (Discord: @stalund)
# Friends of Backstage
People that have made significant contributions to the project and earned write access.
- Andrew Thauer - Wealthsimple (GitHub: [andrewthauer](https://github.com/andrewthauer))
- Oliver Sand - SDA SE (GitHub: [Fox32](https://github.com/Fox32))
- David Tuite - Roadie (GitHub: [dtuite](https://github.com/dtuite))
- Adam Harvey - DXC Technology (GitHub: [adamdmharvey](https://github.com/adamdmharvey))
- Dominik Henneke - SDA SE (GitHub: [dhenneke](https://github.com/dhenneke))
README.md
+1 -1
View File
@@ -16,7 +16,7 @@
## What is Backstage?
[Backstage](https://backstage.io/) is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure. So your product teams can ship high-quality code quickly — without compromising autonomy.
[Backstage](https://backstage.io/) is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly — without compromising autonomy.
Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.
app-config.yaml
+67 -8
View File
@@ -38,7 +38,7 @@ proxy:
headers:
Authorization:
$env: TRAVISCI_AUTH_TOKEN
travis-api-version: 3
travis-api-version: '3'
'/newrelic/apm/api':
target: https://api.newrelic.com/v2
@@ -46,28 +46,45 @@ proxy:
X-Api-Key:
$env: NEW_RELIC_REST_API_KEY
'/pagerduty':
target: https://api.pagerduty.com
headers:
Authorization:
$env: PAGERDUTY_TOKEN
'/buildkite/api':
target: https://api.buildkite.com/v2/
headers:
Authorization:
$env: BUILDKITE_TOKEN
'/sentry/api':
target: https://sentry.io/api/
allowedMethods: ['GET']
headers:
Authorization:
$env: SENTRY_TOKEN
organization:
name: My Company
# Reference documentation http://backstage.io/docs/features/techdocs/configuration
techdocs:
storageUrl: http://localhost:7000/api/techdocs/static/docs
requestUrl: http://localhost:7000/api/techdocs
storageUrl: http://localhost:7000/api/techdocs/static/docs
builder: 'local' # Alternatives - 'external'
generators:
techdocs: 'docker'
techdocs: 'docker' # Alternatives - 'local'
publisher:
type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
sentry:
organization: my-company
rollbar:
organization: my-company
accountToken:
$env: ROLLBAR_ACCOUNT_TOKEN
# NOTE: The rollbar-backend & accountToken key may be deprecated in the future (replaced by a proxy config)
accountToken: my-rollbar-account-token
lighthouse:
baseUrl: http://localhost:3003
@@ -120,7 +137,7 @@ catalog:
$env: GITHUB_TOKEN
#### Example for how to add your GitHub Enterprise instance using the API:
# - target: https://ghe.example.net
# apiBaseUrl: https://ghe.example.net/api/v3
# apiBaseUrl: https://ghe.example.net/api
# token:
# $env: GHE_TOKEN
ldapOrg:
@@ -140,6 +157,19 @@ catalog:
# dn: ou=access,ou=groups,ou=example,dc=example,dc=net
# options:
# filter: (&(objectClass=some-group-class)(!(groupType=email)))
microsoftGraphOrg:
### Example for how to add your Microsoft Graph tenant
#providers:
# - target: https://graph.microsoft.com/v1.0
# authority: https://login.microsoftonline.com
# tenantId:
# $env: MICROSOFT_GRAPH_TENANT_ID
# clientId:
# $env: MICROSOFT_GRAPH_CLIENT_ID
# clientSecret:
# $env: MICROSOFT_GRAPH_CLIENT_SECRET_TOKEN
# userFilter: accountEnabled eq true and userType eq 'member'
# groupFilter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')
locations:
# Backstage example components
@@ -176,8 +206,18 @@ scaffolder:
api:
token:
$env: AZURE_TOKEN
bitbucket:
api:
host: https://bitbucket.org
username:
$env: BITBUCKET_USERNAME
token:
$env: BITBUCKET_TOKEN
auth:
environment: development
### Providing an auth.session.secret will enable session support in the auth-backend
# session:
# secret: custom session secret
providers:
google:
development:
@@ -222,6 +262,20 @@ auth:
$env: AUTH_OAUTH2_AUTH_URL
tokenUrl:
$env: AUTH_OAUTH2_TOKEN_URL
oidc:
development:
metadataUrl:
$env: AUTH_OIDC_METADATA_URL
clientId:
$env: AUTH_OIDC_CLIENT_ID
clientSecret:
$env: AUTH_OIDC_CLIENT_SECRET
authorizationUrl:
$env: AUTH_OIDC_AUTH_URL
tokenUrl:
$env: AUTH_OIDC_TOKEN_URL
tokenSignedResponseAlg:
$env: AUTH_OIDC_TOKEN_SIGNED_RESPONSE_ALG
auth0:
development:
clientId:
@@ -261,6 +315,9 @@ costInsights:
bigQuery:
name: BigQuery
icon: search
events:
name: Events
icon: data
metrics:
DAU:
name: Daily Active Users
@@ -270,10 +327,12 @@ costInsights:
homepage:
clocks:
- label: UTC
timzone: UTC
timezone: UTC
- label: NYC
timezone: 'America/New_York'
- label: STO
timezone: 'Europe/Stockholm'
- label: TYO
timezone: 'Asia/Tokyo'
pagerduty:
eventsBaseUrl: 'https://events.pagerduty.com/v2'
contrib/chart/backstage/templates/backend-secret.yaml
+1
View File
@@ -20,4 +20,5 @@ stringData:
AZURE_TOKEN: {{ .Values.auth.azure.api.token }}
NEW_RELIC_REST_API_KEY: {{ .Values.auth.newRelicRestApiKey }}
TRAVISCI_AUTH_TOKEN: {{ .Values.auth.travisciAuthToken }}
PAGERDUTY_TOKEN: {{ .Values.auth.pagerdutyToken }}
{{- end }}
contrib/chart/backstage/values.yaml
+1
View File
@@ -250,3 +250,4 @@ auth:
gitlabToken: g
newRelicRestApiKey: r
travisciAuthToken: fake-travis-ci-auth-token
pagerdutyToken: h
contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md
+2 -2
View File
@@ -3,7 +3,7 @@
ExampleComponent.tsx reference
```tsx
import React, { FC } from 'react';
import React from 'react';
import { Typography, Grid } from '@material-ui/core';
import {
InfoCard,
@@ -18,7 +18,7 @@ import {
import { useApi } from '@backstage/core-api';
import ExampleFetchComponent from '../ExampleFetchComponent';
const ExampleComponent: FC<{}> = () => {
const ExampleComponent = () => {
const identityApi = useApi(identityApiRef);
const userId = identityApi.getUserId();
const profile = identityApi.getProfile();
contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md
+3 -3
View File
@@ -3,7 +3,7 @@
ExampleFetchComponent.tsx reference
```tsx
import React, { FC } from 'react';
import React from 'react';
import { useAsync } from 'react-use';
import Alert from '@material-ui/lab/Alert';
import {
@@ -57,7 +57,7 @@ type DenseTableProps = {
viewer: Viewer;
};
export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
export const DenseTable = ({ viewer }: DenseTableProps) => {
const columns: TableColumn[] = [
{ title: 'Name', field: 'name' },
{ title: 'Created', field: 'createdAt' },
@@ -76,7 +76,7 @@ export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
);
};
const ExampleFetchComponent: FC<{}> = () => {
const ExampleFetchComponent = () => {
const auth = useApi(githubAuthApiRef);
const { value, loading, error } = useAsync(async (): Promise<any> => {
docs/FAQ.md
+74 -16
View File
@@ -48,10 +48,9 @@ source candidates. (And we'll probably end up writing some brand new ones, too.)
### What's the roadmap for Backstage?
We envision three phases, which you can learn about in
[our project roadmap](https://github.com/backstage/backstage#project-roadmap).
Even though the open source version of Backstage is relatively new compared to
our internal version, we have already begun work on various aspects of all three
phases. Looking at the
[our project roadmap](overview/roadmap.md). Even though the open source version
of Backstage is relatively new compared to our internal version, we have already
begun work on various aspects of all three phases. Looking at the
[milestones for active issues](https://github.com/backstage/backstage/milestones)
will also give you a sense of our progress.
@@ -115,10 +114,65 @@ type of content. Plugins all use a common set of platform APIs and reusable UI
components. Plugins can fetch data either from the backend or an API exposed
through the proxy.
Learn more about
[the different components](https://github.com/backstage/backstage#overview) that
Learn more about [the different components](overview/what-is-backstage.md) that
make up Backstage.
### How do I keep my Backstage app up to date?
In many ways one can view Backstage as a library rather than an application or
service. The `@backstage/create-app` tool that is used to create your own
Backstage app is similar to
[`create-react-app`](https://github.com/facebook/create-react-app) in that it
gives you a starting point. The code you get is meant to be evolved, and most of
the functionality you get out of the box is brought in via npm dependencies.
Keeping your app up to date generally means keeping your dependencies up to
date. The Backstage CLI provides a command to help you with that. Simply run
`yarn backstage-cli versions:bump` at the root of your repo, and the latest
versions of all Backstage packages will be installed.
While staying up to date with new releases and changes will keep your app up to
date, it can often be convenient to use the changes done to the
`@backstage/create-app` template as another method to stay up to date. For that
purpose, any changes done to the template are documented along with upgrade
instructions in the
[changelog](https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md)
of the `@backstage/create-app` package.
### Why can't I dynamically install plugins without modifications the app?
This decision is part of the core architecture and development flow of
Backstage. Plugins have a lot of freedom in what they provide and how they are
integrated into the app, and it would therefore add a lot of complexity to allow
plugins to be integrated via configuration the same way as they can be
integrated with code.
By bundling all plugins and their dependencies into one app bundle it is also
possible to do significant optimizations to the app load time by allowing
plugins to share dependencies between each other when possible. This contributes
to Backstage being fast, which is an important part of the user and developer
experience.
### Why are there no published Docker images or helm charts for Backstage?
As mentioned above, Backstage is not a packaged service that you can use out of
the box. In order to get started with Backstage you need to use the
`@backstage/create-app` package to create and customize your own Backstage app.
In order to build a Docker image from your own app, you can use the
`yarn build-image` command which is included out of the box in the app template.
By default this image will bundle up both the frontend and the backend into a
single image that you can deploy using your favorite tooling.
There are also some examples that can help you deploy Backstage to kubernetes in
the
[contrib](https://github.com/backstage/backstage/tree/master/contrib/kubernetes)
folder.
It is possible that example images will be provided in the future, which can be
used to quickly try out a small subset of the functionality of Backstage, but
these would not be able to provide much more functionality on top of what you
can see on a demo site.
### Do I have to write plugins in TypeScript?
No, you can use JavaScript if you prefer. We want to keep the Backstage core
@@ -126,17 +180,17 @@ APIs in TypeScript, but aren't forcing it on individual plugins.
### How do I find out if a plugin already exists?
Before you write a plugin,
You can browse and search for all available plugins in the
[Plugin Marketplace](https://backstage.io/plugins).
If you can't find it in the marketplace, before you write a plugin
[search the plugin issues](https://github.com/backstage/backstage/issues?q=is%3Aissue+label%3Aplugin+)
to see if it already exists or is in the works. If no one's thought of it yet,
great! Open a new issue as
to see if is in the works. If no one's thought of it yet, great! Open a new
issue as
[a plugin suggestion](https://github.com/backstage/backstage/issues/new/choose)
and describe what your plugin will do. This will help coordinate our
contributors' efforts and avoid duplicating existing functionality.
You can browse and search for all available plugins in the
[Plugin Marketplace](https://backstage.io/plugins).
### Which plugin is used the most at Spotify?
By far, our most-used plugin is our TechDocs plugin, which we use for creating
@@ -182,6 +236,10 @@ 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.
For more information, see our
[Owners](https://github.com/backstage/backstage/blob/master/OWNERS.md) and
[Governance](https://github.com/backstage/backstage/blob/master/GOVERNANCE.md).
### Does Spotify provide a managed version of Backstage?
No, this is not a service offering. We build the piece of software, and someone
@@ -215,14 +273,14 @@ data is shared with.
Yes. The core frontend framework could be used for building any large-scale web
application where (1) multiple teams are building separate parts of the app, and
(2) you want the overall experience to be consistent. That being said, in
[Phase 2](https://github.com/backstage/backstage#project-roadmap) of the project
we will add features that are needed for developer portals and systems for
managing software ecosystems. Our ambition will be to keep Backstage modular.
[Phase 2](overview/roadmap.md) of the project we will add features that are
needed for developer portals and systems for managing software ecosystems. Our
ambition will be to keep Backstage modular.
### How can I get involved?
Jump right in! Come help us fix some of the
[early bugs and first issues](https://github.com/backstage/backstage/labels/good%20first%20issue)
[early bugs and good first issues](https://github.com/backstage/backstage/contribute)
or reach [a new milestone](https://github.com/backstage/backstage/milestones).
Or write an open source plugin for Backstage, like this
[Lighthouse plugin](https://github.com/backstage/backstage/tree/master/plugins/lighthouse).
docs/api/utility-apis.md
+2 -2
View File
@@ -33,10 +33,10 @@ hook exported by `@backstage/core`, or the `withApis` HOC if you prefer class
components. For example, the `ErrorApi` can be accessed like this:
```tsx
import React, { FC } from 'react';
import React from 'react';
import { useApi, errorApiRef } from '@backstage/core';
export const MyComponent: FC<{}> = () => {
export const MyComponent = () => {
const errorApi = useApi(errorApiRef);
// Signal to the app that something went wrong, and display the error to the user.
docs/architecture-decisions/adr005-catalog-core-entities.md
+1 -1
View File
@@ -58,7 +58,7 @@ discover existing functionality in the ecosystem.
APIs are implemented by components and make their boundaries explicit. They
might be defined using an RPC IDL (e.g. in Protobuf, GraphQL or similar), a data
schema (e.g. in Avro, TFRecord or similar), or as code interfaces (e.g.
framework APIs in Swift, Kotlin, Java, C++, Typescript etc). In any case, APIs
framework APIs in Swift, Kotlin, Java, C++, TypeScript etc). In any case, APIs
exposed by components need to be in a known machine-readable format so we can
build further tooling and analysis on top.
docs/architecture-decisions/adr006-avoid-react-fc.md
+1 -1
View File
@@ -6,7 +6,7 @@ description: Architecture Decision Record (ADR) log on Avoid React.FC and React.
## Context
Facebook has removed `React.FC` from their base template for a Typescript
Facebook has removed `React.FC` from their base template for a TypeScript
project. The reason for this was that it was found to be an unnecessary feature
with next to no benefits in combination with a few downsides.
docs/assets/software-catalog/bsc-register-2.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 171 KiB

After

Width:  |  Height:  |  Size: 101 KiB

docs/assets/techdocs/architecture-basic.drawio.svg
+462
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 64 KiB

docs/assets/techdocs/architecture-recommended.drawio.svg
+391
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 57 KiB

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

After

Width:  |  Height:  |  Size: 11 KiB

docs/assets/techdocs/techdocs_big_picture.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 111 KiB

docs/auth/auth-backend-classes.md
+121 -44
View File
@@ -6,57 +6,84 @@ description: Documentation on Auth backend classes
## How Does Authentication Work?
The Backstage application can use various authentication providers for
authentication. A provider has to implement an `AuthProviderRouteHandlers`
interface for handling authentication. This interface consists of four methods.
Each of these methods is hosted at an endpoint `/auth/[provider]/method`, where
`method` performs a certain operation as follows:
The Backstage application can use various external authentication providers for
authentication. An external provider is wrapped using an
`AuthProviderRouteHandlers` interface for handling authentication. This
interface consists of four methods. Each of these methods is hosted at an
endpoint (by default) `/api/auth/[provider]/method`, where `method` performs a
certain operation as follows:
```
/auth/[provider]/start -> start
/auth/[provider]/handler/frame -> frameHandler
/auth/[provider]/refresh -> refresh
/auth/[provider]/logout -> logout
/auth/[provider]/start -> Initiate a login from the web page
/auth/[provider]/handler/frame -> Handle a finished authentication operation
/auth/[provider]/refresh -> Refresh the validity of a login
/auth/[provider]/logout -> Log out a logged-in user
```
For more information on how these methods are used and for which purpose, refer
to the [OAuth documentation](oauth.md).
The flow is as follows:
For details on the parameters, input and output conditions for each method,
refer to the type documentation under
`plugins/auth-backend/src/providers/types.ts`.
1. A user attempts to sign in.
2. A popup window is opened, pointing to the `auth` endpoint. That endpoint does
initial preparations and then re-directs the user to an external
authenticator, still inside the popup.
3. The authenticator validates the user and returns the result of the validation
(success OR failure), to the wrapper's endpoint (`handler/frame`).
4. The `handler/frame` rendered b´webpage will issue the appropriate response to
the webpage that opened the popup window, and the popup is closed.
5. The user signs out by clicking on a UI interface and the webpage makes a
request to logout the user.
There are currently two different classes for two authentication mechanisms that
implement this interface: an `OAuthAdapter` for [OAuth](https://oauth.net/2/)
based mechanisms and a `SAMLAuthProvider` for
[SAML](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)
based mechanisms.
[SAML](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
### OAuth mechanisms
If you do not have an `OAuth2` or `SAML` based authentication provider, look in
the section [below](#implementing-your-own-auth-wrapper).
### OAuth Mechanisms
For more information on how these methods are used and for which purpose, refer
to the [OAuth documentation](oauth.md).
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. For a
list of available providers, look at the available wrappers in
`backstage/plugins/auth-backend/src/providers/`.
All of these use the authorization flow of OAuth2 to implement authentication.
All of these use the **authorization flow** of OAuth2 to implement
authentication.
If your authentication provider is any of the above mentioned (except generic
OAuth2) providers, you can configure them by setting the right variables in
`app-config.yaml` under the `auth` section.
If your authentication provider is any of the above mentioned providers, you can
configure them by setting the right variables in `app-config.yaml` under the
`auth` section.
### SAML
The SAML Provider is currently under development. Additional validation and
profile handling is still required before use in production.
To configure the SAML Auth provider, look at the configuration parameters
supported by
[Passport-SAML](https://github.com/node-saml/passport-saml#config-parameter-details)
under the `auth.providers.saml` key
For security reasons, validate that the response from the IdP is indeed signed
by also providing the `cert` configuration.
### Configuration
Each authentication provider (except SAML) needs five parameters: an OAuth
client ID, a client secret, an authorization endpoint and a token endpoint, and
an app origin. The app origin is the URL at which the frontend of the
application is hosted, and it is read from the `app.baseUrl` config. This is
required because the application opens a popup window to perform the
authentication, and once the flow is completed, the popup window sends a
`postMessage` to the frontend application to indicate the result of the
operation. Also this URL is used to verify that authentication requests are
coming from only this endpoint.
client ID, a client secret, an authorization endpoint, a token endpoint, and an
app origin. The app origin is the URL at which the frontend of the application
is hosted, and it is read from the `app.baseUrl` config. This is required
because the application opens a popup window to perform the authentication, and
once the flow is completed, the popup window sends a `postMessage` to the
frontend application to indicate the result of the operation. Also this URL is
used to verify that authentication requests are coming from only this endpoint.
These values are configured via the `app-config.yaml` present in the root of
your app folder.
@@ -82,23 +109,68 @@ auth:
development:
clientId:
$env:
saml:
entryPoint:
$env: AUTH_SAML_ENTRY_POINT
issuer:
$env: AUTH_SAML_ISSUER
...
```
## Technical Notes
## Implementing Your Own Auth Wrapper
### OAuthEnvironmentHandler
The core interface of any auth wrapper is the `AuthProviderRouteHandlers`
interface. This interface has four methods corresponding to the API described in
the initial section. Any auth wrapper will have to implement this interface.
The concept of an "env" is core to the way the auth backend works. It uses an
When initiating a login, a pop-up window is created by the frontend, to allow
the user to initiate a login. This login request is done to the `/start`
endpoint which is handled by the `start` method.
The `start` method re-directs to the external auth provider who authenticates
the request and re-directs the request to the `/frame/handler` endpoint, which
is handled by the `frameHandler` method.
The `frameHandler` returns an HTML response, containing a script that does a
`postMessage` to the frontend's window, containing the result of the request.
The `WebMessageResponse` type is the message sent by the `postMessage` to the
frontend.
A `postMessageResponse` utility function wraps the logic of generating a
`postMessage` response that ensures that CORS is successfully handled. This
function takes an `express.Response`, a `WebMessageResponse` and the URL of the
frontend (`appOrigin`) as parameters and return an HTML page with the script and
the message.
### OAuth Wrapping Interfaces.
Each OAuth external provider is supported by a corresponding
[Passport](https://github.com/jaredhanson/passport) strategy. For a generic
OAuth2 provider, passport has a `passport-oauth2` strategy. The strategy class
handles the implementation details of working with each provider.
Each strategy is wrapped by an `OAuthHandlers` interface.
This interface cannot be directly used as an Express HTTP request handler. To do
so, `OAuthHandlers` are wrapped in an `OAuthAdapter`, which implements the
`AuthProviderRouterHandlers` interface.
#### Env
The concept of an `env` is core to the way the auth backend works. It uses an
`env` query parameter to identify the environment in which the application is
running (`development`, `staging`, `production`, etc). Each runtime can support
multiple environments at the same time and the right handler for each request is
identified and dispatched to based on the `env` parameter. All
`AuthProviderRouteHandlers` are wrapped within an `OAuthEnvironmentHandler`.
running (`development`, `staging`, `production`, etc). Each runtime can
simultaneously support multiple environments at the same time and the right
handler for each request is identified and dispatched to, based on the `env`
parameter.
To instantiate multiple OAuth providers for different environments, use
`OAuthEnvironmentHandler` is a utility wrapper for an `OAuthHandlers` that
implements the `AuthProviderRouteHandlers` interface while supporting multiple
`env`s.
To instantiate OAuth providers (the same but for different environments), use
`OAuthEnvironmentHandler.mapConfig`. It's a helper to iterate over a
configuration object that is a map of environment to configurations. See one of
configuration object that is a map of environments to configurations. See one of
the existing OAuth providers for an example of how it is used.
Given the following configuration:
@@ -113,13 +185,18 @@ production:
```
The `OAuthEnvironmentHandler.mapConfig(config, envConfig => ...)` call will
split the `config` by the top level `development` and `production` keys, and
pass on each block as `envConfig`.
split the config by the top level `development` and `production` keys, and pass
on each block as `envConfig`.
For a list of currently available providers, look in the `factories` module
located in `plugins/auth-backend/src/providers/factories.ts`
For convenience, the `AuthProviderFactory` is a factory function that has to be
implemented which can then generate a `AuthProviderRouteHandlers` for a given
provider.
### OAuth2 provider
All of the supported providers provide an `AuthProviderFactory` that returns an
`OAuthEnvironmentHandler`, capable of handling authentication for multiple
environments.
### OAuth2 Provider
The `oauth2` provider abstracts a generic **OAuth2 + OIDC** based authentication
provider. What this means is that after the application has been given
docs/auth/index.md
+1 -1
View File
@@ -93,6 +93,6 @@ sign-in methods.
More details are provided in dedicated sections of the documentation.
- [OAuth](./oauth.md): Description of the generic OAuth flow implemented by the
[auth-backend](../../plugins/auth-backend).
[auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend).
- [Glossary](./glossary.md): Glossary of some common terms related to the auth
flows.
docs/cli/commands.md
+606
View File
@@ -0,0 +1,606 @@
---
id: commands
title: Commands
description: Descriptions of all commands available in the CLI.
---
This page lists all commands provided by the Backstage CLI, what they're for,
and where to use them.
The documentation for each command begins with specifying its scope, this
indicates where the command should be used by selecting from the following list:
- `app` - A frontend app package, such as `packages/app`.
- `backend` - A backend package, such as `packages/backend`.
- `frontend-plugin` - A frontend plugin package.
- `backend-plugin` - A backend plugin package.
- `root` - The monorepo root.
- `any` - Any kind of package, but not the repo root.
## help
This command displays a help summary or detailed help screens for each command.
Below is a cleaned up output of `yarn backstage-cli --help`.
```text
app:build Build an app for a production release
app:diff Diff an existing app with the creation template
app:serve Serve an app for local development
backend:build Build a backend plugin
backend:bundle Bundle the backend into a deployment archive
backend:build-image Bundles the package into a docker image
backend:dev Start local development server with HMR for the backend
plugin:build Build a plugin
plugin:diff Diff an existing plugin with the creation template
plugin:serve Serves the dev/ folder of a plugin
build Build a package for publishing
build-workspace Builds a temporary dist workspace from the provided packages
lint Lint a package
test Run tests, forwarding args to Jest, defaulting to watch mode
clean Delete cache directories
create-plugin Creates a new plugin in the current repository
remove-plugin Removes plugin in the current repository
config:print Print the app configuration for the current package
config:check Validate that the given configuration loads and matches schema
versions:bump Bump Backstage packages to the latest versions
versions:check Check Backstage package versioning
prepack Prepares a package for packaging before publishing
postpack Restores the changes made by the prepack command
help [command] display help for command
```
## app:build
Scope: `app`
Builds a bundle of static content from the app, which can then be served via any
static web server such as `nginx`, or via the
[`app-backend`](https://www.npmjs.com/package/@backstage/plugin-app-backend)
plugin directly from a Backstage backend instance.
The command also reads and injects static configuration into the bundle. It is
important to note that when deploying using your own static content hosting
solution, this will be the final configuration used in the frontend unless you
for example hook in configuration loading from the backend. When using the
`nginx` based Dockerfile in this repo along with its included run script,
`APP_CONFIG_` environment variables will be injected into the frontend, and when
serving using the `app-backend` plugin, the configuration is completely injected
from the backend and the configuration at the time of calling this command will
not be used.
Note that even when injecting configuration at runtime, it is not possible to
change the base path of the app. For example, if you at build time have
`app.baseUrl` set to `http://dev-app.com/my-app`, you can change that to
`https://prod-app.com/my-app`, but not to `https://prod-app.com`, as that would
change the path.
During the build, the following variables are set:
```java
process.env.NODE_ENV = 'production';
process.env.BUILD_INFO = {
cliVersion: '0.4.0', // The version of the CLI package
gitVersion: 'v0.4.0-86-ge54815618', // output of `git describe --always`
packageVersion: '1.0.5', // The version of the app package itself
timestamp: 1678900000000, // Date.now() when the build started
commit: 'e548156182a973ed4b459e18533afc22c85ffff8', // output of `git rev-parse HEAD`
};
```
Some CI environments do not properly report correct resource limits, potentially
leading to errors such as `ENOMEM` during compilation. If you run into this
issue you can limit the parallelization of the build process by setting the
environment variable `BACKSTAGE_CLI_BUILD_PARALLEL`, which is forwarded to the
[`terser-webpack-plugin`](https://github.com/webpack-contrib/terser-webpack-plugin#parallel).
You can set it to `false` or `1` to completely disable parallelization, but
usually a low value such as `2` is enough.
```text
Usage: backstage-cli app:build
Options:
--stats Write bundle stats to output directory
--config &lt;path&gt; Config files to load instead of app-config.yaml (default: [])
-h, --help display help for command
```
## app:diff
Scope: `app`
Diff an existing app with the template used in `@backstage/create-app`. This
will verify that your app package has not diverged from the template, and can be
useful to run after updating the version of `@backstage/cli` in your app.
This command is experimental and may be removed in the future.
```text
Usage: backstage-cli app:diff
Options:
--check Fail if changes are required
--yes Apply all changes
-h, --help display help for command
```
## app:serve
Scope: `app`
Serve an app for local development. This starts up a local development server,
using a bundling configuration that is quite similar to that of the `app:build`
command, but with development features such as React Hot Module Replacement,
faster sourcemaps, no minification, etc.
The static configuration is injected into the frontend, but it does not support
watching, meaning that changes in for example `app-config.yaml` are not
reflected until the serve process is restarted.
During the build, the following variables are set:
```java
process.env.NODE_ENV = 'development';
process.env.BUILD_INFO = { /* See app:build */ };
```
The server listening configuration is controlled through the static
configuration. The `app.baseUrl` determines the listening host and port, as well
as whether HTTPS is used or not. It is also possible to override the listening
host and port if needed by setting `app.listen.host` and `app.listen.port`.
```text
Usage: backstage-cli app:serve [options]
Options:
--check Enable type checking and linting
--config &lt;path&gt; Config files to load instead of app-config.yaml (default: [])
-h, --help display help for command
```
## backend:build
Scope: `backend-plugin`
This builds a backend package for publishing and use in production. The build
output is written to `dist/`. Be sure to list any additional file that the
package depends on at runtime in the `"files"` field inside `package.json`, a
common example being the `migrations` directory.
```text
Usage: backstage-cli backend:build [options]
Options:
-h, --help display help for command
```
## backend:bundle
Scope: `backend`
Bundle the backend and all of its local dependencies into a deployment archive.
The archive is written to `dist/bundle.tar.gz`, and contains the packaged
version of all dependencies of the target package, along with the target package
itself. The layout of the packages in the archive is the same as the directory
layout in the target monorepo, and the bundle also contains the root
`package.json` and `yarn.lock`.
To use the bundle, extract it into a target directory, run
`yarn install --production`, and then start the target backend package using for
example `node package/backend`.
The `dist/bundle.tar.gz` is accompanied by a `dist/skeleton.tar.gz`, which has
the same layout, but only contains `package.json` files and `yarn.lock`. This
can be used to run a `yarn install` in environments that will benefit from the
caching that this enables, such as Docker image builds. To use the skeleton
archive, simply extract it first, run install, and then extract the main bundle.
The following is an example of a `Dockerfile` that can be used to package the
output of `backstage-cli backend:bundle` into an image:
```Dockerfile
FROM node:14-buster
WORKDIR /app
ADD yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./
RUN yarn install --production --network-timeout 600000 && rm -rf "$(yarn cache dir)"
ADD packages/backend/dist/bundle.tar.gz app-config.yaml ./
CMD node packages/backend
```
```text
Usage: backstage-cli backend:bundle [options]
Bundle the backend into a deployment archive
Options:
--build-dependencies Build all local package dependencies before bundling the backend
-h, --help display help for command
```
## backend:build-image
Scope: `backend`
Builds a Docker image of the backend package, forwarding all unknown options to
`docker image build`. For example:
```bash
yarn backstage-cli backend:build-image --build --tag my-backend-image
```
The image is built using the backend package along with all of its local package
dependencies. It expects to find a `Dockerfile` at the root of the backend
package, which will be used during the build.
The Dockerfile is **NOT** executed within the package or repo itself. Because
the packages in the repo itself are configured for development instead of
production use, the final Docker build happens in a separate temporary
directory, to which the backend package and dependencies have been copied. Only
files listed within the `"files"` field within each package's `package.json` are
copied over, along with the root `package.json`, `yarn.lock`, and any
`app-config.*.yaml` files.
During the build a `skeleton.tar` file is created and put at the repo root. This
file contains the `package.json` of each included package, which together with
the root `package.json` and `yarn.lock` can be used to run a cached
`yarn install` before the full production builds of all the packages are copied
over, providing a significant speedup if Docker build layer caching available.
This command is experimental and we hope to be able to replace it with one that
is less integrated directly with Docker, and also supports multi-stage Docker
builds. It is possible to replicate most of what this command does by manually
building each package, and then use the `build-workspace` to create the
temporary workspace, and finally copy over any additional files to the workspace
and execute the Docker build within it.
```text
Usage: backstage-cli backend:build-image [options]
Options:
--build Build packages before packing them into the image
--backstage-cli-help display help for command
```
## backend:dev
Scope: `backend`, `backend-plugin`
Starts a backend package in development mode, with watch mode enabled for all
local dependencies.
```text
Usage: backstage-cli backend:dev [options]
Options:
--check Enable type checking and linting
--inspect Enable debugger
--config &lt;path&gt; Config files to load instead of app-config.yaml (default: [])
-h, --help display help for command
```
## create-plugin
Scope: `root`
Creates a new plugin within the repository. This command is typically wrapped up
in the root `package.json` to be executed with `yarn create-plugin`, using
options that are appropriate for the organization that owns the app repo. A
recommended scope for internal packages is `@internal`.
```text
Usage: backstage-cli create-plugin [options]
Options:
--backend Create plugin with the backend dependencies as default
--scope &lt;scope&gt; npm scope
--npm-registry &lt;URL&gt; npm registry URL
--no-private Public npm package
-h, --help display help for command
```
## remove-plugin
Scope: `root`
A utility to remove a plugin from a repo, essentially undoing everything that
was done by `create-plugin`.
This is primarily intended as a utility for manual tests and end to end testing
scripts.
```text
Usage: backstage-cli remove-plugin [options]
Options:
-h, --help display help for command
```
## plugin:build
Scope: `frontend-plugin`
Build a frontend plugin for publishing to a package registry. There is no need
to run this command during development or even in CI unless the package is being
published. The `app:bundle` command does not use the output for this command
when bundling local package dependencies.
The output is written to a `dist/` folder. It also outputs type declarations for
the plugin, and therefore requires `yarn tsc` to have been run first. The input
type declarations are expected to be found within `dist-types/` at the root of
the monorepo.
```text
Usage: backstage-cli plugin:build [options]
Options:
-h, --help display help for command
```
## plugin:serve
Scope: `frontend-plugin`
Serves a frontend plugin by itself for isolated development. The serve task
itself is essentially identical to `app:serve`, but the entrypoint is instead
set to the `dev/` folder within the plugin.
The `dev/` folder typically contains a small wrapper script that hooks up any
necessary mock APIs or other things that are needed for the plugin to function.
The `@backstage/dev-utils` package provides utilities to that end.
```text
Usage: backstage-cli plugin:serve [options]
Options:
--check Enable type checking and linting
--config &lt;path&gt; Config files to load instead of app-config.yaml (default: [])
-h, --help display help for command
```
## plugin:diff
Scope: `frontend-plugin`
Compares a frontend plugin to the `create-plugin` template, making sure that it
hasn't diverged from the template and recommending updates when it has. A good
practice is to run this command after updating the version of the CLI in a
project.
```text
Usage: backstage-cli plugin:diff [options]
Options:
--check Fail if changes are required
--yes Apply all changes
-h, --help display help for command
```
## build
Scope: `any`
Build a single package for publishing, just like the `plugin:build` and
`backend:build` commands. This command is intended for standalone packages that
aren't plugins, and for example support building of isomorphic packages for
usage in both the frontend and backend.
For frontend packages you'll want to include `esm` output, and for backend
packages `cjs`. Whether to include `types` depends on if you need type
declarations for the package, and also requires `yarn tsc` to have been run
first.
```text
Usage: backstage-cli build [options]
Options:
--outputs &lt;formats&gt; List of formats to output [types,cjs,esm]
-h, --help display help for command
```
## lint
Scope: `any`
Lint a package. In addition to the default `eslint` behavior, this command will
include TypeScript files, treat warnings as errors, and default to linting the
entire directory if no specific files are listed.
```text
Usage: backstage-cli lint [options]
Options:
--format &lt;format&gt; Lint report output format (default: "eslint-formatter-friendly")
--fix Attempt to automatically fix violations
-h, --help display help for command
```
## test
Scope: `any`
Run tests, forwarding all unknown options to Jest, and defaulting to watch mode.
When executing the tests, `process.env.NODE_ENV` will be set to `"test"`.
This command uses a default Jest configuration that is included in the CLI,
which is set up with similar goals for speed, scale, and working within a
monorepo. The configuration sets the `src` as the root directory, enforces the
`.test.` infix for tests, and uses `src/setupTests.ts` as the test setup
location.
If needed, the configuration can be extended using a `"jest"` field in
`package.json`, both within the target package and the monorepo root, with
configuration in the target package taking precedence. Refer to the
[Jest configuration documentation](https://jestjs.io/docs/en/configuration) for
a full list of configuration options.
In addition to the Jest configuration there's an optional `transformModules`
option, which is an array of module names to include in transformations.
Normally modules inside `node_modules` are not transformed, but there are cases
were published packages are not transpiled far enough to be usable by Jest, in
which case you need to enable transform of them.
Another way to override the Jest configuration is to place a `jest.config.js` or
`jest.config.ts` file in the package root. As opposed to the `package.json` way
of overriding config, this completely removes the base config, and so you need
to set it up from scratch.
```text
Usage: backstage-cli test [options]
Options:
--backstage-cli-help display help for command
```
## config:print
Scope: `root`
Print the static configuration, defaulting to reading `app-config.yaml` in the
repo root, using schema collected from all local packages in the repo.
For example, to validate that a given configuration value is visible in the
frontend when building the `my-app` package, you can use the following:
```bash
yarn backstage-cli config:print --frontend --package my-app
```
```text
Usage: backstage-cli config:print [options]
Options:
--package &lt;name&gt; Only load config schema that applies to the given package
--frontend Print only the frontend configuration
--with-secrets Include secrets in the printed configuration
--format &lt;format&gt; Format to print the configuration in, either json or yaml [yaml]
--config &lt;path&gt; Config files to load instead of app-config.yaml (default: [])
-h, --help display help for command
```
## config:check
Scope: `root`
Validate that static configuration loads and matches schema, defaulting to
reading `app-config.yaml` in the repo root and using schema collected from all
local packages in the repo.
```text
Usage: backstage-cli config:check [options]
Options:
--package &lt;name&gt; Only load config schema that applies to the given package
--config &lt;path&gt; Config files to load instead of app-config.yaml (default: [])
-h, --help display help for command
```
## versions:bump
Scope: `root`
Bump all `@backstage` packages to the latest versions. This checks for updates
in the package registry, and will update entries both in `yarn.lock` and
`package.json` files when necessary.
```text
Usage: backstage-cli versions:bump [options]
Options:
-h, --help display help for command
```
## versions:check
Scope: `root`
Validate `@backstage` dependencies within the repo, making sure that there are
no duplicates of packages that might lead to breakages. For example,
`@backstage/core` must not be loaded in twice, so having two different versions
of it installed will cause this command to exit with an error.
By supplying the `--fix` flag the command will attempt to fix any conflict that
can be resolved by editing `yarn.lock`, but will not attempt to search for
remote updates or modify any `package.json` files.
```text
Usage: backstage-cli versions:check [options]
Options:
--fix Fix any auto-fixable versioning problems
-h, --help display help for command
```
## prepack
Scope: `any`
This command should be added as `scripts.prepack` in all packages. It enables
packaging- and publish-time overrides for fields inside `packages.json`.
The checked in version of all packages in a Backstage monorepo are tailored for
local development, and as such `main` and similar fields inside `package.json`
point to development source, i.e. `src/index.ts`. Using this when publishing
would lead to a broken package, since `src/` is not included in the published
package and we instead need to point to files in the `dist/` directory. This
command allows for those fields to be rewritten when needed, and does so by
copying all fields within `publishConfig` to the top-level of each
`package.json`, skipping `access`, `registry`, and `tag`.
The need for this command may be removed in the future, as this exact method of
overriding fields for publishing is already supported by some package managers.
```text
Usage: backstage-cli prepack [options]
Options:
-h, --help display help for command
```
## postpack
Scope: `any`
This should be added as `scripts.postpack` in all packages. It restores
`package.json` to what it looked like before calling the `prepack` command.
```text
Usage: backstage-cli postpack [options]
Options:
-h, --help display help for command
```
## clean
Scope: `any`
Remove cache and output directories.
```text
Usage: backstage-cli clean [options]
Options:
-h, --help display help for command
```
## build-workspace
Scope: `any`, `root`
Builds a mirror of the workspace using the packaged production version of each
package. This essentially calls `yarn pack` in each included package and unpacks
the resulting archive in the target `workspace-dir`.
```text
Usage: backstage-cli build-workspace [options] &lt;workspace-dir&gt;
```
docs/cli/index.md
+108
View File
@@ -0,0 +1,108 @@
---
id: index
title: Overview
description: Overview of the Backstage CLI
---
## Summary
Backstage provides an opinionated set of tooling for both frontend and backend
development. It is delivered through the
[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) package and
executed either directly through `yarn backstage-cli <command>` or within
`package.json` scripts. When creating an app using
[`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app)
it contains package scripts for executing the most common commands.
Under the hood the CLI uses [Webpack](https://webpack.js.org/) for bundling,
[Rollup](https://rollupjs.org/) for building packages,
[Jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for
linting. It also includes custom tooling for working within Backstage apps, for
example for keeping the app up to date and verifying static configuration.
For a full list of CLI commands, see the [commands](./commands.md) page.
## Introduction
A goal of Backstage is to provide a delightful developer experience in and
around the project. Creating new apps and plugins should be simple, iteration
speed should be fast, and the overhead of maintaining custom tooling should be
minimal. As a part of accomplishing this goal, Backstage provides its own set of
opinionated tooling, delivered primarily through the
[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) package.
The `@backstage/cli` package provides a single executable script,
`backstage-cli`, which you can run directly with `yarn` or within a script in
`package.json`. If you have a Backstage app set up, you can try out the
following command to print the top-level help page of the CLI:
```text
yarn backstage-cli --help
```
If you are familiar with [`create-react-app`](https://create-react-app.dev/) you
may recognize the pattern of bundling tooling up as a CLI, as it uses a package
called [`react-scripts`](https://www.npmjs.com/package/react-scripts) to bring
most of the functionality into the created project. The Backstage equivalent of
`create-react-app` is
[`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app),
and the equivalent of `react-scripts` is `@backstage/cli`. There are however a
couple of key differences between the two. Most notably, Backstage apps are
monorepos and the CLI is tailored for that environment. It provides tooling both
for bundling and developing full end-user apps, but also for developing,
building and publishing individual packages within the monorepo, as well as
tooling that is more unique to Backstage, such as commands for working with
static configuration.
## Opinionated Tooling
The Backstage CLI is highly opinionated in what tools are used and how they are
configured. It is tailored for development in large TypeScript monorepos with
hundreds of separate packages, but with the ability to have edits anywhere in
the codebase reflected within a few seconds. The build output is also optimized
for this setup, and aims to provide an excellent user experience with fast page
load times in modern browsers, rather than a wide range of support.
While the Backstage tooling is opinionated in how to develop and build packages,
it is also possible to use your own tooling either partially or fully. For
example, the CLI provides a command for building a plugin package for
publishing, but the output is a quite standard combination of transpiled
JavaScript and TypeScript type declarations. The usage of the command from the
CLI can therefore easily be replaced with other tools if necessary.
Just like `react-scripts`, the Backstage CLI does not provide many hooks for
overriding or customizing the build process. This is to allow for evolution of
the CLI without having to take a wide API surface into account. This allows us
to quickly iterate and improve the tooling, as well as to more easily keep
dependencies up to date.
## Opinions & Goals
In no particular order, this is a list of opinions and goals that guide the
design and development of the Backstage CLI:
- All you need for development is `yarn start`, there should be no need to
manually build packages or run other separate tasks.
- Development experience comes first. The toolchain is optimized for keeping
development smooth, rather than making it easy to for example build and
publish packages.
- Type checking and linting is left for text editors and Continuous Integration.
Most text editors provide tooling for these checks, and running them a second
time during compilation slows down iteration speed and consumes more system
resources.
- Backstage is run in modern browsers. We keep transpilation lightweight and
rely on modern technologies such as HTTP/2 to optimize frontend speed.
## Glossary
- **Package** - A package in the Node.js ecosystem, often published to a package
registry such as [NPM](https://www.npmjs.com/).
- **Monorepo** - A project layout that consists of multiple packages within a
single project, where packages are able to have local dependencies on each
other. Often enabled through tooling such as [lerna](https://lerna.js.org/)
and [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)
- **Local Package** - One of the packages within a monorepo. These package may
or may not also be published to a package registry.
- **Bundle** - A collection of the deployment artifacts. The output of the
bundling process, which brings a collection of packages into a single
collection of deployment artifacts.
docs/conf/defining.md
+109 -6
View File
@@ -4,16 +4,119 @@ title: Defining Configuration for your Plugin
description: Documentation on Defining Configuration for your Plugin
---
There is currently no tooling support or helpers for defining plugin
configuration. But it's on the roadmap.
Configuration in Backstage is organized via a configuration schema, which in
turn is defined using a superset of
[JSON Schema Draft-07](https://json-schema.org/specification-links.html#draft-7).
Each plugin or package within a Backstage app can contribute to the schema,
which during validation is stitched together into a single schema.
Meanwhile, document the config values that you are reading in your plugin
README.
## Schema Collection and Definition
## Format
Schemas are collected from all packages and dependencies in each repo that are a
part of the Backstage ecosystem, including transitive dependencies. The current
definition of "part of the ecosystem" is that a package has at least one
dependency in the `@backstage` namespace, but this is subject to change.
Each package is searched for a schema at a single point of entry, a top-level
`"configSchema"` field in `package.json`. The field can either contain an
inlined JSON schema, or a relative path to a schema file. Supported schema file
formats are `.json` or `.d.ts`.
> When defining a schema file, be sure to include the file in your
> `package.json` > `"files"` field as well!
TypeScript configuration schema files should export a single `Config` type, for
example:
```ts
export interface Config {
app: {
/**
* Frontend root URL
* @visibility frontend
*/
baseUrl: string;
// Use @items.<name> to assign annotations to primitive array items
/** @items.visibility frontend */
myItems: string[];
};
}
```
Separate `.json` schema files can use a top-level
`"$schema": "https://backstage.io/schema/config-v1"` declaration in order to
receive schema validation and autocompletion. For example:
```json
{
"$schema": "https://backstage.io/schema/config-v1",
"type": "object",
"properties": {
"app": {
"type": "object",
"properties": {
"baseUrl": {
"type": "string",
"description": "Frontend root URL",
"visibility": "frontend"
}
},
"required": ["baseUrl"]
},
"required": ["app"]
}
}
```
## Visibility
The `https://backstage.io/schema/config-v1` meta schema is a superset of JSON
Schema Draft 07. The single addition is a custom `visibility` keyword, which is
used to indicate whether the given config value should be visible in the
frontend or not. The possible values are `frontend`, `backend`, and `secret`,
where `backend` is the default. A visibility of `secret` has the same scope at
runtime, but it will be treated with more care in certain contexts, and defining
both `frontend` and `secret` for the same value in two different schemas will
result in an error during schema merging.
The visibility only applies to the direct parent of where the keyword is placed
in the schema. For example, if you set the visibility to `frontend` for a subset
of the schema with `type: "object"`, but none of the descendants, only an empty
object will be available in the frontend. The full ancestry does not need to
have correctly defined visibilities however, so it is enough to only for example
declare the visibility of a leaf node of `type: "string"`.
| `visibility` | |
| ------------ | ------------------------------------------------------------------ |
| `frontend` | Visible in frontend and backend |
| `backend` | (Default) Only in backend |
| `secret` | Only in backend and may be excluded from logs for security reasons |
## Validation
Schemas can be validated using the `backstage-cli config:check` command. If you
want to validate anything else than the default `app-config.yaml`, be sure to
pass in all of the configuration files as `--config <path>` options as well.
To validate and examine the frontend configuration, use the
`backstage-cli config:print --frontend` command. Just like for validation you
may need to pass in all files using one or multiple `--config <path>` options.
## Guidelines
> Make limited use of static configuration. The first question to ask is whether
> a particular option actually needs to be static configuration, or if it might
> just as well be a TypeScript API. In general, options that you want to be able
> to change for different deployment environments should be static
> configuration, while it should otherwise be avoided.
When defining configuration for your plugin, keep keys camelCased and stick to
existing casing conventions such as `baseUrl`.
existing casing conventions such as `baseUrl` rather than `baseURL`.
It is also usually best to prefer objects over arrays, as it makes it possible
to override individual values using separate files or environment variables.
Avoid creating new top-level fields as much as possible. Either place your
configuration within an existing known top-level block, or create a single new
one using e.g. the name of the product that the plugin integrates.
docs/conf/index.md
+16 -2
View File
@@ -33,6 +33,20 @@ values that are common between the two only need to be defined once. Such as the
For more details, see [Writing Configuration](./writing.md).
## Configuration Schema
The configuration is validated using JSON Schema definitions. Each plugin and
package can provide pieces of the configuration schema, which are stitched
together to form a complete schema during validation. The configuration schema
is also used to select what configuration is available in the frontend using a
custom `visibility` keyword, as configuration is by default only available in
the backend.
You can validate your configuration against the schema using
`backstage-cli config:check`, and define a schema for your own plugin either
using JSON Schema or TypeScript. For more information, see
[Defining Configuration](./defining.md).
## Reading Configuration
As a plugin developer, you likely end up wanting to define configuration that
@@ -49,5 +63,5 @@ More details are provided in dedicated sections of the documentation.
plugin.
- [Writing Configuration](./writing.md): How to provide configuration for your
Backstage deployment.
- [Defining Configuration](./defining.md): How to define configuration for users
of your plugin.
- [Defining Configuration](./defining.md): How to define a configuration schema
for users of your plugin or package.
docs/conf/writing.md
+11 -14
View File
@@ -97,10 +97,10 @@ order:
- If no config flags are provided, `app-config.local.yaml` has higher priority
than `app-config.yaml`.
## Secrets
## Secrets and Dynamic Data
Secrets are supported via special secret keys that are prefixed with `$`, which
in turn provide a number of different ways to read in secrets. To load a
Secrets are supported via special data loading keys that are prefixed with `$`,
which in turn provide a number of different ways to read in secrets. To load a
configuration value as a secret, supply an object with one of the special secret
keys, for example `$env` or `$file`. A full list of supported secret keys can be
found below. For example, the following will read the config key
@@ -117,10 +117,6 @@ will return the value of the environment variable `MY_SECRET_KEY` when the
backend started up. All secrets are loaded at startup, so changing the contents
of secret files or environment variables will not be reflected at runtime.
Note that secrets will never be included in the frontend bundle or development
builds. When loading configuration you have to explicitly enable reading of
secrets, which is only done for the backend configuration.
As hinted at, secrets can be loaded from a bunch of different sources, and can
be extended with more. Below is a list of the currently supported methods for
loading secrets.
@@ -145,16 +141,17 @@ itself:
$file: ./my-secret.txt
```
### Data File Secrets
### Including Files
This reads secrets from a path within a JSON-like data file. The file path
behaves similar to file secrets, but with the addition of a url fragment that is
used to point to a specific value inside the file. Supported file extensions are
`.json`, `.yaml`, and `.yml`. For example, the following would read out
`my-secret-key` from `my-secrets.json`:
The `$include` keyword can be used to load in JSON data from an external file.
It's able to load and parse data from `.json`, `.yml`, and `.yaml` files. It's
also possible to include a url fragment (`#`) to point to a value at the given
path in the file.
For example, the following would read `my-secret-key` from `my-secrets.json`:
```yaml
$data: ./my-secrets.json#deployment.key
$include: ./my-secrets.json#deployment.key
```
Example `my-secrets.json` file:
docs/features/software-catalog/descriptor-format.md
+123 -37
View File
@@ -31,6 +31,7 @@ we recommend that you name them `catalog-info.yaml`.
- [Kind: Resource](#kind-resource)
- [Kind: System](#kind-system)
- [Kind: Domain](#kind-domain)
- [Kind: Location](#kind-location)
## Overall Shape Of An Entity
@@ -43,7 +44,7 @@ software catalog API.
"kind": "Component",
"metadata": {
"annotations": {
"backstage.io/managed-by-location": "file:/tmp/component-info.yaml",
"backstage.io/managed-by-location": "file:/tmp/catalog-info.yaml",
"example.com/service-discovery": "artistweb",
"circleci.com/project-slug": "github/example-org/artist-website"
},
@@ -93,6 +94,43 @@ significance and have reserved purposes and distinct shapes.
See below for details about these fields.
## Substitutions In The Descriptor Format
The descriptor format supports substitutions using `$text`, `$json`, and
`$yaml`.
Placeholders like `$json: https://example.com/entity.json` are substituted by
the content of the referenced file. Files can be referenced from any configured
integration similar to locations by passing an absolute URL. It's also possible
to reference relative files like `./referenced.yaml` from the same location.
Relative references are handled relative to the folder of the
`catalog-info.yaml` that contains the placeholder. There are three different
types of placeholders:
- `$text`: Interprets the contents of the referenced file as plain text and
embeds it as a string.
- `$json`: Interprets the contents of the referenced file as JSON and embeds the
parsed structure.
- `$yaml`: Interprets the contents of the referenced file as YAML and embeds the
parsed structure.
For example, this can be used to load the definition of an API entity from a web
server and embed it as a string in the field `spec.definition`:
```yaml
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
name: petstore
description: The Petstore API
spec:
type: openapi
lifecycle: production
owner: petstore@example.com
definition:
$text: https://petstore.swagger.io/v2/swagger.json
```
## Common to All Kinds: The Envelope
The root envelope object has the following structure.
@@ -344,7 +382,7 @@ spec:
type: website
lifecycle: production
owner: artist-relations@example.com
implementsApis:
providesApis:
- artist-api
```
@@ -369,7 +407,7 @@ The current set of well-known and common values for this field is:
- `service` - a backend service, typically exposing an API
- `website` - a website
- `library` - a software library, such as an NPM module or a Java library
- `library` - a software library, such as an npm module or a Java library
### `spec.lifecycle` [required]
@@ -406,10 +444,18 @@ Apart from being a string, the software catalog leaves the format of this field
open to implementers to choose. Most commonly, it is set to the ID or email of a
group of people in an organizational structure.
### `spec.implementsApis` [optional]
### `spec.providesApis` [optional]
Links APIs that are implemented by the component, e.g. `artist-api`. This field
is optional.
Links APIs that are provided by the component, e.g. `artist-api`. This field is
optional.
The software catalog expects a list of one or more strings that references the
names of other entities of the `kind` `API`.
### `spec.consumesApis` [optional]
Links APIs that are consumed by the component, e.g. `artist-api`. This field is
optional.
The software catalog expects a list of one or more strings that references the
names of other entities of the `kind` `API`.
@@ -497,7 +543,7 @@ The current set of well-known and common values for this field is:
- `service` - a backend service, typically exposing an API
- `website` - a website
- `library` - a software library, such as an NPM module or a Java library
- `library` - a software library, such as an npm module or a Java library
### `spec.templater` [required]
@@ -592,6 +638,9 @@ The current set of well-known and common values for this field is:
[OpenAPI](https://swagger.io/specification/) version 2 or version 3 spec.
- `asyncapi` - An API definition based on the
[AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/) spec.
- `graphql` - An API definition based on
[GraphQL schemas](https://spec.graphql.org/) for consuming
[GraphQL](https://graphql.org/) based APIs.
- `grpc` - An API definition based on
[Protocol Buffers](https://developers.google.com/protocol-buffers) to use with
[gRPC](https://grpc.io/).
@@ -659,10 +708,12 @@ metadata:
description: The infra business unit
spec:
type: business-unit
profile:
displayName: Infrastructure
email: infrastructure@example.com
picture: https://example.com/groups/bu-infrastructure.jpeg
parent: ops
ancestors: [ops, global-synergies, acme-corp]
children: [backstage, other]
descendants: [backstage, other, team-a, team-b, team-c, team-d]
```
In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
@@ -685,6 +736,14 @@ Some common values for this field could be:
- `product-area`
- `root` - as a common virtual root of the hierarchy, if desired
### `spec.profile` [optional]
Optional profile information about the group, mainly for display purposes. All
fields of this structure are also optional. The email would be a group email of
some form, that the group may wish to be used for contacting them. The picture
is expected to be a URL pointing to an image that's representative of the group,
and that a browser could fetch and render on a group page or similar.
### `spec.parent` [optional]
The immediate parent group in the hierarchy, if any. Not all groups must have a
@@ -698,20 +757,6 @@ namespace as the user. Only `Group` entities may be referenced. Most commonly,
this field points to a group in the same namespace, so in those cases it is
sufficient to enter only the `metadata.name` field of that group.
### `spec.ancestors` [required]
The recursive list of parents up the hierarchy, by stepping through parents one
by one. The list must be present, but may be empty if `parent` is not present.
The first entry in the list is equal to `parent`, and then the following ones
are progressively farther up the hierarchy.
The entries of this array are
[entity references](https://backstage.io/docs/features/software-catalog/references),
with the default kind `Group` and the default namespace equal to the same
namespace as the user. Only `Group` entities may be referenced. Most commonly,
these entries point to groups in the same namespace, so in those cases it is
sufficient to enter only the `metadata.name` field of those groups.
### `spec.children` [required]
The immediate child groups of this group in the hierarchy (whose `parent` field
@@ -726,20 +771,6 @@ namespace as the user. Only `Group` entities may be referenced. Most commonly,
these entries point to groups in the same namespace, so in those cases it is
sufficient to enter only the `metadata.name` field of those groups.
### `spec.descendants` [required]
The immediate and recursive child groups of this group in the hierarchy
(children, and children's children, etc.). The list must be present, but may be
empty if there are no child groups. The items are not guaranteed to be ordered
in any particular way.
The entries of this array are
[entity references](https://backstage.io/docs/features/software-catalog/references),
with the default kind `Group` and the default namespace equal to the same
namespace as the user. Only `Group` entities may be referenced. Most commonly,
these entries point to groups in the same namespace, so in those cases it is
sufficient to enter only the `metadata.name` field of those groups.
## Kind: User
Describes the following entity kind:
@@ -811,3 +842,58 @@ This kind is not yet defined, but is reserved [for future use](system-model.md).
## Kind: Domain
This kind is not yet defined, but is reserved [for future use](system-model.md).
## Kind: Location
Describes the following entity kind:
| Field | Value |
| ------------ | ----------------------- |
| `apiVersion` | `backstage.io/v1alpha1` |
| `kind` | `Location` |
A location is a marker that references other places to look for catalog data.
Descriptor files for this kind may look as follows.
```yaml
apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
name: org-data
spec:
type: url
targets:
- http://github.com/myorg/myproject/org-data-dump/catalog-info-staff.yaml
- http://github.com/myorg/myproject/org-data-dump/catalog-info-consultants.yaml
```
In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
shape, this kind has the following structure.
### `apiVersion` and `kind` [required]
Exactly equal to `backstage.io/v1alpha1` and `Location`, respectively.
### `spec.type` [optional]
The single location type, that's common to the targets specified in the spec. If
it is left out, it is inherited from the location type that originally read the
entity data. For example, if you have a `url` type location, that when read
results in a `Location` kind entity with no `spec.type`, then the referenced
targets in the entity will implicitly also be of `url` type. This is useful
because you can define a hierarchy of things in a directory structure using
relative target paths (see below), and it will work out no matter if it's
consumed locally on disk from a `file` location, or as uploaded on a VCS.
### `spec.target` [optional]
A single target as a string. Can be either an absolute path/URL (depending on
the type), or a relative path such as `./details/catalog-info.yaml` which is
resolved relative to the location of this Location entity itself.
### `spec.targets` [optional]
A list of targets as strings. They can all be either absolute paths/URLs
(depending on the type), or relative paths such as `./details/catalog-info.yaml`
which are resolved relative to the location of this Location entity itself.
docs/features/software-catalog/extending-the-model.md
+288 -27
View File
@@ -1,7 +1,7 @@
---
id: extending-the-model
title: Extending the model
description: Documentation on Extending the model
description: Documentation on extending the catalog model
---
The Backstage catalog [entity data model](descriptor-format.md) is based on the
@@ -28,63 +28,324 @@ Backstage comes with a number of catalog concepts out of the box:
We'll list different possibilities for extending this below.
## Adding a New apiVersion of an Existing Kind
Example intents:
> "I want to evolve this core kind, tweaking the semantics a bit so I will bump
> the apiVersion a step"
> "This core kind is a decent fit but we want to evolve it at will so we'll move
> it to our own company's apiVersion space and use that instead of
> `backstage.io`."
The `backstage.io` apiVersion space is reserved for use by the Backstage
maintainers. Please do not change or add versions within that space.
If you add an [apiVersion](descriptor-format.md#apiversion-and-kind-required)
space of your own, you are effectively branching out from the underlying kind
and making your own. An entity kind is identified by the apiVersion + kind pair,
so even though the resulting entity may be similar to the core one, there will
be no guarantees that plugins will be able to parse or understand its data. See
below about adding a new kind.
## Adding a New Kind
> TODO: Fill in
Example intents:
> "The kinds that come with the package are lacking. I want to model this other
> thing that is a poor fit for either of the builtins."
> "This core kind is a decent fit but we want to evolve it at will so we'll move
> it to our own company's apiVersion space and use that instead of
> `backstage.io`."
A [kind](descriptor-format.md#apiversion-and-kind-required) is an overarching
family, or an idea if you will, of entities that also share a schema. Backstage
comes with a number of builtin ones that we believe are useful for a large
variety of needs that one may want to model in Backstage. The primary ambition
is to map things to these kinds, but sometimes you may want or need to extend
beyond them.
Introducing a new apiVersion is basically the same as adding a new kind. Bear in
mind that most plugins will be compiled against the builtin
`@backstage/catalog-model` package and have expectations that kinds align with
that.
The catalog backend itself, from a storage and API standpoint, does not care
about the kind of entities it stores. Extending with new kinds is mainly a
matter of permitting them to pass validation when building the backend catalog
using the `CatalogBuilder`, and then to make plugins be able to understand the
new kind.
For the consuming side, it's a different story. Adding a kind has a very large
impact. The very foundation of Backstage is to attach behavior and views and
functionality to entities that we ascribe some meaning to. There will be many
places where code checks `if (kind === 'X')` for some hard coded `X`, and casts
it to a concrete type that it imported from a package such as
`@backstage/catalog-model`.
If you want to model something that doesn't feel like a fit for either of the
builtin kinds, feel free to reach out to the Backstage maintainers to discuss
how to best proceed.
If you end up adding that new kind, you must namespace its `apiVersion`
accordingly with a prefix that makes sense, typically based on your organization
name - e.g. `my-company.net/v1`. Also do pick a new `kind` identifier that does
not collide with the builtin kinds.
## Adding a New Type of an Existing Kind
Backstage natively supports tracking of the following component
[`type`](descriptor-format.md)'s:
Example intents:
- Services
- Websites
- Libraries
- Documentation
- Other
> "This is clearly a component, but it's of a type that doesn't quite fit with
> the ones I've seen before."
![](../../assets/software-catalog/bsc-extend.png)
> "We don't call our teams "team", can't we put "flock" as the group type?"
Since these types are likely not the only kind of software you will want to
track in Backstage, it is possible to add your own software types that fit your
organization's data model. Inside Spotify our model has grown significantly over
the years, and now includes ML models, Apps, data pipelines and many more.
Some entity kinds have a `type` field in its spec. This is where an organization
are free to express the variety of entities within a kind. This field is
expected to follow some taxonomy that makes sense for yourself. The chosen value
may affect what operations and views are enabled in Backstage for that entity.
Inside Spotify our model has grown significantly over the years, and our
component types now include ML models, apps, data pipelines and many more.
It might be tempting to put software that doesn't fit into any of the existing
types into Other. There are a few reasons why we advise against this; firstly,
we have found that it is preferred to match the conceptual model that your
engineers have when describing your software. Secondly, Backstage helps your
engineers manage their software by integrating the infrastructure tooling
through plugins. Different plugins are used for managing different types of
components.
types into an Other catch-all type. There are a few reasons why we advise
against this; firstly, we have found that it is preferred to match the
conceptual model that your engineers have when describing your software.
Secondly, Backstage helps your engineers manage their software by integrating
the infrastructure tooling through plugins. Different plugins are used for
managing different types of components.
For example, the
[Lighthouse plugin](https://github.com/backstage/backstage/tree/master/plugins/lighthouse)
only makes sense for Websites. The more specific you can be in how you model
your software, the easier it is to provide plugins that are contextual.
> TODO: Fill in
Adding a new type takes relatively little effort and carries little risk. Any
type value is accepted by the catalog backend, but plugins may have to be
updated if you want particular behaviors attached to that new type.
## Changing the Validation Rules for The Entity Envelope or Metadata Fields
Example intents:
> "We want to import our old catalog but the default set of allowed characters
> for a metadata.name are too strict."
> "I want to change the rules for annotations so that I'm allowed to store any
> data in annotation values, not just strings."
After pieces of raw entity data have been read from a location, they are passed
through a fixed number of so called `Validators`, as part of the entity policy
check step. They ensure that the types and syntax of the base envelope and
metadata make sense - in short, things that aren't entity-kind-specific. Some or
all of these validators can be replaced when building the backend catalog using
the `CatalogBuilder`.
The risk and impact of this type of extension varies, based on what it is that
you want to do. For example, extending the valid character set for kinds,
namespaces and names can be fairly harmless, with a few notable exceptions -
there is code that expects these to never ever contain a colon or slash, for
example, and introducing URL-unsafe characters risks breaking plugins that
aren't careful about encoding arguments. Supporting non-strings in annotations
may be possible but has not yet been tried out in the real world - there is
likely to be some level of plugin breakage that can be hard to predict.
Before making this kind of extension, we recommend that you contact the
Backstage maintainers or a support partner to discuss your use case.
## Changing the Validation Rules for Core Entity Fields
> TODO: Fill in
Example intent:
> "I don't like that the owner is mandatory. I'd like it to be optional."
After reading and policy-checked entity data from a location, it is sent through
the processor chain looking for processors that implement the
`validateEntityKind` step, to see that the data is of a known kind and abides by
its schema. There is a builtin processor that implements this for all known core
kinds and matches the data against their fixed validation schema. This processor
can be replaced when building the backend catalog using the `CatalogBuilder`,
with a processor of your own that validates the data differently.
This type of extension is high risk, and may have high impact across the
ecosystem depending on the type of change that is made. It is therefore not
recommended in normal cases. There will be a large number of plugins and
processors - and even the core itself - that make assumptions about the shape of
the data and import the typescript data type from the `@backstage/catalog-model`
package.
## Adding New Fields to the Metadata Object
> TODO: Fill in
Example intent:
> "Our entities have this auxiliary property that I would like to express for
> several entity kinds and it doesn't really fit as a spec field."
The metadata object is currently left open for extension. Any unknown fields
found in the metadata will just be stored verbatim in the catalog. However we
want to caution against extending the metadata excessively. Firstly, you run the
risk of colliding with future extensions to the model. Secondly, it is common
that this type of extension lives more comfortably elsewhere - primarily in the
metadata labels or annotations, but sometimes you even may want to make a new
component type or similar instead.
There are some situations where metadata can be the right place. If you feel
that you have run into such a case and that it would apply to others, do feel
free to contact the Backstage maintainers or a support partner to discuss your
use case. Maybe we can extend the core model to benefit both you and others.
## Adding New Fields to the Spec Object of an Existing Kind
> TODO: Fill in
Example intent:
> "The builtin Component kind is fine but we want to add an additional field to
> the spec for describing whether it's in prod or staging."
A kind's schema validation typically doesn't forbid "unknown" fields in an
entity `spec`, and the catalog will happily store whatever is in it. So doing
this will usually work from the catalog's point of view.
Adding fields like this is subject to the same risks as mentioned about metadata
extensions above. Firstly, you run the risk of colliding with future extensions
to the model. Secondly, it is common that this type of extension lives more
comfortably elsewhere - primarily in the metadata labels or annotations, but
sometimes you even may want to make a new component type or similar instead.
There are some situations where the spec can be the right place. If you feel
that you have run into such a case and that it would apply to others, do feel
free to contact the Backstage maintainers or a support partner to discuss your
use case. Maybe we can extend the core model to benefit both you and others.
## Adding a New Annotation
> TODO: Fill in
Example intents:
> "Our custom made build system has the concept of a named pipeline-set, and we
> want to associate individual components with their corresponding pipeline-sets
> so we can show their build status."
> "We have an alerting system that automatically monitors service health, and
> there's this integration key that binds the service to an alerts pool. We want
> to be able to show the ongoing alerts for our services in Backstage so it'd be
> nice to attach that integration key to the entity somehow."
Annotations are mainly intended to be consumed by plugins, for feature detection
or linking into external systems. Sometimes they are added by humans, but often
they are automatically generated at ingestion time by processors. There is a set
of [well-known annotations](well-known-annotations.md), but you are free to add
additional ones. This carries no risk or impact to other systems as long as you
abide by the following naming rules.
- The `backstage.io` annotation prefix is reserved for use by the Backstage
maintainers. Reach out to us if you feel that you would like to make an
addition to that prefix.
- Annotations that pertain to a well known third party system should ideally be
prefixed with a domain, in a way that makes sense to a reader and connects it
clearly to the system (or the maker of the system). For example, you might use
a `pagerduty.com` prefix for pagerduty related annotations, but maybe not
`ldap.com` for LDAP annotations since it's not directly affiliated with or
owned by an LDAP foundation/company/similar.
- Annotations that have no prefix at all, are considered local to your Backstage
instance and can be used freely as such, but you should not make use of them
outside of your organization. For example, if you were to open source a plugin
that generates or consumes annotations, then those annotations must be
properly prefixed with your company domain or a domain that pertains to the
annotation at hand.
## Adding a New Label
> TODO: Fill in
Example intents:
> "Our process reaping system wants to periodically scrape for components that
> have a certain property."
> "It'd be nice if our service owners could just tag their components somehow to
> let the CD system know to automatically generate SRV records or not for that
> service."
Labels are mainly intended to be used for filtering of entities, by external
systems that want to find entities that have some certain property. This is
sometimes used for feature detection / selection. An example could be to add a
label `deployments.my-company.net/register-srv: "true"`.
At the time of writing this, the use of labels is very limited and we are still
settling together with the community on how to best use them. If you feel that
your use case fits the labels best, we would appreciate if you let the Backstage
maintainers know.
You are free to add labels. This carries no risk or impact to other systems as
long as you abide by the following naming rules.
- The `backstage.io` label prefix is reserved for use by the Backstage
maintainers. Reach out to us if you feel that you would like to make an
addition to that prefix.
- Labels that pertain to a well known third party system should ideally be
prefixed with a domain, in a way that makes sense to a reader and connects it
clearly to the system (or the maker of the system). For example, you might use
a `pagerduty.com` prefix for pagerduty related labels, but maybe not
`ldap.com` for LDAP labels since it's not directly affiliated with or owned by
an LDAP foundation/company/similar.
- Labels that have no prefix at all, are considered local to your Backstage
instance and can be used freely as such, but you should not make use of them
outside of your organization. For example, if you were to open source a plugin
that generates or consumes labels, then those labels must be properly prefixed
with your company domain or a domain that pertains to the label at hand.
## Adding a New Relation Type
> TODO: Fill in
Example intents:
> "We have this concept of service maintainership, separate from ownership, that
> we would like to make relations to individual users for."
> We feel that we want to explicitly model the team-to-global-department mapping
> as a relation, because it is core to our org setup and we frequently query for
> it.
Any processor can emit relations for entities as they are being processed, and
new processors can be added when building the backend catalog using the
`CatalogBuilder`. They can emit relations based on the entity data itself, or
based on information gathered from elsewhere. Relations are directed and go from
a source entity to a target entity. They are also tied to the entity that
originated them - the one that was subject to processing when the relation was
emitted. Relations may be dangling (referencing something that does not actually
exist by that name in the catalog), and callers need to be aware of that.
There is a set of [well-known relations](well-known-relations.md), but you are
free to emit your own as well. You cannot change the fact that they are directed
and have a source and target that have to be an
[entity reference](references.md), but you can invent your own types. You do not
have to make any changes to the catalog backend in order to accept new relation
types.
At the time of writing this, we do not have any namespacing/prefixing scheme for
relation types. The type is also not validated to contain only some particular
set of characters. Until rules for this are settled, you should stick to using
only letters, dashes and digits, and to avoid collisions with future core
relation types, you may want to prefix the type somehow. For example:
`myCompany-maintainerOf` + `myCompany-maintainedBy`.
If you have a suggestion for a relation type to be elevated to the core
offering, reach out to the Backstage maintainers or a support partner.
## Using a Well-Known Relation Type for a New Purpose
Example intents:
> "The ownerOf/ownedBy relation types sound like a good fit for expressing how
> users are technical owners of our company specific ServiceAccount kind, and we
> want to reuse those relation types for that."
At the time of writing, this is uncharted territory. If the documented use of a
relation states that one end of the relation commonly is a User or a Group, for
example, then consumers are likely to have conditional statements on the form
`if (x.kind === 'User') {} else {}`, which get confused when an unexpected kind
appears.
If you want to extend the use of an established relation type in a way that has
an effect outside of your organization, reach out to the Backstage maintainers
or a support partner to discuss risk/impact. It may even be that one end of the
relation could be considered for addition to the core.
docs/features/software-catalog/references.md
+2 -2
View File
@@ -51,7 +51,7 @@ spec:
type: service
lifecycle: experimental
owner: group:pet-managers
implementsApis:
providesApis:
- petstore
- internal/streetlights
- hello-world
@@ -66,7 +66,7 @@ catalog that is of kind `Group`, namespace `default` (which, actually, also can
be left out in its own yaml file because that's the default value there too),
and name `pet-managers`.
The entries in `implementsApis` are also references. In this case, none of them
The entries in `providesApis` are also references. In this case, none of them
needs to specify a kind since we know from the context that that's the only kind
that's supported here. The second entry specifies a namespace but the other ones
don't, and in this context, the default is to refer to the same namespace as the
docs/features/software-catalog/system-model.md
+2 -2
View File
@@ -44,8 +44,8 @@ Backstage model and the primary way to discover existing functionality in the
ecosystem.
APIs are implemented by components and form boundaries between components. They
might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a data schema (eg
Avro, TFRecord, ...), or as code interfaces. In any case, APIs exposed by
might be defined using an RPC IDL (e.g., Protobuf, GraphQL, ...), a data schema
(e.g., Avro, TFRecord, ...), or as code interfaces. In any case, APIs exposed by
components need to be in a known machine-readable format so we can build further
tooling and analysis on top.
docs/features/software-catalog/well-known-annotations.md
+20 -17
View File
@@ -190,9 +190,25 @@ metadata:
```
The value of these annotations are the corresponding attributes that were found
when ingestion the entity from LDAP. Not all of them may be present, depending
when ingesting the entity from LDAP. Not all of them may be present, depending
on what attributes that the server presented at ingestion time.
### graph.microsoft.com/tenant-id, graph.microsoft.com/group-id, graph.microsoft.com/user-id
```yaml
# Example:
metadata:
annotations:
graph.microsoft.com/tenant-id: 6902611b-ffc1-463f-8af3-4d5285dc057b
graph.microsoft.com/group-id: c57e8ba2-6cc4-1039-9ebc-d5f241a7ca21
graph.microsoft.com/user-id: 2de244b5-104b-4e8f-a3b8-dce3c31e54b6
```
The value of these annotations are the corresponding attributes that were found
when ingesting the entity from the Microsoft Graph API. Not all of them may be
present, depending on what attributes that the server presented at ingestion
time.
### sonarqube.org/project-key
```yaml
@@ -222,22 +238,9 @@ annotation, with the same value format.
### backstage.io/definition-at-location
This annotation allowed to load the API definition from another location. Now
placeholders can be used instead:
```
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
name: petstore
description: The Petstore API
spec:
type: openapi
lifecycle: production
owner: petstore@example.com
definition:
$text: https://petstore.swagger.io/v2/swagger.json
```
This annotation allowed to load the API definition from another location. Use
[substitution](./descriptor-format.md#substitutions-in-the-descriptor-format)
instead.
## Links
docs/features/software-catalog/well-known-relations.md
+16 -5
View File
@@ -45,17 +45,28 @@ entity, but there will always be one ultimate owner.
This relation is commonly generated based on `spec.owner` of the owned entity,
where present.
### `consumesApi` and `providesApi`
### `providesApi` and `apiProvidedBy`
A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
[Component](descriptor-format.md#kind-component) or
[System](descriptor-format.md#kind-system).
These relations express that a component or system either exposes an API -
meaning that it hosts callable endpoints from which you can consume that API -
or that they are dependent on being able to consume that API.
These relations express that a component or system exposes an API - meaning that
it hosts callable endpoints from which you can consume that API.
This relation is commonly generated based on `spec.implementsApis` of the
This relation is commonly generated based on `spec.providesApis` of the
component or system in question.
### `consumesApi` and `apiConsumedBy`
A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
[Component](descriptor-format.md#kind-component) or
[System](descriptor-format.md#kind-system).
These relations express that a component or system consumes an API - meaning
that it depends on endpoints of the API.
This relation is commonly generated based on `spec.consumesApis` of the
component or system in question.
### `dependsOn` and `dependencyOf`
docs/features/software-templates/adding-templates.md
+4
View File
@@ -55,6 +55,10 @@ contains more information about the required fields.
Once we have a `template.yaml` ready, we can then add it to the service catalog
for use by the scaffolder.
_NOTE_: When the `publish` step is completed, it is currently assumed by the
scaffolder that the final repository should contain a `catalog-info.yaml` in
order to register this with the Catalog in Backstage.
Currently the catalog supports loading definitions from GitHub + Local Files. To
load from other places, not only will there need to be another preparer, but the
support to load the location will also need to be added to the Catalog.
docs/features/techdocs/README.md
+39 -17
View File
@@ -45,8 +45,6 @@ about TechDocs and the philosophy in its
[v2]: https://github.com/backstage/backstage/milestone/22
[v3]: https://github.com/backstage/backstage/milestone/17
<!-- TODO: Add link to milestone for v3 -->
## Use Cases
#### TechDocs V.0
@@ -96,29 +94,53 @@ Build a widget (plugin) framework so that contributors can easily contribute
features to TechDocs - that others can use. And, also, so that we can easily
migrate Spotify's existing TechDocs features to open source.
## Structure
## Platforms Supported
- [Getting Started]
- [Concepts]
- [Creating and Publishing Documentation]
- [FAQ]
See [TechDocs Architecture](architecture.md) to get an overview of where these
providers are used.
| Source Code Hosting Provider | Support Status |
| ---------------------------- | -------------- |
| GitHub | Yes ✅ |
| GitHub Enterprise | Yes ✅ |
| BitBucket | Yes ✅ |
| Azure DevOps | Yes ✅ |
| GitLab | Yes ✅ |
| GitLab Enterprise | Yes ✅ |
| File Storage Provider | Support Status |
| --------------------------------- | -------------- |
| Local Filesystem of Backstage app | Yes ✅ |
| Google Cloud Storage (GCS) | Yes ✅ |
| Amazon Web Services (AWS) S3 | Yes ✅ |
| Azure Storage | No ❌ |
[Reach out to us](#feedback) if you want to request more platforms.
## Tech Stack
| Stack | Location |
| ------------------------------------------- | -------------------------------------------------------- |
| Frontend | [`@backstage/plugin-techdocs`][techdocs/frontend] |
| Backend | [`@backstage/plugin-techdocs-backend`][techdocs/backend] |
| Docker Container (for generating doc sites) | [`techdocs-container`][techdocs/container] |
| CLI (for local development) | [`@techdocs/cli`][techdocs/cli] |
| Stack | Location |
| ----------------------------------------------- | -------------------------------------------------------- |
| Frontend Plugin | [`@backstage/plugin-techdocs`][techdocs/frontend] |
| Backend Plugin | [`@backstage/plugin-techdocs-backend`][techdocs/backend] |
| CLI (for local development and generating docs) | [`@techdocs/cli`][techdocs/cli] |
| Docker Container (for generating docs) | [`techdocs-container`][techdocs/container] |
[getting started]: getting-started.md
[concepts]: concepts.md
[creating and publishing documentation]: creating-and-publishing.md
[faq]: FAQ.md 'Frequently asked questions'
[techdocs/frontend]:
https://github.com/backstage/backstage/blob/master/plugins/techdocs
[techdocs/backend]:
https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend
[techdocs/container]: https://github.com/backstage/techdocs-container
[techdocs/cli]: https://github.com/backstage/techdocs-cli
## Feedback
We have created a sweet and short TechDocs user survey -
https://docs.google.com/forms/d/e/1FAIpQLSdn5Vn3MQhCdyYRuW8cMzZkMQF0bFxXYN168gZRvESLfJWVVg/viewform
This is to gather inputs from you (the Backstage community) which will help us
best serve TechDocs adopters and existing users. Your inputs will shape our
roadmap and we will share it in the open.
For any other general queries, reach out to us in the `#docs-like-code` channel
of our [Discord chatroom](https://github.com/backstage/backstage#community).
docs/features/techdocs/architecture.md
+149 -3
View File
@@ -1,7 +1,153 @@
---
id: architecture
title: Architecture
description: Documentation on Architecture
title: TechDocs Architecture
description: Documentation on TechDocs Architecture
---
![TechDocs Big Picture](../../assets/techdocs/techdocs_big_picture.png)
## Basic (out-of-the-box)
When you deploy Backstage (with TechDocs enabled by default), you get a basic
out-of-the box experience.
<img data-zoomable src="../../assets/techdocs/architecture-basic.drawio.svg" alt="TechDocs Architecture diagram" />
> Note: See below for our recommended deployment architecture which takes care
> of stability, scalability and speed.
When you open a TechDocs site in Backstage, the
[TechDocs Reader](./concepts.md#techdocs-reader) makes a request to
`techdocs-backend` with the entity ID and the path of the current page you are
looking at. In response, it receives the static files (HTML, CSS, JSON, etc.) to
render on the page in TechDocs/Backstage.
The static files consist of HTML, CSS and Images generated by MkDocs. We remove
all the JavaScript before adding them to Backstage for security reasons. And
there are some additional techdocs metadata JSON files that TechDocs needs to
render a site.
The TechDocs Reader then applies a list of "Transformers" (see
[Concepts](./concepts.md)) which modify the generated static HTML files for a
number of use cases e.g. Remove certain headers, filter out some HTML tags, etc.
Currently, we use the Backstage server's (or techdocs-backend's) local file
system to store the generated files. Publishing to an external storage system
(AWS S3, GCS, etc.) is also possible, but has not been implemented yet.
A word about `UrlReader` vs Git preparer - Right now, we have two ways to fetch
files from its source repository for docs site generation. 1. By using Git
and 2. By directly using Source control (GitHub, Azure, etc.) APIs. This work is
heavily in progress. Please reach out to us on Discord in the #docs-like-code
channel to talk about it.
## Recommended deployment
This is how we recommend deploying TechDocs in production environment.
<img data-zoomable src="../../assets/techdocs/architecture-recommended.drawio.svg" alt="TechDocs Architecture diagram" />
The key difference in the recommended deployment approach is where the docs are
built.
We assume each entity lives in a repository somewhere (GitHub, GitLab, etc.). We
recommend using a CI/CD pipeline with the repository that has a dedicated
step/job to generate docs for TechDocs. The generated static files are then
stored in a cloud storage solution of your choice.
[Track progress here](https://github.com/backstage/backstage/issues/3096).
Similar to how it is done in the Basic setup, the TechDocs Reader requests
`techdocs-backend` plugin for the docs site. `techdocs-backend` then requests
your configured storage solution for the necessary files and returns them to
TechDocs Reader.
We will provide instructions, scripts and/or templates (e.g. GitHub Actions) to
generate docs in your CI/CD system.
[Track progress here.](https://github.com/backstage/backstage/issues/3400) You
will be able to use `techdocs-cli` to generate docs and publish the generated
docs site files to your cloud storage system.
Note about caching: We have noticed internally that some storage providers can
be quite slow, which is why we are recommending a cache that sits between the
TechDocs Reader and the Storage.
_Feel free to suggest better ideas to us in #docs-like-code channel in Discord
or via a GitHub issue._
### Security consideration
Our biggest security concern is managing the access to the docs in the cloud
storage. We also want to have only one security solution for all different types
of storage (GCS, AWS, custom SFTP server, etc.) Restricting access to the
storage and only allowing `techdocs-backend` to fetch files is a good way to
achieve this.
This would also allow us to use the access control management Backstage when
that is ready.
[Track progress here.](https://github.com/backstage/backstage/issues/3218)
In theory, you can directly enable TechDocs Reader to read from your storage.
But, you will have to think about how to do it without the docs being public and
how access to user groups is managed.
For cloud storage access tokens, `techdocs-backend` only needs a token with Read
permissions. But in your CI/CD system, there needs to be a token with Write
permissions to publish the generated docs site files.
## FAQs
**Q: Why do you have separate "basic" and "recommended" deployment approaches?**
A: The basic or out-of-the-box setup is what you get when you create a new app
or do a git clone of the Backstage repository. We want the first experience to
_just work magically_ so that you can have your first experience with TechDocs
which is smooth. However, if you decide to deploy Backstage/TechDocs for
production use, the basic setup would work but there are going to be downsides
as you scale with the number of documentation sites and sizes of them. So you
would want to make sure the deployment is as stable as possible. Hence there is
a recommended approach. There can be even more deployment approaches to TechDocs
and we welcome such "Alternative" ideas from the community.
**Q: Why don't you recommend techdocs-backend local filesystem to serve static
files?**
A: It would make scaling a Backstage instance harder. Think about the case where
we have distributed Backstage deployments. Using a separate file storage system
for TechDocs makes it easier to do some operations like delete a docs site and
wipe its contents.
**Q: Why aren't docs built on the fly i.e. when users visits a page, generate
docs site in real-time?**
A: Generating the content from Markdown on the fly is not optimal (although that
is how the basic out-of-the-box setup is implemented). Storage solutions act as
a cache for the generated static content. TechDocs is also currently built on
MkDocs which does not allow us to generate docs per-page, so we would have to
build all docs for a entity on every request.
# Future work
_Ideas here are far fetched and not in the project's milestone for near future
(~6 months)._
We currently depend on MkDocs to parse doc sites written in Markdown. And we
store the generated static assets and re-use it later to render in Backstage. A
better (futuristic) approach will be to directly parse whatever type of source
files you have in your docs repository and directly render in Backstage in
real-time.
# Features status
Status of all the features mentioned above.
**In place ✅**
- Basic setup with techdocs-backend file server as storage.
- Basic setup with cloud storage solution.
**Work in progress 🚧**
- `techdocs-cli` is able to generate docs in CI/CD environment.
- `techdocs-cli` is able to publish docs site to any storage.
**Not implemented yet ❌**
- `techdocs-backend` integration with Backstage access control management.
docs/features/techdocs/concepts.md
+44 -15
View File
@@ -8,15 +8,45 @@ Spotify's docs-like-code solution in Backstage
This page describes concepts that are introduced with Spotify's docs-like-code
solution in Backstage.
### TechDocs Core Plugin
## Generating TechDocs Steps
The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created
as a wrapper around multiple MkDocs plugins and Python Markdown extensions to
standardize the configuration of MkDocs used for TechDocs.
### TechDocs Preparer
[TechDocs Core](https://github.com/backstage/mkdocs-techdocs-core)
Preparing is the first step of generating documentation for an entity. It
fetches the source markdown files from the source code hosting provider (GitHub,
GitLab, etc.) and passes the files to the generator for next steps.
### TechDocs container
There are two kinds of preparers available -
1. Common Git Preparer - Uses `git clone` on any repository url.
2. Url Reader - Uses source code hosting provider's API to download files.
(Faster and recommended)
### TechDocs Generator
Generating is the second step after preparing the markdown source files. This
step either runs the TechDocs container (defined below) or runs `mkdocs` CLI to
generate static HTML files and its assets.
### TechDocs Publisher
Publishing is the third and final step after preparing and generating docs.
TechDocs Publisher uploads the generated files to a storage.
The `techdocs-backend` plugin currently comes with two publishers - Google Cloud
Storage and Local Filesystem. You can configure them in your Backstage app.
[See here](./configuration.md).
A TechDocs publisher is responsible for two things (two-way communication
between `techdocs-backend` and the storage)
1. Publish generated static files to a storage (Configured by
`techdocs.builder`)
2. Read files from the storage when users visit a TechDocs site
[TechDocs Backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
## TechDocs Container
The TechDocs container is a Docker container available at
[DockerHub](https://hub.docker.com/r/spotify/techdocs). It builds static HTML
@@ -25,16 +55,15 @@ MkDocs.
[TechDocs Container](https://github.com/backstage/techdocs-container)
### TechDocs publisher
## TechDocs Core Plugin
The `techdocs-backend` plugin currently comes with one publisher -
`LocalPublish`.
The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created
as a wrapper around multiple MkDocs plugins and Python Markdown extensions to
standardize the configuration of MkDocs used for TechDocs.
[TechDocs Backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
[TechDocs Core](https://github.com/backstage/mkdocs-techdocs-core)
More standalone publishers will come in the near future...
### TechDocs CLI
## TechDocs CLI
The TechDocs CLI was created to make it easy to write, generate and preview
documentation for publishing. Currently it mostly acts as a wrapper around the
@@ -43,7 +72,7 @@ container.
[TechDocs CLI](https://github.com/backstage/techdocs-cli)
### TechDocs Reader
## TechDocs Reader
Documentation generated by TechDocs is generated as static HTML sites. The
TechDocs Reader was therefore created to be able to integrate pre-generated HTML
@@ -55,7 +84,7 @@ TechDocs widgets for a customized full-featured TechDocs experience.
[TechDocs Reader](https://github.com/backstage/backstage/blob/master/plugins/techdocs/src/reader/README.md)
### Transformers
## Transformers
Transformers are different pieces of functionality used inside the TechDocs
Reader. The reason why transformers were introduced was to provide a way to
docs/features/techdocs/configuration.md
+89
View File
@@ -0,0 +1,89 @@
---
id: configuration
title: TechDocs Configuration Options
description:
Reference documentation for configuring TechDocs using app-config.yaml
---
Using the `app-config.yaml` in the Backstage app, you can configure TechDocs
using several options. This page serves as a reference to all the available
configuration options for TechDocs.
```yaml
# File: app-config.yaml
techdocs:
# TechDocs makes API calls to techdocs-backend using this URL. e.g. get docs of an entity, get metadata, etc.
requestUrl: http://localhost:7000/api/techdocs
# Just another route in techdocs-backend where TechDocs requests the static files from. This URL uses an HTTP middleware
# to serve files from either a local directory or an External storage provider.
storageUrl: http://localhost:7000/api/techdocs/static/docs
# generators.techdocs can have two values: 'docker' or 'local'. This is to determine how to run the generator - whether to
# spin up the techdocs-container docker image or to run mkdocs locally (assuming all the dependencies are taken care of).
# You want to change this to 'local' if you are running Backstage using your own custom Docker setup and want to avoid running
# into Docker in Docker situation. Read more here
# https://backstage.io/docs/features/techdocs/getting-started#disable-docker-in-docker-situation-optional
generators:
techdocs: 'docker'
# techdocs.builder can be either 'local' or 'external.
# If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to generate the docs, publish to storage
# and show the generated docs afterwords. This is the "Basic" setup of the TechDocs Architecture.
# If builder is set to 'external', techdocs-backend will only fetch the docs and will NOT try to generate and publish. In this case of 'external',
# we assume that docs are being built by an external process (e.g. in the CI/CD pipeline of the repository). This is the "Recommended" setup of
# the architecture. Read more here https://backstage.io/docs/features/techdocs/architecture
builder: 'local'
# techdocs.publisher is used to configure the Storage option, whether you want to use the local filesystem to store generated docs
# or you want to use External storage providers like Google Cloud Storage, AWS S3, etc.
publisher:
# techdocs.publisher.type can be - 'local' or 'googleGcs' (awsS3, azureStorage, etc. to be available as well).
# When set to 'local', techdocs-backend will create a 'static' directory at its root to store generated documentation files.
# When set to 'googleGcs', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files.
# When set to 'awsS3', techdocs-backend will use an Amazon Web Service (AWS) S3 bucket to store generated documentation files.
type: 'local'
# Required when techdocs.publisher.type is set to 'googleGcs'. Skip otherwise.
googleGcs:
# An API key is required to write to a storage bucket.
credentials:
$file: '/path/to/google_application_credentials.json',
# Your GCP Project ID where the Cloud Storage Bucket is hosted.
projectId: 'gcp-project-id'
# Cloud Storage Bucket Name
bucketName: 'techdocs-storage',
# Required when techdocs.publisher.type is set to 'awsS3'. Skip otherwise.
awsS3:
# An API key is required to write to a storage bucket.
credentials:
accessKeyId:
$env: TECHDOCS_AWSS3_ACCESS_KEY_ID_CREDENTIAL
secretAccessKey:
$env: TECHDOCS_AWSS3_SECRET_ACCESS_KEY_CREDENTIAL
region:
$env: AWSS3_REGION
# AWS S3 Bucket Name
bucketName: 'techdocs-storage',
```
docs/features/techdocs/creating-and-publishing.md
+1 -1
View File
@@ -41,7 +41,7 @@ setup for free.
### Manually add documentation setup to already existing repository
Prerequisities:
Prerequisites:
- An existing component
[registered in backstage](../software-catalog/index.md#adding-components-to-the-catalog)
docs/features/techdocs/getting-started.md
+180 -56
View File
@@ -1,7 +1,7 @@
---
id: getting-started
title: Getting Started
description: Getting Started Guidelines
description: Getting Started Documentation
---
TechDocs functions as a plugin to Backstage, so you will need to use Backstage
@@ -10,50 +10,147 @@ to use TechDocs.
If you haven't setup Backstage already, start
[here](../../getting-started/index.md).
## Installing TechDocs
> If you used `npx @backstage/create-app`, TechDocs may already be present.
>
> You should skip to [`Setting the Configuration`](#setting-the-configuration)
> below.
TechDocs is provided with the Backstage application by default. If you want to
set up TechDocs manually, keep following the instructions below.
### Adding the package
## Adding TechDocs frontend plugin
The first step is to add the TechDocs plugin to your Backstage application.
Navigate to your new Backstage application folder:
```bash
cd hello-world/
```
Then navigate to your `packages/app` folder to install TechDocs:
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/
cd packages/app
yarn add @backstage/plugin-techdocs
```
After a short while, the TechDocs plugin should be successfully installed.
Once the package has been installed, you need to import the plugin in your app.
Next, you need to set up some basic configuration. Enter the following command:
```bash
yarn install
```
Add this to `packages/app/src/plugins.ts`:
Add the following to `packages/app/src/plugins.ts`:
```typescript
export { plugin as TechDocs } from '@backstage/plugin-techdocs';
```
### Setting the configuration
Now let us embed the TechDocs router in our main Backstage frontend router. In
`packages/app/src/App.tsx`, import the TechDocs router and add the following to
`AppRoutes`:
TechDocs allows for configuration of the docs storage URL through your
`app-config.yaml` file. We provide two different values to be configured,
`requestUrl` and `storageUrl`. The `requestUrl` is what the reader will request
its data from, and `storageUrl` is where the backend can find the stored
documentation.
```tsx
import { Router as DocsRouter } from '@backstage/plugin-techdocs';
The default storage and request URLs:
// ...
const AppRoutes = () => {
<Routes>
// ... other plugin routes
<Route path="/docs/*" element={<DocsRouter />} />
</Routes>;
};
```
That's it! But now, we need the TechDocs Backend plugin for the frontend to
work.
## Adding TechDocs Backend plugin
Navigate to `packages/backend` of your Backstage app, and install the
`@backstage/plugin-techdocs-backend` package.
```bash
cd my-backstage-app/
cd packages/backend
yarn add @backstage/plugin-techdocs-backend
```
Create a file called `techdocs.ts` inside `packages/backend/src/plugins/` and
add the following
```typescript
import {
createRouter,
Preparers,
Generators,
Publisher,
} from '@backstage/plugin-techdocs-backend';
import { PluginEnvironment } from '../types';
import Docker from 'dockerode';
export default async function createPlugin({
logger,
config,
discovery,
reader,
}: PluginEnvironment) {
// Preparers are responsible for fetching source files for documentation.
const preparers = await Preparers.fromConfig(config, {
logger,
reader,
});
// Generators are used for generating documentation sites.
const generators = await Generators.fromConfig(config, {
logger,
});
// Publisher is used for
// 1. Publishing generated files to storage
// 2. Fetching files from storage and passing them to TechDocs frontend.
const publisher = await Publisher.fromConfig(config, {
logger,
discovery,
});
// Docker client (conditionally) used by the generators, based on techdocs.generators config.
const dockerClient = new Docker();
return await createRouter({
preparers,
generators,
publisher,
dockerClient,
logger,
config,
discovery,
});
}
```
You may need to install the `dockerode` package. But you may already have it in
your backend since [Scaffolder plugin](../software-templates/index.md) also uses
it.
See [Concepts](concepts.md) and [TechDocs Architecture](architecture.md) to
learn more about how preparers, generators and publishers work.
Final step is to import the techdocs backend plugin in Backstage app backend.
Add the following to your `packages/backend/src/index.ts`:
```typescript
import techdocs from './plugins/techdocs';
// .... main should already be present.
async function main() {
// ... other backend plugin envs
const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs'));
// ... other backend plugin routes
apiRouter.use('/techdocs', await techdocs(techdocsEnv));
}
```
That's it! TechDocs frontend and backend have now been added to your Backstage
app. Now let us tweak some configurations to suit your needs.
## Setting the configuration
**See [TechDocs Configuration Options](configuration.md) for complete
configuration reference.**
### Setting TechDocs URLs
```yaml
techdocs:
@@ -61,22 +158,59 @@ techdocs:
requestUrl: http://localhost:7000/api/techdocs/
```
If you want `techdocs-backend` to manage building and publishing, you want
`requestUrl` to point to the default value (or wherever `techdocs-backend` is
hosted). `storageUrl` should be where your publisher publishes your docs. Using
the default `LocalPublish` that is the default value.
`requestUrl` is used by TechDocs frontend plugin to discover techdocs-backend
endpoints, and the `storageUrl` is another endpoint in `techdocs-backend` which
acts as a middleware between TechDocs and the storage (where the static
generated docs site are stored). These default values should mostly work for
you. These options will soon be optional to set.
If you have a setup where you are not using `techdocs-backend` for managing
building and publishing of your documentation, you want to change the
`requestUrl` to point to your storage. In this case `storageUrl` is not
required.
### Should TechDocs Backend generate docs?
### Disable Docker in Docker situation (Optional)
```yaml
techdocs:
storageUrl: http://localhost:7000/api/techdocs/static/docs
requestUrl: http://localhost:7000/api/techdocs/
builder: 'local'
```
The TechDocs backend plugin runs a docker container with mkdocs installed to
Set `techdocs.builder` to `'local'` if you want your TechDocs Backend to be
responsible for generating documentation sites. If set to `'external'`,
Backstage will assume that the sites are being generated on each entity's CI/CD
pipeline, and are being stored in a storage somewhere.
When `techdocs.builder` is set to `'external'`, TechDocs becomes more or less a
read-only experience where it serves static files from a storage containing all
the generated documentation. Read more in the "Basic" and "Recommended" setup of
TechDocs [here](architecture.md)
### Choosing storage (publisher)
TechDocs needs to know where to store generated documentation sites and where to
fetch the sites from. This is managed by a
[Publisher](./concepts.md#techdocs-publisher). Examples: Google Cloud Storage,
Amazon S3, or local filesystem of Backstage server.
It is okay to use the local filesystem in a "Basic" setup when you are trying
out Backstage for the first time. Using Cloud Storage is documented
[here](./using-cloud-storage.md).
```yaml
techdocs:
storageUrl: http://localhost:7000/api/techdocs/static/docs
requestUrl: http://localhost:7000/api/techdocs/
builder: 'local'
publisher:
type: 'local'
```
### Disabling Docker in Docker situation (Optional)
You can skip this if your `techdocs.builder` is set to `'external'`.
The TechDocs Backend plugin runs a docker container with mkdocs installed to
generate the frontend of the docs from source files (Markdown). If you are
deploying Backstage using Docker, this will mean that your Backstage Docker
container will try to run another Docker container for TechDocs backend.
container will try to run another Docker container for TechDocs Backend.
To avoid this problem, we have a configuration available. You can set a value in
your `app-config.yaml` that tells the techdocs generator if it should run the
@@ -95,7 +229,7 @@ environment is compatible with techdocs.
You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from
pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g.
apt). See our
[Dockerfile](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/Dockerfile)
[Dockerfile](https://github.com/backstage/techdocs-container/blob/main/Dockerfile)
for the latest requirements. You should be trying to match your Dockerfile with
this one.
@@ -104,27 +238,17 @@ Note: We recommend Python version 3.7 or higher.
Caveat: Please install the `mkdocs-techdocs-core` package after all other Python
packages. The order is important to make sure we get correct version of some of
the dependencies. For example, we want `Markdown` version to be
[3.2.2](https://github.com/spotify/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11).
[3.2.2](https://github.com/backstage/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11).
You can also explicitly install `Markdown==3.2.2` after installing all other
Python packages.
## Run Backstage locally
## Running Backstage locally
Change folder to `<backstage-project-root>/packages/backend` and run the
following command:
Start the frontend and the backend app by
[running backstage locally](../../getting-started/running-backstage-locally.md).
```bash
yarn start
```
Open a new command line window. Change directory to your Backstage application
root and run the following command:
```bash
yarn start
```
Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/).
Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/)
to see all your documentation sites.
## Additional reading
docs/features/techdocs/using-cloud-storage.md
+267
View File
@@ -0,0 +1,267 @@
---
id: using-cloud-storage
title: Using Cloud Storage for TechDocs generated files
description: Using Cloud Storage for TechDocs generated files
---
In the [TechDocs architecture](./architecture.md) you have the option to choose
where you want to store the Generated static files which TechDocs uses to render
documentation. In both the "Basic" and "Recommended" setup, you can add cloud
storage providers like Google GCS, Amazon AWS S3, etc. By default, TechDocs uses
the local filesystem of the `techdocs-backend` plugin in the "Basic" setup. And
in the recommended setup, having one of the cloud storage is a prerequisite.
Read more on the TechDocs Architecture documentation page.
On this page you can read how to enable them.
## Configuring Google GCS Bucket with TechDocs
Follow the
[official Google Cloud documentation](https://googleapis.dev/nodejs/storage/latest/index.html#quickstart)
for the latest instructions on the following steps involving GCP.
**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
Set `techdocs.publisher.type` to `'googleGcs'`.
```yaml
techdocs:
publisher:
type: 'googleGcs'
```
**2. GCP (Google Cloud Platform) Project**
Create or choose a dedicated GCP project. Set
`techdocs.publisher.googleGcs.projectId` to the project ID.
```yaml
techdocs:
publisher:
type: 'googleGcs'
googleGcs:
projectId: 'gcp-project-id'
```
**3. Service account API key**
Create a new Service Account and a key associated with it. In roles of the
service account, use "Storage Admin".
If you want to create a custom role, make sure to include both `get` and
`create` permissions for both "Objects" and "Buckets". See
https://cloud.google.com/storage/docs/access-control/iam-permissions
A service account can have many keys. Open your newly created account's page (in
IAM & Admin console), and create a new key. Use JSON format for the key.
A `<GCP-PROJECT-ID-random-uid>.json` file will be downloaded. This is the secret
key TechDocs will use to make API calls. Make it available in your Backstage
server and/or your local development server and set it in the app config
`techdocs.publisher.googleGcs.credentials`.
```yaml
techdocs:
publisher:
type: 'googleGcs'
googleGcs:
projectId: 'gcp-project-id'
credentials:
$file: '/path/to/google_application_credentials.json'
```
**4. GCS Bucket**
Create a dedicated bucket for TechDocs sites. techdocs-backend will publish
documentation to this bucket. TechDocs will fetch files from here to serve
documentation in Backstage.
Set the name of the bucket to `techdocs.publisher.googleGcs.bucketName`.
```yaml
techdocs:
publisher:
type: 'googleGcs'
googleGcs:
projectId: 'gcp-project-id'
credentials:
$file: '/path/to/google_application_credentials.json'
bucketName: 'name-of-techdocs-storage-bucket'
```
**5. That's it!**
Your Backstage app is now ready to use Google Cloud Storage for TechDocs, to
store the static generated documentation files.
## Configuring AWS S3 Bucket with TechDocs
Follow the
[official AWS S3 documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html)
for the latest instructions on the following steps involving AWS S3.
**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
Set `techdocs.publisher.type` to `'awsS3'`.
```yaml
techdocs:
publisher:
type: 'awsS3'
```
**2. AWS Policies**
AWS Policies lets you **control access** to Amazon Web Services (AWS) products
and resources.
Here we will use a user policy **and** a bucket policy to show you the different
possibilities you have but you can use only one.
<img data-zoomable src="../../assets/techdocs/aws-s3.drawio.svg" alt="AWS S3" width="500" />
This is an example of how you can manage your policies:
a. Admin user creates a **bucket policy** granting a set of permissions to our
TechDocs user.
b. Admin user attaches a **user policy** to the TechDocs user granting
additional permissions.
c. TechDocs User then tries permissions granted via both the **bucket** policy
and the **user** policy.
**2.1 Creation**
**2.1.1 Create an Admin user** (if you don't have one yet)
Create an **administrator user** account `ADMIN_USER` and grant it administrator
privileges by attaching a user policy giving the account **full access**.
Note down the Admin User credentials and IAM User Sign-In URL as you will need
to use this information in the next step.
**2.1.2 Create an AWS S3 Bucket**
Using the credentials of your Admin User `ADMIN_USER`, and the special IAM user
sign-in URL, create a dedicated **bucket** for TechDocs sites. techdocs-backend
will publish documentation to this bucket. TechDocs will fetch files from here
to serve documentation in Backstage.
Set the name of the bucket to `techdocs.publisher.awsS3.bucketName`.
```yaml
techdocs:
publisher:
type: 'awsS3'
awsS3:
bucketName: 'name-of-techdocs-storage-bucket'
```
**2.1.3 Create the `TechDocs` user**
This user will be used to interact with your bucket, it will only have
permissions to **get - put** objects.
In the IAM console, do the following:
- Create a new user, `TechDocs`
- Note down the TechDocs User credentials
- Note down the Amazon Resource Name (ARN) for the TechDocs user. In the IAM
console, select the TechDocs user, and you can find the user ARN in the
Summary tab.
**2.2 Attach policies**
Remember that you can use Bucket policy **or** User policy.
Just make sure that you grant all the permissions to the TechDocs user:
`3:PutObject`, `s3:GetObject`, `s3:ListBucket` and `s3:GetBucketLocation`.
**2.2.1 Create the bucket policy**
You now have to attach the following policy to your bucket in the Permission
section:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "statement1",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/TechDocs"
},
"Action": ["s3:GetBucketLocation", "s3:ListBucket"],
"Resource": ["arn:aws:s3:::name-of-techdocs-storage-bucket"]
},
{
"Sid": "statement2",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/TechDocs"
},
"Action": ["s3:GetObject"],
"Resource": ["arn:aws:s3:::name-of-techdocs-storage-bucket/*"]
}
]
}
```
- The first statement grants **TechDocs User** the bucket operation permissions
`s3:GetBucketLocation` and `s3:ListBucket` which are permissions required by
the console.
- The second statement grants the `s3:GetObject` permission.
(**NOTE :** if you do not use the user policy defined below you must also add
the `s3:PutObject` permission to allow the TechDocs user to add objects.)
**2.2.2 Create the user policy**
Create an inline policy for the TechDocs user by using the following policy:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PermissionForObjectOperations",
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": ["arn:aws:s3:::name-of-techdocs-storage-bucket/*"]
}
]
}
```
See more details in the section
[Working with Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html).
Now you need to fill in the environment variables with the `TechDocs` User
credentials. You can also specify a region if you want to accesses the resources
in a specific region. Otherwise no region will be selected by default.
```properties
TECHDOCS_AWSS3_ACCESS_KEY_ID_CREDENTIAL="TECHDOCS_ACCESS_KEY_ID"
TECHDOCS_AWSS3_SECRET_ACCESS_KEY_CREDENTIAL="TECHDOCS_SECRET_ACCESS_KEY"
AWSS3_REGION="" // Optional
```
Make it available in your Backstage server and/or your local development server
and set it in the app config techdocs.publisher.awsS3.
```yaml
techdocs:
publisher:
type: 'awsS3'
awsS3:
credentials:
accessKeyId:
$env: TECHDOCS_AWSS3_ACCESS_KEY_ID_CREDENTIAL
secretAccessKey:
$env: TECHDOCS_AWSS3_SECRET_ACCESS_KEY_CREDENTIAL
region:
$env: AWSS3_REGION
```
**3. That's it!**
Your Backstage app is now ready to use AWS S3 for TechDocs, to store the static
generated documentation files.
docs/getting-started/configure-app-with-plugins.md
+47 -1
View File
@@ -6,7 +6,53 @@ description: Documentation on How Configuring App with plugins
## Adding existing plugins to your app
Coming soon!
The following steps assume that you have created a new Backstage app and want to
add an existing plugin to it. We are using the
[CircleCI](https://github.com/backstage/backstage/blob/master/plugins/circleci/README.md)
plugin in this example.
1. Add the plugin's npm package to the repo:
```bash
yarn add @backstage/plugin-circleci
```
2. Add the plugin itself:
```js
// packages/app/src/plugins.ts
export { plugin as Circleci } from '@backstage/plugin-circleci';
```
3. Register the plugin router:
```jsx
// packages/app/src/components/catalog/EntityPage.tsx
import { Router as CircleCIRouter } from '@backstage/plugin-circleci';
// Then somewhere inside <EntityPageLayout>
<EntityPageLayout.Content
path="/ci-cd/*"
title="CI/CD"
element={<CircleCIRouter />}
/>;
```
Note that stand-alone plugins that are not "attached" to the Software Catalog
would be added outside the `EntityPage`.
4. [Optional] Add proxy config:
```yaml
// app-config.yaml
proxy:
'/circleci/api':
target: https://circleci.com/api/v1.1
headers:
Circle-Token:
$env: CIRCLECI_AUTH_TOKEN
```
### Adding a plugin page to the Sidebar
docs/getting-started/create-an-app.md
+38 -2
View File
@@ -14,7 +14,7 @@ need to run Backstage in your own environment.
To create a Backstage app, you will need to have
[Node.js](https://nodejs.org/en/download/) Active LTS Release installed
(currently v12).
(currently v14).
Backstage provides a utility for creating new apps. It guides you through the
initial setup of selecting the name of the app and a database for the backend.
@@ -38,6 +38,42 @@ app-folder is the name that was provided when prompted.
Inside that directory, it will generate all the files and folder structure
needed for you to run your app.
### Linking in local Backstage packages
It can often be useful to try out changes to the packages in the main Backstage
repo within your own app. For example if you want to make modifications to
`@backstage/core` and try them out in your app.
To link in external packages, add them to your `package.json` and `lerna.json`
workspace paths. These can be either relative or absolute paths with or without
globs. For example:
```json
"packages": [
"packages/*",
"plugins/*",
"../backstage/packages/core", // New path added to work on @backstage/core
],
```
Then reinstall packages to make yarn set up symlinks:
```bash
yarn install
```
With this in place you can now modify the `@backstage/core` package within the
main repo, and have those changes be reflected and tested in your app. Simply
run your app using `yarn start` as normal.
Note that for backend packages you need to make sure that linked packages are
not dependencies of any non-linked package. If you for example want to work on
`@backstage/backend-common`, you need to also link in other backend plugins and
packages that depend on `@backstage/backend-common`, or temporarily disable
those plugins in your backend. This is because the transformation of backend
module tree stops whenever a non-local package is encountered, and from that
point node will `require` packages directly for that entire module subtree.
### Troubleshooting
The create app command doesn't always work as expected, this is a collection of
@@ -51,7 +87,7 @@ You may encounter the following error message:
Couldn't find any versions for "file-saver" that matches "eligrey-FileSaver.js-1.3.8.tar.gz-art-external"
```
This is likely because you have a globally configured NPM proxy, which breaks
This is likely because you have a globally configured npm proxy, which breaks
the installation of the `material-table` dependency. This is a known issue and
being worked on in `material-table`, but for now you can work around it using
the following:
docs/getting-started/index.md
+1 -1
View File
@@ -10,7 +10,7 @@ you're planning to do.
Creating a standalone instance makes it simpler to customize the application for
your needs whilst staying up to date with the project. You will also depend on
`@backstage` packages from NPM, making the project much smaller. This is the
`@backstage` packages from npm, making the project much smaller. This is the
recommended approach if you want to kick the tyres of Backstage or setup your
own instance.
docs/getting-started/running-backstage-locally.md
+5 -5
View File
@@ -8,19 +8,19 @@ description: Documentation on How to run Backstage Locally
- Node.js
First make sure you are using Node.js with an Active LTS Release, currently v12.
First make sure you are using Node.js with an Active LTS Release, currently v14.
This is made easy with a version manager such as
[nvm](https://github.com/nvm-sh/nvm) which allows for version switching.
```bash
# Installing a new version
nvm install 12
> Downloading and installing node v12.18.3...
> Now using node v12.18.3 (npm v6.14.6)
nvm install 14
> Downloading and installing node v14.15.1...
> Now using node v14.15.1 (npm v6.14.8)
# Checking your version
node --version
> v12.18.3
> v14.15.1
```
- Yarn
docs/overview/roadmap.md
+35 -39
View File
@@ -47,55 +47,42 @@ guidelines to get started.
### Ongoing work 🚧
- **[Plugins for managing micro services end-2-end](https://github.com/backstage/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.
- **[Platform stabilization](https://github.com/backstage/backstage/milestone/19)** -
Stabilize the core of Backstage, including its core features, so that the
platform can be depended on for production use. After this, plugins will
require little-to-no maintenance.
- **[Users and teams](https://github.com/backstage/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.
- **[Kubernetes plugin for service owners](https://github.com/backstage/backstage/issues/2857)** -
Improve native support for Kubernetes, making it easier for service owners to
see and manage their services running in K8s, regardless if that's locally, in
AWS, GCS, Azure, or elsewhere.
- **[Backstage platform is stable](https://github.com/backstage/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.
- **Global search** - Extend the basic search functionality currently available
in the Backstage Service Catalog to become a global search experience.
* **[Improved Kubernetes plugin](https://github.com/backstage/backstage/issues/2857)** -
Native support for Kubernetes, making it easier for developers to see and
manage their services running in k8s.
- Further improvements to platform documentation. Examples include a Golden Path
for plugin development.
- **[Software Templates V2](https://github.com/backstage/backstage/issues/2771)** -
Expand the templates to make the steps more composable by adding the ability
to add more steps for custom logic, including webhooks and using authorization
from integrations.
### Future work 🔮
- **Deploy a product demo at `demo.backstage.io`** - Deploy a typical Backstage
deployment available publicly so that people can click around and get a feel
for the product without having to install anything.
- **Golden Path for Plugin Development** - Create an easy, standardized way for
developers to build plugins that will encourage contributions and lead to a
richer ecosystem for everyone.
- **[Global search](https://github.com/backstage/backstage/issues/1499)** -
Extend the basic search available in the Backstage Service Catalog with a
global search experience. Long term this search solution should be extensible,
making it possible for you add custom search results.
- **[[TechDocs V.2] Stabilization release](https://github.com/backstage/backstage/milestone/17)** -
Platform stability and compatibility improvements.
- **Additional auth providers** - Backstage should work for most (all!) auth
solutions. Since Backstage can be used by companies regardless of what cloud
(or on prem) you are using we are especially keen to get auth support for
[AWS](https://github.com/backstage/backstage/issues/290),
[Azure](https://github.com/backstage/backstage/issues/348) and others.
- **[Initial GraphQL API](https://github.com/backstage/backstage/milestone/13)** -
A GraphQL API will open up the rich metadata provided by Backstage in a single
- **[GraphQL API](https://github.com/backstage/backstage/milestone/13)** - A
GraphQL API will open up the rich metadata provided by Backstage in a single
query. Plugins can easily query this API as well as extend the model where
needed.
- **Inter-Plugin Communication** - **[Under consideration]** Establish more
clearly defined patterns for plugins to communicate.
- **Improved Access Control** - **[Under consideration]** Provide finer grained
access controls and management for better control of the platform user
experience.
### Plugins
Building and maintaining [plugins](https://backstage.io/plugins) is the work of
@@ -110,8 +97,17 @@ Are you missing a plugin for your favorite tool? Please
[suggest a new one](https://github.com/backstage/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.
### Community Initiatives 🧑‍🤝‍🧑 (Coming soon)
- **Backstage Monthly Meetup** - A space for the community to come together to
share and learn about the latest happenings in Backstage.
- **Backstage Hackathons** - Open to everyone in our Backstage community, a
celebration of you, the project and building awesome things together
### Completed milestones ✅
- [Deploy a product demo at `demo.backstage.io`](https://demo.backstage.io)
- [Kubernetes plugin - v1](https://github.com/backstage/backstage/tree/master/plugins/kubernetes)
- [Helm charts](https://github.com/backstage/backstage/tree/master/contrib/chart/backstage)
- [Backstage Design System 💅](https://backstage.io/blog/2020/09/30/backstage-design-system)
docs/overview/stability-index.md
+395
View File
@@ -0,0 +1,395 @@
---
id: stability-index
title: Stability Index
description:
An overview of the commitment to stability for different parts of the
Backstage codebase.
---
## Overview
The purpose of the Backstage Stability Index is to communicate the stability of
various parts of the project. It is tracked using a scoring system where a
higher score indicates a higher level of stability and is a commitment to
smoother transitions between breaking changes. Importantly, the Stability Index
does not supersede [semver](https://semver.org/), meaning we will still adhere
to semver and only do breaking changes in minor releases as long as we are on
`0.x`.
Each package or section is assigned a stability score between 0 and 3, with each
point building on top of the previous one:
- **0** - Breaking changes are noted in the changelog, and documentation is
updated.
- **1** - The changelog entry includes a clearly documented upgrade path,
providing guidance for how to migrate previous usage patterns to the new
version.
- **2** - Breaking changes always include a deprecation phase where both the old
and the new APIs can be used in parallel. This deprecation must have been
released for at least two weeks before the deprecated API is removed in a
minor version bump.
- **3** - The time limit for the deprecation is 3 months instead of two weeks.
TL;DR:
- **0** - There's a changelog entry.
- **1** - There's a migration guide.
- **2** - 2 weeks of deprecation.
- **3** - 3 months of deprecation.
## Packages
### `example-app` [GitHub](https://github.com/backstage/backstage/tree/master/packages/app/)
This is the `packages/app` package, and it serves as an example as well as
utility for local development in the main Backstage repo.
Stability: `N/A`
### `example-backend` [GitHub](https://github.com/backstage/backstage/tree/master/packages/backend/)
This is the `packages/backend` package, and it serves as an example as well as
utility for local development in the main Backstage repo.
Stability: `N/A`
### `backend-common` [GitHub](https://github.com/backstage/backstage/tree/master/packages/backend-common/)
A collection of common helpers to be used by both backend plugins, and for
constructing backend packages.
Stability: `1`
### `catalog-client` [GitHub](https://github.com/backstage/backstage/tree/master/packages/catalog-client/)
An HTTP client for interacting with the catalog backend. Usable both in frontend
and Backend.
Stability: `0`. This is a very new addition and we have some immediate changes
planned.
### `catalog-model` [GitHub](https://github.com/backstage/backstage/tree/master/packages/catalog-model/)
Contains the core catalog model, and utilities for working with entities. Usable
both in frontend and Backend.
Stability: `2`. The catalog model is evolving, but because of the broad usage we
want to ensure some stability.
### `cli` [GitHub](https://github.com/backstage/backstage/tree/master/packages/cli/)
The main toolchain used for Backstage development. The various CLI commands and
options passed to those commands, as well as the environment variables read by
the CLI, are considered to be the interface that the stability index refers to.
The build output may change over time and is not considered a breaking change
unless it is likely to affect external tooling.
Stability: `2`
### `cli-common` [GitHub](https://github.com/backstage/backstage/tree/master/packages/cli-common/)
Lightweight utilities used by the various Backstage CLIs, not intended for
external use.
Stability: `N/A`
### `config` [GitHub](https://github.com/backstage/backstage/tree/master/packages/config/)
Provides the logic and interfaces for reading static configuration.
Stability: `2`
### `config-loader` [GitHub](https://github.com/backstage/backstage/tree/master/packages/config-loader/)
Used to load in static configuration, mainly for use by the CLI and
@backstage/backend-common.
Stability: `1`. Mainly intended for internal use.
### `core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core/)
#### Section: React Components
All of the React components exported from `src/components/` and `src/layout/`
Stability: `1`. These components have not received a proper review of the API,
but we also want to ensure stability.
#### Section: Plugin API
The parts of the core API that are used by plugins, and the way plugins expose
functionality to apps and other plugins. Includes for example `createPlugin`,
`createRouteRef`, `createApiRef`.
Stability: `2`. There are planned breaking changes around the way that plugins
expose features and do routing. We still commit to keeping a short deprecation
period so that plugins outside of the main repo have time to migrate.
#### Section: App API
The APIs used exclusively in the app, such as `createApp` and the system icons.
Stability: `2`
#### Section: Utility API Definitions
The type declarations of the core Utility APIs.
Stability: `2`. Changes to the Utility API type declarations need time to
propagate.
#### Section: Utility API Implementations
The interfaces and default implementations for various Utility APIs, such as
ErrorApi, IdentityApi, the auth APIs, etc.
Stability: `1`. Most changes to the core utility APIs will not lead to
widespread breaking changes since most apps rely on the default implementations.
### `core-api` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core-api/)
The non-visual parts of @backstage/core. Everything in this packages is
re-exported from @backstage/core, and this package should not be used directly.
Stability: See @backstage/core
### `create-app` [GitHub](https://github.com/backstage/backstage/tree/master/packages/create-app/)
The CLI used to scaffold new Backstage projects.
Stability: `2`
### `dev-utils` [GitHub](https://github.com/backstage/backstage/tree/master/packages/dev-utils/)
Provides utilities for developing plugins in isolation.
Stability: `0`. This package is largely broken and needs updates.
### `docgen` [GitHub](https://github.com/backstage/backstage/tree/master/packages/docgen/)
Internal CLI utility for generating API Documentation.
Stability: `N/A`
### `e2e-test` [GitHub](https://github.com/backstage/backstage/tree/master/packages/e2e-test/)
Internal CLI utility for running e2e tests.
Stability: `N/A`
### `integration` [GitHub](https://github.com/backstage/backstage/tree/master/packages/integration/)
Provides shared utilities for managing integrations towards different types of
third party systems. This package is currently internal and its functionality
will likely be exposed via separate APIs in the future.
Some of the functionality in this package is not available elsewhere yes, so if
it's necessary it can be used, but there will be breaking changes.
Stability: `0`
### `storybook` [GitHub](https://github.com/backstage/backstage/tree/master/packages/storybook/)
Internal storybook build for publishing stories to
https://backstage.io/storybook
Stability: `N/A`
### `test-utils` [GitHub](https://github.com/backstage/backstage/tree/master/packages/test-utils/)
Utilities for writing tests for Backstage plugins and apps.
Stability: `2`
### `test-utils-core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/test-utils-core/)
Internal testing utilities that are separated out for usage in
@backstage/core-api. All exports are re-exported by @backstage/test-utils. This
package should not be depended on directly.
Stability: See @backstage/test-utils
### `theme` [GitHub](https://github.com/backstage/backstage/tree/master/packages/theme/)
The core Backstage MUI theme along with customization utilities.
#### Section: TypeScript
This is the TypeScript API exported by the theme package.
Stability: `2`
#### Section: Visual Theme
The visual theme exported by the theme packages, where for example changing a
color could be considered a breaking change.
Stability: `1`
## Plugins
Plugins are rarely marked as stable as the `@backstage/core` plugin API is under
heavy development.
Many backend plugins are split into "REST API" and "TypeScript Interface"
sections. The "TypeScript Interface" refers to the API used to integrate the
plugin into the backend.
Any plugin that is not listed below is untracked and can generally be considered
unstable with a score of `0`. Open a Pull Request if you want your plugin to be
added!
### `api-docs` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/api-docs/)
Components to discover and display API entities as an extension to the catalog
plugin.
Stability: `0`
### `app-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/app-backend/)
A backend plugin that can be used to serve the frontend app and inject
configuration.
Stability: `2`
### `auth-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/auth-backend/)
A backend plugin that implements the backend portion of the various
authentication flows used in Backstage.
#### Section: REST API
Stability: `2`
#### Section: TypeScript Interface
Stability: `1`
### `catalog` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog/)
The frontend plugin for the catalog, with the table and building blocks for the
entity pages.
Stability: `1`. We're planning some work to overhaul how entity pages are
constructed.
### `catalog-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend/)
The backend API for the catalog, also exposes the processing subsystem for
customization of the catalog. Powers the @backstage/plugin-catalog frontend
plugin.
#### Section: REST API
Stability: `1`. There are plans to remove and rework some endpoints.
#### Section: TypeScript Interface
Stability: `1`. There are plans to rework parts of the Processor interface.
### `catalog-graphql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog-graphql/)
Provides the catalog schema and resolvers for the graphql backend.
Stability: `0`. Under heavy development and subject to change.
### `explore` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/explore/)
A frontend plugin that introduces the concept of exploring internal and external
tooling in an organization.
Stability: `0`. Only an example at the moment and not customizable.
### `graphiql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/graphiql/)
Integrates GraphiQL as a tool to browse GraphQL API endpoints inside Backstage.
Stability: `1`
### `graphql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/graphql/)
A backend plugin that provides
Stability: `0`. Under heavy development and subject to change.
### `kubernetes` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/kubernetes/)
The frontend component of the Kubernetes plugin, used to browse and visualize
Kubernetes resources.
Stability: `1`.
### `kubernetes-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/kubernetes-backend/)
The backend component of the Kubernetes plugin, used to fetch Kubernetes
resources from clusters and associate them with entities in the Catalog.
Stability: `1`.
### `proxy-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/proxy-backend/)
A backend plugin used to set up proxying to other endpoints based on static
configuration.
Stability: `1`
### `register-component` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/register-component/)
A frontend plugin that allows the user to register entity locations in the
catalog.
Stability: `0`. This plugin is likely to be replaced by a generic entity import
plugin instead.
### `scaffolder` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/scaffolder/)
The frontend scaffolder plugin where one can browse templates and initiate
scaffolding jobs.
Stability: `1`
### `scaffolder-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend/)
The backend scaffolder plugin that provides an implementation for templates in
the catalog.
Stability: `1`. There is planned work to rework the scaffolder in
https://github.com/backstage/backstage/issues/2771.
### `tech-radar` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/tech-radar/)
Visualize the your company's official guidelines of different areas of software
development.
Stability: `0`
### `techdocs` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/techdocs/)
The frontend component of the TechDocs plugin, used to browse technical
documentation of entities.
Stability: `1`
### `techdocs-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/)
The backend component of the TechDocs plugin, used to transform and serve
TechDocs.
Stability: `0`
### `user-settings` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/user-settings/)
A frontend plugin that provides a page where the user can tweak various
settings.
Stability: `1`
### `welcome` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/welcome/)
A plugin that can be used to welcome the user to Backstage.
Stability: `0`. This used to be the start page for the example app, but has been
replaced by the catalog plugin. It is still viewable at `/welcome` but may be
removed.
docs/overview/what-is-backstage.md
+1 -1
View File
@@ -9,7 +9,7 @@ Powered by a centralized service catalog, Backstage restores order to your micro
[Backstage](https://backstage.io/) is an open platform for building developer
portals. Powered by a centralized service catalog, Backstage restores order to
your microservices and infrastructure. So your product teams can ship
your microservices and infrastructure and enables your product teams to ship
high-quality code quickly — without compromising autonomy.
Backstage unifies all your infrastructure tooling, services, and documentation
docs/plugins/index.md
+1 -1
View File
@@ -33,4 +33,4 @@ that someone else will pick up the work.
If your plugin isn't supposed to live as a standalone page, but rather needs to
be presented as a part of a Service Catalog (e.g. a separate tab or a card on an
"Overview" tab), then check out
[the instruction](integrating-plugin-into-service-catalog.md). on how to do it.
[the instruction](integrating-plugin-into-service-catalog.md) on how to do it.
docs/plugins/proxying.md
+20 -13
View File
@@ -52,19 +52,7 @@ configuration will lead to the proxy acting on backend requests to
The value inside each route is either a simple URL string, or an object on the
format accepted by
[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware). It
is also possible to limit the forwarded HTTP methods with the configuration
`allowedMethods`, for example `allowedMethods: ['GET']` to enforce read-only
access.
By default, the proxy will only forward safe HTTP request headers to the target.
Those are based on the headers that are considered safe for CORS and includes
headers like `content-type` or `last-modified`, as well as all headers that are
set by the proxy. If the proxy should forward other headers like
`authorization`, this must be enabled by the `allowedHeaders` config, for
example `allowedHeaders: ['Authorization']`. This should help to not
accidentally forward confidential headers (`cookie`, `X-Auth-Request-User`) to
third-parties.
[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware).
If the value is a string, it is assumed to correspond to:
@@ -85,3 +73,22 @@ except with the following caveats for convenience:
`'^/api/proxy/larger-example/v1/': '/'` is added. That means that a request to
`/api/proxy/larger-example/v1/some/path` will be translated to a request to
`http://larger.example.com:8080/svc.v1/some/path`.
There are also additional settings:
- `allowedMethods`: Limit the forwarded HTTP methods. For example
`allowedMethods: ['GET']` enforces read-only access.
- `allowedHeaders`: A list of headers that should be forwarded to and received
from the target.
By default, the proxy will only forward safe HTTP request headers to the target.
Those are based on the headers that are considered safe for CORS and includes
headers like `content-type` or `last-modified`, as well as all headers that are
set by the proxy. If the proxy should forward other headers like
`authorization`, this must be enabled by the `allowedHeaders` config, for
example `allowedHeaders: ['Authorization']`. This should help to not
accidentally forward confidential headers (`cookie`, `X-Auth-Request-User`) to
third-parties.
The same logic applies to headers that are sent from the target back to the
frontend.
docs/plugins/publishing.md
+4 -4
View File
@@ -1,16 +1,16 @@
---
id: publishing
title: Publishing
description: Documentation on Publishing NPM packages
description: Documentation on Publishing npm packages
---
## NPM
## npm
NPM packages are published through CI/CD in the
npm packages are published through CI/CD in the
[.github/workflows/master.yml](https://github.com/backstage/backstage/blob/master/.github/workflows/master.yml)
workflow. Every commit that is merged to master will be checked for new versions
of all public packages, and any new versions will automatically be published to
NPM.
npm.
### Creating a new release
docs/plugins/testing.md
+44 -35
View File
@@ -16,15 +16,15 @@ frameworks and libraries like [Mocha](https://mochajs.org/),
Running all tests:
yarn test-react
yarn test
Running an individual test (e.g. `MyComponent.test.js`):
yarn test-react MyComponent
yarn test MyComponent
To run both `MyComponent.test.js` and `MyControl.test.js` suite of tests:
yarn test-react MyCo
yarn test MyCo
Note: if `console.logs` are not appearing, run only the individual test you are
working on.
@@ -52,12 +52,12 @@ render React components.
TODO.
# Writing Unit Tests
## Writing Unit Tests
The following principles are good guides for determining if you are writing high
quality frontend unit tests.
## Bad Unit Test Principle
### Bad Unit Test Principle
> No unit test is better than a bad one.
@@ -69,7 +69,7 @@ Writing a poor unit test:
- Adds to future work by requiring updates to the unit test for irrelevant code
changes.
## Input/Output Principle
### Input/Output Principle
> A unit test verifies an output matches an expected input.
@@ -77,7 +77,7 @@ For backend, this would be that when you provide configuration X, then the
object responds with Y. For frontend, this would be that when you provide
properties X to a component, then the visual functionality responds with Y.
## Blackbox Principle
### Blackbox Principle
> A good unit test does not tell the object how it should do its job but should
> only compare inputs to outputs.
@@ -86,7 +86,7 @@ Consider a unit test for a form. A good unit test would not test the order of
the form fields. Instead, it would verify that the inputs to the form fields
lead to a certain backend call when submit is clicked.
## Scalability Principle
### Scalability Principle
> Unit test quality is directly proportionate to how much code can change
> without having to touch the unit test.
@@ -97,7 +97,7 @@ to the code, you have to update the unit test. A good unit test suite allows a
lot of flexibility in _how_ the code is written so that future refactoring can
occur without having to touch the original unit tests.
## Increasing Complexity Principle
### Increasing Complexity Principle
> The ordering of unit tests in a suite should proceed from least specific to
> most specific.
@@ -116,7 +116,7 @@ throwing an error saying that output was incorrect will lead the next developer
into thinking they may have broken the entire functionality of the object rather
than simply letting them know they had an invalid input.
## Broken Functionality Principle
### Broken Functionality Principle
> Generally, a unit test should not test exactly how the output appears, it
> should test that the functionality has an expected _general_ response to an
@@ -131,7 +131,7 @@ test a slightly different color on the button the unit test will break. A better
unit test would verify that the button's CSS classname is assigned properly on
hover or test for something completely different.
## Example: Loading Indicator
### Example: Loading Indicator
A classic unit test on frontends is verifying a loading indicator displays when
a backend request is being made.
@@ -192,11 +192,14 @@ returns a result or displays an error or console message, like so:
**`StringUtil ellipsis`**
export function ellipsis(text, maxLength, midCharIx = 0, ellipsis = '...') {
// Do something blackbox. We should not care about the internals, only inputs and outputs.
...
return someFinalValue;
}
```js
export function ellipsis(text, maxLength, midCharIx = 0, ellipsis = '...') {
// Do something blackbox. We should not care about the internals,
// only inputs and outputs.
...
return someFinalValue;
}
```
There are four things to test for in a utility function:
@@ -207,34 +210,40 @@ There are four things to test for in a utility function:
> Handle Invalid Input (handle thrown errors):
it('Throws an error on improper arguments', () => {
expect(() => {
ellipsis();
}).toThrowError('Expected \'text\' to be defined');
});
```js
it('Throws an error on improper arguments', () => {
expect(() => {
ellipsis();
}).toThrowError("Expected 'text' to be defined");
});
```
> Verify default input arguments:
it('Works with defaults', () => {
expect(ellipsis('Hello world', 3)).toBe('Hel...');
expect(ellipsis('', 3)).toBe('');
expect(ellipsis('H', 3)).toBe('H');
expect(ellipsis('Hello', 5)).toBe('Hello');
});
```js
it('Works with defaults', () => {
expect(ellipsis('Hello world', 3)).toBe('Hel...');
expect(ellipsis('', 3)).toBe('');
expect(ellipsis('H', 3)).toBe('H');
expect(ellipsis('Hello', 5)).toBe('Hello');
});
```
> Verify output for expected input arguments:
This is especially true for edge cases!
it('Works with midCharIx', () => {
expect(ellipsis('Hello world', 3, 6)).toBe('...o w...');
expect(ellipsis('', 3, 6)).toBe('');
expect(ellipsis('Backstage is amazing', 4, 10)).toBe('...e is...');
});
```js
it('Works with midCharIx', () => {
expect(ellipsis('Hello world', 3, 6)).toBe('...o w...');
expect(ellipsis('', 3, 6)).toBe('');
expect(ellipsis('Backstage is amazing', 4, 10)).toBe('...e is...');
});
```
## Non-React Classes
Testing a Javascript object which is _not_ a React component follows a lot of
Testing a JavaScript object which is _not_ a React component follows a lot of
the same principles as testing objects in other languages.
### API Testing Principles
@@ -243,7 +252,7 @@ Testing an API involves verifying four things:
1. Invalid inputs are caught before being sent to the server.
2. Valid inputs translate into a valid browser request.
3. Server response is translated into an expected Javascript object.
3. Server response is translated into an expected JavaScript object.
4. Server errors are handled gracefully.
### Mocking API Calls
@@ -372,4 +381,4 @@ IDE.
In most cases, we have found that using `console.log` works well.
Note: if your console.logs are not being displayed, focus your specific unit
test from the command line by running them like so `yarn test-react MyTest`.
test from the command line by running them like so `yarn test MyTest`.
docs/reference/createPlugin-feature-flags.md
+1 -1
View File
@@ -27,7 +27,7 @@ To inspect the state of a feature flag inside your plugin, you can use the
`FeatureFlagsApi`, accessed via the `featureFlagsApiRef`. For example:
```tsx
import React, { FC } from 'react';
import React from 'react';
import { Button } from '@material-ui/core';
import { featureFlagsApiRef, useApi } from '@backstage/core';
docs/reference/createPlugin.md
+9 -5
View File
@@ -4,7 +4,7 @@ title: createPlugin
description: Documentation on createPlugin
---
Taking a plugin config as argument and returns a new plugin.
Takes a plugin config as an argument and returns a new plugin.
## Plugin Config
@@ -28,18 +28,22 @@ type PluginHooks = {
### Creating a basic plugin
Showcasing adding multiple routes, a feature flag and a redirect.
Showcasing adding a route and a feature flag.
```jsx
import { createPlugin } from '@backstage/core';
import { createPlugin, createRouteRef } from '@backstage/core';
import ExampleComponent from './components/ExampleComponent';
export const rootRouteRef = createRouteRef({
path: '/new-plugin',
title: 'New Plugin',
});
export default createPlugin({
id: 'new-plugin',
register({ router, featureFlags }) {
router.addRoute(rootRouteRef, ExampleComponent);
featureFlags.register('enable-example-component');
router.registerRoute('/new-plugin', ExampleComponent);
},
});
```
docs/support/project-structure.md
+17 -3
View File
@@ -41,8 +41,8 @@ the code.
appreciate contributions in here and encourage them being kept up to date.
- [`docs/`](https://github.com/backstage/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
where we keep all of our documentation Markdown files. These end up on
https://backstage.io/docs. Just keep in mind that changes to the
[`sidebars.json`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.json)
file may be needed as sections are added/removed.
@@ -89,6 +89,12 @@ are separated out into their own folder, see further down.
There are no "core" packages in the backend. Instead we have `backend-common`
which contains helper middleware and other utils.
- [`catalog-client`](https://github.com/backstage/backstage/tree/master/packages/catalog-client) -
An isomorphic client to interact with the Software Catalog. Backend plugins
can use the package directly. Frontend plugins can use the client by using
`@backstage/plugin-catalog` in combination with `useApi` and the
`catalogApiRef`.
- [`catalog-model/`](https://github.com/backstage/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
@@ -155,7 +161,7 @@ are separated out into their own folder, see further down.
- [`docgen/`](https://github.com/backstage/backstage/tree/master/packages/docgen) -
Uses the
[Typescript Compiler API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API)
[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/backstage/backstage/tree/master/packages/e2e-test) -
@@ -163,11 +169,19 @@ are separated out into their own folder, see further down.
packages, publish them, created a new app, and the run it. CI uses this for
e2e-tests.
- [`integration/`](https://github.com/backstage/backstage/tree/master/packages/integration) -
Common functionalities of integrations like GitHub, GitLab, etc.
- [`storybook/`](https://github.com/backstage/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-common/`](https://github.com/backstage/backstage/tree/master/packages/techdocs-common) -
Common functionalities for TechDocs, to be shared between
[techdocs-backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
plugin and [techdocs-cli](https://github.com/backstage/techdocs-cli).
- [`test-utils-core/`](https://github.com/backstage/backstage/tree/master/packages/test-utils-core)
- [`test-utils/`](https://github.com/backstage/backstage/tree/master/packages/test-utils)
docs/tutorials/journey.md
+1 -1
View File
@@ -22,7 +22,7 @@ music and wants to have a theme tune for every service in Backstage.
Sam built a Spotify plugin for Backstage that allows service owners to define a
theme tune for their service. The theme tune plays whenever a user visits the
service page in Backstage. The plugin is published to NPM and available for any
service page in Backstage. The plugin is published to npm and available for any
organization to easily install and add to their Backstage installation.
# 1. A New Plugin
docs/tutorials/quickstart-app-plugin.md
+5 -5
View File
@@ -81,13 +81,13 @@ import { useApi } from '@backstage/core-api';
_from inline:_
```tsx
const ExampleComponent: FC<{}> = () => ( ... )
const ExampleComponent = () => ( ... )
```
_to block:_
```tsx
const ExampleComponent: FC<{}> = () => {
const ExampleComponent = () => {
return (
...
@@ -135,7 +135,7 @@ changes, let's start by wiping this component clean.
1. Replace everything in the file with the following:
```tsx
import React, { FC } from 'react';
import React from 'react';
import { useAsync } from 'react-use';
import Alert from '@material-ui/lab/Alert';
import {
@@ -147,7 +147,7 @@ import {
import { useApi } from '@backstage/core-api';
import { graphql } from '@octokit/graphql';
const ExampleFetchComponent: FC<{}> = () => {
const ExampleFetchComponent = () => {
return <div>Nothing to see yet</div>;
};
@@ -223,7 +223,7 @@ type DenseTableProps = {
viewer: Viewer;
};
export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
export const DenseTable = ({ viewer }: DenseTableProps) => {
const columns: TableColumn[] = [
{ title: 'Name', field: 'name' },
{ title: 'Created', field: 'createdAt' },
microsite/README.md
+5
View File
@@ -204,3 +204,8 @@ For more information about custom pages, click [here](https://docusaurus.io/docs
# Full Documentation
Full documentation can be found on the [website](https://docusaurus.io/).
## Additional notes
- If you want to make images zoomable on click, add the `data-zoomable` attribute to your `img` element.
- In a docs or blog `.md` file, convert `![This is image](/microsite/static/img/code.png)` syntax to `<img data-zoomable src="/microsite/static/img/code.png" alt="This is image" />`
microsite/blog/2020-03-16-announcing-backstage.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
title: Announcing Backstage
author: Stefan Ålund
author: Stefan Ålund, Spotify
authorURL: http://twitter.com/stalund
authorImageURL: https://pbs.twimg.com/profile_images/121166861/6919c047c0d0edaace78c3009b28e917-user-full-200-130.generated_400x400.jpg
---

Some files were not shown because too many files have changed in this diff Show More