Merge branch 'master' of https://ghe.spotify.net/cost-engineering/backstage
This commit is contained in:
Ryan Vazquez
@@ -0,0 +1,8 @@
|
||||
# Changesets
|
||||
|
||||
Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
|
||||
with multi-package repos, or single-package repos to help you version and publish your code. You can
|
||||
find the full documentation for it [in our repository](https://github.com/changesets/changesets)
|
||||
|
||||
We have a quick list of common questions to get you started engaging with this project in
|
||||
[our documentation](https://github.com/changesets/changesets/blob/master/docs/common-questions.md)
|
||||
@@ -0,0 +1,59 @@
|
||||
{
|
||||
"$schema": "https://unpkg.com/@changesets/config@1.3.0/schema.json",
|
||||
"changelog": "@changesets/cli/changelog",
|
||||
"commit": false,
|
||||
"linked": [
|
||||
[
|
||||
"example-app",
|
||||
"@backstage/backend-common",
|
||||
"example-backend",
|
||||
"@backstage/catalog-model",
|
||||
"@backstage/cli-common",
|
||||
"@backstage/cli",
|
||||
"@backstage/config-loader",
|
||||
"@backstage/config",
|
||||
"@backstage/core-api",
|
||||
"@backstage/core",
|
||||
"@backstage/create-app",
|
||||
"@backstage/dev-utils",
|
||||
"docgen",
|
||||
"e2e-test",
|
||||
"storybook",
|
||||
"@techdocs/cli",
|
||||
"@backstage/test-utils-core",
|
||||
"@backstage/test-utils",
|
||||
"@backstage/theme",
|
||||
"@backstage/plugin-api-docs",
|
||||
"@backstage/plugin-app-backend",
|
||||
"@backstage/plugin-auth-backend",
|
||||
"@backstage/plugin-catalog-backend",
|
||||
"@backstage/plugin-catalog",
|
||||
"@backstage/plugin-circleci",
|
||||
"@backstage/plugin-gcp-projects",
|
||||
"@backstage/plugin-github-actions",
|
||||
"@backstage/plugin-gitops-profiles",
|
||||
"@backstage/plugin-graphiql",
|
||||
"@backstage/plugin-graphql-backend",
|
||||
"@backstage/plugin-identity-backend",
|
||||
"@backstage/plugin-jenkins",
|
||||
"@backstage/plugin-lighthouse",
|
||||
"@backstage/plugin-newrelic",
|
||||
"@backstage/plugin-proxy-backend",
|
||||
"@backstage/plugin-register-component",
|
||||
"@backstage/plugin-rollbar-backend",
|
||||
"@backstage/plugin-rollbar",
|
||||
"@backstage/plugin-scaffolder-backend",
|
||||
"@backstage/plugin-scaffolder",
|
||||
"@backstage/plugin-sentry-backend",
|
||||
"@backstage/plugin-sentry",
|
||||
"@backstage/plugin-tech-radar",
|
||||
"@backstage/plugin-techdocs-backend",
|
||||
"@backstage/plugin-techdocs",
|
||||
"@backstage/plugin-welcome"
|
||||
]
|
||||
],
|
||||
"access": "public",
|
||||
"baseBranch": "master",
|
||||
"updateInternalDependencies": "patch",
|
||||
"ignore": []
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
comment: false # Ref: https://docs.codecov.io/docs/pull-request-comments
|
||||
|
||||
coverage:
|
||||
status:
|
||||
project:
|
||||
default:
|
||||
threshold: 0% # Ref: https://docs.codecov.io/docs/codecovyml-reference#coveragestatus
|
||||
target: auto
|
||||
|
||||
# Since Backstage is a mono repo, flags here help in getting the code coverage of individual packages.
|
||||
# Documentation: https://docs.codecov.io/docs/flags
|
||||
flags:
|
||||
core:
|
||||
paths:
|
||||
- packages/core/
|
||||
core-api:
|
||||
paths:
|
||||
- packages/core-api/
|
||||
@@ -7,3 +7,5 @@
|
||||
**/.git/**
|
||||
**/public/**
|
||||
**/microsite/**
|
||||
**/templates/**
|
||||
**/sample-templates/**
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
name: Changeset
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
|
||||
jobs:
|
||||
create-release-pr:
|
||||
name: Create Changeset PR
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v1
|
||||
- name: Install Dependencies
|
||||
run: yarn --frozen-lockfile
|
||||
- name: Create Release Pull Request
|
||||
uses: changesets/action@master
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
@@ -93,9 +93,11 @@ jobs:
|
||||
if: ${{ steps.yarn-lock.outcome == 'success' }}
|
||||
run: yarn lerna -- run test --since origin/master -- --coverage
|
||||
|
||||
- name: test all packages
|
||||
- name: test all packages (and upload coverage)
|
||||
if: ${{ steps.yarn-lock.outcome == 'failure' }}
|
||||
run: yarn lerna -- run test -- --coverage
|
||||
run: |
|
||||
yarn lerna -- run test -- --coverage
|
||||
bash <(curl -s https://codecov.io/bash)
|
||||
|
||||
- name: verify plugin template
|
||||
run: yarn lerna -- run diff -- --check
|
||||
|
||||
@@ -27,25 +27,12 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
# Beginning of yarn setup, keep in sync between all workflows, see ci.yml
|
||||
- name: use node.js ${{ matrix.node-version }}
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: ${{ matrix.node-version }}
|
||||
registry-url: https://registry.npmjs.org/ # Needed for auth
|
||||
- name: find location of global yarn cache
|
||||
id: yarn-cache
|
||||
run: echo "::set-output name=dir::$(yarn cache dir)"
|
||||
- name: cache global yarn cache
|
||||
uses: actions/cache@v2
|
||||
with:
|
||||
path: ${{ steps.yarn-cache.outputs.dir }}
|
||||
key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
|
||||
restore-keys: |
|
||||
${{ runner.os }}-yarn-
|
||||
- name: yarn install
|
||||
run: yarn install --frozen-lockfile
|
||||
# End of yarn setup
|
||||
|
||||
- run: yarn tsc
|
||||
- name: yarn build
|
||||
|
||||
@@ -3,6 +3,8 @@ name: E2E Test Linux
|
||||
on:
|
||||
pull_request:
|
||||
paths-ignore:
|
||||
- 'contrib/**'
|
||||
- 'docs/**'
|
||||
- 'microsite/**'
|
||||
|
||||
jobs:
|
||||
|
||||
@@ -59,8 +59,13 @@ jobs:
|
||||
- name: verify type dependencies
|
||||
run: yarn lint:type-deps
|
||||
|
||||
- name: test
|
||||
run: yarn lerna -- run test -- --coverage
|
||||
- name: test (and upload coverage)
|
||||
run: |
|
||||
yarn lerna -- run test -- --coverage
|
||||
bash <(curl -s https://codecov.io/bash)
|
||||
# Upload code coverage for some specific flags. Also see .codecov.yml
|
||||
bash <(curl -s https://codecov.io/bash) -f packages/core/coverage/* -F core
|
||||
bash <(curl -s https://codecov.io/bash) -f packages/core-api/coverage/* -F core-api
|
||||
|
||||
# Publishes current version of packages that are not already present in the registry
|
||||
- name: publish
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
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/spotify/backstage/projects/5
|
||||
# New issues with TechDocs in their title or docs-like-code label will be added to the board.
|
||||
|
||||
on:
|
||||
issues:
|
||||
types: [opened, reopened, labeled, edited]
|
||||
pull_request:
|
||||
types: [opened, reopened, labeled, edited]
|
||||
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
jobs:
|
||||
assign_issue_or_pr_to_project:
|
||||
runs-on: ubuntu-latest
|
||||
name: Triage
|
||||
steps:
|
||||
- name: Assign new issue to Incoming based on its title.
|
||||
uses: srggrs/assign-one-project-github-action@1.2.0
|
||||
if: |
|
||||
contains(github.event.issue.title, 'TechDocs') ||
|
||||
contains(github.event.issue.title, 'techdocs') ||
|
||||
contains(github.event.issue.title, 'Techdocs')
|
||||
with:
|
||||
project: 'https://github.com/spotify/backstage/projects/5'
|
||||
column_name: 'Incoming'
|
||||
|
||||
- name: Assign new issue to Incoming based on its label.
|
||||
uses: srggrs/assign-one-project-github-action@1.2.0
|
||||
if: |
|
||||
contains(github.event.issue.labels.*.name, 'docs-like-code')
|
||||
with:
|
||||
project: 'https://github.com/spotify/backstage/projects/5'
|
||||
column_name: 'Incoming'
|
||||
|
||||
- name: Assign new PR to Incoming based on its title.
|
||||
uses: srggrs/assign-one-project-github-action@1.2.0
|
||||
if: |
|
||||
contains(github.event.pull_request.title, 'TechDocs') ||
|
||||
contains(github.event.pull_request.title, 'techdocs') ||
|
||||
contains(github.event.pull_request.title, 'Techdocs')
|
||||
with:
|
||||
project: 'https://github.com/spotify/backstage/projects/5'
|
||||
column_name: 'Incoming'
|
||||
|
||||
- name: Assign new PR to Incoming based on its label.
|
||||
uses: srggrs/assign-one-project-github-action@1.2.0
|
||||
if: |
|
||||
contains(github.event.pull_request.labels.*.name, 'docs-like-code')
|
||||
with:
|
||||
project: 'https://github.com/spotify/backstage/projects/5'
|
||||
column_name: 'Incoming'
|
||||
+55
-1
@@ -8,11 +8,48 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re
|
||||
|
||||
> Collect changes for the next release below
|
||||
|
||||
### @backstage/core
|
||||
|
||||
- Renamed `SessionStateApi` to `SessionApi` and `logout` to `signOut`. Custom implementations of the `SingInPage` app-component will need to rename their `logout` function. The different auth provider items for the `UserSettingsMenu` have been consolidated into a single `ProviderSettingsItem`, meaning you need to replace existing usages of `OAuthProviderSettings` and `OIDCProviderSettings`. [#2555](https://github.com/spotify/backstage/pull/2555).
|
||||
|
||||
## v0.1.1-alpha.22
|
||||
|
||||
### @backstage/core
|
||||
|
||||
- Introduced initial version of an inverted app/plugin relationship, where plugins export components for apps to use, instead registering themselves directly into the app. This enables more fine-grained control of plugin features, and also composition of plugins such as catalog pages with additional cards and tabs. This breaks the use of `RouteRef`s, and there will be more changes related to this in the future, but this change lays the initial foundation. See `packages/app` and followup PRs for how to update plugins for this change. [#2076](https://github.com/spotify/backstage/pull/2076)
|
||||
- Switch to an automatic dependency injection mechanism for all Utility APIs, allowing plugins to ship default implementations of their APIs. See [https://backstage.io/docs/api/utility-apis](https://backstage.io/docs/api/utility-apis). [#2285](https://github.com/spotify/backstage/pull/2285)
|
||||
|
||||
### @backstage/cli
|
||||
|
||||
- Change `backstage-cli backend:build-image` to forward all args to `docker image build`, instead of just tag. Also add `--build` flag for building all dependent packages before packaging the workspace for the docker build. [#2299](https://github.com/spotify/backstage/pull/2299)
|
||||
|
||||
### @backstage/create-app
|
||||
|
||||
- Change root `tsc` output dir to `dist-types`, in order to allow for standalone plugin repos. [#2278](https://github.com/spotify/backstage/pull/2278)
|
||||
|
||||
### @backstage/catalog-backend
|
||||
|
||||
- We have simplified the way that GitHub ingestion works. The `catalog.processors.githubApi` key is deprecated, in favor of `catalog.processors.github`. At the same time, the location type `github/api` is likewise deprecated, in favor of `github`. This location type now serves both raw HTTP reads and APIv3 reads, depending on how you configure it. It also supports having several providers at once - for example, both public GitHub and an internal GitHub Enterprise, with different keys. If you still use the `catalog.processors.githubApi` config key, things will work but you will get a deprecation warning at startup. In a later release, support for the old key will go away entirely. See the [configuration section in the docs](https://backstage.io/docs/features/software-catalog/configuration) for more details.
|
||||
|
||||
## v0.1.1-alpha.21
|
||||
|
||||
- Added many more frontend plugins to the template along with the sidebar. [#1942](https://github.com/spotify/backstage/pull/1942), [#2084](https://github.com/spotify/backstage/pull/2084)
|
||||
|
||||
### @backstage/core
|
||||
|
||||
- Material-UI: Bumped to 4.11.0, which is the version that create-app will
|
||||
resolve to, because we wanted to get the renaming of ExpansionPanel to
|
||||
Accordion into place. This gets rid of a lot of console deprecation warnings
|
||||
in newly scaffolded apps.
|
||||
|
||||
### @backstage/cli
|
||||
|
||||
- Set `NODE_ENV` to `test` when running test. [#2214](https://github.com/spotify/backstage/pull/2214)
|
||||
|
||||
- Fix for backend plugins names requiring to be prefixed with `@backstage` to build. [#2224](https://github.com/spotify/backstage/pull/2224)
|
||||
|
||||
### @backstage/backend-common
|
||||
|
||||
- The backend plugin
|
||||
[service builder](https://github.com/spotify/backstage/blob/master/packages/backend-common/src/service/lib/ServiceBuilderImpl.ts)
|
||||
no longer adds `express.json()` automatically to all routes. While convenient
|
||||
@@ -22,14 +59,31 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re
|
||||
still had to cater to that manually. We therefore decided to let plugins add
|
||||
`express.json()` themselves if they happen to deal with JSON data.
|
||||
|
||||
### @backstage/catalog-backend
|
||||
|
||||
- Add rules configuration for catalog location and entity kinds. The default rules should cover most use-cases, but you may need to allow specific entity kinds when using things like Template or Group entities. [#2118](https://github.com/spotify/backstage/pull/2118)
|
||||
|
||||
## v0.1.1-alpha.20
|
||||
|
||||
- Includes https://github.com/spotify/backstage/pull/2097 to resolve issues with create-plugin command.
|
||||
### @backstage/cli
|
||||
|
||||
- Use config files according to `NODE_ENV` when serving and building frontend packages. [#2077](https://github.com/spotify/backstage/pull/2077)
|
||||
|
||||
- Pin `rollup-plugin-dts` to avoid a later broken version. [#2097](https://github.com/spotify/backstage/pull/2097)
|
||||
|
||||
## v0.1.1-alpha.19
|
||||
|
||||
### @backstage/backend-common
|
||||
|
||||
- Allow listen host and port to be configured separately, in order to support PORT environment variables. [#1950](https://github.com/spotify/backstage/pull/1950)
|
||||
|
||||
### @backstage/core
|
||||
|
||||
- Added new `DiscoveryApi` for discovering backend endpoint in the frontend, and use in most plugins. See [packages/app/src/apis.ts](https://github.com/spotify/backstage/blob/master/packages/app/src/apis.ts) for how to register in your app. [#2074](https://github.com/spotify/backstage/pull/2074)
|
||||
|
||||
### @backstage/create-app
|
||||
|
||||
- Added catalog and scaffolder frontend plugins to the template along with the sidebar. [#1942](https://github.com/spotify/backstage/pull/1942), [#2084](https://github.com/spotify/backstage/pull/2084)
|
||||
- Many plugins have been added to the catalog and will for now be required to be added to separate apps as well. This will be solved as [#1536](https://github.com/spotify/backstage/issues/1536) gets sorted out, but for now you may need to install some plugins just to get pages to work.
|
||||
|
||||
### @backstage/catalog-backend
|
||||
|
||||
+16
-29
@@ -62,35 +62,7 @@ Have you started using Backstage? Adding your company to [ADOPTERS](ADOPTERS.md)
|
||||
|
||||
So...feel ready to jump in? Let's do this. 👏🏻💯
|
||||
|
||||
To run a Backstage app, you will need to have the following installed:
|
||||
|
||||
- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12
|
||||
- [yarn](https://classic.yarnpkg.com/en/docs/install)
|
||||
|
||||
After cloning this repo, open a terminal window and start the example app using the following commands from the project root:
|
||||
|
||||
```bash
|
||||
yarn install # Install dependencies
|
||||
|
||||
yarn start # Start dev server, use --check to enable linting and type-checks
|
||||
```
|
||||
|
||||
The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
|
||||
|
||||
Depending on the work you're doing, you often also want to run the example backend. Start the backend in a separate terminal session using the following:
|
||||
|
||||
```bash
|
||||
cd packages/backend
|
||||
|
||||
yarn start
|
||||
|
||||
yarn lerna run mock-data # Populate the backend with mock data
|
||||
```
|
||||
|
||||
And that's it! You are good to go 👍
|
||||
|
||||
If you need help, just jump into our [Discord chatroom](https://discord.gg/MUpMjP2).
|
||||
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
|
||||
|
||||
@@ -100,6 +72,21 @@ If you're contributing to the backend or CLI tooling, be mindful of cross-platfo
|
||||
|
||||
Also be sure to skim through our [ADRs](https://github.com/spotify/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/spotify/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for.
|
||||
|
||||
# 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.
|
||||
|
||||
## 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)
|
||||
4. Add generated changset 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
|
||||
|
||||
For more information, checkout [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in changesets repository.
|
||||
|
||||
# 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.
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
|
||||
[](https://discord.gg/EBHEGzX)
|
||||
|
||||
[](https://codecov.io/gh/spotify/backstage)
|
||||
[](https://github.com/spotify/backstage/releases)
|
||||
|
||||
## What is Backstage?
|
||||
@@ -31,33 +32,7 @@ A detailed project roadmap, including already delivered milestones, is available
|
||||
|
||||
## Getting Started
|
||||
|
||||
There are two different ways to get started with Backstage, either by creating a standalone app, or by cloning this repo. Which method you use depends on what 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 recommended approach if you want to kick the tyres of Backstage or setup your own instance.
|
||||
|
||||
On the other hand, if you want to contribute plugins or to the project in general, it's easier to fork and clone this project. That will let you stay up to date with the latest changes, and gives you an easier path to make Pull Requests towards this repo.
|
||||
|
||||
### Creating a Standalone App
|
||||
|
||||
Backstage provides the `@backstage/create-app` package to scaffold standalone instances of Backstage. You will need to have
|
||||
[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
|
||||
(currently v12), and [yarn](https://classic.yarnpkg.com/en/docs/install). You will also need to have [Docker](https://docs.docker.com/engine/install/) installed to use some features like Software Templates and TechDocs.
|
||||
|
||||
Using `npx` you can then run the following to create an app in a chosen subdirectory of your current working directory:
|
||||
|
||||
```bash
|
||||
npx @backstage/create-app
|
||||
```
|
||||
|
||||
You will be taken through a wizard to create your app, and the output should look something like this. You can read more about this process [here](https://backstage.io/docs/getting-started/create-an-app)
|
||||
|
||||
### Contributing to Backstage
|
||||
|
||||
You can read more in our [CONTRIBUTING.md](./CONTRIBUTING.md#get-started) guide, which can help you get setup with a Backstage development environment.
|
||||
|
||||
### Next steps
|
||||
|
||||
Take a look at the [Getting Started](https://backstage.io/docs/getting-started/index) guide to learn how to set up Backstage, and how to develop on the platform.
|
||||
Check out [the documentation](https://backstage.io/docs/getting-started) on how to start using Backstage.
|
||||
|
||||
## Documentation
|
||||
|
||||
|
||||
+54
-21
@@ -35,6 +35,8 @@ organization:
|
||||
techdocs:
|
||||
storageUrl: http://localhost:7000/techdocs/static/docs
|
||||
requestUrl: http://localhost:7000/techdocs/docs
|
||||
generators:
|
||||
techdocs: 'docker'
|
||||
|
||||
sentry:
|
||||
organization: spotify
|
||||
@@ -57,10 +59,24 @@ catalog:
|
||||
rules:
|
||||
- allow: [Component, API, Group, Template, Location]
|
||||
processors:
|
||||
githubApi:
|
||||
privateToken:
|
||||
$secret:
|
||||
env: GITHUB_PRIVATE_TOKEN
|
||||
github:
|
||||
providers:
|
||||
- target: https://github.com
|
||||
token:
|
||||
$secret:
|
||||
env: GITHUB_PRIVATE_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
|
||||
# token:
|
||||
# $secret:
|
||||
# env: GHE_PRIVATE_TOKEN
|
||||
#### Example for how to add your GitHub Enterprise instance using raw HTTP fetches (token is optional):
|
||||
# - target: https://ghe.example.net
|
||||
# rawBaseUrl: https://ghe.example.net/raw
|
||||
# token:
|
||||
# $secret:
|
||||
# env: GHE_PRIVATE_TOKEN
|
||||
bitbucketApi:
|
||||
username:
|
||||
$secret:
|
||||
@@ -76,23 +92,40 @@ catalog:
|
||||
privateToken:
|
||||
$secret:
|
||||
env: AZURE_PRIVATE_TOKEN
|
||||
exampleEntityLocations:
|
||||
github:
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-order-component.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/podcast-api-component.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/queue-proxy-component.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/searcher-component.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-lib-component.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/www-artist-component.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/shuffle-api-component.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/react-ssr-template/template.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/create-react-app/template.yaml
|
||||
- https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/docs-template/template.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/hello-world-api.yaml
|
||||
- https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/streetlights-api.yaml
|
||||
|
||||
locations:
|
||||
# Backstage example components
|
||||
- type: github
|
||||
target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/all-components.yaml
|
||||
|
||||
# Example component for github-actions
|
||||
- type: github
|
||||
target: https://github.com/spotify/backstage/blob/master/plugins/github-actions/examples/sample.yaml
|
||||
|
||||
# Example component for techdocs
|
||||
- type: github
|
||||
target: https://github.com/spotify/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml
|
||||
|
||||
# Backstage example APIs
|
||||
- type: github
|
||||
target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml
|
||||
|
||||
# Backstage example templates
|
||||
- type: github
|
||||
target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml
|
||||
|
||||
scaffolder:
|
||||
github:
|
||||
token:
|
||||
$secret:
|
||||
env: GITHUB_ACCESS_TOKEN
|
||||
visibility: public # or 'internal' or 'private'
|
||||
gitlab:
|
||||
api:
|
||||
baseUrl: https://gitlab.com
|
||||
token:
|
||||
$secret:
|
||||
env: GITLAB_ACCESS_TOKEN
|
||||
|
||||
auth:
|
||||
providers:
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
# Backstage Contrib
|
||||
|
||||
This directory contains various community contributions related to Backstage.
|
||||
|
||||
Unless otherwise specified, all content in this hierarchy fall under the same
|
||||
[licensing terms](../LICENSE) as in the rest of the repository, and come with
|
||||
no guarantees of functionality or fitness of purpose. That being said, we
|
||||
really appreciate contributions in here and encourage them being kept up to
|
||||
date.
|
||||
@@ -0,0 +1,23 @@
|
||||
FROM node:12 AS build
|
||||
|
||||
RUN mkdir /app
|
||||
COPY . /app
|
||||
WORKDIR /app
|
||||
|
||||
RUN yarn install
|
||||
RUN yarn workspace example-app build
|
||||
|
||||
# Contruct backstage-frontend image
|
||||
FROM nginx:mainline
|
||||
|
||||
RUN apt-get update && apt-get -y install jq && rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Copy from build stage
|
||||
COPY --from=build /app/packages/app/dist /usr/share/nginx/html
|
||||
|
||||
COPY docker/default.conf.template /etc/nginx/conf.d/default.conf.template
|
||||
COPY docker/run.sh /usr/local/bin/run.sh
|
||||
|
||||
CMD run.sh
|
||||
|
||||
ENV PORT 80
|
||||
@@ -0,0 +1,19 @@
|
||||
# Standalone Dockerfile for frontend
|
||||
|
||||
This directory contains the resources which will help you build backstage without any requirements
|
||||
other than docker itself. It uses a multi-stage Dockerfile to build and ship backstage.
|
||||
|
||||
## Usage
|
||||
|
||||
You can simply run the following command to build backstage.
|
||||
|
||||
```
|
||||
# Make sure you are in the root directory of backstage then run
|
||||
docker build -t backstage-frontend -f ./contrib/docker/multi-stage-frontend/Dockerfile .
|
||||
```
|
||||
|
||||
After a successful build, You can simply run backstage frontend with the following command.
|
||||
|
||||
```
|
||||
docker run -it --rm -p 3080:80 backstage-frontend
|
||||
```
|
||||
@@ -0,0 +1,58 @@
|
||||
### Source repo: https://github.com/johnson-jesse/simple-backstage-app-plugin
|
||||
|
||||
ExampleComponent.tsx reference
|
||||
|
||||
```tsx
|
||||
import React, { FC } from 'react';
|
||||
import { Typography, Grid } from '@material-ui/core';
|
||||
import {
|
||||
InfoCard,
|
||||
Header,
|
||||
Page,
|
||||
pageTheme,
|
||||
Content,
|
||||
ContentHeader,
|
||||
HeaderLabel,
|
||||
SupportButton,
|
||||
identityApiRef,
|
||||
} from '@backstage/core';
|
||||
import { useApi } from '@backstage/core-api';
|
||||
import ExampleFetchComponent from '../ExampleFetchComponent';
|
||||
|
||||
const ExampleComponent: FC<{}> = () => {
|
||||
const identityApi = useApi(identityApiRef);
|
||||
const userId = identityApi.getUserId();
|
||||
const profile = identityApi.getProfile();
|
||||
|
||||
return (
|
||||
<Page theme={pageTheme.tool}>
|
||||
<Header
|
||||
title="Welcome to github-playground!"
|
||||
subtitle="Optional subtitle"
|
||||
>
|
||||
<HeaderLabel label="Owner" value="Team X" />
|
||||
<HeaderLabel label="Lifecycle" value="Alpha" />
|
||||
</Header>
|
||||
<Content>
|
||||
<ContentHeader title="Plugin title">
|
||||
<SupportButton>A description of your plugin goes here.</SupportButton>
|
||||
</ContentHeader>
|
||||
<Grid container spacing={3} direction="column">
|
||||
<Grid item>
|
||||
<InfoCard title={userId}>
|
||||
<Typography variant="body1">
|
||||
{`${profile.displayName} | ${profile.email}`}
|
||||
</Typography>
|
||||
</InfoCard>
|
||||
</Grid>
|
||||
<Grid item>
|
||||
<ExampleFetchComponent />
|
||||
</Grid>
|
||||
</Grid>
|
||||
</Content>
|
||||
</Page>
|
||||
);
|
||||
};
|
||||
|
||||
export default ExampleComponent;
|
||||
```
|
||||
@@ -0,0 +1,111 @@
|
||||
### Source repo: https://github.com/johnson-jesse/simple-backstage-app-plugin
|
||||
|
||||
ExampleFetchComponent.tsx reference
|
||||
|
||||
```tsx
|
||||
import React, { FC } from 'react';
|
||||
import { useAsync } from 'react-use';
|
||||
import Alert from '@material-ui/lab/Alert';
|
||||
import {
|
||||
Table,
|
||||
TableColumn,
|
||||
Progress,
|
||||
githubAuthApiRef,
|
||||
} from '@backstage/core';
|
||||
import { useApi } from '@backstage/core-api';
|
||||
import { graphql } from '@octokit/graphql';
|
||||
|
||||
const query = `{
|
||||
viewer {
|
||||
repositories(first: 100) {
|
||||
totalCount
|
||||
nodes {
|
||||
name
|
||||
createdAt
|
||||
description
|
||||
diskUsage
|
||||
isFork
|
||||
}
|
||||
pageInfo {
|
||||
endCursor
|
||||
hasNextPage
|
||||
}
|
||||
}
|
||||
}
|
||||
}`;
|
||||
|
||||
type Node = {
|
||||
name: string;
|
||||
createdAt: string;
|
||||
description: string;
|
||||
diskUsage: number;
|
||||
isFork: boolean;
|
||||
};
|
||||
|
||||
type Viewer = {
|
||||
repositories: {
|
||||
totalCount: number;
|
||||
nodes: Node[];
|
||||
pageInfo: {
|
||||
endCursor: string;
|
||||
hasNextPage: boolean;
|
||||
};
|
||||
};
|
||||
};
|
||||
|
||||
type DenseTableProps = {
|
||||
viewer: Viewer;
|
||||
};
|
||||
|
||||
export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
|
||||
const columns: TableColumn[] = [
|
||||
{ title: 'Name', field: 'name' },
|
||||
{ title: 'Created', field: 'createdAt' },
|
||||
{ title: 'Description', field: 'description' },
|
||||
{ title: 'Disk Usage', field: 'diskUsage' },
|
||||
{ title: 'Fork', field: 'isFork' },
|
||||
];
|
||||
|
||||
return (
|
||||
<Table
|
||||
title="List Of User's Repositories"
|
||||
options={{ search: false, paging: false }}
|
||||
columns={columns}
|
||||
data={viewer.repositories.nodes}
|
||||
/>
|
||||
);
|
||||
};
|
||||
|
||||
const ExampleFetchComponent: FC<{}> = () => {
|
||||
const auth = useApi(githubAuthApiRef);
|
||||
|
||||
const { value, loading, error } = useAsync(async (): Promise<any> => {
|
||||
const token = await auth.getAccessToken();
|
||||
|
||||
const gqlEndpoint = graphql.defaults({
|
||||
// Uncomment baseUrl if using enterprise
|
||||
// baseUrl: 'https://github.MY-BIZ.com/api',
|
||||
headers: {
|
||||
authorization: `token ${token}`,
|
||||
},
|
||||
});
|
||||
const { viewer } = await gqlEndpoint(query);
|
||||
return viewer;
|
||||
}, []);
|
||||
|
||||
if (loading) return <Progress />;
|
||||
if (error) return <Alert severity="error">{error.message}</Alert>;
|
||||
if (value && value.repositories) return <DenseTable viewer={value} />;
|
||||
|
||||
return (
|
||||
<Table
|
||||
title="List Of User's Repositories"
|
||||
options={{ search: false, paging: false }}
|
||||
columns={[]}
|
||||
data={[]}
|
||||
/>
|
||||
);
|
||||
};
|
||||
|
||||
export default ExampleFetchComponent;
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
# Basic Kubernetes example with Helm
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: FAQ
|
||||
title: FAQ
|
||||
description: All FAQ related to Backstage
|
||||
---
|
||||
|
||||
## Product FAQ
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: backend
|
||||
title: Backend
|
||||
description: About Backend
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: utility-apis
|
||||
title: Utility APIs
|
||||
description: Backstage Utility APIs
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: adrs-adr001
|
||||
title: ADR001: Architecture Decision Record (ADR) log
|
||||
sidebar_label: ADR001
|
||||
description: Architecture Decision Record (ADR) logs as a reference point for the team
|
||||
---
|
||||
|
||||
| Created | Status |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: adrs-adr002
|
||||
title: ADR002: Default Software Catalog File Format
|
||||
sidebar_label: ADR002
|
||||
description: Architecture Decision Record (ADR) log on Default Software Catalog File Format
|
||||
---
|
||||
|
||||
| Created | Status |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: adrs-adr003
|
||||
title: ADR003: Avoid Default Exports and Prefer Named Exports
|
||||
sidebar_label: ADR003
|
||||
description: Architecture Decision Record (ADR) log on Avoid Default Exports and Prefer Named Exports
|
||||
---
|
||||
|
||||
| Created | Status |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: adrs-adr004
|
||||
title: ADR004: Module Export Structure
|
||||
sidebar_label: ADR004
|
||||
description: Architecture Decision Record (ADR) log on Module Export Structure
|
||||
---
|
||||
|
||||
| Created | Status |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: adrs-adr005
|
||||
title: ADR005: Catalog Core Entities
|
||||
sidebar_label: ADR005
|
||||
description: Architecture Decision Record (ADR) log on Catalog Core Entities
|
||||
---
|
||||
|
||||
| Created | Status |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: adrs-adr006
|
||||
title: ADR006: Avoid React.FC and React.SFC
|
||||
sidebar_label: ADR006
|
||||
description: Architecture Decision Record (ADR) log on Avoid React.FC and React.SFC
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: adrs-adr007
|
||||
title: ADR007: Use MSW to mock http requests
|
||||
sidebar_label: ADR007
|
||||
description: Architecture Decision Record (ADR) log on Use MSW to mock http requests
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
id: adrs-adr008
|
||||
title: ADR008: Default Catalog File Name
|
||||
sidebar_label: ADR008
|
||||
description: Architecture Decision Record (ADR) log on Default Catalog File Name
|
||||
---
|
||||
|
||||
## Background
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
id: adrs-overview
|
||||
title: Architecture Decision Records (ADR)
|
||||
sidebar_label: Overview
|
||||
description: Overview of Architecture Decision Records (ADR)
|
||||
---
|
||||
|
||||
The substantial architecture decisions made in the Backstage project live here.
|
||||
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: add-auth-provider
|
||||
title: Adding authentication providers
|
||||
description: Documentation on Adding authentication providers
|
||||
---
|
||||
|
||||
## Passport
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: auth-backend-classes
|
||||
title: Auth backend classes
|
||||
description: Documentation on Auth backend classes
|
||||
---
|
||||
|
||||
## How Does Authentication Work?
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: auth-backend
|
||||
title: Auth backend
|
||||
description: Documentation on Auth backend
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: glossary
|
||||
title: Glossary
|
||||
description: All Glossaries related to auth
|
||||
---
|
||||
|
||||
- **Popup** - A separate browser window opened on top of the previous one.
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: index
|
||||
title: User Authentication and Authorization in Backstage
|
||||
description: Documentation on User Authentication and Authorization in Backstage
|
||||
---
|
||||
|
||||
## Summary
|
||||
@@ -34,6 +35,13 @@ full list of providers, see the
|
||||
|
||||
### Identity - WIP
|
||||
|
||||
> NOTE: Identity management and the `SignInPage` in Backstage is NOT a method
|
||||
> for blocking access for unauthorized users, that either requires additional
|
||||
> backend implementation or a separate service like Google's Identity-Aware
|
||||
> Proxy. The identity system only serves to provide a personalized experience
|
||||
> and access to a Backstage Identity Token, which can be passed to backend
|
||||
> plugins.
|
||||
|
||||
Identity management is still work in progress, but there are already a couple of
|
||||
pieces in place that can be used.
|
||||
|
||||
|
||||
+5
-2
@@ -1,6 +1,9 @@
|
||||
---
|
||||
id: oauth
|
||||
title: OAuth and OpenID Connect
|
||||
description: This section describes how Backstage allows plugins to request
|
||||
OAuth Access Tokens and OpenID Connect ID Tokens on behalf of the user, to be
|
||||
used for auth to various third party APIs
|
||||
---
|
||||
|
||||
This section describes how Backstage allows plugins to request OAuth Access
|
||||
@@ -104,10 +107,10 @@ request an access token.
|
||||
|
||||
The following diagram visualizes the flow described in the previous section.
|
||||
|
||||
|
||||
|
||||
|
||||
<!--
|
||||
@startuml oauth-popup-flow
|
||||
@startuml /../assets/auth/oauth-popup-flow
|
||||
|
||||
skinparam monochrome true
|
||||
skinparam shadowing false
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: defining
|
||||
title: Defining Configuration for your Plugin
|
||||
description: Documentation on Defining Configuration for your Plugin
|
||||
---
|
||||
|
||||
There is currently no tooling support or helpers for defining plugin
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: index
|
||||
title: Static Configuration in Backstage
|
||||
description: Documentation on Static Configuration in Backstage
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: reading
|
||||
title: Reading Backstage Configuration
|
||||
description: Documentation on Reading Backstage Configuration
|
||||
---
|
||||
|
||||
## Config API
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: writing
|
||||
title: Writing Backstage Configuration Files
|
||||
description: Documentation on Writing Backstage Configuration Files
|
||||
---
|
||||
|
||||
## File Format
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: contributing-to-storybook
|
||||
title: Contributing to Storybook
|
||||
description: Documentation on How to Contribute to Storybook
|
||||
---
|
||||
|
||||
You find our storybook at
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: design
|
||||
title: Design
|
||||
description: Documentation on Design
|
||||
---
|
||||
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
id: figma
|
||||
title: Figma
|
||||
description: Documentation on using Figma to build your own plugins for
|
||||
Backstage
|
||||
---
|
||||
|
||||
We have a [Figma component library](https://www.figma.com/@backstage) that you
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: software-catalog-api
|
||||
title: API
|
||||
description: Documentation on Software Catalog API
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -1,8 +1,70 @@
|
||||
---
|
||||
id: software-catalog-configuration
|
||||
title: Catalog Configuration
|
||||
description: Documentation on Software Catalog Configuration
|
||||
---
|
||||
|
||||
## Processors
|
||||
|
||||
The catalog makes use of so called processors to perform all kinds of ingestion
|
||||
tasks, such as reading raw entity data from a remote source, parsing it,
|
||||
transforming it, and validating it. These processors are configured under the
|
||||
`catalog.processors` key.
|
||||
|
||||
### Processor: github
|
||||
|
||||
The `github` processor is responsible for fetching entity data from files on
|
||||
GitHub or GitHub Enterprise. The configuration for this processor lives under
|
||||
`catalog.processors.github`. Example:
|
||||
|
||||
```yaml
|
||||
catalog:
|
||||
processors:
|
||||
github:
|
||||
providers:
|
||||
- target: https://github.com
|
||||
token:
|
||||
$secret:
|
||||
env: GITHUB_PRIVATE_TOKEN
|
||||
- target: https://ghe.example.net
|
||||
apiBaseUrl: https://ghe.example.net/api/v3
|
||||
rawBaseUrl: https://ghe.example.net/raw
|
||||
token:
|
||||
$secret:
|
||||
env: GHE_PRIVATE_TOKEN
|
||||
```
|
||||
|
||||
The main subkey is `providers`, where you can list the various GitHub compatible
|
||||
providers you want to be able to fetch data from. Each entry is a structure with
|
||||
up to four elements:
|
||||
|
||||
- `target` (required): The string prefix of the location target that you want to
|
||||
match on, with no trailing slash. For GitHub, it should be exactly
|
||||
`https://github.com`.
|
||||
- `token` (optional): An authentication token as expected by GitHub. If
|
||||
supplied, it will be passed along with all calls to this provider, both API
|
||||
and raw. If it is not supplied, anonymous access will be used.
|
||||
- `apiBaseUrl` (optional): If you want to communicate using the APIv3 method
|
||||
with this provider, specify the base URL for its endpoint here, with no
|
||||
trailing slash. Specifically when the target is github, you can leave it out
|
||||
to be inferred automatically. For a GitHub Enterprise installation, it is
|
||||
commonly at `https://api.<host>` or `https://<host>/api/v3`.
|
||||
- `rawBaseUrl` (optional): If you want to communicate using the raw HTTP method
|
||||
with this provider, specify the base URL for its endpoint here, with no
|
||||
trailing slash. Specifically when the target is public GitHub, you can leave
|
||||
it out to be inferred automatically. For a GitHub Enterprise installation, it
|
||||
is commonly at `https://api.<host>` or `https://<host>/api/v3`.
|
||||
|
||||
You need to supply either `apiBaseUrl` or `rawBaseUrl` or both (except for
|
||||
public GitHub, for which we can infer them). The `apiBaseUrl` will always be
|
||||
preferred over the other if a `token` is given, otherwise `rawBaseUrl` will be
|
||||
preferred.
|
||||
|
||||
If you do not supply a public GitHub provider, one will be added automatically,
|
||||
silently at startup for convenience. So you only have to list it if you want to
|
||||
supply a token for it - and if you do, you can also leave out the `apiBaseUrl`
|
||||
and `rawBaseUrl` fields.
|
||||
|
||||
## Static Location Configuration
|
||||
|
||||
To enable declarative catalog setups, it is possible to add locations to the
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
id: descriptor-format
|
||||
title: Descriptor Format of Catalog Entities
|
||||
sidebar_label: YAML File Format
|
||||
description: Documentation on Descriptor Format of Catalog Entities which
|
||||
describes the default data shape and semantics of catalog entities
|
||||
---
|
||||
|
||||
This section describes the default data shape and semantics of catalog entities.
|
||||
@@ -471,6 +473,7 @@ Describes the following entity kind:
|
||||
An API describes an interface that can be exposed by a component. The API can be
|
||||
defined in different formats, like [OpenAPI](https://swagger.io/specification/),
|
||||
[AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/),
|
||||
[GraphQL](https://graphql.org/learn/schema/),
|
||||
[gRPC](https://developers.google.com/protocol-buffers), or other formats.
|
||||
|
||||
Descriptor files for this kind may look as follows.
|
||||
@@ -483,6 +486,8 @@ metadata:
|
||||
description: Retrieve artist details
|
||||
spec:
|
||||
type: openapi
|
||||
lifecycle: production
|
||||
owner: artist-relations@example.com
|
||||
definition: |
|
||||
openapi: "3.0.0"
|
||||
info:
|
||||
@@ -527,6 +532,41 @@ The current set of well-known and common values for this field is:
|
||||
[Protocol Buffers](https://developers.google.com/protocol-buffers) to use with
|
||||
[gRPC](https://grpc.io/).
|
||||
|
||||
### `spec.lifecycle` [required]
|
||||
|
||||
The lifecycle state of the API, e.g. `production`. This field is required.
|
||||
|
||||
The software catalog accepts any lifecycle value, but an organization should
|
||||
take great care to establish a proper taxonomy for these.
|
||||
|
||||
The current set of well-known and common values for this field is:
|
||||
|
||||
- `experimental` - an experiment or early, non-production API, signaling that
|
||||
users may not prefer to consume it over other more established APIs, or that
|
||||
there are low or no reliability guarantees
|
||||
- `production` - an established, owned, maintained API
|
||||
- `deprecated` - an API that is at the end of its lifecycle, and may disappear
|
||||
at a later point in time
|
||||
|
||||
### `spec.owner` [required]
|
||||
|
||||
The owner of the API, e.g. `artist-relations@example.com`. This field is
|
||||
required.
|
||||
|
||||
In Backstage, the owner of an API is the singular entity (commonly a team) that
|
||||
bears ultimate responsibility for the API, and has the authority and capability
|
||||
to develop and maintain it. They will be the point of contact if something goes
|
||||
wrong, or if features are to be requested. The main purpose of this field is for
|
||||
display purposes in Backstage, so that people looking at catalog items can get
|
||||
an understanding of to whom this API belongs. It is not to be used by automated
|
||||
processes to for example assign authorization in runtime systems. There may be
|
||||
others that also develop or otherwise touch the API, but there will always be
|
||||
one ultimate owner.
|
||||
|
||||
Apart from being a string, the software catalog leaves the format of this field
|
||||
open to implementers to choose. Most commonly, it is set to the ID or email of a
|
||||
group of people in an organizational structure.
|
||||
|
||||
### `spec.definition` [required]
|
||||
|
||||
The definition of the API, based on the format defined by `spec.type`. This
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: extending-the-model
|
||||
title: Extending the model
|
||||
description: Documentation on Extending the model
|
||||
---
|
||||
|
||||
Backstage natively supports tracking of the following component
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
id: external-integrations
|
||||
title: External integrations
|
||||
description: Documentation on External integrations to integrate systems
|
||||
with Backstage
|
||||
---
|
||||
|
||||
Backstage natively supports storing software components in
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
id: software-catalog-overview
|
||||
title: Backstage Service Catalog (alpha)
|
||||
sidebar_label: Overview
|
||||
description: The Backstage Service Catalog — actually, a software catalog, since
|
||||
it includes more than just services
|
||||
---
|
||||
|
||||
## What is a Service Catalog?
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: installation
|
||||
title: Installing in your Backstage App
|
||||
description: Documentation on How to install Backstage Plugin
|
||||
---
|
||||
|
||||
The catalog plugin comes in two packages, `@backstage/plugin-catalog` and
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: system-model
|
||||
title: System Model
|
||||
description: Documentation on System Model
|
||||
---
|
||||
|
||||
We believe that a strong shared understanding and terminology around software
|
||||
|
||||
@@ -2,6 +2,9 @@
|
||||
id: well-known-annotations
|
||||
title: Well-known Annotations on Catalog Entities
|
||||
sidebar_label: Well-known Annotations
|
||||
description: Documentation on lists a number of well known Annotations, that
|
||||
have defined semantics. They can be attached to catalog entities and consumed
|
||||
by plugins as needed
|
||||
---
|
||||
|
||||
This section lists a number of well known
|
||||
@@ -51,13 +54,13 @@ The value of this annotation is a location reference string (see above). If this
|
||||
annotation is specified, it is expected to point to a repository that the
|
||||
TechDocs system can read and generate docs from.
|
||||
|
||||
### backstage.io/jenkins-github-folder
|
||||
### jenkins.io/github-folder
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
metadata:
|
||||
annotations:
|
||||
backstage.io/jenkins-github-folder: folder-name/job-name
|
||||
jenkins.io/github-folder: folder-name/job-name
|
||||
```
|
||||
|
||||
The value of this annotation is the path to a job on Jenkins, that builds this
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: adding-templates
|
||||
title: Adding your own Templates
|
||||
description: Documentation on Adding your own Templates
|
||||
---
|
||||
|
||||
Templates are stored in the **Service Catalog** under a kind `Template`. The
|
||||
@@ -105,13 +106,6 @@ curl \
|
||||
This should then have added the catalog, and also should now be listed under the
|
||||
create page at http://localhost:3000/create.
|
||||
|
||||
Alternatively, if you want to get setup with some mock templates that are
|
||||
already provided, run the following to load those templates:
|
||||
|
||||
```
|
||||
yarn lerna run mock-data
|
||||
```
|
||||
|
||||
The `type` field which is chosen in the request to add the `template.yaml` to
|
||||
the Service Catalog here, will be come the `PreparerKey` which will be used to
|
||||
select the `Preparer` when creating a job.
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: extending-preparer
|
||||
title: Create your own Preparer
|
||||
description: Documentation on Creating your own Preparer
|
||||
---
|
||||
|
||||
Preparers are responsible for reading the location of the definition of a
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: extending-publisher
|
||||
title: Create your own Publisher
|
||||
description: Documentation on Creating your own Publisher
|
||||
---
|
||||
|
||||
Publishers are responsible for pushing and storing the templated skeleton after
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: extending-templater
|
||||
title: Creating your own Templater
|
||||
description: Documentation on Creating your own Templater
|
||||
---
|
||||
|
||||
Templaters are responsible for taking the directory path for the skeleton
|
||||
|
||||
@@ -2,12 +2,14 @@
|
||||
id: software-templates-index
|
||||
title: Backstage Software Templates
|
||||
sidebar_label: Overview
|
||||
description: The Software Templates part of Backstage is a tool that can help
|
||||
you create Components inside Backstage
|
||||
---
|
||||
|
||||
The Software Templates part of Backstage is a tool that can help you create
|
||||
Components inside Backstage. By default, it has the ability to load skeletons of
|
||||
code, template in some variables, and then publish the template to some location
|
||||
like GitHub.
|
||||
code, template in some variables, and then publish the template to some
|
||||
locations like GitHub or GitLab.
|
||||
|
||||
<video width="100%" height="100%" controls>
|
||||
<source src="https://backstage.io/blog/assets/2020-08-05/feature.mp4" type="video/mp4">
|
||||
@@ -38,8 +40,10 @@ internally.
|
||||
|
||||
After filling in these variables, you'll get some more fields to fill out which
|
||||
are required for backstage usage: the owner, (which is a `user` in the backstage
|
||||
system), the `storePath` (which right now must be a GitHub Organisation), and a
|
||||
non-existing github repository name in the format `organisation/reponame`.
|
||||
system), the `storePath` (which right now must be a GitHub Organisation or
|
||||
GitHub user), a non-existing github repository name in the format
|
||||
`organisation/reponame`, and a GitHub team or user account which should be
|
||||
granted admin access to the repository.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: installation
|
||||
title: Installing in your Backstage App
|
||||
description: Documentation on How to install Backstage App
|
||||
---
|
||||
|
||||
The scaffolder plugin comes in two packages, `@backstage/plugin-scaffolder` and
|
||||
@@ -86,41 +87,74 @@ import {
|
||||
createRouter,
|
||||
FilePreparer,
|
||||
GithubPreparer,
|
||||
GitlabPreparer,
|
||||
Preparers,
|
||||
Publishers,
|
||||
GithubPublisher,
|
||||
GitlabPublisher,
|
||||
CreateReactAppTemplater,
|
||||
Templaters,
|
||||
RepoVisibilityOptions,
|
||||
} from '@backstage/plugin-scaffolder-backend';
|
||||
import { Octokit } from '@octokit/rest';
|
||||
import { Gitlab } from '@gitbeaker/node';
|
||||
import type { PluginEnvironment } from '../types';
|
||||
import Docker from 'dockerode';
|
||||
|
||||
export default async function createPlugin({ logger }: PluginEnvironment) {
|
||||
export default async function createPlugin({
|
||||
logger,
|
||||
config,
|
||||
}: PluginEnvironment) {
|
||||
const cookiecutterTemplater = new CookieCutter();
|
||||
const craTemplater = new CreateReactAppTemplater();
|
||||
const templaters = new Templaters();
|
||||
|
||||
// Register default templaters
|
||||
templaters.register('cookiecutter', cookiecutterTemplater);
|
||||
templaters.register('cra', craTemplater);
|
||||
|
||||
const filePreparer = new FilePreparer();
|
||||
const githubPreparer = new GithubPreparer();
|
||||
const gitlabPreparer = new GitlabPreparer(config);
|
||||
const preparers = new Preparers();
|
||||
|
||||
// Register default preparers
|
||||
preparers.register('file', filePreparer);
|
||||
preparers.register('github', githubPreparer);
|
||||
preparers.register('gitlab', gitlabPreparer);
|
||||
preparers.register('gitlab/api', gitlabPreparer);
|
||||
|
||||
// Create GitHub client with your access token from environment variables
|
||||
const githubClient = new Octokit({ auth: process.env.GITHUB_ACCESS_TOKEN });
|
||||
const publisher = new GithubPublisher({ client: githubClient });
|
||||
const publishers = new Publishers();
|
||||
|
||||
const githubToken = config.getString('scaffolder.github.token');
|
||||
const repoVisibility = config.getString(
|
||||
'scaffolder.github.visibility',
|
||||
) as RepoVisibilityOptions;
|
||||
|
||||
const githubClient = new Octokit({ auth: githubToken });
|
||||
const githubPublisher = new GithubPublisher({
|
||||
client: githubClient,
|
||||
token: githubToken,
|
||||
repoVisibility,
|
||||
});
|
||||
publishers.register('file', githubPublisher);
|
||||
publishers.register('github', githubPublisher);
|
||||
|
||||
const gitLabConfig = config.getOptionalConfig('scaffolder.gitlab.api');
|
||||
|
||||
if (gitLabConfig) {
|
||||
const gitLabToken = gitLabConfig.getString('token');
|
||||
const gitLabClient = new Gitlab({
|
||||
host: gitLabConfig.getOptionalString('baseUrl'),
|
||||
token: gitLabToken,
|
||||
});
|
||||
const gitLabPublisher = new GitlabPublisher(gitLabClient, gitLabToken);
|
||||
publishers.register('gitlab', gitLabPublisher);
|
||||
publishers.register('gitlab/api', gitLabPublisher);
|
||||
}
|
||||
|
||||
const dockerClient = new Docker();
|
||||
return await createRouter({
|
||||
preparers,
|
||||
templaters,
|
||||
publisher,
|
||||
publishers,
|
||||
logger,
|
||||
dockerClient,
|
||||
});
|
||||
@@ -167,7 +201,7 @@ catalog:
|
||||
target: https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml
|
||||
```
|
||||
|
||||
### Runtime Dependencies
|
||||
### Runtime Dependencies / Configuration
|
||||
|
||||
For the scaffolder backend plugin to function, it needs a GitHub access token,
|
||||
and access to a running Docker daemon. You can create a GitHub access token
|
||||
@@ -177,11 +211,37 @@ docs on creating private GitHub access tokens is available
|
||||
Note that the need for private GitHub access tokens will be replaced with GitHub
|
||||
Apps integration further down the line.
|
||||
|
||||
> **Right now it is only possible to scaffold repositories inside GitHub
|
||||
> organizations, and not under personal accounts.**
|
||||
#### Github
|
||||
|
||||
The GitHub access token is passed along using the `GITHUB_ACCESS_TOKEN`
|
||||
environment variable.
|
||||
The Github access token is retrieved from environment variables via the config.
|
||||
The config file needs to specify what environment variable the token is
|
||||
retrieved from. Your config should have the following objects.
|
||||
|
||||
#### Gitlab
|
||||
|
||||
For Gitlab, we currently support the configuration of the GitLab publisher and
|
||||
allows to configure the private access token and the base URL of a GitLab
|
||||
instance:
|
||||
|
||||
```yaml
|
||||
scaffolder:
|
||||
github:
|
||||
token:
|
||||
$secret:
|
||||
env: GITHUB_ACCESS_TOKEN
|
||||
visibility: public # or 'internal' or 'private'
|
||||
gitlab:
|
||||
api:
|
||||
baseUrl: https://gitlab.com
|
||||
token:
|
||||
$secret:
|
||||
env: SCAFFOLDER_GITLAB_PRIVATE_TOKEN
|
||||
```
|
||||
|
||||
You can configure who can see the new repositories that the scaffolder creates
|
||||
by specifying `visibility` option. Valid options are `public`, `private` and
|
||||
`internal`. `internal` options is for GitHub Enterprise clients, which means
|
||||
public within the organization.
|
||||
|
||||
### Running the Backend
|
||||
|
||||
|
||||
@@ -2,18 +2,16 @@
|
||||
id: faqs
|
||||
title: TechDocs FAQ
|
||||
sidebar_label: FAQ
|
||||
description: This page answers frequently asked questions about TechDocs
|
||||
---
|
||||
|
||||
This page answers frequently asked questions about [TechDocs](README.md).
|
||||
|
||||
_Got a question that you think others might be interested in knowing the answer
|
||||
to? Edit this file
|
||||
[here](https://github.com/spotify/backstage/edit/master/docs/features/techdocs/FAQ.md)._
|
||||
|
||||
## Technology
|
||||
|
||||
- [What static site generator is TechDocs using?](./#what-static-site-generator-is-techdocs-using)
|
||||
- [What is the mkdocs-techdocs-core plugin?](./#what-is-the-mkdocs-techdocs-core-plugin)
|
||||
- [What static site generator is TechDocs using?](#what-static-site-generator-is-techdocs-using)
|
||||
- [What is the mkdocs-techdocs-core plugin?](#what-is-the-mkdocs-techdocs-core-plugin)
|
||||
- [Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc)?](#does-techdocs-support-file-formats-other-than-markdown-eg-rst-asciidoc-)
|
||||
|
||||
#### What static site generator is TechDocs using?
|
||||
|
||||
@@ -30,3 +28,10 @@ package is a MkDocs Plugin that works like a wrapper around multiple MkDocs
|
||||
plugins (e.g.
|
||||
[MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as
|
||||
well as a selection of Python Markdown extensions that TechDocs supports.
|
||||
|
||||
#### Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc) ?
|
||||
|
||||
Not right now. We are currently using MkDocs to generate the documentation from
|
||||
source. So, they have to be in Markdown format. However, in future we want to
|
||||
support other alternatives to MkDocs. That will make it possible to use other
|
||||
file formats.
|
||||
|
||||
@@ -2,22 +2,29 @@
|
||||
id: techdocs-overview
|
||||
title: TechDocs Documentation
|
||||
sidebar_label: Overview
|
||||
description: TechDocs is Spotify’s homegrown docs-like-code solution built
|
||||
directly into Backstage
|
||||
---
|
||||
|
||||
## What is it?
|
||||
|
||||
<!-- Intro, backstory, etc.: -->
|
||||
|
||||
Wait, what is TechDocs? TechDocs is Spotify’s homegrown docs-like-code solution
|
||||
built directly into Backstage. Today, it is now one of the core products in
|
||||
Spotify’s developer experience offering with 2,400+ documentation sites and
|
||||
1,000+ engineers using it daily.
|
||||
TechDocs is Spotify’s homegrown docs-like-code solution built directly into
|
||||
Backstage. This means engineers write their documentation in Markdown files
|
||||
which live together with their code.
|
||||
|
||||
Today, it is one of the core products in Spotify’s developer experience offering
|
||||
with 2,400+ documentation sites and 1,000+ engineers using it daily. Read more
|
||||
about TechDocs and the philosophy in its
|
||||
[announcement blog post](https://backstage.io/blog/2020/09/08/announcing-tech-docs).
|
||||
🎉
|
||||
|
||||
## Features
|
||||
|
||||
- A centralized place to discover documentation.
|
||||
- A centralized place to discover and read documentation.
|
||||
|
||||
- A clear end-to-end docs-like-code solution. (_Coming soon in V.1_)
|
||||
- A clear end-to-end docs-like-code solution.
|
||||
|
||||
- A tightly coupled feedback loop with the developer workflow. (_Coming soon in
|
||||
V.3_)
|
||||
@@ -26,12 +33,12 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
|
||||
|
||||
## Project roadmap
|
||||
|
||||
| Version | Description |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [TechDocs V.0 ✅][v0] | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. [See V.0 Use Cases.](./#techdocs-v0) |
|
||||
| [TechDocs V.1 🚧][v1] | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. [See V.1 Use Cases.](./#techdocs-v1) |
|
||||
| [TechDocs V.2 🔮⌛][v2] | Platform stability and compatibility improvements. [See V.2 Use Cases.](./#techdocs-v2) |
|
||||
| TechDocs V.3 🔮⌛ | Widget Architecture - TechDocs widget architecture available, so the community can create their own customized features. |
|
||||
| Version | Description |
|
||||
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [TechDocs V.0 ✅][v0] | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. [See V.0 Use Cases.](#techdocs-v0) |
|
||||
| [TechDocs V.1 ✅][v1] | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. [See V.1 Use Cases.](#techdocs-v1) |
|
||||
| [TechDocs V.2 🔮⌛][v2] | Platform stability and compatibility improvements. [See V.2 Use Cases.](#techdocs-v2) |
|
||||
| TechDocs V.3 🔮⌛ | Widget Architecture - TechDocs widget architecture available, so the community can create their own customized features. |
|
||||
|
||||
[v0]: https://github.com/spotify/backstage/milestone/15
|
||||
[v1]: https://github.com/spotify/backstage/milestone/16
|
||||
@@ -44,7 +51,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
|
||||
#### TechDocs V.0
|
||||
|
||||
- As a user I can navigate to a manually curated docs explore page.
|
||||
- As a user I can navigte to and read mock documentation that is manually
|
||||
- As a user I can navigate to and read mock documentation that is manually
|
||||
uploaded by the TechDocs core team.
|
||||
|
||||
#### TechDocs V.1
|
||||
@@ -101,7 +108,3 @@ more to come...
|
||||
https://github.com/spotify/backstage/blob/master/packages/techdocs-container
|
||||
[techdocs/cli]:
|
||||
https://github.com/spotify/backstage/blob/master/packages/techdocs-cli
|
||||
|
||||
## TechDocs Big Picture
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
id: architecture
|
||||
title: Architecture
|
||||
description: Documentation on Architecture
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
id: concepts
|
||||
title: Concepts
|
||||
description: Documentation on concepts that are introduced with
|
||||
Spotify's docs-like-code solution in Backstage
|
||||
---
|
||||
|
||||
This page describes concepts that are introduced with Spotify's docs-like-code
|
||||
@@ -8,9 +10,9 @@ solution in Backstage.
|
||||
|
||||
### TechDocs Core Plugin
|
||||
|
||||
The TechDocs Core Plugin is a MkDocs plugin created as a wrapper around multiple
|
||||
MkDocs plugins and Python Markdown extensions to standardize the configuration
|
||||
of MkDocs used for TechDocs.
|
||||
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 Core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md)
|
||||
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
id: creating-and-publishing
|
||||
title: Creating and publishing your docs
|
||||
sidebar_label: Creating and Publishing Documentation
|
||||
description: Guidance on how to create and publish documentation
|
||||
---
|
||||
|
||||
This section will guide you through:
|
||||
@@ -11,7 +12,7 @@ This section will guide you through:
|
||||
- [Manually add documentation setup to already existing repository](#manually-add-documentation-setup-to-already-existing-repository)
|
||||
- [Writing and previewing your documentation](#writing-and-previewing-your-documentation)
|
||||
|
||||
## Prerequisities
|
||||
## Prerequisites
|
||||
|
||||
- A working Backstage instance with TechDocs installed (see
|
||||
[TechDocs getting started](getting-started.md))
|
||||
@@ -30,11 +31,6 @@ the documentation template.
|
||||
Create an entity from the documentation template and you will get the needed
|
||||
setup for free.
|
||||
|
||||
!!! warning Currently the Backstage Software Templates are limited to create
|
||||
repositories inside GitHub organizations. You also need to generate an personal
|
||||
access token and use as an environment variable. Read more about this
|
||||
[here](../software-templates/installation.md#runtime-dependencies).
|
||||
|
||||
### Manually add documentation setup to already existing repository
|
||||
|
||||
Prerequisities:
|
||||
@@ -81,12 +77,12 @@ updated documentation next time you run Backstage!
|
||||
## Writing and previewing your documentation
|
||||
|
||||
Using the `techdocs-cli` you can preview your docs inside a local Backstage
|
||||
instance and get automatic recompilation on changes. This is useful for when you
|
||||
want to write your documentation.
|
||||
instance and get live reload on changes. This is useful when you want to preview
|
||||
your documentation while writing.
|
||||
|
||||
To do this you can run:
|
||||
|
||||
```bash
|
||||
cd ~/<repository-path>/
|
||||
cd /path/to/docs-repository/
|
||||
npx @techdocs/cli serve
|
||||
```
|
||||
|
||||
@@ -1,40 +1,14 @@
|
||||
---
|
||||
id: getting-started
|
||||
title: Getting Started
|
||||
description: Getting Started Guidelines
|
||||
---
|
||||
|
||||
TechDocs functions as a plugin to Backstage, so you will need to use Backstage
|
||||
to use TechDocs.
|
||||
|
||||
## What is Backstage?
|
||||
|
||||
Backstage is an open platform for building developer portals. It’s based on the
|
||||
developer portal we’ve been using internally at Spotify for over four years.
|
||||
[Read more here](https://github.com/spotify/backstage).
|
||||
|
||||
## Prerequisities
|
||||
|
||||
In order to use Backstage and TechDocs, you need to have the following
|
||||
installed:
|
||||
|
||||
- [Node.js](https://nodejs.org) Active LTS (long term support), currently v12
|
||||
- [Yarn](https://yarnpkg.com/getting-started/install)
|
||||
|
||||
## Creating a new Backstage app
|
||||
|
||||
> If you have already created a Backstage application, jump to
|
||||
> [Installing TechDocs](#installing-techdocs), otherwise complete this step.
|
||||
|
||||
To create a new Backstage application for TechDocs, run the following command:
|
||||
|
||||
```bash
|
||||
npx @backstage/create-app
|
||||
```
|
||||
|
||||
You will then be prompted to enter a name for your application. Once that's
|
||||
done, a new Backstage application will be created in a new folder. For example,
|
||||
if you choose the name `hello-world`, a new `hello-world` folder is created
|
||||
containing your new Backstage application.
|
||||
If you haven't setup Backstage already, start
|
||||
[here](../../getting-started/index.md).
|
||||
|
||||
## Installing TechDocs
|
||||
|
||||
@@ -74,7 +48,7 @@ export { plugin as TechDocs } from '@backstage/plugin-techdocs';
|
||||
### Setting the configuration
|
||||
|
||||
TechDocs allows for configuration of the docs storage URL through your
|
||||
`app-config` file. We provide two different values to be configured,
|
||||
`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.
|
||||
@@ -87,16 +61,40 @@ techdocs:
|
||||
requestUrl: http://localhost:7000/techdocs/docs
|
||||
```
|
||||
|
||||
If you want `techdocs-backend` to manage building and publishing you want
|
||||
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.
|
||||
|
||||
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
|
||||
building and publishing of your documentation, you want to change the
|
||||
`requestUrl` to point to your storage. In this case `storageUrl` is not
|
||||
required.
|
||||
|
||||
### Disable Docker in Docker situation (Optional)
|
||||
|
||||
The TechDocs backend plugin runs a docker container with mkdocs 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.
|
||||
|
||||
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
|
||||
`local` mkdocs or run it from `docker`. This defaults to running as `docker` if
|
||||
no config is provided.
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
generators:
|
||||
techdocs: local
|
||||
```
|
||||
|
||||
Setting `generators.techdocs` to `local` means you will have to make sure your
|
||||
environment is compatible with techdocs. You will have to install the
|
||||
`mkdocs-techdocs-container` and 'mkdocs' package from pip, as well as graphviz
|
||||
and plantuml from your package manager. This has only been tested with python
|
||||
3.7 and python 3.8.
|
||||
|
||||
## Run Backstage locally
|
||||
|
||||
Change folder to `<backstage-project-root>/packages/backend` and run the
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: app-custom-theme
|
||||
title: Customize the look-and-feel of your App
|
||||
description: Documentation on Customizing look and feel of the App
|
||||
---
|
||||
|
||||
Backstage ships with a default theme with a light and dark mode variant. The
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: configure-app-with-plugins
|
||||
title: Configuring App with plugins
|
||||
description: Documentation on How Configuring App with plugins
|
||||
---
|
||||
|
||||
## Adding existing plugins to your app
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: create-an-app
|
||||
title: Create an App
|
||||
description: Documentation on Creating an App
|
||||
---
|
||||
|
||||
To get set up quickly with your own Backstage project you can create a Backstage
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: deployment-k8s
|
||||
title: Kubernetes
|
||||
description: Documentation on Kubernetes and K8s Deployment
|
||||
---
|
||||
|
||||
Coming soon!
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: deployment-other
|
||||
title: Other
|
||||
description: Documentation on different ways of Deployment
|
||||
---
|
||||
|
||||
## Deploying Locally
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
id: development-environment
|
||||
title: Development Environment
|
||||
description: Documentation on how to get set up for doing development on
|
||||
the Backstage repository
|
||||
---
|
||||
|
||||
This section describes how to get set up for doing development on the Backstage
|
||||
|
||||
@@ -1,84 +1,51 @@
|
||||
---
|
||||
id: index
|
||||
title: Running Backstage Locally
|
||||
title: Getting Started
|
||||
description: Documentation on How to get started with Backstage
|
||||
---
|
||||
|
||||
First make sure you are using NodeJS with an Active LTS Release, currently v12.
|
||||
This is made easy with a version manager such as nvm which allows for version
|
||||
switching.
|
||||
There are two different ways to get started with Backstage, either by creating a
|
||||
standalone app, or by cloning this repo. Which method you use depends on what
|
||||
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
|
||||
recommended approach if you want to kick the tyres of Backstage or setup your
|
||||
own instance.
|
||||
|
||||
On the other hand, if you want to contribute plugins or to the project in
|
||||
general, it's easier to fork and clone this project. That will let you stay up
|
||||
to date with the latest changes, and gives you an easier path to make Pull
|
||||
Requests towards this repo.
|
||||
|
||||
### Creating a Standalone App
|
||||
|
||||
Backstage provides the `@backstage/create-app` package to scaffold standalone
|
||||
instances of Backstage. You will need to have
|
||||
[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
|
||||
(currently v12), and [yarn](https://classic.yarnpkg.com/en/docs/install). You
|
||||
will also need to have [Docker](https://docs.docker.com/engine/install/)
|
||||
installed to use some features like Software Templates and TechDocs.
|
||||
|
||||
Using `npx` you can then run the following to create an app in a chosen
|
||||
subdirectory of your current working directory:
|
||||
|
||||
```bash
|
||||
# Checking your version
|
||||
node --version
|
||||
> v14.7.0
|
||||
|
||||
# Adding a second node version
|
||||
nvm install 12
|
||||
> Downloading and installing node v12.18.3...
|
||||
> Now using node v12.18.3 (npm v6.14.6)
|
||||
npx @backstage/create-app
|
||||
```
|
||||
|
||||
To get up and running with a local Backstage to evaluate it, let's clone it off
|
||||
of GitHub and run an initial build.
|
||||
You will be taken through a wizard to create your app, and the output should
|
||||
look something like this. You can read more about this process
|
||||
[here](https://backstage.io/docs/getting-started/create-an-app).
|
||||
|
||||
```bash
|
||||
# Start from your local development folder
|
||||
git clone git@github.com:spotify/backstage.git
|
||||
cd backstage
|
||||
### Contributing to Backstage
|
||||
|
||||
# Fetch our dependencies and run an initial build
|
||||
yarn install
|
||||
yarn tsc
|
||||
yarn build
|
||||
```
|
||||
You can read more in our
|
||||
[CONTRIBUTING](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)
|
||||
guide, which can help you get setup with a Backstage development environment.
|
||||
|
||||
Phew! Now you have a local repository that's ready to run and to add any open
|
||||
source contributions into.
|
||||
### Next steps
|
||||
|
||||
We are now going to launch two things: an example Backstage frontend app, and an
|
||||
example Backstage backend that the frontend talks to. You are going to need two
|
||||
terminal windows, both starting from the Backstage project root.
|
||||
|
||||
In the first window, run
|
||||
|
||||
```bash
|
||||
cd packages/backend
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up a backend instance on port 7000.
|
||||
|
||||
In the other window, we will first populate the catalog with some nice mock data
|
||||
to look at, and then launch the frontend. These commands are run from the
|
||||
project root, not inside the backend directory.
|
||||
|
||||
```bash
|
||||
yarn lerna run mock-data
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up the frontend on port 3000, and should automatically open a
|
||||
browser window showing it.
|
||||
|
||||
Congratulations! That should be it. Let us know how it went
|
||||
[on discord](https://discord.gg/EBHEGzX), file issues for any
|
||||
[feature](https://github.com/spotify/backstage/issues/new?labels=help+wanted&template=feature_template.md)
|
||||
or
|
||||
[plugin suggestions](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME),
|
||||
or
|
||||
[bugs](https://github.com/spotify/backstage/issues/new?labels=bug&template=bug_template.md)
|
||||
you have, and feel free to
|
||||
[contribute](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)!
|
||||
|
||||
## Creating a Plugin
|
||||
|
||||
The value of Backstage grows with every new plugin that gets added. Here is a
|
||||
collection of tutorials that will guide you through setting up and extending an
|
||||
instance of Backstage with your own plugins.
|
||||
|
||||
- [Development Environment](development-environment.md)
|
||||
- [Create a Backstage Plugin](../plugins/create-a-plugin.md)
|
||||
- [Structure of a Plugin](../plugins/structure-of-a-plugin.md)
|
||||
- [Utility APIs](../api/utility-apis.md)
|
||||
|
||||
[Back to Docs](../README.md)
|
||||
Take a look at the [Running Backstage Locally](./running-backstage-locally.md)
|
||||
guide to learn how to set up Backstage, and how to develop on the platform.
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: installation
|
||||
title: Installation
|
||||
description: Documentation on Installation
|
||||
---
|
||||
|
||||
Coming soon!
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
id: running-backstage-locally
|
||||
title: Running Backstage Locally
|
||||
description: Documentation on How to run Backstage Locally
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js
|
||||
|
||||
First make sure you are using NodeJS with an Active LTS Release, currently v12.
|
||||
This is made easy with a version manager such as
|
||||
[nvm](https://github.com/nvm-sh/nvm) which allows for version switching.
|
||||
|
||||
```bash
|
||||
# Installing a new version
|
||||
nvm install 12
|
||||
> Downloading and installing node v12.18.3...
|
||||
> Now using node v12.18.3 (npm v6.14.6)
|
||||
|
||||
# Checking your version
|
||||
node --version
|
||||
> v12.18.3
|
||||
```
|
||||
|
||||
- yarn
|
||||
|
||||
Please refer to the
|
||||
[installation instructions for yarn](https://classic.yarnpkg.com/en/docs/install/).
|
||||
|
||||
- Docker
|
||||
|
||||
We use Docker for few of our core features. So, you will need Docker installed
|
||||
locally to use features like Software Templates and TechDocs. Please refer to
|
||||
the
|
||||
[installation instructions for Docker](https://docs.docker.com/engine/install/).
|
||||
|
||||
## Clone and Build
|
||||
|
||||
To get up and running with a local Backstage to evaluate it, let's clone it off
|
||||
of GitHub and run an initial build.
|
||||
|
||||
```bash
|
||||
# Start from your local development folder
|
||||
git clone git@github.com:spotify/backstage.git
|
||||
cd backstage
|
||||
|
||||
# Fetch our dependencies and run an initial build
|
||||
yarn install
|
||||
yarn tsc
|
||||
yarn build
|
||||
```
|
||||
|
||||
Phew! Now you have a local repository that's ready to run and to add any open
|
||||
source contributions into.
|
||||
|
||||
We are now going to launch two things: an example Backstage frontend app, and an
|
||||
example Backstage backend that the frontend talks to. You are going to need two
|
||||
terminal windows, both starting from the Backstage project root.
|
||||
|
||||
In the first window, run
|
||||
|
||||
```bash
|
||||
cd packages/backend
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up a backend instance on port 7000.
|
||||
|
||||
In the other window, we will then launch the frontend. This command is run from
|
||||
the project root, not inside the backend directory.
|
||||
|
||||
```bash
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up the frontend on port 3000, and should automatically open a
|
||||
browser window showing it.
|
||||
|
||||
## Authentication
|
||||
|
||||
When Backstage starts, you can choose to enter as a Guest user and start
|
||||
exploring.
|
||||
|
||||
But you can also set up any of the available authentication methods. The easiest
|
||||
option will be GitHub. To setup GitHub authentication in Backstage, see
|
||||
[these instructions](https://github.com/spotify/backstage/tree/master/plugins/auth-backend#github).
|
||||
|
||||
---
|
||||
|
||||
Congratulations! That should be it. Let us know how it went
|
||||
[on discord](https://discord.gg/EBHEGzX), file issues for any
|
||||
[feature](https://github.com/spotify/backstage/issues/new?labels=help+wanted&template=feature_template.md)
|
||||
or
|
||||
[plugin suggestions](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME),
|
||||
or
|
||||
[bugs](https://github.com/spotify/backstage/issues/new?labels=bug&template=bug_template.md)
|
||||
you have, and feel free to
|
||||
[contribute](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)!
|
||||
|
||||
## Creating a Plugin
|
||||
|
||||
The value of Backstage grows with every new plugin that gets added. Here is a
|
||||
collection of tutorials that will guide you through setting up and extending an
|
||||
instance of Backstage with your own plugins.
|
||||
|
||||
- [Development Environment](development-environment.md)
|
||||
- [Create a Backstage Plugin](../plugins/create-a-plugin.md)
|
||||
- [Structure of a Plugin](../plugins/structure-of-a-plugin.md)
|
||||
- [Utility APIs](../api/utility-apis.md)
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
id: adopting
|
||||
title: Strategies for adopting
|
||||
description: Documentation on some general best practices that have been key
|
||||
to Backstage's success inside Spotify
|
||||
---
|
||||
|
||||
This document outlines some general best practices that have been key to
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: architecture-overview
|
||||
title: Architecture overview
|
||||
description: Documentation on Architecture overview
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: architecture-terminology
|
||||
title: Architecture terminology
|
||||
description: Documentation on Architecture terminology
|
||||
---
|
||||
|
||||
Backstage is constructed out of three parts. We separate Backstage in this way
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: background
|
||||
title: The Spotify Story
|
||||
description: Documentation on Background and Story behind making of Backstage
|
||||
---
|
||||
|
||||
Backstage was born out of necessity at Spotify. We found that as we grew, our
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
id: logos
|
||||
title: Logos
|
||||
sidebar_label: Logo assets
|
||||
description: Guidelines for how to use the Backstage logos and icons
|
||||
---
|
||||
|
||||
Guidelines for how to use the Backstage logo and icon can be found
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: roadmap
|
||||
title: Project roadmap
|
||||
description: Roadmap of Backstage Project
|
||||
---
|
||||
|
||||
## Current status
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: support
|
||||
title: Support and community
|
||||
description: Support and Community Details and Links
|
||||
---
|
||||
|
||||
- [Discord chatroom](https://discord.gg/MUpMjP2) - Get support or discuss the
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
id: vision
|
||||
title: Vision
|
||||
description: Goal is to provide engineers with the best developer experience in
|
||||
the world
|
||||
---
|
||||
|
||||
Our goal is to provide engineers with the best developer experience in the
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
id: what-is-backstage
|
||||
title: What is Backstage?
|
||||
description: Backsatge is an open platform for building developer portals.
|
||||
Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure
|
||||
---
|
||||
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: add-to-marketplace
|
||||
title: Add to Marketplace
|
||||
description: Documentation on Adding Plugin to Marketplace
|
||||
---
|
||||
|
||||
## Adding a Plugin to the Marketplace
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: backend-plugin
|
||||
title: Backend plugin
|
||||
description: Documentation on Backend plugin
|
||||
---
|
||||
|
||||
## TODO
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
id: call-existing-api
|
||||
title: Call Existing API
|
||||
description: Describes the various options that Backstage frontend plugins have,
|
||||
in communicating with service APIs that already exist
|
||||
---
|
||||
|
||||
This article describes the various options that Backstage frontend plugins have,
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user