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..326cfdd8b4 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: @@ -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) - [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 e1c4c7072f..904fdf3356 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,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/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 0c8879c96b..613c9b7216 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,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)