diff --git a/docs/README.md b/docs/README.md index 904fdf3356..6763554afb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ better yet, a pull request. - 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) - Getting started diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md new file mode 100644 index 0000000000..9093e98e2e --- /dev/null +++ b/docs/overview/architecture-overview.md @@ -0,0 +1,190 @@ +# Typical Backstage architecture + +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 +plugin and the service catalog. + +There are 3 main components in this architecture: + +1. The core Backstage UI +2. The UI plugins and their backing services +3. Databases + +Running this architecture in a real environment typically involves +containerising the components. Various commands are provided for accomplishing +this. + +![The architecture of a basic Backstage application](./architecture-overview/backstage-typical-architecture.png) + +# The UI + +The UI is a thin, client-side wrapper around a set of plugins. It provides some +core UI components and libraries for shared activities such as config +management. [[live demo](https://backstage-demo.roadie.io/)] + +![UI with different components highlighted](./architecture-overview/core-vs-plugin-components-highlighted.png) + +Each plugin typically makes itself available in the UI on a dedicated URL. For +example, the lighthouse plugin is registered with the UI on `/lighthouse`. +[[live demo](https://backstage-demo.roadie.io/lighthouse)] + +![The lighthouse plugin UI](./architecture-overview/lighthouse-plugin.png) + +The Circle CI plugin is available on `/circleci`. + +![Circle CI Plugin UI](./architecture-overview/circle-ci.png) + +# Plugins and plugin backends + +Each plugin is a client side application which mounts itself on the UI. Plugins +are written in TypeScript or JavaScript. They each live in their own directory +in `backstage/plugins`. For example, the source code for the lighthouse plugin +is available at +[backstage/plugins/lighthouse](https://github.com/spotify/backstage/tree/master/plugins/lighthouse). + +## Installing plugins + +Plugins are typically loaded by the UI in your Backstage applications +`plugins.ts` file. For example, +[here](https://github.com/spotify/backstage/blob/master/packages/app/src/plugins.ts) +is that file in the Backstage sample app. + +Plugins can be enabled, and passed configuration in `apis.ts`. For example, +[here](https://github.com/spotify/backstage/blob/master/packages/app/src/apis.ts) +is that file in the Backstage sample app. + +This is how the lighthouse plugin would be enabled in a typical Backstage +application: + +```tsx +import { ApiHolder, ApiRegistry } from '@backstage/core'; +import { + lighthouseApiRef, + LighthouseRestApi, +} from '@backstage/plugin-lighthouse'; + +const builder = ApiRegistry.builder(); + +export const lighthouseApi = new LighthouseRestApi(/* URL of the lighthouse microservice! */); +builder.add(lighthouseApiRef, lighthouseApi); + +export default builder.build() as ApiHolder; +``` + +As of this moment, there is no config based install procedure for plugins. Some +code changes are required. + +## Plugin architecture + +Architecturally, plugins can take three forms: + +1. Standalone +2. Service backed +3. Third-party backed + +### Standalone plugins + +Standalone plugins run entirely in the browser. +[The tech radar plugin](https://backstage-demo.roadie.io/tech-radar), for +example, simply renders hard-coded information. It doesn't make any API requests +to other services. + +![tech radar plugin ui](./architecture-overview/tech-radar-plugin.png) + +The architecture of the Tech Radar installed into a Backstage app is very +simple. + +![ui and tech radar plugin connected together](./architecture-overview/tech-radar-plugin-architecture.png) + +### Service backed plugins + +Service backed plugins make API requests to a service which is within the +purview of the organisation running Backstage. + +The lighthouse plugin, for example, makes requests to the +[lighthouse-audit-service](https://github.com/spotify/lighthouse-audit-service). +The lighthouse-audit-service is a microservice which runs a copy of Google's +[Lighthouse library](https://github.com/GoogleChrome/lighthouse/) and stores the +results in a PostgreSQL database. + +Its architecture looks like this: + +![lighthouse plugin backed to microservice and database](./architecture-overview/lighthouse-plugin-architecture.png) + +The service catalog in Backstage is another example of a service backed plugin. +It retrieves a list of services, or "entities", from the Backstage Backend +service and renders them in a table for the user. + +### Third-party backed plugins + +Third-party backed plugins are similar to service backed plugins. The main +difference is that the service which backs the plugin is hosted outside of the +ecosystem of the company hosting Backstage. + +The Circle CI plugin is an example of a third-party backed plugin. Circle CI is +a SaaS service which can be used without any knowledge of Backstage. It has an +API which a Backstage plugin consumes to display content. + +Requests which go to Circle CI from the users browser are passed through a proxy +service that Backstage provides. Without this, the requests would be blocked by +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. + +![CircleCi plugin talking to proxy talking to SaaS Circle CI](./architecture-overview/circle-ci-plugin-architecture.png) + +# Databases + +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. + +To learn more about the future of databases and Backstage, see the following two +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) + +# Containerization + +The example Backstage architecture shown above would Dockerize into three +separate docker images. + +1. The frontend container +2. The backend container +3. The lighthouse audit service container + +![Boxes around the architecture to indicate how it is containerised](./architecture-overview/containerised.png) + +The frontend container can be built with a provided command. + +```bash +yarn install +yarn tsc +yarn build +yarn run docker-build +``` + +Running this will simply generate a Docker container containing the contents of +the UIs `dist` directory. The resulting container will be about 50MB in size. + +The backend container can be built by running the following command in the +`packages/backend` directory. + +```bash +yarn run build-image +``` + +This will create a ~500MB container called `example-backend`. + +The lighthouse-audit-service container is already publicly available in Docker +Hub and can be downloaded and ran with + +```bash +docker run spotify/lighthouse-audit-service:latest +``` diff --git a/docs/overview/architecture-overview/backstage-typical-architecture.png b/docs/overview/architecture-overview/backstage-typical-architecture.png new file mode 100644 index 0000000000..44b9967d28 Binary files /dev/null and b/docs/overview/architecture-overview/backstage-typical-architecture.png differ diff --git a/docs/overview/architecture-overview/circle-ci-plugin-architecture.png b/docs/overview/architecture-overview/circle-ci-plugin-architecture.png new file mode 100644 index 0000000000..bc1f2d97cc Binary files /dev/null and b/docs/overview/architecture-overview/circle-ci-plugin-architecture.png differ diff --git a/docs/overview/architecture-overview/circle-ci.png b/docs/overview/architecture-overview/circle-ci.png new file mode 100644 index 0000000000..c5695196f1 Binary files /dev/null and b/docs/overview/architecture-overview/circle-ci.png differ diff --git a/docs/overview/architecture-overview/containerised.png b/docs/overview/architecture-overview/containerised.png new file mode 100644 index 0000000000..55da3c2c36 Binary files /dev/null and b/docs/overview/architecture-overview/containerised.png differ diff --git a/docs/overview/architecture-overview/core-vs-plugin-components-highlighted.png b/docs/overview/architecture-overview/core-vs-plugin-components-highlighted.png new file mode 100644 index 0000000000..7d08fc5e36 Binary files /dev/null and b/docs/overview/architecture-overview/core-vs-plugin-components-highlighted.png differ diff --git a/docs/overview/architecture-overview/lighthouse-plugin-architecture.png b/docs/overview/architecture-overview/lighthouse-plugin-architecture.png new file mode 100644 index 0000000000..0da5d6f042 Binary files /dev/null and b/docs/overview/architecture-overview/lighthouse-plugin-architecture.png differ diff --git a/docs/overview/architecture-overview/lighthouse-plugin.png b/docs/overview/architecture-overview/lighthouse-plugin.png new file mode 100644 index 0000000000..9692fc0833 Binary files /dev/null and b/docs/overview/architecture-overview/lighthouse-plugin.png differ diff --git a/docs/overview/architecture-overview/tech-radar-plugin-architecture.png b/docs/overview/architecture-overview/tech-radar-plugin-architecture.png new file mode 100644 index 0000000000..d55be5ee82 Binary files /dev/null and b/docs/overview/architecture-overview/tech-radar-plugin-architecture.png differ diff --git a/docs/overview/architecture-overview/tech-radar-plugin.png b/docs/overview/architecture-overview/tech-radar-plugin.png new file mode 100644 index 0000000000..dbf39b6c63 Binary files /dev/null and b/docs/overview/architecture-overview/tech-radar-plugin.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 613c9b7216..168ebb4b37 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,7 @@ site_description: 'Main documentation for Backstage features and platform APIs' nav: - 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' - Getting started: