Merge pull request #3087 from adamdmharvey/doc-clarifications
Clarifications in documentation
This commit is contained in:
Ben Lambert
@@ -12,7 +12,7 @@ This both applies to objects given to and returned from the software catalog
|
||||
API, as well as to the descriptor files that the software catalog can ingest
|
||||
natively. In the API request/response cycle, a JSON representation is used,
|
||||
while the descriptor files are on YAML format to be more easily maintainable by
|
||||
humans. However, the structure and semantics is the same in both cases.
|
||||
humans. However, the structure and semantics are the same in both cases.
|
||||
|
||||
Although it's possible to name catalog entity descriptor files however you wish,
|
||||
we recommend that you name them `catalog-info.yaml`.
|
||||
@@ -113,7 +113,7 @@ data.
|
||||
Backstage specific entities have an `apiVersion` that is prefixed with
|
||||
`backstage.io/`, to distinguish them from other types of object that share the
|
||||
same type of structure. This may be relevant when co-hosting these
|
||||
specifications with e.g. kubernetes object manifests, or when an organization
|
||||
specifications with e.g. Kubernetes object manifests, or when an organization
|
||||
adds their own specific kinds of entity to the catalog.
|
||||
|
||||
Early versions of the catalog will be using alpha/beta versions, e.g.
|
||||
|
||||
@@ -13,7 +13,7 @@ need to run Backstage in your own environment.
|
||||
## Create an app
|
||||
|
||||
To create a Backstage app, you will need to have
|
||||
[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
|
||||
[Node.js](https://nodejs.org/en/download/) Active LTS Release installed
|
||||
(currently v12).
|
||||
|
||||
Backstage provides a utility for creating new apps. It guides you through the
|
||||
|
||||
@@ -8,10 +8,10 @@ sidebar_label: Kubernetes and Helm
|
||||
# Helm charts
|
||||
|
||||
An example Backstage app can be deployed in Kubernetes using the
|
||||
[Backstage Helm charts](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage)
|
||||
[Backstage Helm charts](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage).
|
||||
|
||||
First, choose a DNS name where backstage will be hosted create a yaml file for
|
||||
your custom configuration.
|
||||
First, choose a DNS name where Backstage will be hosted, and create a YAML file
|
||||
for your custom configuration.
|
||||
|
||||
```yaml
|
||||
appConfig:
|
||||
@@ -31,7 +31,7 @@ appConfig:
|
||||
|
||||
Then use it to run:
|
||||
|
||||
```
|
||||
```bash
|
||||
git clone https://github.com/spotify/backstage.git
|
||||
cd contrib/chart/backstage
|
||||
helm dependency update
|
||||
|
||||
@@ -4,7 +4,7 @@ title: Kubernetes
|
||||
description: Documentation on Kubernetes and K8s Deployment
|
||||
---
|
||||
|
||||
Backstage itself provides tooling up to the point of building docker images.
|
||||
Backstage itself provides tooling up to the point of building Docker images.
|
||||
Beyond that point we do not have an opinionated way to deploy Backstage within
|
||||
Kubernetes, as each cluster has its own unique set of tooling and patterns.
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Then open http://localhost/ on your browser.
|
||||
Deploying to Heroku is relatively easy following these steps.
|
||||
|
||||
First, make sure you have the
|
||||
[heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log
|
||||
[Heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log
|
||||
into it as well as login into Heroku's
|
||||
[container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime).
|
||||
|
||||
@@ -32,7 +32,7 @@ $ heroku login
|
||||
$ heroku container:login
|
||||
```
|
||||
|
||||
You _might_ also need to set your Heroku app's stack to `container`
|
||||
You _might_ also need to set your Heroku app's stack to `container`.
|
||||
|
||||
```bash
|
||||
$ heroku stack:set container -a <your-app>
|
||||
|
||||
@@ -24,7 +24,7 @@ different ways.
|
||||
## Overview
|
||||
|
||||
The following diagram shows how Backstage might look when deployed inside a
|
||||
company which uses the Tech Radar plugin, the Lighthouse plugin, the Circle CI
|
||||
company which uses the Tech Radar plugin, the Lighthouse plugin, the CircleCI
|
||||
plugin and the service catalog.
|
||||
|
||||
There are 3 main components in this architecture:
|
||||
@@ -53,9 +53,9 @@ example, the Lighthouse plugin is registered with the UI on `/lighthouse`.
|
||||
|
||||
|
||||
|
||||
The Circle CI plugin is available on `/circleci`.
|
||||
The CircleCI plugin is available on `/circleci`.
|
||||
|
||||
|
||||
|
||||
|
||||
## Plugins and plugin backends
|
||||
|
||||
@@ -154,29 +154,28 @@ Cross Origin Resource Sharing policies which prevent a browser page served at
|
||||
[https://example.com](https://example.com) from serving resources hosted at
|
||||
https://circleci.com.
|
||||
|
||||
|
||||
|
||||
|
||||
## Databases
|
||||
|
||||
As we have seen, both the lighthouse-audit-service and catalog-backend require a
|
||||
database to work with.
|
||||
As we have seen, both the `lighthouse-audit-service` and `catalog-backend`
|
||||
require a database to work with.
|
||||
|
||||
At the time of writing, the lighthouse-audit-service requires PostgreSQL to work
|
||||
with. The service catalog backend uses an in-memory Sqlite3 instance. This is a
|
||||
development oriented setup and there are plans to support other databases in the
|
||||
future.
|
||||
At the time of writing, the `lighthouse-audit-service` requires PostgreSQL to
|
||||
work with. The service catalog backend uses an in-memory Sqlite3 instance. This
|
||||
is a development-oriented setup and there are plans to support other databases
|
||||
in the future.
|
||||
|
||||
To learn more about the future of databases and Backstage, see the following two
|
||||
To learn more about the future of databases and Backstage, see the following
|
||||
GitHub issues.
|
||||
|
||||
[Knex + Plugins (Multiple vs Single Database) · Issue #1598 · spotify/backstage](https://github.com/spotify/backstage/issues/1598)
|
||||
|
||||
[Update migrations to support postgres by dariddler · Pull Request #1527 · spotify/backstage](https://github.com/spotify/backstage/pull/1527#discussion_r450374145)
|
||||
- [Knex + Plugins (Multiple vs Single Database) · Issue #1598 · spotify/backstage](https://github.com/spotify/backstage/issues/1598)
|
||||
- [Update migrations to support postgres by dariddler · Pull Request #1527 · spotify/backstage](https://github.com/spotify/backstage/pull/1527#discussion_r450374145)
|
||||
|
||||
## Containerization
|
||||
|
||||
The example Backstage architecture shown above would Dockerize into three
|
||||
separate docker images.
|
||||
separate Docker images.
|
||||
|
||||
1. The frontend container
|
||||
2. The backend container
|
||||
|
||||
@@ -88,7 +88,7 @@ The proxy is powered by the `http-proxy-middleware` package. See
|
||||
[Proxying](proxying.md) for a full description of its configuration options.
|
||||
|
||||
Internally at Spotify, the proxy option has been the overwhelmingly most popular
|
||||
choice for plugin makers. Since we have DNS based service discovery in place and
|
||||
choice for plugin makers. Since we have DNS-based service discovery in place and
|
||||
a microservices framework that made it trivial to expose plain HTTP, it has been
|
||||
a matter of just adding a few lines of Backstage config to get the benefit of
|
||||
being easily and robustly reachable from users' web browsers as well.
|
||||
|
||||
@@ -248,15 +248,15 @@ Testing an API involves verifying four things:
|
||||
|
||||
### Mocking API Calls
|
||||
|
||||
[Mocking in jest](https://facebook.github.io/jest/docs/en/mock-functions.html)
|
||||
[Mocking in Jest](https://facebook.github.io/jest/docs/en/mock-functions.html)
|
||||
involves wrapping existing functions (like an API call function) with an
|
||||
alternative.
|
||||
|
||||
For example:
|
||||
|
||||
**./Api.js**
|
||||
**`./MyApi.js`**
|
||||
|
||||
```
|
||||
```js
|
||||
export {
|
||||
fetchSomethingFromServer: () => {
|
||||
// Live production call to a URI. Must be avoided during testing!
|
||||
@@ -265,9 +265,9 @@ export {
|
||||
};
|
||||
```
|
||||
|
||||
**./\_\_mocks\_\_/Api.js**
|
||||
**`./\_\_mocks\_\_/MyApi.js`**
|
||||
|
||||
```
|
||||
```js
|
||||
export {
|
||||
fetchSomethingFromServer: () => {
|
||||
// Simulate a production call, but avoid jest and just use a promise
|
||||
@@ -276,16 +276,16 @@ export {
|
||||
}
|
||||
```
|
||||
|
||||
**./Api.test.js**
|
||||
**`./MyApi.test.js`**
|
||||
|
||||
```
|
||||
```js
|
||||
/* eslint-disable import/first */
|
||||
|
||||
jest.mock('./MyApi'); // Instruct Jest to swap all future imports of './MyApi.js' to './__mocks__/MyApi.js'
|
||||
|
||||
import MyApi from './MyApi'; // Will actually return the contents of the file in the __mocks__ folder now
|
||||
|
||||
it ('loads data', (done) => {
|
||||
it('loads data', done => {
|
||||
MyApi.fetchSomethingFromServer().then(result => {
|
||||
expect(result).toBe('some result object simulating server data here');
|
||||
done();
|
||||
|
||||
@@ -41,10 +41,10 @@ the code.
|
||||
appreciate contributions in here and encourage them being kept up to date.
|
||||
|
||||
- [`docs/`](https://github.com/spotify/backstage/tree/master/docs) - This is
|
||||
where we keep all of our documentation markdown files. These ends up on
|
||||
http://backstage.io/docs. Just keep in mind that changes to
|
||||
[this](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json)
|
||||
file also needs to be updated.
|
||||
where we keep all of our documentation Markdown files. These ends up on
|
||||
http://backstage.io/docs. Just keep in mind that changes to the
|
||||
[`sidebars.json`](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json)
|
||||
file may be needed as sections are added/removed.
|
||||
|
||||
- [`.editorconfig`](https://github.com/spotify/backstage/tree/master/.editorconfig) -
|
||||
A configuration file used by most common code editors.
|
||||
@@ -111,13 +111,13 @@ are separated out into their own folder, see further down.
|
||||
We also want as few dependencies as possible to reduce download time when
|
||||
running the cli which is another reason this is a separate package.
|
||||
|
||||
* [`config/`](https://github.com/spotify/backstage/tree/master/packages/config) -
|
||||
- [`config/`](https://github.com/spotify/backstage/tree/master/packages/config) -
|
||||
The way we read configuration data. This package can take a bunch of config
|
||||
objects and merge them together.
|
||||
[app-config.yaml](https://github.com/spotify/backstage/blob/master/app-config.yaml)
|
||||
is an example of an config object.
|
||||
|
||||
* [`config-loader/`](https://github.com/spotify/backstage/tree/master/packages/config-loader) -
|
||||
- [`config-loader/`](https://github.com/spotify/backstage/tree/master/packages/config-loader) -
|
||||
This package is used to read config objects. It does not know how to merge,
|
||||
but only reads files and passes them on to the config. As this part is only
|
||||
used by the backend, we chose to separate `config` and `config-loader` into
|
||||
@@ -130,21 +130,21 @@ are separated out into their own folder, see further down.
|
||||
Apart from that it re-exports everything from [`core-api`] so that users only
|
||||
need to rely on one package.
|
||||
|
||||
* [`core-api/`](https://github.com/spotify/backstage/tree/master/packages/core-api) -
|
||||
- [`core-api/`](https://github.com/spotify/backstage/tree/master/packages/core-api) -
|
||||
This package contains APIs and definitions of such. It is it's own package
|
||||
because we needed to split our `test-utils` package. It's an implementation
|
||||
detail that we try to hide from our users, and no one should have to depend on
|
||||
it directly.
|
||||
|
||||
* [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) -
|
||||
- [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) -
|
||||
This package contains specific testing facilities used when testing
|
||||
`core-api`.
|
||||
|
||||
* [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) -
|
||||
- [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) -
|
||||
This package contains more general purpose testing facilities for testing a
|
||||
Backstage App.
|
||||
|
||||
* [`create-app/`](https://github.com/spotify/backstage/tree/master/packages/create-app) -
|
||||
- [`create-app/`](https://github.com/spotify/backstage/tree/master/packages/create-app) -
|
||||
An CLI to specifically scaffold a new Backstage App. It does so by using a
|
||||
[template](https://github.com/spotify/backstage/tree/master/packages/create-app/templates/default-app).
|
||||
|
||||
@@ -152,32 +152,32 @@ are separated out into their own folder, see further down.
|
||||
Helps you setup a plugin for isolated development so that it can be served
|
||||
separately.
|
||||
|
||||
* [`docgen/`](https://github.com/spotify/backstage/tree/master/packages/docgen) -
|
||||
- [`docgen/`](https://github.com/spotify/backstage/tree/master/packages/docgen) -
|
||||
Uses the
|
||||
[Typescript Compiler API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API)
|
||||
to read out definitions and generate documentation for it.
|
||||
|
||||
* [`e2e-test/`](https://github.com/spotify/backstage/tree/master/packages/e2e-test) -
|
||||
- [`e2e-test/`](https://github.com/spotify/backstage/tree/master/packages/e2e-test) -
|
||||
Another CLI that can be run to try out what would happen if you built all the
|
||||
packages, publish them, created a new app, and the run it. CI uses this for
|
||||
e2e-tests.
|
||||
|
||||
* [`storybook/`](https://github.com/spotify/backstage/tree/master/packages/storybook) -
|
||||
- [`storybook/`](https://github.com/spotify/backstage/tree/master/packages/storybook) -
|
||||
This folder contains only the storybook config. Stories are within the core
|
||||
package. The Backstage Storybook is found
|
||||
[here](https://backstage.io/storybook)
|
||||
|
||||
* [`techdocs-cli/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) -
|
||||
- [`techdocs-cli/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) -
|
||||
Used for verifying TechDocs locally.
|
||||
|
||||
* [`techdocs-container/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-container) -
|
||||
- [`techdocs-container/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-container) -
|
||||
Used by the `techdocs-cli`
|
||||
|
||||
* [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core)
|
||||
- [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core)
|
||||
|
||||
* [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils)
|
||||
- [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils)
|
||||
|
||||
* [`theme/`](https://github.com/spotify/backstage/tree/master/packages/theme) -
|
||||
- [`theme/`](https://github.com/spotify/backstage/tree/master/packages/theme) -
|
||||
Holds the Backstage Theme.
|
||||
|
||||
### `plugins/`
|
||||
|
||||
@@ -239,12 +239,12 @@ hits merge.
|
||||
# 8. Attack of the Clones
|
||||
|
||||
Sam just released v1.8.4 of the plugin, and at this point it's so popular that a
|
||||
couple of other plugins has started depending on the `sam.wise/spotify-track-id`
|
||||
annotation. One such plugin being the `spotify-album-art` plugin that can
|
||||
display the album art of the theme tune as the background of the entity header.
|
||||
Sam thinks it's all pretty cool, but doesn't like that the annotation that was
|
||||
once an internal concern of the plugin is now becoming a standard in the
|
||||
community.
|
||||
couple of other plugins have started depending on the
|
||||
`sam.wise/spotify-track-id` annotation. One such plugin being the
|
||||
`spotify-album-art` plugin that can display the album art of the theme tune as
|
||||
the background of the entity header. Sam thinks it's all pretty cool, but
|
||||
doesn't like that the annotation that was once an internal concern of the plugin
|
||||
is now becoming a standard in the community.
|
||||
|
||||
In order to standardize the annotation in Backstage, Sam submits a Pull Request
|
||||
to the Backstage Core repo. The request suggests a new well-known metadata
|
||||
|
||||
@@ -7,7 +7,7 @@ title: Monorepo App Setup With Authentication
|
||||
|
||||
<br />
|
||||
|
||||
> This document takes you through setting up a backstage app that runs in your
|
||||
> This document takes you through setting up a Backstage app that runs in your
|
||||
> own environment. It starts with a skeleton install and verifying of the
|
||||
> monorepo's functionality. Next, GitHub authentication is added and tested.
|
||||
>
|
||||
|
||||
Reference in New Issue
Block a user