Merge branch 'master' of github.com:spotify/backstage into shmidt-i/app-catalog-tabs-routes-everything-is-connected
This commit is contained in:
Ivan Shmidt
+2
-2
@@ -3,7 +3,7 @@ id: FAQ
|
||||
title: FAQ
|
||||
---
|
||||
|
||||
## Product FAQ:
|
||||
## Product FAQ
|
||||
|
||||
### Can we call Backstage something different? So that it fits our company better?
|
||||
|
||||
@@ -67,7 +67,7 @@ valuable as you grow.
|
||||
Yes! The Backstage UI is built using Material-UI. With the theming capabilities
|
||||
of Material-UI, you are able to adapt the interface to your brand guidelines.
|
||||
|
||||
## Technical FAQ:
|
||||
## Technical FAQ
|
||||
|
||||
### Why Material-UI?
|
||||
|
||||
|
||||
+2
-103
@@ -1,104 +1,3 @@
|
||||
# Documentation structure
|
||||
# Documentation
|
||||
|
||||
**Note!** This documentation structure is very much work in progress. If (when,
|
||||
really 😆) you find broken links or missing content, please create an issue or,
|
||||
better yet, a pull request.
|
||||
|
||||
# Plugins
|
||||
|
||||
- Overview
|
||||
- [What is Backstage?](overview/what-is-backstage.md)
|
||||
- [Backstage architecture](overview/architecture-overview.md)
|
||||
- [Architecture and terminology](overview/architecture-terminology.md)
|
||||
- [Roadmap](overview/roadmap.md)
|
||||
- [Vision](overview/vision.md)
|
||||
- Getting started
|
||||
- [Running Backstage locally](getting-started/index.md)
|
||||
- [Installation](getting-started/installation.md)
|
||||
- [Local development](getting-started/development-environment.md)
|
||||
- [Demo deployment](https://backstage-demo.roadie.io)
|
||||
- Production deployments
|
||||
- [Create an App](getting-started/create-an-app.md)
|
||||
- App configuration
|
||||
- [Configuring App with plugins](getting-started/configure-app-with-plugins.md)
|
||||
- [Customize the look-and-feel of your App](getting-started/app-custom-theme.md)
|
||||
- Deployment scenarios
|
||||
- [Kubernetes](getting-started/deployment-k8s.md)
|
||||
- [Other](getting-started/deployment-other.md)
|
||||
- Features
|
||||
- Software Catalog
|
||||
- [Overview](features/software-catalog/index.md)
|
||||
- [System model](features/software-catalog/system-model.md)
|
||||
- [YAML File Format](features/software-catalog/descriptor-format.md)
|
||||
- [Extending the model](features/software-catalog/extending-the-model.md)
|
||||
- [External integrations](features/software-catalog/external-integrations.md)
|
||||
- [API](features/software-catalog/api.md)
|
||||
- Software creation templates
|
||||
- [Overview](features/software-templates/index.md)
|
||||
- [Adding templates](features/software-templates/adding-templates.md)
|
||||
- Extending the Scaffolder:
|
||||
- [Overview](features/software-templates/extending/index.md)
|
||||
- [Create your own Templater](features/software-templates/extending/create-your-own-templater.md)
|
||||
- [Create your own Publisher](features/software-templates/extending/create-your-own-publisher.md)
|
||||
- [Create your own Preparer](features/software-templates/extending/create-your-own-preparer.md)
|
||||
- Docs-like-code
|
||||
- [Overview](features/techdocs/README.md)
|
||||
- [Getting Started](features/techdocs/getting-started.md)
|
||||
- [Concepts](features/techdocs/concepts.md)
|
||||
- [Creating and Publishing Documentation](features/techdocs/creating-and-publishing.md)
|
||||
- [FAQ](features/techdocs/FAQ.md)
|
||||
- Plugins
|
||||
- [Overview](plugins/index.md)
|
||||
- [Existing plugins](plugins/existing-plugins.md)
|
||||
- [Creating a new plugin](plugins/create-a-plugin.md)
|
||||
- [Developing a plugin](plugins/plugin-development.md)
|
||||
- [Structure of a plugin](plugins/structure-of-a-plugin.md)
|
||||
- Backends and APIs
|
||||
- [Proxying](plugins/proxying.md)
|
||||
- [Backstage backend plugin](plugins/backend-plugin.md)
|
||||
- [Call existing API](plugins/call-existing-api.md)
|
||||
- Testing
|
||||
- [Overview](plugins/testing.md)
|
||||
- Publishing
|
||||
- [Open source and NPM](plugins/publishing.md)
|
||||
- [Private/internal (non-open source)](plugins/publish-private.md)
|
||||
- Configuration
|
||||
- [Overview](conf/index.md)
|
||||
- [Reading Configuration](conf/reading.md)
|
||||
- [Writing Configuration](conf/writing.md)
|
||||
- [Defining Configuration](conf/defining.md)
|
||||
- Authentication and identity
|
||||
- [Overview](auth/index.md)
|
||||
- [Add auth provider](auth/add-auth-provider.md)
|
||||
- [Auth backend](auth/auth-backend.md)
|
||||
- [OAuth](auth/oauth.md)
|
||||
- [Glossary](auth/glossary.md)
|
||||
- Designing for Backstage
|
||||
- [Backstage Design Language System (DLS)](dls/design.md)
|
||||
- [Storybook -- reusable UI components](http://backstage.io/storybook)
|
||||
- [Contributing to Storybook](dls/contributing-to-storybook.md)
|
||||
- [Figma resources](dls/figma.md)
|
||||
- API references
|
||||
- TypeScript API
|
||||
- [Utility APIs](api/utility-apis.md)
|
||||
- [Utility API References](reference/utility-apis/README.md)
|
||||
- [createPlugin](reference/createPlugin.md)
|
||||
- [createPlugin-feature-flags](reference/createPlugin-feature-flags.md)
|
||||
- [createPlugin-router](reference/createPlugin-router.md)
|
||||
- Backend APIs
|
||||
- [Backend](api/backend.md)
|
||||
- Tutorials
|
||||
- [Overview](tutorials/index.md)
|
||||
- Architecture Decision Records (ADRs)
|
||||
- [Overview](architecture-decisions/index.md)
|
||||
- [ADR001 - Architecture Decision Record (ADR) log](architecture-decisions/adr001-add-adr-log.md)
|
||||
- [ADR002 - Default Software Catalog File Format](architecture-decisions/adr002-default-catalog-file-format.md)
|
||||
- [ADR003 - Avoid Default Exports and Prefer Named Exports](architecture-decisions/adr003-avoid-default-exports.md)
|
||||
- [ADR004 - Module Export Structure](architecture-decisions/adr004-module-export-structure.md)
|
||||
- [ADR005 - Catalog Core Entities](architecture-decisions/adr005-catalog-core-entities.md)
|
||||
- [ADR006 - Avoid React.FC and React.SFC](architecture-decisions/adr006-avoid-react-fc.md)
|
||||
- [ADR007 - Use MSW for Mocking Network Requests](architecture-decisions/adr007-use-msw-to-mock-service-requests.md)
|
||||
- [ADR008 - Default Catalog File Name](architecture-decisions/adr008-default-catalog-file-name.md)
|
||||
- [Contribute](../CONTRIBUTING.md)
|
||||
- [Support](overview/support.md)
|
||||
- [FAQ](FAQ.md)
|
||||
The Backstage documentation is available at https://backstage.io/docs
|
||||
|
||||
@@ -71,18 +71,23 @@ import {
|
||||
AlertApiForwarder,
|
||||
ErrorApiForwarder,
|
||||
ErrorAlerter,
|
||||
ConfigApi
|
||||
} from '@backstage/core';
|
||||
|
||||
const builder = ApiRegistry.builder();
|
||||
|
||||
// The alert API is a self-contained implementation that shows alerts to the user.
|
||||
const alertApi = builder.add(alertApiRef, new AlertApiForwarder());
|
||||
const apis = (config: ConfigApi) => {
|
||||
const builder = ApiRegistry.builder();
|
||||
|
||||
// The error API uses the alert API to send error notifications to the user.
|
||||
builder.add(errorApiRef, new ErrorAlerter(alertApi, new ErrorApiForwarder()));
|
||||
// The alert API is a self-contained implementation that shows alerts to the user.
|
||||
const alertApi = builder.add(alertApiRef, new AlertApiForwarder());
|
||||
|
||||
// The error API uses the alert API to send error notifications to the user.
|
||||
builder.add(errorApiRef, new ErrorAlerter(alertApi, new ErrorApiForwarder()));
|
||||
return builder.build();
|
||||
}
|
||||
|
||||
const app = createApp({
|
||||
apis: apiBuilder.build(),
|
||||
apis,
|
||||
// ... other config
|
||||
});
|
||||
```
|
||||
|
||||
@@ -4,8 +4,6 @@ title: Architecture Decision Records (ADR)
|
||||
sidebar_label: Overview
|
||||
---
|
||||
|
||||
#
|
||||
|
||||
The substantial architecture decisions made in the Backstage project lives here.
|
||||
For more information about ADRs, when to write them, and why, please see
|
||||
[this blog post](https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-architecture-decision-record/).
|
||||
@@ -25,7 +23,10 @@ Records should be stored under the `architecture-decisions` directory.
|
||||
- Submit a pull request
|
||||
- Address and integrate feedback from the community
|
||||
- Eventually, assign a number
|
||||
- Add the full path of the ADR to the [`mkdocs.yml`](/mkdocs.yml)
|
||||
- Add the path of the ADR to the microsite sidebar in
|
||||
[`sidebars.json`](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json)
|
||||
- Add the path of the ADR to the
|
||||
[`mkdocs.yml`](https://github.com/spotify/backstage/blob/master/mkdocs.yml)
|
||||
- Merge the pull request
|
||||
|
||||
## Superseding an ADR
|
||||
|
||||
|
Before Width: | Height: | Size: 303 KiB After Width: | Height: | Size: 303 KiB |
|
Before Width: | Height: | Size: 269 KiB After Width: | Height: | Size: 269 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 101 KiB |
|
Before Width: | Height: | Size: 45 KiB After Width: | Height: | Size: 45 KiB |
|
Before Width: | Height: | Size: 8.6 KiB After Width: | Height: | Size: 8.6 KiB |
|
Before Width: | Height: | Size: 414 KiB After Width: | Height: | Size: 414 KiB |
|
Before Width: | Height: | Size: 234 KiB After Width: | Height: | Size: 234 KiB |
|
Before Width: | Height: | Size: 45 KiB After Width: | Height: | Size: 45 KiB |
|
Before Width: | Height: | Size: 54 KiB After Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 746 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 134 KiB |
@@ -1,4 +1,7 @@
|
||||
# Authentication Backend Classes Layout and Description
|
||||
---
|
||||
id: auth-backend-classes
|
||||
title: Auth backend classes
|
||||
---
|
||||
|
||||
## How Does Authentication Work?
|
||||
|
||||
|
||||
+2
-2
@@ -104,6 +104,8 @@ request an access token.
|
||||
|
||||
The following diagram visualizes the flow described in the previous section.
|
||||
|
||||
|
||||
|
||||
<!--
|
||||
@startuml oauth-popup-flow
|
||||
|
||||
@@ -152,5 +154,3 @@ Browser <- Backend: Tokens and info
|
||||
|
||||
@enduml
|
||||
-->
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
id: software-catalog-configuration
|
||||
title: Catalog Configuration
|
||||
---
|
||||
|
||||
## Static Location Configuration
|
||||
|
||||
To enable declarative catalog setups, it is possible to add locations to the
|
||||
catalog via [static configuration](../../conf/index.md). Locations are added to
|
||||
the catalog under the `catalog.locations` key, for example:
|
||||
|
||||
```yaml
|
||||
catalog:
|
||||
locations:
|
||||
- type: github
|
||||
target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
|
||||
```
|
||||
|
||||
The locations added through static configuration can not be removed through the
|
||||
catalog locations API. To remove the locations, you have to remove them from the
|
||||
configuration.
|
||||
|
||||
## Catalog Rules
|
||||
|
||||
By default the catalog will only allow ingestion of entities with the kind
|
||||
`Component` and `API`. In order to allow entities of other kinds to be added,
|
||||
you need to add rules to the catalog. Rules are added either in a separate
|
||||
`catalog.rules` key, or added to statically configured locations.
|
||||
|
||||
For example, given the following configuration:
|
||||
|
||||
```yaml
|
||||
catalog:
|
||||
rules:
|
||||
- allow: [Component, API, System]
|
||||
|
||||
locations:
|
||||
- type: github
|
||||
target: https://github.com/org/example/blob/master/org-data.yaml
|
||||
allow: [Group]
|
||||
```
|
||||
|
||||
We are able to add entities of kind `Component`, `API`, or `System` from any
|
||||
location, and `Group` entities from the `org-data.yaml`, which will also be read
|
||||
as statically configured location.
|
||||
|
||||
Note that if the `catalog.rules` key is present it will replace the default
|
||||
value, meaning that you need to add rules for `Component` and `API` kinds if you
|
||||
want those to be allowed.
|
||||
|
||||
The following configuration will reject any kind of entities from being added to
|
||||
the catalog:
|
||||
|
||||
```yaml
|
||||
catalog:
|
||||
rules: []
|
||||
```
|
||||
@@ -370,8 +370,8 @@ metadata:
|
||||
description:
|
||||
Next.js application skeleton for creating isomorphic web applications.
|
||||
tags:
|
||||
- Recommended
|
||||
- React
|
||||
- recommended
|
||||
- react
|
||||
spec:
|
||||
owner: web@example.com
|
||||
templater: cookiecutter
|
||||
|
||||
@@ -12,7 +12,7 @@ Backstage natively supports tracking of the following component
|
||||
- Documentation
|
||||
- Other
|
||||
|
||||
|
||||
|
||||
|
||||
Since these types are likely not the only kind of software you will want to
|
||||
track in Backstage, it is possible to
|
||||
@@ -31,9 +31,10 @@ catalog.
|
||||
It might be tempting to put software that doesn't fit into any of the existing
|
||||
types into Other. There are a few reasons why we advice against this; firstly,
|
||||
we have found that it is preferred to match the conceptual model that your
|
||||
engineers have when describing your sofware. Secondly, Backstage helps your
|
||||
engineers manage their software by integrating the infratrucure tooling through
|
||||
plugins. Different plugins are used for managing different types of components.
|
||||
engineers have when describing your software. Secondly, Backstage helps your
|
||||
engineers manage their software by integrating the infrastructure tooling
|
||||
through plugins. Different plugins are used for managing different types of
|
||||
components.
|
||||
|
||||
For example, the
|
||||
[Lighthouse plugin](https://github.com/spotify/backstage/tree/master/plugins/lighthouse)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
id: software-catalog-overview
|
||||
title: Backstage Service Catalog (alpha)
|
||||
sidebar_label: Backstage Service Catalog
|
||||
---
|
||||
|
||||
## What is a Service Catalog?
|
||||
@@ -54,18 +55,18 @@ There are 3 ways to add components to the catalog:
|
||||
Users can register new components by going to `/create` and clicking the
|
||||
**REGISTER EXISTING COMPONENT** button:
|
||||
|
||||
|
||||
|
||||
|
||||
Backstage expects the full URL to the YAML in your source control. Example:
|
||||
|
||||
```
|
||||
```bash
|
||||
https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
|
||||
```
|
||||
|
||||
_More examples can be found
|
||||
[here](https://github.com/spotify/backstage/tree/master/packages/catalog-model/examples)._
|
||||
|
||||
|
||||
|
||||
|
||||
It is important to note that any kind of software can be registered in
|
||||
Backstage. Even if the software is not maintained by your company (SaaS
|
||||
@@ -78,12 +79,28 @@ All software created through the
|
||||
[Backstage Software Templates](../software-templates/index.md) are automatically
|
||||
registered in the catalog.
|
||||
|
||||
### Static catalog configuration
|
||||
|
||||
In addition to manually registering components, it is also possible to register
|
||||
components though [static configuration](../../conf/index.md). For example, the
|
||||
above example can be added using the following configuration:
|
||||
|
||||
```yaml
|
||||
catalog:
|
||||
locations:
|
||||
- type: github
|
||||
target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
|
||||
```
|
||||
|
||||
More information about catalog configuration can be found
|
||||
[here](configuration.md).
|
||||
|
||||
### Updating component metadata
|
||||
|
||||
Teams owning the components are responsible for maintaining the metadata about
|
||||
them, and do so using their normal Git workflow.
|
||||
|
||||
|
||||
|
||||
|
||||
Once the change has been merged, Backstage will automatically show the updated
|
||||
metadata in the service catalog after a short while.
|
||||
@@ -92,25 +109,25 @@ metadata in the service catalog after a short while.
|
||||
|
||||
By default the service catalog shows components owned by the team of the logged
|
||||
in user. But you can also switch to _All_ to see all the components across your
|
||||
companie's software ecosystem. Basic inline _search_ and _column filtering_
|
||||
makes it easy to browse a big set of components.
|
||||
company's software ecosystem. Basic inline _search_ and _column filtering_ makes
|
||||
it easy to browse a big set of components.
|
||||
|
||||
|
||||
|
||||
|
||||
## Starring components
|
||||
|
||||
For easy and quick access to components you visit frequently, Backstage supports
|
||||
_starring_ of components:
|
||||
|
||||
|
||||
|
||||
|
||||
## Integrated tooling through plugins
|
||||
|
||||
The service catalog is a great way to organise the infrastructure tools you use
|
||||
The service catalog is a great way to organize the infrastructure tools you use
|
||||
to manage the software. This is how Backstage creates one developer portal for
|
||||
all your tools. Rather than asking teams to jump between different
|
||||
infrastructure UI’s (and incurring additional cognitive overhead each time they
|
||||
make a context switch), most of these tools can be organised around the entities
|
||||
infrastructure UIs (and incurring additional cognitive overhead each time they
|
||||
make a context switch), most of these tools can be organized around the entities
|
||||
in the catalog.
|
||||
|
||||
|
||||
|
||||
@@ -3,55 +3,26 @@ id: system-model
|
||||
title: System Model
|
||||
---
|
||||
|
||||
We believe that a strong shared understanding and terminology around systems,
|
||||
software and resources leads to a better Backstage experience.
|
||||
We believe that a strong shared understanding and terminology around software
|
||||
and resources leads to a better Backstage experience.
|
||||
|
||||
_This description originates from
|
||||
[this RFC](https://github.com/spotify/backstage/issues/390). Note that some of
|
||||
the concepts are not yet supported in Backstage._
|
||||
|
||||
## Concepts
|
||||
## Core Entities
|
||||
|
||||
We model our technology using these five concepts (further explained below):
|
||||
We model software in the Backstage catalogue using these three core entities
|
||||
(further explained below):
|
||||
|
||||
- **Components** are individual pieces of software
|
||||
|
||||
- **APIs** are the boundaries between different components
|
||||
|
||||
- **Domains** are a high-level grouping of systems
|
||||
- **Systems** encapsulate the implementation of APIs
|
||||
- **APIs** are the boundaries between different components and systems
|
||||
- **Components** are pieces of software
|
||||
- **Resources** are physical or virtual infrastructure needed to operate a
|
||||
system
|
||||
component
|
||||
|
||||
|
||||
|
||||
### Domain
|
||||
|
||||
While systems are the basic level of encapsulation for resources, components and
|
||||
APIs, it is often useful to group a collection of systems that share
|
||||
terminology, domain models, business purpose, or documentation, i.e. they form a
|
||||
bounded context.
|
||||
|
||||
For example, it would make sense if the different systems in the “Payments”
|
||||
domain would come with some documentation on how to accept payments for a new
|
||||
product or use-case, share the same entity types in their APIs, and integrate
|
||||
well with each other.
|
||||
|
||||
### System
|
||||
|
||||
With increasing complexity in software, we believe that systems form an
|
||||
important abstraction level to help us reason about software ecosystems. Systems
|
||||
are a useful concept in that they allow us to ignore the implementation details
|
||||
of a certain functionality for consumers, while allowing the owning team to make
|
||||
changes as they see fit (leading to low coupling).
|
||||
|
||||
A system, in this sense, is a collection of resources and components that
|
||||
exposes one or several APIs. Components and resources in a system are typically
|
||||
owned by the same team and are expected to co-evolve. As such, systems usually
|
||||
consist of at most a handful of components.
|
||||
|
||||
For example, a playlist management system might encapsulate a backend service to
|
||||
update playlists, a backend service to query them, and a database to store them.
|
||||
It could expose an RPC API, a daily snapshots dataset, and an event stream of
|
||||
playlist updates.
|
||||
|
||||
|
||||
### Component
|
||||
|
||||
@@ -60,34 +31,80 @@ backend service or data pipeline (list not exhaustive). A component can be
|
||||
tracked in source control, or use some existing open source or commercial
|
||||
software.
|
||||
|
||||
A component can implement APIs for other components to consume. It might depend
|
||||
on the resources of the system it belongs to, and APIs from other components or
|
||||
other systems. All other aspects of the component, e.g. any code dependencies,
|
||||
must be encapsulated.
|
||||
A component can implement APIs for other components to consume. In turn it might
|
||||
depend on APIs implemented by other components, or resources that are attached
|
||||
to it at runtime.
|
||||
|
||||
### API
|
||||
|
||||
We believe APIs form an important (maybe the most important) abstraction that
|
||||
allows large software ecosystems to scale. Thus, APIs are a first class citizen
|
||||
in the Backstage model and the primary way to discover existing functionality in
|
||||
the ecosystem.
|
||||
APIs form an important (maybe the most important) abstraction that allows large
|
||||
software ecosystems to scale. Thus, APIs are a first class citizen in the
|
||||
Backstage model and the primary way to discover existing functionality in the
|
||||
ecosystem.
|
||||
|
||||
APIs are implemented by components and form boundaries between components and
|
||||
systems. They might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a
|
||||
data schema (eg Avro, TFRecord, ...), or as code interfaces. In any case, APIs
|
||||
exposed by components need to be in a known machine-readable format so we can
|
||||
build further tooling and analysis on top.
|
||||
APIs are implemented by components and form boundaries between components. They
|
||||
might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a data schema (eg
|
||||
Avro, TFRecord, ...), or as code interfaces. In any case, APIs exposed by
|
||||
components need to be in a known machine-readable format so we can build further
|
||||
tooling and analysis on top.
|
||||
|
||||
Some APIs might be exposed by the system, making them available for any other
|
||||
Spotify component to consume. Those public APIs must be documented and humanly
|
||||
discoverable in Backstage.
|
||||
APIs have a visibility: they are either public (making them available for any
|
||||
other component to consume), restricted (only available to a whitelisted set of
|
||||
consumers), or private (only available within their system). As public APIs are
|
||||
going to be the primary way interaction between components, Backstage supports
|
||||
documenting, indexing and searching all APIs so we can browse them as
|
||||
developers.
|
||||
|
||||
### Resource
|
||||
|
||||
Resources are the infrastructure a system needs to operate, like BigTable
|
||||
databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with
|
||||
components and systems will better allow us to visualize resource footprint, and
|
||||
create tooling around them.
|
||||
Resources are the infrastructure a component needs to operate at runtime, like
|
||||
BigTable databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together
|
||||
with components and systems will better allow us to visualize resource
|
||||
footprint, and create tooling around them.
|
||||
|
||||
## Ecosystem Modeling
|
||||
|
||||
A large catalogue of components, APIs and resources can be highly granular and
|
||||
hard to understand as a whole. It might thus be convenient to further categorize
|
||||
these entities using the following (optional) concepts:
|
||||
|
||||
- **Systems** are a collection of entities that cooperate to perform some
|
||||
function
|
||||
- **Domains** relate entities and systems to part of the business
|
||||
|
||||
### System
|
||||
|
||||
With increasing complexity in software, systems form an important abstraction
|
||||
level to help us reason about software ecosystems. Systems are a useful concept
|
||||
in that they allow us to ignore the implementation details of a certain
|
||||
functionality for consumers, while allowing the owning team to make changes as
|
||||
they see fit (leading to low coupling).
|
||||
|
||||
A system, in this sense, is a collection of resources and components that
|
||||
exposes one or several public APIs. The main benefit of modelling a system is
|
||||
that it hides its resources and private APIs between the components for any
|
||||
consumers. This means that as the owner, you can evolve the implementation, in
|
||||
terms of components and resources, without your consumers being able to notice.
|
||||
Typically, a system will consist of at most a handful of components (see Domain
|
||||
for a grouping of systems).
|
||||
|
||||
For example, a playlist management system might encapsulate a backend service to
|
||||
update playlists, a backend service to query them, and a database to store them.
|
||||
It could expose an RPC API, a daily snapshots dataset, and an event stream of
|
||||
playlist updates.
|
||||
|
||||
### Domain
|
||||
|
||||
While systems are the basic level of encapsulation for related entities, it is
|
||||
often useful to group a collection of systems that share terminology, domain
|
||||
models, metrics, KPIs, business purpose, or documentation, i.e. they form a
|
||||
bounded context.
|
||||
|
||||
For example, it would make sense if the different systems in the “Payments”
|
||||
domain would come with some documentation on how to accept payments for a new
|
||||
product or use-case, share the same entity types in their APIs, and integrate
|
||||
well with each other. Other domains could be “Content Ingestion”, “Ads” or
|
||||
“Search”.
|
||||
|
||||
## Current status
|
||||
|
||||
|
||||
@@ -22,8 +22,8 @@ metadata:
|
||||
Next.js application skeleton for creating isomorphic web applications.
|
||||
# some tags to display in the frontend
|
||||
tags:
|
||||
- Recommended
|
||||
- React
|
||||
- recommended
|
||||
- react
|
||||
spec:
|
||||
# which templater key to use in the templaters builder
|
||||
templater: cookiecutter
|
||||
@@ -54,11 +54,11 @@ contains more information about the required fields.
|
||||
Once we have a `template.yaml` ready, we can then add it to the service catalog
|
||||
for use by the scaffolder.
|
||||
|
||||
Currently the catalog supports loading definitions from Github + Local Files. To
|
||||
Currently the catalog supports loading definitions from GitHub + Local Files. To
|
||||
load from other places, not only will there need to be another preparer, but the
|
||||
support to load the location will also need to be added to the Catalog.
|
||||
|
||||
For loading from a file the following command should work when the backend is
|
||||
For loading from a file, the following command should work when the backend is
|
||||
running:
|
||||
|
||||
```sh
|
||||
@@ -69,7 +69,7 @@ curl \
|
||||
--data-raw "{\"type\": \"file\", \"target\": \"${YOUR PATH HERE}/template.yaml\"}"
|
||||
```
|
||||
|
||||
If loading from a git location, you can run the following
|
||||
If loading from a Git location, you can run the following
|
||||
|
||||
```sh
|
||||
curl \
|
||||
@@ -83,7 +83,7 @@ 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 for you, you can run the following to load those templates:
|
||||
already provided, run the following to load those templates:
|
||||
|
||||
```
|
||||
yarn lerna run mock-data
|
||||
|
||||
@@ -54,7 +54,7 @@ The `protocol` is set on the
|
||||
when added to the service catalog. You can see more about this `PreparerKey`
|
||||
here in [Register your own template](../adding-templates.md)
|
||||
|
||||
**note:** Currently the catalog supports loading definitions from Github + Local
|
||||
**note:** Currently the catalog supports loading definitions from GitHub + Local
|
||||
Files, which translate into the two `PreparerKeys` `file` and `github`. To load
|
||||
from other places, not only will there need to be another preparer, but the
|
||||
support to load the location will also need to be added to the Catalog.
|
||||
|
||||
@@ -7,8 +7,8 @@ Publishers are responsible for pushing and storing the templated skeleton after
|
||||
the values have been templated by the `Templater`. See
|
||||
[Create your own templater](./create-your-own-templater.md) for more info.
|
||||
|
||||
They recieve a directory or location where the templater has sucessfully run on,
|
||||
and is now ready to store somewhere. They also get given some other options
|
||||
They receive a directory or location where the templater has sucessfully run
|
||||
and is now ready to store somewhere. They also are given some other options
|
||||
which are sent from the frontend, such as the `storePath` which is a string of
|
||||
where the frontend thinks we should save this templated folder.
|
||||
|
||||
@@ -17,7 +17,7 @@ Currently we provide the following `publishers`:
|
||||
- `github`
|
||||
|
||||
This publisher is passed through to the `createRouter` function of the
|
||||
`@spotify/plugin-scaffolder-backend`. Currently only one publisher is supported,
|
||||
`@spotify/plugin-scaffolder-backend`. Currently, only one publisher is supported,
|
||||
but PR's are always welcome.
|
||||
|
||||
An full example backend can be found
|
||||
|
||||
@@ -8,14 +8,14 @@ returned by the preparers, and then executing the templating command on top of
|
||||
the file and returning the completed template path. This may or may not be the
|
||||
same directory as the input directory.
|
||||
|
||||
They also recieve additional values from the frontend, which can be used to
|
||||
They also receive additional values from the frontend, which can be used to
|
||||
interpolate into the skeleton files.
|
||||
|
||||
Currently we provide the following templaters:
|
||||
|
||||
- `cookiecutter`
|
||||
|
||||
This templater is added the `TemplaterBuilder` and then passed into the
|
||||
This templater is added to the `TemplaterBuilder` and then passed into the
|
||||
`createRouter` function of the `@spotify/plugin-scaffolder-backend`
|
||||
|
||||
An full example backend can be found
|
||||
@@ -48,7 +48,7 @@ This `TemplaterKey` is used to select the correct templater from the
|
||||
`spec.templater` in the
|
||||
[Template Entity](../../software-catalog/descriptor-format.md#kind-template).
|
||||
|
||||
If you wish to add a new templater you'll need to register it with the
|
||||
If you wish to add a new templater, you'll need to register it with the
|
||||
`TemplaterBuilder`.
|
||||
|
||||
### Creating your own Templater to add to the `TemplaterBuilder`
|
||||
@@ -83,10 +83,10 @@ follows:
|
||||
- `dockerClient` - a [dockerode](https://github.com/apocas/dockerode) client to
|
||||
be able to run docker containers.
|
||||
|
||||
_note_ currently the templaters that we provide are basically docker action
|
||||
_note_ Currently the templaters that we provide are basically Docker action
|
||||
containers that are run on top of the skeleton folder. This keeps dependencies
|
||||
to a minimal for running backstage scaffolder, but you don't /have/ to use
|
||||
docker. You could create your own templater that spins up an EC2 instance and
|
||||
Docker. You could create your own templater that spins up an EC2 instance and
|
||||
downloads the folder and does everything using an AMI if you want. It's entirely
|
||||
up to you!
|
||||
|
||||
@@ -116,8 +116,8 @@ metadata:
|
||||
description:
|
||||
Next.js application skeleton for creating isomorphic web applications.
|
||||
tags:
|
||||
- Recommended
|
||||
- React
|
||||
- recommended
|
||||
- react
|
||||
spec:
|
||||
owner: web@example.com
|
||||
templater: handlebars
|
||||
@@ -138,7 +138,7 @@ spec:
|
||||
description: Description of the component
|
||||
```
|
||||
|
||||
You see that the `spec.templater` is set as `handlebars`, you'll need to
|
||||
You see that the `spec.templater` is set as `handlebars`, so you'll need to
|
||||
register this with the `TemplaterBuilder` like so:
|
||||
|
||||
```ts
|
||||
|
||||
@@ -5,11 +5,11 @@ title: Extending the Scaffolder
|
||||
|
||||
Welcome. Take a seat. You're at the Scaffolder Documentation.
|
||||
|
||||
So - You wanna create stuff inside your company from some prebaked templates?
|
||||
So, you want to create stuff inside your company from some prebaked templates?
|
||||
You're at the right place.
|
||||
|
||||
This guide is gonna take you through how the Scaffolder in Backstage works.
|
||||
We'll dive into some jargon and run through whats going on in the backend to be
|
||||
This guide is going to take you through how the Scaffolder in Backstage works.
|
||||
We'll dive into some jargon and run through what's going on in the backend to be
|
||||
able to create these templates. There's also more guides that you might find
|
||||
useful at the bottom of this document. At it's core, theres 3 simple stages.
|
||||
|
||||
@@ -25,9 +25,9 @@ scaffolder that you will need to know:
|
||||
3. Publish
|
||||
|
||||
Each of these steps can be configured for your own use case, but we provide some
|
||||
sensible defaults too.
|
||||
sensible defaults, too.
|
||||
|
||||
Lets dive a little deeper into these phases.
|
||||
Let's dive a little deeper into these phases.
|
||||
|
||||
### Glossary and Jargon
|
||||
|
||||
@@ -38,8 +38,8 @@ the router to pick the correct `Preparer` to run for the `Template` entity.
|
||||
|
||||
**Templater** - The templater is responsible for actually running the chosen
|
||||
templater on top of the previously returned temporary directory from the
|
||||
**Preprarer**. We advise making these docker containers as it can keep all
|
||||
dependencies, for example Cookiecutter, self contained and not a dependency on
|
||||
**Preprarer**. We advise making these Docker containers as it can keep all
|
||||
dependencies--for example Cookiecutter--self contained and not a dependency on
|
||||
the host machine.
|
||||
|
||||
**Publisher** - The publisher is responsible for taking the finished directory,
|
||||
@@ -50,11 +50,11 @@ passed through to the scaffolder backend.
|
||||
|
||||
### How it works
|
||||
|
||||
The main of the heavy lifting is done in the
|
||||
Most of the heavy lifting is done in the
|
||||
[router.ts](https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/service/router.ts#L93)
|
||||
file in the `scaffolder-backend` plugin.
|
||||
|
||||
There are 2 routes defined in the router. `POST /v1/jobs` and
|
||||
There are two routes defined in the router: `POST /v1/jobs` and
|
||||
`GET /v1/job/:jobId`
|
||||
|
||||
To create a scaffolding job, a JSON object containing the
|
||||
@@ -78,7 +78,7 @@ additional templating values must be posted as the post body.
|
||||
The values should represent something that is valid with the `schema` part of
|
||||
the [Template Entity](../../software-catalog/descriptor-format.md#kind-template)
|
||||
|
||||
Once that has been posted, a job will be setup with different stages. And the
|
||||
Once that has been posted, a job will be setup with different stages, and the
|
||||
job processor will complete each stage before moving onto the next stage, whilst
|
||||
collecting logs and mutating the running job.
|
||||
|
||||
|
||||
@@ -4,8 +4,8 @@ title: Software Templates
|
||||
---
|
||||
|
||||
The Software Templates part of Backstage is a tool that can help you create
|
||||
Components inside Backstage. It by default has the ability to load skeletons of
|
||||
code, template in some variables and then publish the template to some location
|
||||
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.
|
||||
|
||||
<video width="100%" height="100%" controls>
|
||||
@@ -33,8 +33,8 @@ 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, and the `storePath` which right now must be a Github Organisation and a
|
||||
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`.
|
||||
|
||||
|
||||
@@ -51,13 +51,13 @@ It shouldn't take too long, and you'll have a success screen!
|
||||
|
||||
|
||||
If it fails, you'll be able to click on each section to get the log from the
|
||||
step that failed which can be helpful to debug.
|
||||
step that failed which can be helpful in debugging.
|
||||
|
||||
|
||||
|
||||
### View Component in Catalog
|
||||
|
||||
When it's been created you'll see the `View in Catalog` button, which will take
|
||||
When it's been created, you'll see the `View in Catalog` button, which will take
|
||||
you to the registered component in the catalog:
|
||||
|
||||
|
||||
|
||||
@@ -109,7 +109,7 @@ export default async function createPlugin({ logger }: PluginEnvironment) {
|
||||
preparers.register('file', filePreparer);
|
||||
preparers.register('github', githubPreparer);
|
||||
|
||||
// Create Github client with your access token from environment variables
|
||||
// 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 });
|
||||
|
||||
|
||||
@@ -101,3 +101,7 @@ 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
|
||||
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ sites with the Backstage UI.
|
||||
|
||||
The TechDocs Reader purpose is also to open up the opportunity to integrate
|
||||
TechDocs widgets for a customized full-featured TechDocs experience.
|
||||
([coming soon V.2](https://github.com/spotify/backstage/milestone/17))
|
||||
([coming soon V.3](./README.md#project-roadmap))
|
||||
|
||||
[TechDocs Reader](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md)
|
||||
|
||||
@@ -53,4 +53,4 @@ Reader. The reason why transformers were introduced was to provide a way to
|
||||
transform the HTML content on pre and post render (e.g. rewrite docs links or
|
||||
modify css).
|
||||
|
||||
[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/transformers/README.md)
|
||||
[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md)
|
||||
|
||||
@@ -6,26 +6,43 @@ sidebar_label: Creating and Publishing Documentation
|
||||
|
||||
This section will guide you through:
|
||||
|
||||
- Creating a basic setup for your documentation
|
||||
- Writing and previewing your documentation in a local Backstage environment
|
||||
- Creating a build ready for publication
|
||||
- Publishing your documentation and making your Backstage instance read your
|
||||
published docs.
|
||||
- [Create a basic documentation setup](#create-a-basic-documentation-setup)
|
||||
- [Use the documentation template](#use-the-documentation-template)
|
||||
- [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
|
||||
|
||||
- [Docker](https://docs.docker.com/get-docker/)
|
||||
- Static file hosting
|
||||
- A working Backstage instance with TechDocs installed (see
|
||||
[TechDocs getting started](getting-started.md))
|
||||
|
||||
## Create a basic documentation setup
|
||||
|
||||
In your home directory (also known as `~`), create a directory that contains
|
||||
your documentation (for example, `hello-docs`). Inside this directory, create a
|
||||
file called `mkdocs.yml`. Below is a basic example of how it could look.
|
||||
### Use the documentation template
|
||||
|
||||
The `~/hello-docs/mkdocs.yml` file should have the following content:
|
||||
Your working Backstage instance should by default have a documentation template
|
||||
added. If not, follow these
|
||||
[instructions](../software-templates/installation.md#adding-templates) to add
|
||||
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:
|
||||
|
||||
- `catalog-info.yml` file registered to Backstage.
|
||||
|
||||
Create a `mkdocs.yml` file in the root of the repository with the following
|
||||
content:
|
||||
|
||||
```yaml
|
||||
site_name: 'example-docs'
|
||||
@@ -37,7 +54,20 @@ plugins:
|
||||
- techdocs-core
|
||||
```
|
||||
|
||||
The `~/hello-docs/docs/index.md` should have the following content:
|
||||
Update your `catalog-info.yaml` file in the root of the repository with the
|
||||
following content:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
annotations:
|
||||
backstage.io/techdocs-ref: dir:./
|
||||
```
|
||||
|
||||
Create a `/docs` folder in the root of the project with at least a `index.md`
|
||||
file. _(If you add more markdown files, make sure to update the nav in the
|
||||
mkdocs.yml file to get a proper navigation for your documentation.)_
|
||||
|
||||
The `docs/index.md` can for example have the following content:
|
||||
|
||||
```md
|
||||
# example docs
|
||||
@@ -45,6 +75,9 @@ The `~/hello-docs/docs/index.md` should have the following content:
|
||||
This is a basic example of documentation.
|
||||
```
|
||||
|
||||
Commit your changes, open a pull request and merge. You will now get your
|
||||
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
|
||||
@@ -54,83 +87,6 @@ want to write your documentation.
|
||||
To do this you can run:
|
||||
|
||||
```bash
|
||||
cd ~/hello-docs/
|
||||
cd ~/<repository-path>/
|
||||
npx techdocs-cli serve
|
||||
```
|
||||
|
||||
## Build production ready documentation
|
||||
|
||||
To get a build suitable for publication you can build your docs using the
|
||||
`spotify/techdocs` container:
|
||||
|
||||
```bash
|
||||
cd ~/hello-docs/
|
||||
docker run -it -w /content -v $(pwd):/content spotify/techdocs build
|
||||
```
|
||||
|
||||
You should now have a folder called `~/hello-docs/site/`.
|
||||
|
||||
## Deploy to a file server
|
||||
|
||||
In order to serve documentation to TechDocs, our Backstage plugin needs to
|
||||
download the HTML rendered from the previous step. This will likely exist on an
|
||||
external file server, or a storage solution such as Google Cloud Storage.
|
||||
|
||||
When deploying documentation, it should be deployed on that file server/storage
|
||||
solution with the following convention: `{id}/{file}`. For example, if you want
|
||||
to upload the `getting-started/index.html` file for the `backstage`
|
||||
documentation site, we would upload it to our file server as
|
||||
`backstage/getting-started/index.html`.
|
||||
|
||||
To explain further what this would look like for multiple documentation sites,
|
||||
take a look at this example file tree that would be represented on your file
|
||||
server:
|
||||
|
||||
```md
|
||||
/backstage/index.html /backstage/getting-started/index.html
|
||||
/backstage/contributing/index.html /mkdocs/index.html
|
||||
/mkdocs/plugin-development/index.html
|
||||
/mkdocs/plugin-development/debugging/index.html
|
||||
```
|
||||
|
||||
In this file tree, we have two documentation sites available: `backstage` and
|
||||
`mkdocs`. Each of them expose several pages. Let's say both of these are hosted
|
||||
on `http://example.com` as the server URL.
|
||||
|
||||
When you configure the TechDocs plugin in Backstage to use `http://example.com`
|
||||
as the file server/storage solution, it will translate the following URLs to the
|
||||
file server:
|
||||
|
||||
| Backstage URL | File Server URL |
|
||||
| --------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| https://demo.backstage.io/docs/backstage/ | http://example.com/backstage/index.html |
|
||||
| https://demo.backstage.io/docs/mkdocs/plugin-development/ | http://example.com/mkdocs/plugin-development/index.html |
|
||||
|
||||
Then deploying new sites is easy: simply copy over the `site/` folder produced
|
||||
in the [Create documentation](#build-production-ready-documentation) step above
|
||||
to the file server/storage solution under the ID of the documentation site. It
|
||||
will then become immediately available in Backstage under the same ID as you can
|
||||
see in the table above.
|
||||
|
||||
So, if the URL to your file server is `http://example.com/`, your
|
||||
`~/hello-docs/site` folder containing the documentation should be accessible at
|
||||
`http://example.com/hello-docs/`.
|
||||
|
||||
## Configure TechDocs to read from file server
|
||||
|
||||
In order for Backstage to show your documentation, it needs to know where you
|
||||
uploaded it.
|
||||
|
||||
Make sure you have Backstage set up using
|
||||
[TechDocs getting started](getting-started.md).
|
||||
|
||||
To point Backstage to your docs storage, add or change the following lines in
|
||||
your Backstage `app-config.yaml`:
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
storageUrl: http://example.com
|
||||
```
|
||||
|
||||
You can now start Backstage using `yarn start` and open up your browser at
|
||||
`http://localhost:3000/docs/hello-docs` to view your docs.
|
||||
|
||||
@@ -3,16 +3,6 @@ id: getting-started
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
> TechDocs is not yet feature complete - currently you can't set up a complete
|
||||
> end-to-end working TechDocs plugin without customizing the plugin itself.
|
||||
|
||||
> What you can expect from TechDocs V.0 is a demonstration of how to integrate
|
||||
> docs into Backstage. TechDocs can create docs using
|
||||
> [mkdocs](https://www.mkdocs.org/), as well as read published docs. If you
|
||||
> publish generated docs and pass in a `storageUrl` in your `app-config.yaml`,
|
||||
> you can view them in Backstage by going to
|
||||
> `http://localhost:3000/docs/<remote-folder>`.
|
||||
|
||||
TechDocs functions as a plugin to Backstage, so you will need to use Backstage
|
||||
to use TechDocs.
|
||||
|
||||
@@ -48,8 +38,8 @@ containing your new Backstage application.
|
||||
|
||||
## Installing TechDocs
|
||||
|
||||
TechDocs is not provided with the Backstage application by default, so you will
|
||||
now need to set up TechDocs manually. It should take less than a minute.
|
||||
TechDocs is provided with the Backstage application by default. If you want to
|
||||
set up TechDocs manually, keep follow the instructions below.
|
||||
|
||||
### Adding the package
|
||||
|
||||
@@ -84,19 +74,29 @@ 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. The URL provided here is for demo docs to use for testing
|
||||
purposes.
|
||||
`app-config` file.
|
||||
|
||||
To use the demo docs, add the following lines to `app-config.yaml`:
|
||||
The default storage URL:
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
storageUrl: https://techdocs-mock-sites.storage.googleapis.com
|
||||
storageUrl: http://localhost:7000/techdocs/static/docs
|
||||
```
|
||||
|
||||
If you want to configure this to point to another storage URL, change the value
|
||||
of `storageUrl`.
|
||||
|
||||
## Run Backstage locally
|
||||
|
||||
Change folder to your Backstage application root and run the following command:
|
||||
Change folder to `<backstage-project-root>/packages/backend` and run the
|
||||
following command:
|
||||
|
||||
```bash
|
||||
yarn start
|
||||
```
|
||||
|
||||
Open a new command line window. Change directory to your Backstage application
|
||||
root and run the following command:
|
||||
|
||||
```bash
|
||||
yarn start
|
||||
|
||||
@@ -85,7 +85,3 @@ yarn create-plugin # Create a new plugin
|
||||
> See
|
||||
> [package.json](https://github.com/spotify/backstage/blob/master/package.json)
|
||||
> for other yarn commands/options.
|
||||
|
||||
[Next Step - Create a Backstage plugin](../plugins/create-a-plugin.md)
|
||||
|
||||
[Back to Docs](../README.md)
|
||||
|
||||
@@ -3,9 +3,22 @@ id: index
|
||||
title: Running Backstage Locally
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
```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)
|
||||
```
|
||||
|
||||
To get up and running with a local Backstage to evaluate it, let's clone it off
|
||||
of GitHub and run an initial build. First make sure that you have at least node
|
||||
version 12 installed locally.
|
||||
of GitHub and run an initial build.
|
||||
|
||||
```bash
|
||||
# Start from your local development folder
|
||||
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
id: adopting
|
||||
title: Strategies for adopting
|
||||
---
|
||||
|
||||
This document outlines some general best practices that have been key to
|
||||
Backstage's success inside Spotify. Every organization is different and some of
|
||||
these learnings will therefore not be applicable for your company. We are hoping
|
||||
that this can become a living document, and strongly encourage you to contribute
|
||||
back whatever learnings you gather while adopting Backstage inside your company.
|
||||
|
||||
## Organizational setup
|
||||
|
||||
The true value of Backstage is unlocked when it becomes _THE_ developer portal
|
||||
at your company. As such it is important to recognize that you will need a
|
||||
central team that owns your Backstage deployment and treats it like a product.
|
||||
|
||||
This team will have **four** primary objectives:
|
||||
|
||||
1. Maintain and operate your deployment of Backstage. This includes customer
|
||||
support, infrastructure, CI/CD and, as your Backstage product grows, on-call
|
||||
support.
|
||||
|
||||
2. Drive adoption of customers (developers at your company).
|
||||
|
||||
3. Work with senior tech leadership and architects to ensure your organizations
|
||||
best practices for software development are encoded into a set of
|
||||
[Software Templates](../features/software-templates/index.md).
|
||||
|
||||
4. Evangelize Backstage as a central platform towards other
|
||||
infrastructure/platform teams.
|
||||
|
||||
## Internal evangelization
|
||||
|
||||
The last objective deserves more attention, since it is the least obvious, but
|
||||
also the most critical to successfully creating a consolidated platform. When
|
||||
done right, Backstage acts as a "platform of platforms" or marketplace between
|
||||
infra/platform teams and end-users:
|
||||
|
||||
|
||||
|
||||
While anyone at your company can contribute to the platform, the vast majority
|
||||
of work will be done by teams that also has internal engineers as their
|
||||
customers. The central team should treat these _contributing teams_ as customers
|
||||
of the platform as well.
|
||||
|
||||
These teams should be able to autonomously deliver value directly to their
|
||||
customers. This is done primarily by building [plugins](../plugins/index.md).
|
||||
Contributing teams should themselves treat their plugins as, or part of, the
|
||||
products they maintain.
|
||||
|
||||
> Case study: Inside Spotify we have a team that owns our CI platform. They
|
||||
> don't only maintain the pipelines and build servers, but also expose their
|
||||
> product in Backstage through a plugin. Since they also
|
||||
> [maintain their own API](../plugins/call-existing-api.md), they can improve
|
||||
> their product by iterating on API and UI in lockstep. Because the plugin
|
||||
> follows our [platform design guidelines](../dls/design.md) their customers get
|
||||
> a CI experience that is consistent with other tools on the platform (and users
|
||||
> don't have to become experts in Jenkins).
|
||||
|
||||
### Tactics
|
||||
|
||||
Example of tactics we have used to evangelize Backstage internally:
|
||||
|
||||
- Arrange "Lunch & Learns" and seminars. Frequently offer teams interested in
|
||||
Backstage development to come to a seminar where you show, for example, how to
|
||||
build a plugin from scratch.
|
||||
|
||||
- Embedding. As contributing teams start development of their first plugin it is
|
||||
often very appreciated to have one person from the central team come over and
|
||||
"embed" for a Sprint or two.
|
||||
|
||||
- Hack days. Backstage-focused Hackathons or hack days is a fun way to get
|
||||
people into plugin development.
|
||||
|
||||
- Show & tell meetings. In order to build an internal community around Backstage
|
||||
we have quarterly meetings where anyone working on Backstage is invited to
|
||||
present their work. This is a not only a great way to get early feedback, but
|
||||
also helps coordination between teams that are building overlapping
|
||||
experiences.
|
||||
|
||||
- Provide metrics. Add instrumentation to your Backstage deployment and make
|
||||
metrics available to contributing teams. At Spotify we have even gone so far
|
||||
as sending out weekly digest email showing how usage metrics have changed for
|
||||
individual plugins.
|
||||
|
||||
- Pro-actively identify new plugins. Reach out to teams that own internal UIs or
|
||||
platforms that you think would make sense to consolidate into Backstage.
|
||||
|
||||
## KPIs and metrics
|
||||
|
||||
These are some of the metrics that you can use to verify if Backstage has a
|
||||
successful impact on your software development process:
|
||||
|
||||
- **Onboarding time** Time until new engineers are productive. At Spotify we
|
||||
measure this as the time until the employee has merged their 10th PR (this
|
||||
metric was down 55% two years after deploying Backstage). Even though you may
|
||||
not be onboarding engineers at a rapid pace, this metric is a great proxy for
|
||||
the overall complexity of your ecosystem. Reducing it will therefore benefit
|
||||
your whole engineering organization, not just new joiners.
|
||||
|
||||
- **Number of merges per developer/day** Less time spent jumping between
|
||||
different tools and looking for information means more time to focus on
|
||||
shipping code. A second level of bottlenecks can be identified if you
|
||||
categorize contributions by domain (services, web, data, etc).
|
||||
|
||||
- **Deploys to production** Cousin to the metric above: How many times does an
|
||||
engineer push changes into production.
|
||||
|
||||
- **MTTR** With clear ownership of all the pieces in your micro services
|
||||
ecosystem and all tools integrated into one place, Backstage makes it quicker
|
||||
for teams to find the root cause of failures, and fix them.
|
||||
|
||||
- **Context switching** Reducing context switching can help engineers stay in
|
||||
the "zone". We measure the number of different tools an engineer have to
|
||||
interact with in order to get a certain job done (e.g. push a change, follow
|
||||
it into production and validate it did not break anything).
|
||||
|
||||
- **T-shapedness** A
|
||||
[T-shaped](https://medium.com/@jchyip/why-t-shaped-people-e8706198e437)
|
||||
engineer is someone that is able to contribute to different domains of
|
||||
engineering. Teams with T-shaped people have fewer bottlenecks and can
|
||||
therefore deliver more consistently. Backstage makes it easier to be T-shaped
|
||||
since tools and infrastructure is consistent between domains, and information
|
||||
is available centrally.
|
||||
|
||||
- **eNPS** Surveys asking about how productive people feel, how easy it is to
|
||||
find information and overall satisfaction with internal tools.
|
||||
|
||||
- **Fragmentation** _(Experimental)_ Backstage
|
||||
[Software Templates](../features/software-templates/index.md) helps drive
|
||||
standardization in your software ecosystem. By measuring the variance in
|
||||
technology between different software components it is possible to get a sense
|
||||
of the overall fragmentation in your ecosystem. Examples could include:
|
||||
framework versions, languages, deployment methods and various code quality
|
||||
measurements.
|
||||
|
||||
Additionally, these proxy metrics can be used to validate the success of
|
||||
Backstage as _the_ platform:
|
||||
|
||||
- Nr of teams that have contributed at least one plugin (currently 63 inside
|
||||
Spotify)
|
||||
|
||||
- Nr of total plugins (currently 135 inside Spotify)
|
||||
|
||||
- % of contributions coming from outside the central Backstage team (currently
|
||||
85% inside Spotify)
|
||||
|
||||
- Traditional metrics such as visits (MAU, DAU, etc) and page views. Currently
|
||||
~50% of all Spotifiers use Backstage on a monthly basis, even though the
|
||||
percentage of engineers is below 50%. Most engineers actually use Backstage on
|
||||
a daily basis.
|
||||
|
||||
Again, any feedback is appreciated. Please use the Edit button at the top of the
|
||||
page to make a suggestion.
|
||||
|
||||
_**Note!** It might be tempting to try to optimize Backstage usage and
|
||||
"engagement". Even though you want to consolidate all your tooling and technical
|
||||
documentation in Backstage, it is important to remember that time spent in
|
||||
Backstage is time not spent writing code_ 🙃
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
id: background
|
||||
title: The Spotify Story
|
||||
---
|
||||
|
||||
Backstage was born out of necessity at Spotify. We found that as we grew, our
|
||||
infrastructure was becoming more fragmented, our engineers less productive.
|
||||
|
||||
Instead of building and testing code, teams were spending more time looking for
|
||||
the right information just to get started. “Where’s the API for that service
|
||||
we’re all supposed to be using?” “What version of that framework is everyone
|
||||
on?” “This service isn’t responding, who owns it?” “I can’t find documentation
|
||||
for anything!”
|
||||
|
||||
Context switching and cognitive overload were dragging engineers down, day by
|
||||
day. We needed to make it easier for our engineers to do their work without
|
||||
having to become an expert in every aspect of infrastructure tooling.
|
||||
|
||||
Our idea was to centralize and simplify end-to-end software development with an
|
||||
abstraction layer that sits on top of all of our infrastructure and developer
|
||||
tooling. That’s Backstage.
|
||||
|
||||
It’s a developer portal powered by a centralized service catalog — with a plugin
|
||||
architecture that makes it endlessly extensible and customizable.
|
||||
|
||||
Manage all your services, software, tooling, and testing in Backstage. Start
|
||||
building a new microservice using an automated template in Backstage. Create,
|
||||
maintain, and find the documentation for all that software in Backstage.
|
||||
|
||||
One place for everything. Accessible to everyone.
|
||||
@@ -18,12 +18,15 @@ Out of the box, Backstage includes:
|
||||
- [Backstage Service Catalog](../features/software-catalog/index.md) for
|
||||
managing all your software (microservices, libraries, data pipelines,
|
||||
websites, ML models, etc.)
|
||||
|
||||
- [Backstage Software Templates](../features/software-templates/index.md) for
|
||||
quickly spinning up new projects and standardizing your tooling with your
|
||||
organization’s best practices
|
||||
|
||||
- [Backstage TechDocs](../features/techdocs/README.md) for making it easy to
|
||||
create, maintain, find, and use technical documentation, using a "docs like
|
||||
code" approach
|
||||
|
||||
- Plus, a growing ecosystem of
|
||||
[open source plugins](https://github.com/spotify/backstage/tree/master/plugins)
|
||||
that further expand Backstage’s customizability and functionality
|
||||
@@ -33,12 +36,15 @@ Out of the box, Backstage includes:
|
||||
- For _engineering managers_, it allows you to maintain standards and best
|
||||
practices across the organization, and can help you manage your whole tech
|
||||
ecosystem, from migrations to test certification.
|
||||
|
||||
- For _end users_ (developers), it makes it fast and simple to build software
|
||||
components in a standardized way, and it provides a central place to manage
|
||||
all projects and documentation.
|
||||
|
||||
- For _platform engineers_, it enables extensibility and scalability by letting
|
||||
you easily integrate new tools and services (via plugins), as well as
|
||||
extending the functionality of existing ones.
|
||||
|
||||
- For _everyone_, it’s a single, consistent experience that ties all your
|
||||
infrastructure tooling, resources, standards, owners, contributors, and
|
||||
administrators together in one place.
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
id: add-to-marketplace
|
||||
title: Add to Marketplace
|
||||
---
|
||||
|
||||
## Adding a Plugin to the Marketplace
|
||||
|
||||
To add a new plugin to the [plugin marketplace](https://backstage.io/plugins)
|
||||
create a file in `data/plugins` with your plugin's information. Example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Your Plugin
|
||||
author: Your Name
|
||||
authorUrl: # A link to information about the author E.g. Company url, github user profile, etc
|
||||
category: Monitoring # A single category e.g. CI, Machine Learning, Services, Monitoring
|
||||
description: A brief description of the plugin. # Max 170 characters
|
||||
documentation: # A link to your documentation E.g. Your github README
|
||||
iconUrl: # Used as the src attribute for your logo.
|
||||
# You can provide an external url or add your logo under static/img and provide a path
|
||||
# relative to static/ e.g. img/my-logo.png
|
||||
npmPackageName: # Your npm package name E.g. '@backstage/plugin-<etc>' quotes are required
|
||||
```
|
||||
@@ -71,11 +71,7 @@ Example:
|
||||
```yaml
|
||||
# In app-config.yaml
|
||||
proxy:
|
||||
'/frobs':
|
||||
target: 'http://api.frobsco.com/v1'
|
||||
changeOrigin: true
|
||||
pathRewrite:
|
||||
'^/proxy/frobs/': '/'
|
||||
'/frobs': http://api.frobsco.com/v1
|
||||
```
|
||||
|
||||
```ts
|
||||
@@ -86,9 +82,8 @@ fetch(`${backendUrl}/proxy/frobs/list`)
|
||||
.then(payload => setFrobs(payload as Frob[]));
|
||||
```
|
||||
|
||||
The proxy is powered by the `http-proxy-middleware` package, and supports all of
|
||||
its
|
||||
[configuration options](https://github.com/chimurai/http-proxy-middleware#options).
|
||||
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
|
||||
|
||||
@@ -15,20 +15,16 @@ dependencies, then run the following on your command line (invoking the
|
||||
yarn create-plugin
|
||||
```
|
||||
|
||||
<p align='center'>
|
||||
<img src='https://github.com/spotify/backstage/raw/master/docs/getting-started/create-plugin_output.png' width='600' alt='create plugin'>
|
||||
</p>
|
||||
|
||||
|
||||
This will create a new Backstage Plugin based on the ID that was provided. It
|
||||
will be built and added to the Backstage App automatically.
|
||||
|
||||
_If `yarn start` is already running you should be able to see the default page
|
||||
for your new plugin directly by navigating to
|
||||
`http://localhost:3000/my-plugin`._
|
||||
> If `yarn start` is already running you should be able to see the default page
|
||||
> for your new plugin directly by navigating to
|
||||
> `http://localhost:3000/my-plugin`.
|
||||
|
||||
<p align='center'>
|
||||
<img src='https://github.com/spotify/backstage/raw/master/docs/plugins/my-plugin_screenshot.png' width='600' alt='my plugin'>
|
||||
</p>
|
||||
|
||||
|
||||
You can also serve the plugin in isolation by running `yarn start` in the plugin
|
||||
directory. Or by using the yarn workspace command, for example:
|
||||
@@ -40,7 +36,3 @@ yarn workspace @backstage/plugin-welcome start # Also supports --check
|
||||
This method of serving the plugin provides quicker iteration speed and a faster
|
||||
startup and hot reloads. It is only meant for local development, and the setup
|
||||
for it can be found inside the plugin's `dev/` directory.
|
||||
|
||||
[Next Step - Structure of a plugin](structure-of-a-plugin.md)
|
||||
|
||||
[Back to Getting Started](../README.md)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
id: index
|
||||
title: Intro
|
||||
title: Intro to plugins
|
||||
---
|
||||
|
||||
Backstage is a single-page application composed of a set of plugins.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
id: plugin-development
|
||||
title: Plugin Development in Backstage
|
||||
title: Plugin Development
|
||||
---
|
||||
|
||||
Backstage plugins provide features to a Backstage App.
|
||||
@@ -10,28 +10,12 @@ type of content. Plugins all use a common set of platform APIs and reusable UI
|
||||
components. Plugins can fetch data from external sources using the regular
|
||||
browser APIs or by depending on external modules to do the work.
|
||||
|
||||
<!-- MOVED TO create-a-plugin.md ## Creating a new plugin
|
||||
On your command line, invoke the `backstage-cli` to create a new plugin:
|
||||
```bash
|
||||
yarn create-plugin
|
||||
```
|
||||
|
||||
|
||||
|
||||
This will create a new Backstage Plugin based on the ID that was provided. It will be built and
|
||||
added to the Backstage App automatically.
|
||||
|
||||
*If `yarn start` is already running you should be able to see the default page for your new
|
||||
plugin directly by navigating to `http://localhost:3000/my-plugin`.*
|
||||
|
||||
 -->
|
||||
|
||||
## Developing guidelines
|
||||
|
||||
- Consider writing plugins in `TypeScript`.
|
||||
- Plan the directory structure of your plugin so that it becomes easy to manage.
|
||||
- Prefer using the Backstage components, otherwise go with
|
||||
[Material-UI](https://material-ui.com/).
|
||||
- Prefer using the [Backstage components](https://backstage.io/storybook),
|
||||
otherwise go with [Material-UI](https://material-ui.com/).
|
||||
- Check out the shared Backstage APIs before building a new one.
|
||||
|
||||
## Plugin concepts / API
|
||||
|
||||
@@ -3,4 +3,73 @@ id: proxying
|
||||
title: Proxying
|
||||
---
|
||||
|
||||
## TODO
|
||||
## Overview
|
||||
|
||||
The Backstage backend comes packaged with a basic HTTP proxy, that can aid in
|
||||
reaching backend service APIs from frontend plugin code. See
|
||||
[Call Existing API](call-existing-api.md) for a description of when the proxy
|
||||
can be the best choice for communicating with an API.
|
||||
|
||||
## Getting Started
|
||||
|
||||
The plugin is already added to a default Backstage project.
|
||||
|
||||
In `packages/backend/src/index.ts`:
|
||||
|
||||
```ts
|
||||
const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));
|
||||
|
||||
const service = createServiceBuilder(module)
|
||||
.loadConfig(configReader)
|
||||
/** ... other routers ... */
|
||||
.addRouter('/proxy', await proxy(proxyEnv, '/proxy'));
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration for the proxy plugin lives under a `proxy` root key of your
|
||||
`app-config.yaml` file.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
# in app-config.yaml
|
||||
proxy:
|
||||
'/simple-example': http://simple.example.com:8080
|
||||
'/larger-example/v1':
|
||||
target: http://larger.example.com:8080/svc.v1
|
||||
headers:
|
||||
Authorization:
|
||||
$secret:
|
||||
env: EXAMPLE_AUTH_HEADER
|
||||
```
|
||||
|
||||
Each key under the proxy configuration entry is a route to match, below the
|
||||
prefix that the proxy plugin is mounted on. It must start with a slash. For
|
||||
example, if the backend mounts the proxy plugin as `/proxy`, the above
|
||||
configuration will lead to the proxy acting on backend requests to
|
||||
`/proxy/simple-example/...` and `/proxy/larger-example/v1/...`.
|
||||
|
||||
The value inside each route is either a simple URL string, or an object on the
|
||||
format accepted by
|
||||
[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware).
|
||||
|
||||
If the value is a string, it is assumed to correspond to:
|
||||
|
||||
```yaml
|
||||
target: <the string>
|
||||
changeOrigin: true
|
||||
pathRewrite:
|
||||
'^<url prefix><the string>/': '/'
|
||||
```
|
||||
|
||||
When the target is an object, it is given verbatim to `http-proxy-middleware`
|
||||
except with the following caveats for convenience:
|
||||
|
||||
- If `changeOrigin` is not specified, it is set to `true`. This is the most
|
||||
commonly useful value.
|
||||
- If `pathRewrite` is not specified, it is set to a single rewrite that removes
|
||||
the entire prefix and route. In the above example, a rewrite of
|
||||
`'^/proxy/larger-example/v1/': '/'` is added. That means that a request to
|
||||
`/proxy/larger-example/v1/some/path` will be translated to a request to
|
||||
`http://larger.example.com:8080/svc.v1/some/path`.
|
||||
|
||||
@@ -37,5 +37,3 @@ const myPluginRouteRef = createRouteRef({
|
||||
title: 'My Plugin',
|
||||
});
|
||||
```
|
||||
|
||||
[Back to References](../README.md)
|
||||
|
||||
@@ -55,7 +55,7 @@ ApiRef:
|
||||
|
||||
## githubAuth
|
||||
|
||||
Provides authentication towards Github APIs
|
||||
Provides authentication towards GitHub APIs
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
@@ -67,7 +67,7 @@ ApiRef:
|
||||
|
||||
## gitlabAuth
|
||||
|
||||
Provides authentication towards Gitlab APIs
|
||||
Provides authentication towards GitLab APIs
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
id: index
|
||||
title: Overview
|
||||
---
|
||||
|
||||
## Coming soon!
|
||||
@@ -1,12 +1,15 @@
|
||||
# Purpose
|
||||
---
|
||||
id: journey
|
||||
title: Future developer journey
|
||||
---
|
||||
|
||||
This RFC describes a possible journey of a future Backstage plugin developer as
|
||||
they build a plugin that touches many different aspects of a Backstage. The
|
||||
story invents many new things that are not part of Backstage today, but are
|
||||
things that I'm suggesting we should add as long term or north star goals. The
|
||||
idea is to discuss what parts of the story makes sense to aim for, and what we'd
|
||||
want to do differently or not at all. The "chapters" are numbered to make it a
|
||||
bit easier to comment on parts of the story.
|
||||
> This document describes a possible journey of a **_future_** Backstage plugin
|
||||
> developer as they build a plugin that touches many different aspects of a
|
||||
> Backstage. The story invents many new things that are not part of Backstage
|
||||
> today, but are things that I'm suggesting we should add as long term or north
|
||||
> star goals. The idea is to discuss what parts of the story makes sense to aim
|
||||
> for, and what we'd want to do differently or not at all. The "chapters" are
|
||||
> numbered to make it a bit easier to comment on parts of the story.
|
||||
|
||||
# The Protagonist
|
||||
|
||||
Reference in New Issue
Block a user