diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dca9e678dc..6200f3235b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,10 @@ If you are proposing a feature: - Remember that this is a volunteer-driven project, and that contributions are welcome :) +## Add your company to ADOPTERS + +Have you started using Backstage? Adding your company to [ADOPTERS](ADOPTERS.md) really helps the project. + # Get Started! So...feel ready to jump in? Let's do this. Head over to the [Getting Started guide](https://github.com/spotify/backstage#getting-started) 👏🏻💯 diff --git a/README.md b/README.md index 975efee824..8e7574e128 100644 --- a/README.md +++ b/README.md @@ -59,11 +59,9 @@ The Backstage platform consists of a number of different components: - **app** - Main web application that users interact with. It's built up by a number of different _Plugins_. This repo contains an example implementation of an app (located in `packages/app`) and you can easily get started with your own app by [creating one](docs/create-an-app.md). - [**plugins**](https://github.com/spotify/backstage/tree/master/plugins) - Each plugin is treated as a self-contained web app and can include almost any type of content. Plugins all use a common set of platform API's and reusable UI components. Plugins can fetch data either from the _backend_ or through any RESTful API exposed through the _proxy_. - [**service catalog**](https://github.com/spotify/backstage/tree/master/packages/backend) - Service that holds the model of your software ecosystem, including organisational information and what team owns what software. The backend also has a Plugin model for extending its graph. -- **proxy** \* - Terminates HTTPS and exposes any RESTful API to Plugins. +- [**proxy**](https://github.com/spotify/backstage/tree/master/plugins/proxy-backend) - Terminates HTTPS and exposes any RESTful API to Plugins. - **identity** - A backend service that holds your organisation's metadata. -_\* not yet released_ - ## Getting started To run a Backstage app, you will need to have the following installed: @@ -86,7 +84,7 @@ And that's it! You are good to go 👍 ### Next step -Take a look at the [Getting Started](docs/getting-started/README.md) guide to learn more about how to extend the functionality with Plugins. +Take a look at the [Getting Started](docs/getting-started/index.md) guide to learn how to set up Backstage, and how to develop on the platform. ## Documentation @@ -108,6 +106,7 @@ We would love your help in building Backstage! See [CONTRIBUTING](CONTRIBUTING.m - [RFCs](https://github.com/spotify/backstage/labels/rfc) - Help shape the technical direction - [FAQ](docs/FAQ.md) - Frequently Asked Questions - [Code of Conduct](CODE_OF_CONDUCT.md) - This is how we roll +- [Adopters](ADOPTERS.md) - Companies already using Backstage - [Blog](https://backstage.io/blog/) - Announcements and updates - [Newsletter](https://mailchi.mp/spotify/backstage-community) - Give us a star ⭐️ - If you are using Backstage or think it is an interesting project, we would love a star ❤️ diff --git a/docs/README.md b/docs/README.md index bed5fe8fbe..904fdf3356 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,8 +32,12 @@ better yet, a pull request. - [API](features/software-catalog/api.md) - Software creation templates - [Overview](features/software-templates/index.md) - - [Configure templates](features/software-templates/configure-templates.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) @@ -48,7 +52,7 @@ better yet, a pull request. - [Overview](plugins/index.md) - [Existing plugins](plugins/existing-plugins.md) - [Creating a new plugin](plugins/create-a-plugin.md) - - [Developing a plugin](plugins/developing-plugins.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) diff --git a/docs/auth/oauth.md b/docs/auth/oauth.md index 981ae18057..d348dd2f93 100644 --- a/docs/auth/oauth.md +++ b/docs/auth/oauth.md @@ -9,10 +9,11 @@ to various third party APIs. There are occasions when the user wants to perform actions towards third party services that require authorization via OAuth. Backstage provides standardized [Utility APIs](../api/utility-apis.md) such as the -[GoogleAuthApi](../../packages/core-api/src/apis/definitions/auth.ts) for that -use-case. Backstage also includes a set of implementations of these APIs that -integrate with the [auth-backend](../../plugins/auth-backend) plugin to provide -a popup-based OAuth flow. +[GoogleAuthApi](https://github.com/spotify/backstage/blob/master/packages/core-api/src/apis/definitions/auth.ts) +for that use-case. Backstage also includes a set of implementations of these +APIs that integrate with the +[auth-backend](https://github.com/spotify/backstage/tree/master/plugins/auth-backend) +plugin to provide a popup-based OAuth flow. ## Background @@ -51,8 +52,9 @@ easier to make authenticated requests inside a plugin. ## OAuth Flow The following describes the OAuth flow implemented by the -[auth-backend](../../plugins/auth-backend) and -[DefaultAuthConnector](../../packages/core-api/src/lib/AuthConnector/DefaultAuthConnector.ts) +[auth-backend](https://github.com/spotify/backstage/tree/master/plugins/auth-backend) +and +[DefaultAuthConnector](https://github.com/spotify/backstage/blob/master/packages/core-api/src/lib/AuthConnector/DefaultAuthConnector.ts) in `@backstage/core-api`. Component and APIs can request Access or ID Tokens from any available Auth diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 926cfe5b9c..68cee2352c 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -312,7 +312,7 @@ Apart from being a string, the software catalog leaves the format of this field open to implementers to choose. Most commonly, it is set to the ID or email of a group of people in an organizational structure. -## +## Kind: Template Describes the following entity kind: diff --git a/docs/features/software-templates/extending/create-your-own-templater.md b/docs/features/software-templates/extending/create-your-own-templater.md index fd3b7d395f..947190c5e5 100644 --- a/docs/features/software-templates/extending/create-your-own-templater.md +++ b/docs/features/software-templates/extending/create-your-own-templater.md @@ -43,7 +43,7 @@ As you can see in the above code a `TemplaterBuilder` is created and the default This `TemplaterKey` is used to select the correct templater from the `spec.templater` in the -[Template Entity](../software-catalog/descriptor-format.md#kind-template). +[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 `TemplaterBuilder`. @@ -73,9 +73,9 @@ follows: - `directory`- the skeleton directory returned from the `Preparer`, more info at [Create your own preparer](./create-your-own-preparer.md). - `values` - a json object which will resemble the `spec.schema` from the - [Template Entity](../software-catalog/descriptor-format.md#kind-template) + [Template Entity](../../software-catalog/descriptor-format.md#kind-template) which is defined here under spec.schema`. More info can be found here - [Register your own template](./register-your-own-template.md#adding-form-values-in-the-scaffolder-wizard) + [Register your own template](../adding-templates.md#adding-form-values-in-the-scaffolder-wizard) - `logStream` - a stream that you can write to for displaying in the frontend. - `dockerClient` - a [dockerode](https://github.com/apocas/dockerode) client to be able to run docker containers. diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index 04ae53accb..c7358518cd 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -29,7 +29,7 @@ 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 non-existing github repository name in the format `organistaion/reponame`. -![Enter backstage vars](./assets/template-picked-1.png) +![Enter backstage vars](./assets/template-picked-2.png) ### Run! diff --git a/docs/getting-started/customize-app-look-and-feel.md b/docs/getting-started/customize-app-look-and-feel.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/getting-started/development-environment.md b/docs/getting-started/development-environment.md index efceef5892..02729e5bb4 100644 --- a/docs/getting-started/development-environment.md +++ b/docs/getting-started/development-environment.md @@ -50,7 +50,8 @@ system resources and slow things down. ## Package Scripts -There are many commands to be found in the root [package.json](package.json), +There are many commands to be found in the root +[package.json](https://github.com/spotify/backstage/blob/master/package.json), here are some useful ones: ```python @@ -80,7 +81,9 @@ yarn diff # Make sure all plugins are up to date with the latest plugin template yarn create-plugin # Create a new plugin ``` -> See [package.json](/package.json) for other yarn commands/options. +> 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) diff --git a/docs/plugins/create-a-plugin.md b/docs/plugins/create-a-plugin.md index dfc86ef1f5..fa91e38b06 100644 --- a/docs/plugins/create-a-plugin.md +++ b/docs/plugins/create-a-plugin.md @@ -24,7 +24,7 @@ for your new plugin directly by navigating to `http://localhost:3000/my-plugin`._

- my plugin + my plugin

You can also serve the plugin in isolation by running `yarn start` in the plugin diff --git a/docs/plugins/developing-plugins.md b/docs/plugins/developing-plugins.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/plugins/existing-plugins.md b/docs/plugins/existing-plugins.md index e69de29bb2..bd6fd19691 100644 --- a/docs/plugins/existing-plugins.md +++ b/docs/plugins/existing-plugins.md @@ -0,0 +1,11 @@ +# Existing plugins + +## Open source plugins + +The full list of open source plugins can be found +[here](https://github.com/spotify/backstage/tree/master/plugins). + +## Plugin gallery + +TODO: In the future we would like to have something similar to +https://grafana.com/grafana/plugins diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 0c4f77f299..5021ac9896 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -5,15 +5,14 @@ Backstage is a single-page application composed of a set of plugins. Our goal for the plugin ecosystem is that the definition of a plugin is flexible enough to allow you to expose pretty much any kind of infrastructure or software development tool as a plugin in Backstage. By following strong -[design guidelines](https://github.com/spotify/backstage/blob/master/docs/design.md) -we ensure the the overall user experience stays consistent between plugins. +[design guidelines](../dls/design.md) we ensure the the overall user experience +stays consistent between plugins. ![plugin](my-plugin_screenshot.png) ## Creating a plugin -To create a plugin, follow the steps outlined -[here](https://github.com/spotify/backstage/blob/master/docs/getting-started/create-a-plugin.md). +To create a plugin, follow the steps outlined [here](create-a-plugin.md). ## Suggesting a plugin diff --git a/docs/plugins/publishing.md b/docs/plugins/publishing.md index 630624f304..76997c30d2 100644 --- a/docs/plugins/publishing.md +++ b/docs/plugins/publishing.md @@ -3,9 +3,10 @@ ## NPM NPM packages are published through CI/CD in the -[.github/workflows/master.yml](../../.github/workflows/master.yml) workflow. -Every commit that is merged to master will be checked for new versions of all -public packages, and any new versions will automatically be published to NPM. +[.github/workflows/master.yml](https://github.com/spotify/backstage/blob/master/.github/workflows/master.yml) +workflow. Every commit that is merged to master will be checked for new versions +of all public packages, and any new versions will automatically be published to +NPM. ### Creating a new release diff --git a/docs/plugins/structure-of-a-plugin.md b/docs/plugins/structure-of-a-plugin.md index 9d15517e03..ceacf578fe 100644 --- a/docs/plugins/structure-of-a-plugin.md +++ b/docs/plugins/structure-of-a-plugin.md @@ -102,6 +102,6 @@ environment you will probably face challenges like CORS policies and/or backend-side authorization. To smooth this process out you can use proxy - either the one you already have (like nginx/haproxy/etc) or the proxy-backend plugin that we provide for the backstage backend. -[Read more](../../plugins/proxy-backend/README.md) +[Read more](https://github.com/spotify/backstage/blob/master/plugins/proxy-backend/README.md) [Back to Getting Started](../README.md) diff --git a/mkdocs.yml b/mkdocs.yml index d5e89a0412..613c9b7216 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,7 +30,6 @@ nav: - API: 'features/software-catalog/api.md' - Software creation templates: - Overview: 'features/software-templates/index.md' - - Configure templates: 'features/software-templates/configure-templates.md' - Adding templates: 'features/software-templates/adding-templates.md' - Extending the Scaffolder: - Overview: 'features/software-templates/extending/index.md' @@ -51,7 +50,7 @@ nav: - Overview: 'plugins/index.md' - Existing plugins: 'plugins/existing-plugins.md' - Creating a new plugin: 'plugins/create-a-plugin.md' - - Developing a plugin: 'plugins/developing-plugins.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' diff --git a/plugins/proxy-backend/README.md b/plugins/proxy-backend/README.md index 315178dac6..d12031f495 100644 --- a/plugins/proxy-backend/README.md +++ b/plugins/proxy-backend/README.md @@ -14,13 +14,13 @@ To run it within the backend do: 1. Register the router in `packages/backend/src/index.ts`: -``` +```ts const proxyEnv = useHotMemoize(module, () => createEnv('proxy')); const service = createServiceBuilder(module) - .loadConfig(configReader) - /** several different routers */ - .addRouter('/', await proxy(proxyEnv)); + .loadConfig(configReader) + /** several different routers */ + .addRouter('/', await proxy(proxyEnv)); ``` 2. Start the backend @@ -33,5 +33,4 @@ This will launch the full example backend. ## Links -- (http-proxy-middleware)[https://www.npmjs.com/package/http-proxy-middleware] -- (The Backstage homepage)[https://backstage.io] +- [http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware) diff --git a/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml b/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml index d97e151313..543c8fd49a 100644 --- a/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml +++ b/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml @@ -3,7 +3,7 @@ kind: Template metadata: name: springboot-template title: Spring Boot GRPC Service - description: Standard Spring Boot (Java) microservice with recommended configuration fpr GRPRC + description: Standard Spring Boot (Java) microservice with recommended configuration for GRPRC tags: - Recommended - Java diff --git a/plugins/scaffolder-backend/src/scaffolder/stages/templater/helpers.test.ts b/plugins/scaffolder-backend/src/scaffolder/stages/templater/helpers.test.ts index 02bc801385..3e59ed50cb 100644 --- a/plugins/scaffolder-backend/src/scaffolder/stages/templater/helpers.test.ts +++ b/plugins/scaffolder-backend/src/scaffolder/stages/templater/helpers.test.ts @@ -17,6 +17,7 @@ import Stream, { PassThrough } from 'stream'; import os from 'os'; import fs from 'fs'; import Docker from 'dockerode'; +import { Writable } from 'stream'; import { runDockerContainer } from './helpers'; describe('helpers', () => { @@ -26,9 +27,15 @@ describe('helpers', () => { jest .spyOn(mockDocker, 'run') .mockResolvedValue([{ Error: null, StatusCode: 0 }]); - jest - .spyOn(mockDocker, 'pull') - .mockResolvedValue([{ Error: null, StatusCode: 0 }]); + jest.spyOn(mockDocker, 'pull').mockImplementation((async ( + _image: string, + _something: any, + handler: (err: Error | undefined, stream: Writable) => void, + ) => { + const mockStream = new Writable(); + handler(undefined, mockStream); + mockStream.end(); + }) as any); }); describe('runDockerContainer', () => { diff --git a/plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPage.tsx b/plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPage.tsx index c486ee1c9c..98a94d48c1 100644 --- a/plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPage.tsx +++ b/plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPage.tsx @@ -23,17 +23,12 @@ import { Lifecycle, Page, pageTheme, + Progress, SupportButton, useApi, } from '@backstage/core'; import { catalogApiRef } from '@backstage/plugin-catalog'; -import { - Button, - Grid, - LinearProgress, - Link, - Typography, -} from '@material-ui/core'; +import { Button, Grid, Typography, Link } from '@material-ui/core'; import React, { useEffect } from 'react'; import { Link as RouterLink } from 'react-router-dom'; import useStaleWhileRevalidate from 'swr'; @@ -95,13 +90,7 @@ export const ScaffolderPage: React.FC<{}> = () => { documentation, ...). - - NOTE! This feature is WIP. You can follow progress{' '} - - here - - . - + {!templates && isValidating && } {templates && !templates.length && ( Shoot! Looks like you don't have any templates. Check out the @@ -111,7 +100,6 @@ export const ScaffolderPage: React.FC<{}> = () => { )} - {!templates && isValidating && } {templates && templates?.length > 0 &&