Merge branch 'master' of https://github.com/backstage/backstage
This commit is contained in:
Omer Farooq
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/core': patch
|
||||
---
|
||||
|
||||
Clear sidebar search field once a search is executed
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
'@backstage/catalog-model': minor
|
||||
'@backstage/plugin-kubernetes': minor
|
||||
'@backstage/plugin-kubernetes-backend': minor
|
||||
---
|
||||
|
||||
add kubernetes selector to component model
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/backend-common': patch
|
||||
---
|
||||
|
||||
Added readTree support to AzureUrlReader
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
The CLI now detects and transforms linked packages. You can link in external packages by adding them to both the `lerna.json` and `package.json` workspace paths.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-cost-insights': patch
|
||||
---
|
||||
|
||||
fix product icon configuration
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-cost-insights': patch
|
||||
---
|
||||
|
||||
truncate large percentages > 1000%
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/create-app': patch
|
||||
---
|
||||
|
||||
Replace `register-component` plugin with new `catalog-import` plugin
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-catalog-backend': patch
|
||||
---
|
||||
|
||||
Add support for reading groups and users from the Microsoft Graph API.
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-scaffolder': patch
|
||||
'@backstage/plugin-scaffolder-backend': patch
|
||||
---
|
||||
|
||||
Move constructing the catalog-info.yaml URL for scaffolded components to the publishers
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-register-component': patch
|
||||
---
|
||||
|
||||
Remove catalog link on validate popup
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
'@backstage/catalog-model': patch
|
||||
'@backstage/plugin-catalog-backend': patch
|
||||
---
|
||||
|
||||
Marked the `Group` entity fields `ancestors` and `descendants` for deprecation on Dec 6th, 2020. See https://github.com/backstage/backstage/issues/3049 for details.
|
||||
|
||||
Code that consumes these fields should remove those usages as soon as possible. There is no current or planned replacement for these fields.
|
||||
|
||||
The BuiltinKindsEntityProcessor has been updated to inject these fields as empty arrays if they are missing. Therefore, if you are on a catalog instance that uses the updated version of this code, you can start removing the fields from your source catalog-info.yaml data as well, without breaking validation.
|
||||
|
||||
After Dec 6th, the fields will be removed from types and classes of the Backstage repository. At the first release after that, they will not be present in released packages either.
|
||||
|
||||
If your catalog-info.yaml files still contain these fields after the deletion, they will still be valid and your ingestion will not break, but they won't be visible in the types for consuming code.
|
||||
@@ -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
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-sonarqube': patch
|
||||
---
|
||||
|
||||
Add configuration schema
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/backend-common': patch
|
||||
---
|
||||
|
||||
Tweaked development log formatter to include extra fields at the end of each log line
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
Add experimental backend:bundle command
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
Add new `versions:check` and `versions:bump` commands to simplify version management and avoid conflicts
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
'example-app': patch
|
||||
'@backstage/plugin-search': patch
|
||||
---
|
||||
|
||||
Using the search field in the sidebar now navigates to the search result page.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/backend-common': patch
|
||||
---
|
||||
|
||||
Make integration host and url configurations visible in the frontend
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-scaffolder-backend': patch
|
||||
---
|
||||
|
||||
Fix React entity YAML filename to new standard
|
||||
+2
-1
@@ -8,7 +8,8 @@
|
||||
/docs/features/techdocs @backstage/techdocs-core
|
||||
/plugins/cost-insights @backstage/silver-lining
|
||||
/plugins/cloudbuild @trivago/ebarrios
|
||||
/plugins/techdocs @backstage/techdocs-core
|
||||
/plugins/search @backstage/techdocs-core
|
||||
/plugins/techdocs @backstage/techdocs-core
|
||||
/plugins/techdocs-backend @backstage/techdocs-core
|
||||
/packages/techdocs-common @backstage/techdocs-core
|
||||
/.changeset/cost-insights-* @backstage/silver-lining
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
abc
|
||||
adamdmharvey
|
||||
andrewthauer
|
||||
Apdex
|
||||
api
|
||||
@@ -23,6 +24,7 @@ changesets
|
||||
Changesets
|
||||
chanwit
|
||||
Chanwit
|
||||
ci
|
||||
cisphobia
|
||||
cissexist
|
||||
classname
|
||||
@@ -34,6 +36,7 @@ Codecov
|
||||
codehilite
|
||||
Codehilite
|
||||
codeowners
|
||||
composable
|
||||
config
|
||||
Config
|
||||
configmaps
|
||||
@@ -42,10 +45,12 @@ const
|
||||
cookiecutter
|
||||
css
|
||||
dariddler
|
||||
dataflow
|
||||
deadnaming
|
||||
destructured
|
||||
dev
|
||||
devs
|
||||
dhenneke
|
||||
discoverability
|
||||
Discoverability
|
||||
dls
|
||||
@@ -54,6 +59,8 @@ Dockerfile
|
||||
Dockerize
|
||||
dockerode
|
||||
Docusaurus
|
||||
Dominik
|
||||
dtuite
|
||||
dzolotusky
|
||||
eg
|
||||
Ek
|
||||
@@ -64,18 +71,20 @@ facto
|
||||
failover
|
||||
Figma
|
||||
Firekube
|
||||
Fiverr
|
||||
freben
|
||||
Fredrik
|
||||
github
|
||||
Github
|
||||
GitHub
|
||||
gitlab
|
||||
Gitlab
|
||||
GitLab
|
||||
Grafana
|
||||
graphql
|
||||
graphviz
|
||||
Gustavsson
|
||||
Hackathons
|
||||
haproxy
|
||||
Henneke
|
||||
heroku
|
||||
Heroku
|
||||
horizontalpodautoscalers
|
||||
@@ -125,25 +134,30 @@ neuro
|
||||
newrelic
|
||||
nginx
|
||||
Niklas
|
||||
nodegit
|
||||
nohoist
|
||||
nonces
|
||||
npm
|
||||
nvm
|
||||
oauth
|
||||
Oauth
|
||||
oidc
|
||||
Okta
|
||||
Oldsberg
|
||||
onboarding
|
||||
Onboarding
|
||||
pagerduty
|
||||
parallelization
|
||||
Patrik
|
||||
Phoen
|
||||
plantuml
|
||||
Pomaceous
|
||||
postgres
|
||||
postpack
|
||||
pre
|
||||
prebaked
|
||||
preconfigured
|
||||
prepack
|
||||
Preprarer
|
||||
Prerequisities
|
||||
productional
|
||||
@@ -181,10 +195,12 @@ Serverless
|
||||
Sinon
|
||||
smartsymobls
|
||||
Snyk
|
||||
sourcemaps
|
||||
sparklines
|
||||
Spotifiers
|
||||
spotify
|
||||
Spotify
|
||||
sqlite
|
||||
squidfunk
|
||||
src
|
||||
stefanalund
|
||||
@@ -197,6 +213,7 @@ talkdesk
|
||||
Talkdesk
|
||||
tasklist
|
||||
techdocs
|
||||
Telenor
|
||||
templated
|
||||
templater
|
||||
Templater
|
||||
@@ -212,6 +229,9 @@ toolsets
|
||||
tooltip
|
||||
tooltips
|
||||
touchpoints
|
||||
transpiled
|
||||
transpilation
|
||||
Tuite
|
||||
ui
|
||||
untracked
|
||||
upvote
|
||||
@@ -229,3 +249,4 @@ yaml
|
||||
Zalando
|
||||
Zhou
|
||||
Zolotusky
|
||||
zoomable
|
||||
|
||||
@@ -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 }}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# New tags and releases are created by changeset https://github.com/atlassian/changesets
|
||||
name: Create a new release on GitHub when a new tag is created
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*' # Push events to matching v*, i.e. v0.4.0, v1.1.0
|
||||
|
||||
jobs:
|
||||
build:
|
||||
name: Create a new release on GitHub when a new tag is created
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: use node.js 12.x
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: '12.x'
|
||||
|
||||
- name: Install node dependencies
|
||||
run: npm install @octokit/rest
|
||||
|
||||
# GITHUB_REF is of the format refs/tags/vA.B.C
|
||||
# This step extracts vA.B.C from GITHUB_REF
|
||||
- name: Get the version
|
||||
id: get_version
|
||||
run: echo "::set-output name=TAG_NAME::${GITHUB_REF#refs/tags/}"
|
||||
|
||||
# TODO/Note: This will only create a Draft release, which the maintainer can see and publish.
|
||||
# If the Draft release looks good, modify the step to go ahead publish the release. (By adding the third CLI argument.)
|
||||
- name: Create release on GitHub
|
||||
run: node scripts/create-github-release.js ${{ steps.get_version.outputs.TAG_NAME }}
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
|
||||
@@ -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
|
||||
|
||||
@@ -81,7 +81,7 @@ jobs:
|
||||
- uses: Klemensas/action-autotag@1.2.3
|
||||
if: matrix.node-version == '12.x'
|
||||
with:
|
||||
GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
|
||||
GITHUB_TOKEN: '${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}'
|
||||
package_root: 'packages/core'
|
||||
tag_prefix: 'v'
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
+18
-15
@@ -1,15 +1,18 @@
|
||||
| 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. |
|
||||
|
||||
+1
-5
@@ -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
|
||||
|
||||
+33
-21
@@ -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).
|
||||
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
# Process for becoming a maintainer
|
||||
|
||||
## Your organization is not yet a maintainer
|
||||
## a) Your organization is not yet a maintainer
|
||||
|
||||
- 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.
|
||||
@@ -8,7 +8,7 @@
|
||||
- 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.
|
||||
|
||||
## Your organization is currently a maintainer
|
||||
## b) Your organization is currently a maintainer
|
||||
|
||||
To become a maintainer you need to demonstrate the following:
|
||||
|
||||
|
||||
@@ -22,3 +22,6 @@ People that have made significant contributions to the project and earned write
|
||||
|
||||
- Andrew Thauer - Wealthsimple (GitHub: [andrewthauer](https://github.com/andrewthauer))
|
||||
- Oliver Sand - SDA SE (GitHub: [Fox32](https://github.com/Fox32))
|
||||
- David Tuite - Roadie (GitHub: [dtuite](https://github.com/dtuite))
|
||||
- Adam Harvey - DXC Technology (GitHub: [adamdmharvey](https://github.com/adamdmharvey))
|
||||
- Dominik Henneke - SDA SE (GitHub: [dhenneke](https://github.com/dhenneke))
|
||||
|
||||
+29
-6
@@ -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'. 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:
|
||||
@@ -190,6 +207,7 @@ scaffolder:
|
||||
token:
|
||||
$env: AZURE_TOKEN
|
||||
auth:
|
||||
environment: development
|
||||
### Providing an auth.session.secret will enable session support in the auth-backend
|
||||
# session:
|
||||
# secret: custom session secret
|
||||
@@ -290,6 +308,9 @@ costInsights:
|
||||
bigQuery:
|
||||
name: BigQuery
|
||||
icon: search
|
||||
events:
|
||||
name: Events
|
||||
icon: data
|
||||
metrics:
|
||||
DAU:
|
||||
name: Daily Active Users
|
||||
@@ -306,3 +327,5 @@ homepage:
|
||||
timezone: 'Europe/Stockholm'
|
||||
- label: TYO
|
||||
timezone: 'Asia/Tokyo'
|
||||
pagerduty:
|
||||
eventsBaseUrl: 'https://events.pagerduty.com/v2'
|
||||
|
||||
@@ -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 }}
|
||||
|
||||
@@ -250,3 +250,4 @@ auth:
|
||||
gitlabToken: g
|
||||
newRelicRestApiKey: r
|
||||
travisciAuthToken: fake-travis-ci-auth-token
|
||||
pagerdutyToken: h
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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> => {
|
||||
|
||||
+56
@@ -117,6 +117,62 @@ through the proxy.
|
||||
Learn more about [the different components](overview/what-is-backstage.md) that
|
||||
make up Backstage.
|
||||
|
||||
### How do I keep my Backstage app up to date?
|
||||
|
||||
In many ways one can view Backstage as a library rather than an application or
|
||||
service. The `@backstage/create-app` tool that is used to create your own
|
||||
Backstage app is similar to
|
||||
[`create-react-app`](https://github.com/facebook/create-react-app) in that it
|
||||
gives you a starting point. The code you get is meant to be evolved, and most of
|
||||
the functionality you get out of the box is brought in via npm dependencies.
|
||||
Keeping your app up to date generally means keeping your dependencies up to
|
||||
date. The Backstage CLI provides a command to help you with that. Simply run
|
||||
`yarn backstage-cli versions:bump` at the root of your repo, and the latest
|
||||
versions of all Backstage packages will be installed.
|
||||
|
||||
While staying up to date with new releases and changes will keep your app up to
|
||||
date, it can often be convenient to use the changes done to the
|
||||
`@backstage/create-app` template as another method to stay up to date. For that
|
||||
purpose, any changes done to the template are documented along with upgrade
|
||||
instructions in the
|
||||
[changelog](https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md)
|
||||
of the `@backstage/create-app` package.
|
||||
|
||||
### Why can't I dynamically install plugins without modifications the app?
|
||||
|
||||
This decision is part of the core architecture and development flow of
|
||||
Backstage. Plugins have a lot of freedom in what they provide and how they are
|
||||
integrated into the app, and it would therefore add a lot of complexity to allow
|
||||
plugins to be integrated via configuration the same way as they can be
|
||||
integrated with code.
|
||||
|
||||
By bundling all plugins and their dependencies into one app bundle it is also
|
||||
possible to do significant optimizations to the app load time by allowing
|
||||
plugins to share dependencies between each other when possible. This contributes
|
||||
to Backstage being fast, which is an important part of the user and developer
|
||||
experience.
|
||||
|
||||
### Why are there no published Docker images or helm charts for Backstage?
|
||||
|
||||
As mentioned above, Backstage is not a packaged service that you can use out of
|
||||
the box. In order to get started with Backstage you need to use the
|
||||
`@backstage/create-app` package to create and customize your own Backstage app.
|
||||
|
||||
In order to build a Docker image from your own app, you can use the
|
||||
`yarn build-image` command which is included out of the box in the app template.
|
||||
By default this image will bundle up both the frontend and the backend into a
|
||||
single image that you can deploy using your favorite tooling.
|
||||
|
||||
There are also some examples that can help you deploy Backstage to kubernetes in
|
||||
the
|
||||
[contrib](https://github.com/backstage/backstage/tree/master/contrib/kubernetes)
|
||||
folder.
|
||||
|
||||
It is possible that example images will be provided in the future, which can be
|
||||
used to quickly try out a small subset of the functionality of Backstage, but
|
||||
these would not be able to provide much more functionality on top of what you
|
||||
can see on a demo site.
|
||||
|
||||
### Do I have to write plugins in TypeScript?
|
||||
|
||||
No, you can use JavaScript if you prefer. We want to keep the Backstage core
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 171 KiB After Width: | Height: | Size: 128 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 64 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 111 KiB |
@@ -6,57 +6,71 @@ 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.
|
||||
|
||||
### 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.
|
||||
@@ -85,20 +99,60 @@ auth:
|
||||
...
|
||||
```
|
||||
|
||||
## 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 +167,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
|
||||
|
||||
+1
-1
@@ -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.
|
||||
|
||||
@@ -0,0 +1,559 @@
|
||||
---
|
||||
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:build-image Bundles the package into a docker image
|
||||
backend:dev Start local development server with HMR for the backend
|
||||
|
||||
plugin:build Build a plugin
|
||||
plugin:diff Diff an existing plugin with the creation template
|
||||
plugin:serve Serves the dev/ folder of a plugin
|
||||
|
||||
build Build a package for publishing
|
||||
build-workspace Builds a temporary dist workspace from the provided packages
|
||||
lint Lint a package
|
||||
test Run tests, forwarding args to Jest, defaulting to watch mode
|
||||
clean Delete cache directories
|
||||
|
||||
create-plugin Creates a new plugin in the current repository
|
||||
remove-plugin Removes plugin in the current repository
|
||||
|
||||
config:print Print the app configuration for the current package
|
||||
config:check Validate that the given configuration loads and matches schema
|
||||
|
||||
versions:bump Bump Backstage packages to the latest versions
|
||||
versions:check Check Backstage package versioning
|
||||
|
||||
prepack Prepares a package for packaging before publishing
|
||||
postpack Restores the changes made by the prepack command
|
||||
|
||||
help [command] display help for command
|
||||
```
|
||||
|
||||
## app:build
|
||||
|
||||
Scope: `app`
|
||||
|
||||
Builds a bundle of static content from the app, which can then be served via any
|
||||
static web server such as `nginx`, or via the
|
||||
[`app-backend`](https://www.npmjs.com/package/@backstage/plugin-app-backend)
|
||||
plugin directly from a Backstage backend instance.
|
||||
|
||||
The command also reads and injects static configuration into the bundle. It is
|
||||
important to note that when deploying using your own static content hosting
|
||||
solution, this will be the final configuration used in the frontend unless you
|
||||
for example hook in configuration loading from the backend. When using the
|
||||
`nginx` based Dockerfile in this repo along with its included run script,
|
||||
`APP_CONFIG_` environment variables will be injected into the frontend, and when
|
||||
serving using the `app-backend` plugin, the configuration is completely injected
|
||||
from the backend and the configuration at the time of calling this command will
|
||||
not be used.
|
||||
|
||||
Note that even when injecting configuration at runtime, it is not possible to
|
||||
change the base path of the app. For example, if you at build time have
|
||||
`app.baseUrl` set to `http://dev-app.com/my-app`, you can change that to
|
||||
`https://prod-app.com/my-app`, but not to `https://prod-app.com`, as that would
|
||||
change the path.
|
||||
|
||||
During the build, the following variables are set:
|
||||
|
||||
```java
|
||||
process.env.NODE_ENV = 'production';
|
||||
process.env.BUILD_INFO = {
|
||||
cliVersion: '0.4.0', // The version of the CLI package
|
||||
gitVersion: 'v0.4.0-86-ge54815618', // output of `git describe --always`
|
||||
packageVersion: '1.0.5', // The version of the app package itself
|
||||
timestamp: 1678900000000, // Date.now() when the build started
|
||||
commit: 'e548156182a973ed4b459e18533afc22c85ffff8', // output of `git rev-parse HEAD`
|
||||
};
|
||||
```
|
||||
|
||||
Some CI environments do not properly report correct resource limits, potentially
|
||||
leading to errors such as `ENOMEM` during compilation. If you run into this
|
||||
issue you can limit the parallelization of the build process by setting the
|
||||
environment variable `BACKSTAGE_CLI_BUILD_PARALLEL`, which is forwarded to the
|
||||
[`terser-webpack-plugin`](https://github.com/webpack-contrib/terser-webpack-plugin#parallel).
|
||||
You can set it to `false` or `1` to completely disable parallelization, but
|
||||
usually a low value such as `2` is enough.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli app:build
|
||||
|
||||
Options:
|
||||
--stats Write bundle stats to output directory
|
||||
--config <path> Config files to load instead of app-config.yaml (default: [])
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## app:diff
|
||||
|
||||
Scope: `app`
|
||||
|
||||
Diff an existing app with the template used in `@backstage/create-app`. This
|
||||
will verify that your app package has not diverged from the template, and can be
|
||||
useful to run after updating the version of `@backstage/cli` in your app.
|
||||
|
||||
This command is experimental and may be removed in the future.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli app:diff
|
||||
|
||||
Options:
|
||||
--check Fail if changes are required
|
||||
--yes Apply all changes
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## app:serve
|
||||
|
||||
Scope: `app`
|
||||
|
||||
Serve an app for local development. This starts up a local development server,
|
||||
using a bundling configuration that is quite similar to that of the `app:build`
|
||||
command, but with development features such as React Hot Module Replacement,
|
||||
faster sourcemaps, no minification, etc.
|
||||
|
||||
The static configuration is injected into the frontend, but it does not support
|
||||
watching, meaning that changes in for example `app-config.yaml` are not
|
||||
reflected until the serve process is restarted.
|
||||
|
||||
During the build, the following variables are set:
|
||||
|
||||
```java
|
||||
process.env.NODE_ENV = 'development';
|
||||
process.env.BUILD_INFO = { /* See app:build */ };
|
||||
```
|
||||
|
||||
The server listening configuration is controlled through the static
|
||||
configuration. The `app.baseUrl` determines the listening host and port, as well
|
||||
as whether HTTPS is used or not. It is also possible to override the listening
|
||||
host and port if needed by setting `app.listen.host` and `app.listen.port`.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli app:serve [options]
|
||||
|
||||
Options:
|
||||
--check Enable type checking and linting
|
||||
--config <path> Config files to load instead of app-config.yaml (default: [])
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## backend:build
|
||||
|
||||
Scope: `backend`, `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:build-image
|
||||
|
||||
Scope: `backend`
|
||||
|
||||
Builds a Docker image of the backend package, forwarding all unknown options to
|
||||
`docker image build`. For example:
|
||||
|
||||
```bash
|
||||
yarn backstage-cli backend:build-image --build --tag my-backend-image
|
||||
```
|
||||
|
||||
The image is built using the backend package along with all of its local package
|
||||
dependencies. It expects to find a `Dockerfile` at the root of the backend
|
||||
package, which will be used during the build.
|
||||
|
||||
The Dockerfile is **NOT** executed within the package or repo itself. Because
|
||||
the packages in the repo itself are configured for development instead of
|
||||
production use, the final Docker build happens in a separate temporary
|
||||
directory, to which the backend package and dependencies have been copied. Only
|
||||
files listed within the `"files"` field within each package's `package.json` are
|
||||
copied over, along with the root `package.json`, `yarn.lock`, and any
|
||||
`app-config.*.yaml` files.
|
||||
|
||||
During the build a `skeleton.tar` file is created and put at the repo root. This
|
||||
file contains the `package.json` of each included package, which together with
|
||||
the root `package.json` and `yarn.lock` can be used to run a cached
|
||||
`yarn install` before the full production builds of all the packages are copied
|
||||
over, providing a significant speedup if Docker build layer caching available.
|
||||
|
||||
This command is experimental and we hope to be able to replace it with one that
|
||||
is less integrated directly with Docker, and also supports multi-stage Docker
|
||||
builds. It is possible to replicate most of what this command does by manually
|
||||
building each package, and then use the `build-workspace` to create the
|
||||
temporary workspace, and finally copy over any additional files to the workspace
|
||||
and execute the Docker build within it.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli backend:build-image [options]
|
||||
|
||||
Options:
|
||||
--build Build packages before packing them into the image
|
||||
--backstage-cli-help display help for command
|
||||
```
|
||||
|
||||
## backend:dev
|
||||
|
||||
Scope: `backend`, `backend-plugin`
|
||||
|
||||
Starts a backend package in development mode, with watch mode enabled for all
|
||||
local dependencies.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli backend:dev [options]
|
||||
|
||||
Options:
|
||||
--check Enable type checking and linting
|
||||
--inspect Enable debugger
|
||||
--config <path> Config files to load instead of app-config.yaml (default: [])
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## create-plugin
|
||||
|
||||
Scope: `root`
|
||||
|
||||
Creates a new plugin within the repository. This command is typically wrapped up
|
||||
in the root `package.json` to be executed with `yarn create-plugin`, using
|
||||
options that are appropriate for the organization that owns the app repo. A
|
||||
recommended scope for internal packages is `@internal`.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli create-plugin [options]
|
||||
|
||||
Options:
|
||||
--backend Create plugin with the backend dependencies as default
|
||||
--scope <scope> npm scope
|
||||
--npm-registry <URL> npm registry URL
|
||||
--no-private Public npm package
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## remove-plugin
|
||||
|
||||
Scope: `root`
|
||||
|
||||
A utility to remove a plugin from a repo, essentially undoing everything that
|
||||
was done by `create-plugin`.
|
||||
|
||||
This is primarily intended as a utility for manual tests and end to end testing
|
||||
scripts.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli remove-plugin [options]
|
||||
|
||||
Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## plugin:build
|
||||
|
||||
Scope: `frontend-plugin`
|
||||
|
||||
Build a frontend plugin for publishing to a package registry. There is no need
|
||||
to run this command during development or even in CI unless the package is being
|
||||
published. The `app:bundle` command does not use the output for this command
|
||||
when bundling local package dependencies.
|
||||
|
||||
The output is written to a `dist/` folder. It also outputs type declarations for
|
||||
the plugin, and therefore requires `yarn tsc` to have been run first. The input
|
||||
type declarations are expected to be found within `dist-types/` at the root of
|
||||
the monorepo.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli plugin:build [options]
|
||||
|
||||
Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## plugin:serve
|
||||
|
||||
Scope: `frontend-plugin`
|
||||
|
||||
Serves a frontend plugin by itself for isolated development. The serve task
|
||||
itself is essentially identical to `app:serve`, but the entrypoint is instead
|
||||
set to the `dev/` folder within the plugin.
|
||||
|
||||
The `dev/` folder typically contains a small wrapper script that hooks up any
|
||||
necessary mock APIs or other things that are needed for the plugin to function.
|
||||
The `@backstage/dev-utils` package provides utilities to that end.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli plugin:serve [options]
|
||||
|
||||
Options:
|
||||
--check Enable type checking and linting
|
||||
--config <path> Config files to load instead of app-config.yaml (default: [])
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## plugin:diff
|
||||
|
||||
Scope: `frontend-plugin`
|
||||
|
||||
Compares a frontend plugin to the `create-plugin` template, making sure that it
|
||||
hasn't diverged from the template and recommending updates when it has. A good
|
||||
practice is to run this command after updating the version of the CLI in a
|
||||
project.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli plugin:diff [options]
|
||||
|
||||
Options:
|
||||
--check Fail if changes are required
|
||||
--yes Apply all changes
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## build
|
||||
|
||||
Scope: `any`
|
||||
|
||||
Build a single package for publishing, just like the `plugin:build` and
|
||||
`backend:build` commands. This command is intended for standalone packages that
|
||||
aren't plugins, and for example support building of isomorphic packages for
|
||||
usage in both the frontend and backend.
|
||||
|
||||
For frontend packages you'll want to include `esm` output, and for backend
|
||||
packages `cjs`. Whether to include `types` depends on if you need type
|
||||
declarations for the package, and also requires `yarn tsc` to have been run
|
||||
first.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli build [options]
|
||||
|
||||
Options:
|
||||
--outputs <formats> List of formats to output [types,cjs,esm]
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## lint
|
||||
|
||||
Scope: `any`
|
||||
|
||||
Lint a package. In addition to the default `eslint` behavior, this command will
|
||||
include TypeScript files, treat warnings as errors, and default to linting the
|
||||
entire directory if no specific files are listed.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli lint [options]
|
||||
|
||||
Options:
|
||||
--format <format> Lint report output format (default: "eslint-formatter-friendly")
|
||||
--fix Attempt to automatically fix violations
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## test
|
||||
|
||||
Scope: `any`
|
||||
|
||||
Run tests, forwarding all unknown options to Jest, and defaulting to watch mode.
|
||||
When executing the tests, `process.env.NODE_ENV` will be set to `"test"`.
|
||||
|
||||
This command uses a default Jest configuration that is included in the CLI,
|
||||
which is set up with similar goals for speed, scale, and working within a
|
||||
monorepo. The configuration sets the `src` as the root directory, enforces the
|
||||
`.test.` infix for tests, and uses `src/setupTests.ts` as the test setup
|
||||
location.
|
||||
|
||||
If needed, the configuration can be extended using a `"jest"` field in
|
||||
`package.json`, both within the target package and the monorepo root, with
|
||||
configuration in the target package taking precedence. Refer to the
|
||||
[Jest configuration documentation](https://jestjs.io/docs/en/configuration) for
|
||||
a full list of configuration options.
|
||||
|
||||
In addition to the Jest configuration there's an optional `transformModules`
|
||||
option, which is an array of module names to include in transformations.
|
||||
Normally modules inside `node_modules` are not transformed, but there are cases
|
||||
were published packages are not transpiled far enough to be usable by Jest, in
|
||||
which case you need to enable transform of them.
|
||||
|
||||
Another way to override the Jest configuration is to place a `jest.config.js` or
|
||||
`jest.config.ts` file in the package root. As opposed to the `package.json` way
|
||||
of overriding config, this completely removes the base config, and so you need
|
||||
to set it up from scratch.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli test [options]
|
||||
|
||||
Options:
|
||||
--backstage-cli-help display help for command
|
||||
```
|
||||
|
||||
## config:print
|
||||
|
||||
Scope: `root`
|
||||
|
||||
Print the static configuration, defaulting to reading `app-config.yaml` in the
|
||||
repo root, using schema collected from all local packages in the repo.
|
||||
|
||||
For example, to validate that a given configuration value is visible in the
|
||||
frontend when building the `my-app` package, you can use the following:
|
||||
|
||||
```bash
|
||||
yarn backstage-cli config:print --frontend --package my-app
|
||||
```
|
||||
|
||||
```text
|
||||
Usage: backstage-cli config:print [options]
|
||||
|
||||
Options:
|
||||
--package <name> Only load config schema that applies to the given package
|
||||
--frontend Print only the frontend configuration
|
||||
--with-secrets Include secrets in the printed configuration
|
||||
--format <format> Format to print the configuration in, either json or yaml [yaml]
|
||||
--config <path> Config files to load instead of app-config.yaml (default: [])
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## config:check
|
||||
|
||||
Scope: `root`
|
||||
|
||||
Validate that static configuration loads and matches schema, defaulting to
|
||||
reading `app-config.yaml` in the repo root and using schema collected from all
|
||||
local packages in the repo.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli config:check [options]
|
||||
|
||||
Options:
|
||||
--package <name> Only load config schema that applies to the given package
|
||||
--config <path> Config files to load instead of app-config.yaml (default: [])
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## versions:bump
|
||||
|
||||
Scope: `root`
|
||||
|
||||
Bump all `@backstage` packages to the latest versions. This checks for updates
|
||||
in the package registry, and will update entries both in `yarn.lock` and
|
||||
`package.json` files when necessary.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli versions:bump [options]
|
||||
|
||||
Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## versions:check
|
||||
|
||||
Scope: `root`
|
||||
|
||||
Validate `@backstage` dependencies within the repo, making sure that there are
|
||||
no duplicates of packages that might lead to breakages. For example,
|
||||
`@backstage/core` must not be loaded in twice, so having two different versions
|
||||
of it installed will cause this command to exit with an error.
|
||||
|
||||
By supplying the `--fix` flag the command will attempt to fix any conflict that
|
||||
can be resolved by editing `yarn.lock`, but will not attempt to search for
|
||||
remote updates or modify any `package.json` files.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli versions:check [options]
|
||||
|
||||
Options:
|
||||
--fix Fix any auto-fixable versioning problems
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## prepack
|
||||
|
||||
Scope: `any`
|
||||
|
||||
This command should be added as `scripts.prepack` in all packages. It enables
|
||||
packaging- and publish-time overrides for fields inside `packages.json`.
|
||||
|
||||
The checked in version of all packages in a Backstage monorepo are tailored for
|
||||
local development, and as such `main` and similar fields inside `package.json`
|
||||
point to development source, i.e. `src/index.ts`. Using this when publishing
|
||||
would lead to a broken package, since `src/` is not included in the published
|
||||
package and we instead need to point to files in the `dist/` directory. This
|
||||
command allows for those fields to be rewritten when needed, and does so by
|
||||
copying all fields within `publishConfig` to the top-level of each
|
||||
`package.json`, skipping `access`, `registry`, and `tag`.
|
||||
|
||||
The need for this command may be removed in the future, as this exact method of
|
||||
overriding fields for publishing is already supported by some package managers.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli prepack [options]
|
||||
|
||||
Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## postpack
|
||||
|
||||
Scope: `any`
|
||||
|
||||
This should be added as `scripts.postpack` in all packages. It restores
|
||||
`package.json` to what it looked like before calling the `prepack` command.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli postpack [options]
|
||||
|
||||
Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## clean
|
||||
|
||||
Scope: `any`
|
||||
|
||||
Remove cache and output directories.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli clean [options]
|
||||
|
||||
Options:
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
## build-workspace
|
||||
|
||||
Scope: `any`, `root`
|
||||
|
||||
Builds a mirror of the workspace using the packaged production version of each
|
||||
package. This essentially calls `yarn pack` in each included package and unpacks
|
||||
the resulting archive in the target `workspace-dir`.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli build-workspace [options] <workspace-dir>
|
||||
```
|
||||
@@ -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.
|
||||
@@ -83,6 +83,12 @@ object will be available in the frontend. The full ancestry does not need to
|
||||
have correctly defined visibilities however, so it is enough to only for example
|
||||
declare the visibility of a leaf node of `type: "string"`.
|
||||
|
||||
| `visibility` | |
|
||||
| ------------ | ------------------------------------------------------------------ |
|
||||
| `frontend` | Visible in frontend and backend |
|
||||
| `backend` | (Default) Only in backend |
|
||||
| `secret` | Only in backend and may be excluded from logs for security reasons |
|
||||
|
||||
## Validation
|
||||
|
||||
Schemas can be validated using the `backstage-cli config:check` command. If you
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -662,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)
|
||||
@@ -688,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
|
||||
@@ -701,25 +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]
|
||||
|
||||
**NOTE**: This field was marked for deprecation on Nov 22nd, 2020. It will be
|
||||
removed entirely from the model on Dec 6th, 2020 in the repository and will not
|
||||
be present in released packages following the next release after that. Please
|
||||
update your code to not consume this field before the removal date.
|
||||
|
||||
The recursive list of parents up the hierarchy, by stepping through parents one
|
||||
by one. The list must be present, but may be empty if `parent` is not present.
|
||||
The first entry in the list is equal to `parent`, and then the following ones
|
||||
are progressively farther up the hierarchy.
|
||||
|
||||
The entries of this array are
|
||||
[entity references](https://backstage.io/docs/features/software-catalog/references),
|
||||
with the default kind `Group` and the default namespace equal to the same
|
||||
namespace as the user. Only `Group` entities may be referenced. Most commonly,
|
||||
these entries point to groups in the same namespace, so in those cases it is
|
||||
sufficient to enter only the `metadata.name` field of those groups.
|
||||
|
||||
### `spec.children` [required]
|
||||
|
||||
The immediate child groups of this group in the hierarchy (whose `parent` field
|
||||
@@ -734,25 +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]
|
||||
|
||||
**NOTE**: This field was marked for deprecation on Nov 22nd, 2020. It will be
|
||||
removed entirely from the model on Dec 6th, 2020 in the repository and will not
|
||||
be present in released packages following the next release after that. Please
|
||||
update your code to not consume this field before the removal date.
|
||||
|
||||
The immediate and recursive child groups of this group in the hierarchy
|
||||
(children, and children's children, etc.). The list must be present, but may be
|
||||
empty if there are no child groups. The items are not guaranteed to be ordered
|
||||
in any particular way.
|
||||
|
||||
The entries of this array are
|
||||
[entity references](https://backstage.io/docs/features/software-catalog/references),
|
||||
with the default kind `Group` and the default namespace equal to the same
|
||||
namespace as the user. Only `Group` entities may be referenced. Most commonly,
|
||||
these entries point to groups in the same namespace, so in those cases it is
|
||||
sufficient to enter only the `metadata.name` field of those groups.
|
||||
|
||||
## Kind: User
|
||||
|
||||
Describes the following entity kind:
|
||||
@@ -824,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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -238,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
|
||||
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -96,26 +96,38 @@ 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 | Track status |
|
||||
| --------------------------------- | -------------- | ----------------------------------------------------------- |
|
||||
| Local Filesystem of Backstage app | Yes ✅ | |
|
||||
| Google Cloud Storage (GCS) | Yes ✅ | |
|
||||
| Amazon Web Services (AWS) S3 | No ❌ | [#3714](https://github.com/backstage/backstage/issues/3714) |
|
||||
| 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]:
|
||||
@@ -131,3 +143,6 @@ https://docs.google.com/forms/d/e/1FAIpQLSdn5Vn3MQhCdyYRuW8cMzZkMQF0bFxXYN168gZR
|
||||
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).
|
||||
|
||||
@@ -1,7 +1,153 @@
|
||||
---
|
||||
id: architecture
|
||||
title: Architecture
|
||||
description: Documentation on Architecture
|
||||
title: TechDocs Architecture
|
||||
description: Documentation on TechDocs Architecture
|
||||
---
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
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.
|
||||
|
||||
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',
|
||||
|
||||
```
|
||||
@@ -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
|
||||
@@ -108,23 +242,13 @@ the dependencies. For example, we want `Markdown` version to be
|
||||
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
|
||||
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -87,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:
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
+35
-39
@@ -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)
|
||||
|
||||
@@ -39,28 +39,28 @@ TL;DR:
|
||||
|
||||
## Packages
|
||||
|
||||
### [`example-app`](https://github.com/backstage/backstage/tree/master/packages/app/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/backend/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/backend-common/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/catalog-client/)
|
||||
### `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.
|
||||
@@ -68,7 +68,7 @@ and Backend.
|
||||
Stability: `0`. This is a very new addition and we have some immediate changes
|
||||
planned.
|
||||
|
||||
### [`catalog-model`](https://github.com/backstage/backstage/tree/master/packages/catalog-model/)
|
||||
### `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.
|
||||
@@ -77,37 +77,37 @@ Stability: `2`. The catalog model is evolving, but because of the broad usage we
|
||||
|
||||
want to ensure some stability.
|
||||
|
||||
### [`cli`](https://github.com/backstage/backstage/tree/master/packages/cli/)
|
||||
### `cli` [GitHub](https://github.com/backstage/backstage/tree/master/packages/cli/)
|
||||
|
||||
The main toolchain used for Backstage development. The interface that is
|
||||
considered for stability are the various commands and options passed to those
|
||||
commands, as well as the environment variables read by the CLI. The build output
|
||||
may change over time and is not considered a breaking change unless it is likely
|
||||
to affect external tooling.
|
||||
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`](https://github.com/backstage/backstage/tree/master/packages/cli-common/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/config/)
|
||||
### `config` [GitHub](https://github.com/backstage/backstage/tree/master/packages/config/)
|
||||
|
||||
Provides the logic and interfaces for reading static configuration.
|
||||
|
||||
Stability: `2`
|
||||
|
||||
### [`config-loader`](https://github.com/backstage/backstage/tree/master/packages/config-loader/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/core/)
|
||||
### `core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core/)
|
||||
|
||||
#### Section: React Components
|
||||
|
||||
@@ -147,51 +147,62 @@ 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`](https://github.com/backstage/backstage/tree/master/packages/core-api/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/create-app/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/dev-utils/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/docgen/)
|
||||
### `docgen` [GitHub](https://github.com/backstage/backstage/tree/master/packages/docgen/)
|
||||
|
||||
Internal CLI utility for generating API Documentation.
|
||||
|
||||
Stability: `N/A`
|
||||
|
||||
### [`e2e-test`](https://github.com/backstage/backstage/tree/master/packages/e2e-test/)
|
||||
### `e2e-test` [GitHub](https://github.com/backstage/backstage/tree/master/packages/e2e-test/)
|
||||
|
||||
Internal CLI utility for running e2e tests.
|
||||
|
||||
Stability: `N/A`
|
||||
|
||||
### [`storybook`](https://github.com/backstage/backstage/tree/master/packages/storybook/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/test-utils/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/packages/test-utils-core/)
|
||||
### `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
|
||||
@@ -199,7 +210,7 @@ package should not be depended on directly.
|
||||
|
||||
Stability: See @backstage/test-utils
|
||||
|
||||
### [`theme`](https://github.com/backstage/backstage/tree/master/packages/theme/)
|
||||
### `theme` [GitHub](https://github.com/backstage/backstage/tree/master/packages/theme/)
|
||||
|
||||
The core Backstage MUI theme along with customization utilities.
|
||||
|
||||
@@ -229,21 +240,21 @@ 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`](https://github.com/backstage/backstage/tree/master/plugins/api-docs/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/app-backend/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/auth-backend/)
|
||||
### `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.
|
||||
@@ -256,7 +267,7 @@ Stability: `2`
|
||||
|
||||
Stability: `1`
|
||||
|
||||
### [`catalog`](https://github.com/backstage/backstage/tree/master/plugins/catalog/)
|
||||
### `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.
|
||||
@@ -264,7 +275,7 @@ entity pages.
|
||||
Stability: `1`. We're planning some work to overhaul how entity pages are
|
||||
constructed.
|
||||
|
||||
### [`catalog-backend`](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend/)
|
||||
### `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
|
||||
@@ -278,53 +289,53 @@ Stability: `1`. There are plans to remove and rework some endpoints.
|
||||
|
||||
Stability: `1`. There are plans to rework parts of the Processor interface.
|
||||
|
||||
### [`catalog-graphql`](https://github.com/backstage/backstage/tree/master/plugins/catalog-graphql/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/explore/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/graphiql/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/graphql/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/kubernetes/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/kubernetes-backend/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/proxy-backend/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/register-component/)
|
||||
### `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.
|
||||
@@ -332,14 +343,14 @@ catalog.
|
||||
Stability: `0`. This plugin is likely to be replaced by a generic entity import
|
||||
plugin instead.
|
||||
|
||||
### [`scaffolder`](https://github.com/backstage/backstage/tree/master/plugins/scaffolder/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend/)
|
||||
### `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.
|
||||
@@ -347,35 +358,35 @@ the catalog.
|
||||
Stability: `1`. There is planned work to rework the scaffolder in
|
||||
https://github.com/backstage/backstage/issues/2771.
|
||||
|
||||
### [`tech-radar`](https://github.com/backstage/backstage/tree/master/plugins/tech-radar/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/techdocs/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/user-settings/)
|
||||
### `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`](https://github.com/backstage/backstage/tree/master/plugins/welcome/)
|
||||
### `welcome` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/welcome/)
|
||||
|
||||
A plugin that can be used to welcome the user to Backstage.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
+20
-13
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -234,7 +234,7 @@ This is especially true for edge cases!
|
||||
|
||||
## 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 +243,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
|
||||
|
||||
@@ -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';
|
||||
|
||||
|
||||
@@ -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);
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -161,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) -
|
||||
@@ -169,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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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' },
|
||||
|
||||
@@ -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 `` syntax to `<img data-zoomable src="/microsite/static/img/code.png" alt="This is image" />`
|
||||
|
||||
@@ -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
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: What the heck is Backstage anyway?
|
||||
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
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Introducing Lighthouse for Backstage
|
||||
author: Paul Marbach
|
||||
author: Paul Marbach, Spotify
|
||||
authorURL: http://twitter.com/fastfrwrd
|
||||
authorImageURL: https://pbs.twimg.com/profile_images/1224058798958088192/JPxS8uzR_400x400.jpg
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: How to quickly set up Backstage
|
||||
author: Marcus Eide
|
||||
author: Marcus Eide, Spotify
|
||||
authorURL: https://github.com/marcuseide
|
||||
authorImageURL: https://secure.gravatar.com/avatar/20223f1e03673c7c1e6282fbebaf6942
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Introducing Tech Radar for Backstage
|
||||
author: Bilawal Hameed
|
||||
author: Bilawal Hameed, Spotify
|
||||
authorURL: http://twitter.com/bilawalhameed
|
||||
authorImageURL: https://avatars0.githubusercontent.com/bih
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Weaveworks’ COVID-19 app uses Backstage UI
|
||||
author: Jeff Feng
|
||||
author: Jeff Feng, Spotify
|
||||
authorURL: https://github.com/fengypants
|
||||
authorImageURL: https://avatars2.githubusercontent.com/u/46946747
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Starting Phase 2: The Service Catalog
|
||||
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
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Backstage Service Catalog released in alpha
|
||||
author: Stefan Ålund
|
||||
author: Stefan Ålund, Spotify
|
||||
authorURL: http://twitter.com/stalund
|
||||
image: https://backstage.io/blog/assets/6/header.png
|
||||
---
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: How to enable authentication in Backstage using Passport
|
||||
author: Lee Mills
|
||||
author: Lee Mills, Spotify
|
||||
authorURL: https://github.com/leemills83
|
||||
authorImageURL: https://avatars1.githubusercontent.com/u/1236238?s=460&v=4
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Announcing Backstage Software Templates
|
||||
author: Stefan Ålund
|
||||
author: Stefan Ålund, Spotify
|
||||
authorURL: https://twitter.com/stalund
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Announcing TechDocs: Spotify’s docs-like-code plugin for Backstage
|
||||
author: Gary Niemen
|
||||
author: Gary Niemen, Spotify
|
||||
authorURL: https://github.com/garyniemen
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Backstage has been accepted into the CNCF Sandbox
|
||||
author: Stefan Ålund
|
||||
author: Stefan Ålund, Spotify
|
||||
authorURL: https://twitter.com/stalund
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: How to design for Backstage (even if you’re not a designer)
|
||||
author: Kat Zhou
|
||||
author: Kat Zhou, Spotify
|
||||
authorURL: http://twitter.com/katherinemzhou
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: The Plugin Marketplace is open
|
||||
author: Stefan Ålund
|
||||
author: Stefan Ålund, Spotify
|
||||
authorURL: https://twitter.com/stalund
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: New Cost Insights plugin: The engineer’s solution to taming cloud costs
|
||||
author: Janisa Anandamohan
|
||||
author: Janisa Anandamohan, Spotify
|
||||
authorURL: https://twitter.com/janisa_a
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Announcing the Backstage Stability Index
|
||||
author: Patrik Oldsberg, Spotify
|
||||
authorURL: https://github.com/Rugvip
|
||||
---
|
||||
|
||||
**TL;DR** Backstage is heading out of alpha and moving onto the path to stable releases and an eventual version 1.0. As the community and ecosystem continue to grow at an increasing rate, we want to provide a solid foundation for everyone building things in, with, and around Backstage. So, today we’re introducing the [Stability Index](https://backstage.io/docs/overview/stability-index) — a simple way to find out how likely (or unlikely) a specific package or plugin inside Backstage might be updated with major changes. By indicating the reliability of key features and APIs, this quick reference will help contributors and adopters better plan and coordinate their development efforts going forward.
|
||||
|
||||
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
Backstage has a great and growing community of users and contributors. With so much valuable feedback, this inevitably means that sometimes we will go back and revise design decisions that introduce breaking changes. Furthermore, as we continue to ship new features and systems, we’ll continue this cycle of iterating, gathering feedback, and iterating again before reaching a stable API.
|
||||
|
||||
This rapid evolution can create uncertainty around which parts of the project are considered stable and which are not. Regardless of whether you're contributing to the project directly, setting up your own Backstage, or building plugins, you will be using various parts of the project that vary in stability. While many API surfaces of Backstage are reasonably solid and are unlikely to see any big breaking changes, others are more unstable or experimental.
|
||||
|
||||
## The Stability Index
|
||||
|
||||
In order to tackle the problem of uncertainty, and help align contributors, we have recently introduced a Stability Index. Inspired by a [similar concept with the same name in Node.js](https://nodejs.org/docs/latest-v4.x/api/documentation.html#documentation_stability_index), it’s a score assigned to subsets of the project, indicating the level of maturity of the API and the commitment to backwards compatibility. However, because of the current phase of the project, we have used a slightly different implementation. Rather than the score indicating a perceived stability, a higher score is instead a commitment to providing a smoother upgrade path for users, both through better documentation and backwards compatibility. Importantly, the Stability Index does not supersede [semantic versioning](https://semver.org/) (or semver), meaning we will still adhere to semver and only do breaking changes in minor releases as long as we are on 0.x.
|
||||
|
||||
You can find more details about the scores on the [Stability Index](https://backstage.io/docs/overview/stability-index) page, but the following is a TL;DR of the 0–3 scores:
|
||||
|
||||
- **0** — There's a changelog entry.
|
||||
- **1** — There's a migration guide.
|
||||
- **2** — Two weeks of deprecation.
|
||||
- **3** — Three months of deprecation.
|
||||
|
||||
The Stability Index has been tailored for the phase that the project is currently in, and we do not intend to keep it in place in its current form forever. It is, for example, likely that we in the future will increase the deprecation time limits.
|
||||
|
||||
## Staying up to date
|
||||
|
||||
In addition to the Stability Index, we have also recently adopted a weekly release cadence where we cut new releases every Thursday. Along with the two-week deprecation period of many of the API surfaces in Backstage, there is an excellent opportunity to form a routine to update your own Backstage projects either weekly or biweekly.
|
||||
|
||||
In order to make the update process easier, we’ve added a new command to the Backstage CLI that allows you to easily update your project to use the latest Backstage release. The command is called `version:bump` and is executed in the root of your project using the CLI. You can see what it looks like in action below.
|
||||
|
||||
|
||||
|
||||
## Impact
|
||||
|
||||
The Stability Index has already been active for a couple of weeks, and we have immediately seen an impact on the consideration and care taken when working in parts of the project that we have committed to keeping more stable. Both members of the core maintainer team and contributors from the community have taken care to roll out updates responsibly, with examples such as [PR #3524](https://github.com/backstage/backstage/pull/3524) and [PR #3465](https://github.com/backstage/backstage/pull/3465).
|
||||
|
||||
The core team is working hard to bring more stability to broader parts of Backstage, and engineering it in a way that allows for long-term evolution. There are more learnings to be discovered as we continue evolving Backstage, but we are confident that the Stability Index will allow for a clearer path and a smoother ride for everyone involved!
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 391 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 144 KiB |
@@ -54,6 +54,12 @@ class Footer extends React.Component {
|
||||
<a href={this.props.config.fossWebsite}>
|
||||
Open Source @ {this.props.config.organizationName}
|
||||
</a>
|
||||
|
||||
<a href="https://engineering.atspotify.com/">
|
||||
Spotify Engineering Blog
|
||||
</a>
|
||||
<a href="https://developer.spotify.com/">Spotify for Developers</a>
|
||||
|
||||
<a href={this.props.config.repoUrl}>GitHub</a>
|
||||
<a
|
||||
className="github-button"
|
||||
@@ -78,6 +84,9 @@ class Footer extends React.Component {
|
||||
)}
|
||||
</div>
|
||||
</section>
|
||||
<p style={{ textAlign: 'center' }}>
|
||||
<a href="https://spotify.github.io">Made with ❤️ at Spotify</a>
|
||||
</p>
|
||||
<p className="copyright">{this.props.config.copyright}</p>
|
||||
</footer>
|
||||
);
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Argo CD
|
||||
author: roadie.io
|
||||
authorUrl: https://roadie.io
|
||||
category: CI
|
||||
description: View Argo CD status for your projects in Backstage.
|
||||
documentation: https://roadie.io/backstage/plugins/argo-cd
|
||||
iconUrl: https://roadie.io/images/logos/argo.png
|
||||
npmPackageName: '@roadiehq/backstage-plugin-argo-cd'
|
||||
tags:
|
||||
- cd
|
||||
- ci
|
||||
@@ -2,7 +2,7 @@
|
||||
title: AWS Lambda
|
||||
author: roadie.io
|
||||
authorUrl: https://roadie.io
|
||||
category: Monitoring
|
||||
category: Infrastructure
|
||||
description: View AWS Lambda functions for your components in Backstage.
|
||||
documentation: https://roadie.io/backstage/plugins/aws-lambda
|
||||
iconUrl: https://roadie.io/images/logos/lambda.png
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title: Firebase Functions
|
||||
author: roadie.io
|
||||
authorUrl: https://roadie.io/
|
||||
category: Monitoring
|
||||
category: Infrastructure
|
||||
description: View Firebase Functions details for your service in Backstage.
|
||||
documentation: https://roadie.io/backstage/plugins/firebase-functions
|
||||
iconUrl: https://roadie.io/images/logos/firebase.png
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: FOSSA
|
||||
author: SDA SE
|
||||
authorUrl: https://sda.se/
|
||||
category: Quality
|
||||
description: View FOSSA license compliance of your components in Backstage.
|
||||
documentation: https://github.com/backstage/backstage/blob/master/plugins/fossa/README.md
|
||||
iconUrl: https://avatars0.githubusercontent.com/u/9543448?s=400&v=4
|
||||
npmPackageName: '@backstage/plugin-fossa'
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user