From 0deaa7daa828c7a60d143fc371e45d3f21c6378b Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 00:27:57 +0200 Subject: [PATCH 1/5] Add the user Getting Started page This comes from our README https://github.com/spotify/backstage\#getting-started --- docs/getting-started/index.md | 111 ++++++------------ .../running-backstage-locally.md | 84 +++++++++++++ 2 files changed, 123 insertions(+), 72 deletions(-) create mode 100644 docs/getting-started/running-backstage-locally.md diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index c1c6ea9231..4695ab75e9 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -1,84 +1,51 @@ --- id: index -title: Running Backstage Locally +title: Getting Started --- -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. +There are two different ways to get started with Backstage, either by creating a +standalone app, or by cloning this repo. Which method you use depends on what +you're planning to do. + +Creating a standalone instance makes it simpler to customize the application for +your needs whilst staying up to date with the project. You will also depend on +`@backstage` packages from NPM, making the project much smaller. This is the +recommended approach if you want to kick the tyres of Backstage or setup your +own instance. + +On the other hand, if you want to contribute plugins or to the project in +general, it's easier to fork and clone this project. That will let you stay up +to date with the latest changes, and gives you an easier path to make Pull +Requests towards this repo. + +### Creating a Standalone App + +Backstage provides the `@backstage/create-app` package to scaffold standalone +instances of Backstage. You will need to have +[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed +(currently v12), and [yarn](https://classic.yarnpkg.com/en/docs/install). You +will also need to have [Docker](https://docs.docker.com/engine/install/) +installed to use some features like Software Templates and TechDocs. + +Using `npx` you can then run the following to create an app in a chosen +subdirectory of your current working directory: ```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) +npx @backstage/create-app ``` -To get up and running with a local Backstage to evaluate it, let's clone it off -of GitHub and run an initial build. +You will be taken through a wizard to create your app, and the output should +look something like this. You can read more about this process +[here](https://backstage.io/docs/getting-started/create-an-app). -```bash -# Start from your local development folder -git clone git@github.com:spotify/backstage.git -cd backstage +### Contributing to Backstage -# Fetch our dependencies and run an initial build -yarn install -yarn tsc -yarn build -``` +You can read more in our +[CONTRIBUTING](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md) +guide, which can help you get setup with a Backstage development environment. -Phew! Now you have a local repository that's ready to run and to add any open -source contributions into. +### Next steps -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-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 -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](../plugins/create-a-plugin.md) -- [Structure of a Plugin](../plugins/structure-of-a-plugin.md) -- [Utility APIs](../api/utility-apis.md) - -[Back to Docs](../README.md) +Take a look at the +[Running Backstage Locally](/docs/getting-started/running-backstage-locally) +guide to learn how to set up Backstage, and how to develop on the platform. diff --git a/docs/getting-started/running-backstage-locally.md b/docs/getting-started/running-backstage-locally.md new file mode 100644 index 0000000000..04be6499c6 --- /dev/null +++ b/docs/getting-started/running-backstage-locally.md @@ -0,0 +1,84 @@ +--- +id: running-backstage-locally +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. + +```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-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 +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](../plugins/create-a-plugin.md) +- [Structure of a Plugin](../plugins/structure-of-a-plugin.md) +- [Utility APIs](../api/utility-apis.md) + +[Back to Docs](../README.md) From 3e85b8cf91a42dbf4effbd1c2b8004a72f0da0b3 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 00:28:16 +0200 Subject: [PATCH 2/5] Fix docs sidebar for docs gettings started --- microsite/sidebars.json | 1 + 1 file changed, 1 insertion(+) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index a3c11beeac..7b4c852f4d 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -12,6 +12,7 @@ ], "Getting Started": [ "getting-started/index", + "getting-started/running-backstage-locally", "getting-started/installation", "getting-started/development-environment", "getting-started/create-an-app", From 465701e058953fd7dfea04d519f55873480bccbd Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 00:35:32 +0200 Subject: [PATCH 3/5] Use relative file link in docs to refer other page --- docs/getting-started/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 4695ab75e9..c528ad34ad 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -46,6 +46,5 @@ guide, which can help you get setup with a Backstage development environment. ### Next steps -Take a look at the -[Running Backstage Locally](/docs/getting-started/running-backstage-locally) +Take a look at the [Running Backstage Locally](./running-backstage-locally.md) guide to learn how to set up Backstage, and how to develop on the platform. From 705e02f7af1b2ee8f7828fc30630190e253a07d8 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 00:55:07 +0200 Subject: [PATCH 4/5] Remove duplicate section in the README --- README.md | 28 +--------------------------- 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/README.md b/README.md index 4009864edc..65a2a05671 100644 --- a/README.md +++ b/README.md @@ -31,33 +31,7 @@ A detailed project roadmap, including already delivered milestones, is available ## Getting Started -There are two different ways to get started with Backstage, either by creating a standalone app, or by cloning this repo. Which method you use depends on what you're planning to do. - -Creating a standalone instance makes it simpler to customize the application for your needs whilst staying up to date with the project. You will also depend on `@backstage` packages from NPM, making the project much smaller. This is the recommended approach if you want to kick the tyres of Backstage or setup your own instance. - -On the other hand, if you want to contribute plugins or to the project in general, it's easier to fork and clone this project. That will let you stay up to date with the latest changes, and gives you an easier path to make Pull Requests towards this repo. - -### Creating a Standalone App - -Backstage provides the `@backstage/create-app` package to scaffold standalone instances of Backstage. You will need to have -[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed -(currently v12), and [yarn](https://classic.yarnpkg.com/en/docs/install). You will also need to have [Docker](https://docs.docker.com/engine/install/) installed to use some features like Software Templates and TechDocs. - -Using `npx` you can then run the following to create an app in a chosen subdirectory of your current working directory: - -```bash -npx @backstage/create-app -``` - -You will be taken through a wizard to create your app, and the output should look something like this. You can read more about this process [here](https://backstage.io/docs/getting-started/create-an-app) - -### Contributing to Backstage - -You can read more in our [CONTRIBUTING.md](./CONTRIBUTING.md#get-started) guide, which can help you get setup with a Backstage development environment. - -### Next steps - -Take a look at the [Getting Started](https://backstage.io/docs/getting-started/index) guide to learn how to set up Backstage, and how to develop on the platform. +Check out [the documentation](https://backstage.io/docs/getting-started) on how to start using Backstage. ## Documentation From 84b72fbad1869cc6a8b9f96341a88371752202e0 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 09:37:35 +0200 Subject: [PATCH 5/5] Update mkdocks.yml for Techdocs rendering of the docs --- mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index bcf4969892..10cd7df9b2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,7 +12,8 @@ nav: - Strategies for adopting: 'overview/adopting.md' - Logo assets: 'overview/logos.md' - Getting started: - - Running Backstage locally: 'getting-started/index.md' + - Getting Started: 'getting-started/index.md' + - Running Backstage locally: 'getting-started/running-backstage-locally.md' - Installation: 'getting-started/installation.md' - Local development: 'getting-started/development-environment.md' - Demo deployment: https://backstage-demo.roadie.io