From b902e63dd8bb0b659874bdb84bee699d31501683 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Fri, 12 Jun 2020 15:52:31 +0200 Subject: [PATCH] Update README.md --- docs/README.md | 8 +-- docs/getting-started/README.md | 59 ++++++++++++++++++- docs/getting-started/create-a-plugin.md | 4 +- docs/getting-started/structure-of-a-plugin.md | 2 +- plugins/catalog-backend/README.md | 28 +++++++-- 5 files changed, 86 insertions(+), 15 deletions(-) diff --git a/docs/README.md b/docs/README.md index 89160ce9e5..86ca88b75c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,10 +1,10 @@ # Documentation -Check out or see the table of content below. +Check out or see the table of contents below. -- [Architecture and terminology](architecture-terminology.md) -- [Getting started](getting-started/README.md) +- [Architecture and Terminology](architecture-terminology.md) +- [Getting Started](getting-started/README.md) - [References](reference/README.md) - [Publishing](publishing.md) - [Designing for Backstage](design.md) -- [How to add an auth provider](auth/add-auth-provider.md) +- [How to Add an Auth Provider](auth/add-auth-provider.md) diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index eec3aec78b..32830c9bb3 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -1,5 +1,60 @@ # Getting started with Backstage +## Running Backstage Locally + +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. + +```bash +# Start from your local development folder +git clone git@github.com:spotify/backstage.git +cd backstage + +# Fetch our dependencies and run an initial build +yarn install +yarn tsc +yarn build +``` + +Phew! Now you have a local repository that's ready to run and to add any open +source contributions into. + +We are now going to launch two things: an example Backstage frontend app, and an +example Backstage backend that the frontend talks to. You are going to need two +terminal windows, both starting from the Backstage project root. + +In the first window, run + +```bash +cd packages/backend +yarn start +``` + +That starts up a backend instance on port 7000. + +In the other window, we will first populate the catalog with some nice mock data +to look at, and then launch the frontend. These commands are run from the +project root, not inside the backend directory. + +```bash +yarn lerna run mock-catalog-data +yarn start +``` + +That starts up the frontend on port 3000, and should automatically open a +browser window showing it. + +Congratulations! That should be it. Let us know how it went +[on discord](https://discord.gg/EBHEGzX), file issues for any +[feature](https://github.com/spotify/backstage/issues/new?labels=help+wanted&template=feature_template.md) +or +[plugin suggestions](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME), +or +[bugs](https://github.com/spotify/backstage/issues/new?labels=bug&template=bug_template.md) +you have, and feel free to +[contribute](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)! + ## Creating a Plugin The value of Backstage grows with every new plugin that gets added. Here is a @@ -7,8 +62,8 @@ collection of tutorials that will guide you through setting up and extending an instance of Backstage with your own plugins. - [Development Environment](development-environment.md) -- [Create a Backstage plugin](create-a-plugin.md) -- [Structure of a plugin](structure-of-a-plugin.md) +- [Create a Backstage Plugin](create-a-plugin.md) +- [Structure of a Plugin](structure-of-a-plugin.md) - [Utility APIs](utility-apis.md) - Using Backstage components (TODO) diff --git a/docs/getting-started/create-a-plugin.md b/docs/getting-started/create-a-plugin.md index 778623f07a..93c8a4c760 100644 --- a/docs/getting-started/create-a-plugin.md +++ b/docs/getting-started/create-a-plugin.md @@ -1,8 +1,8 @@ -# Backstage Plugins +# Create a Backstage Plugin A Backstage Plugin adds functionality to Backstage. -## Create a plugin +## Create a Plugin To create a new plugin, make sure you've run `yarn install` and installed dependencies, then run the following on your command line (invoking the diff --git a/docs/getting-started/structure-of-a-plugin.md b/docs/getting-started/structure-of-a-plugin.md index 591ffc27d2..fcfb2c0d46 100644 --- a/docs/getting-started/structure-of-a-plugin.md +++ b/docs/getting-started/structure-of-a-plugin.md @@ -1,4 +1,4 @@ -# Structure of a newly created plugin +# Structure of a Plugin Nice, you have a new plugin! We'll soon see how we can develop it into doing great things. But first off, let's look at what we get out of the box. diff --git a/plugins/catalog-backend/README.md b/plugins/catalog-backend/README.md index 8009fa89c0..2d6b365f90 100644 --- a/plugins/catalog-backend/README.md +++ b/plugins/catalog-backend/README.md @@ -1,16 +1,32 @@ # Catalog Backend -WORK IN PROGRESS - This is the backend part of the default catalog plugin. -It responds to requests from the frontend part, and fulfills them by delegating -to your existing catalog related services. +It comes with a builtin database backed implementation of the catalog, that can store +and serve your catalog for you. + +It can also act as a bridge to your existing catalog solutions, either ingesting their +data to store in the database, or by effectively proxying calls to an external catalog +service. ## Getting Started -After starting the backend, you can issue the `yarn mock-catalog-data` command -in this directory to populate the catalog with some mock entities. +This backend plugin can be started in a standalone mode from directly in this package +with `yarn start`. However, it will have limited functionality and that process is +most convenient when developing the catalog backend plugin itself. + +To evaluate the catalog and have a greater amount of functionality available, instead do + +```bash +# in one terminal window, run this from from the very root of the Backstage project +cd packages/backend +yarn start + +# open another terminal window, and run the following from the very root of the Backstage project +yarn lerna run mock-catalog-data +``` + +This will launch the full example backend and populate its catalog with some mock entities. ## Links