From 90b157c99939d80265ff99611b602c596fef226b Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Wed, 12 Apr 2023 14:31:26 -0500 Subject: [PATCH 1/3] Removed running-backstage-locally.md Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- docs/features/kubernetes/installation.md | 3 +- docs/features/techdocs/getting-started.md | 5 +- docs/getting-started/create-an-app.md | 8 +- docs/getting-started/index.md | 4 +- .../running-backstage-locally.md | 106 ------------------ microsite/sidebars.json | 1 - mkdocs.yml | 1 - 7 files changed, 8 insertions(+), 120 deletions(-) delete mode 100644 docs/getting-started/running-backstage-locally.md diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index 17028ef90f..89484ca01b 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -175,8 +175,7 @@ export default async function createPlugin( ## Running Backstage locally -Start the frontend and the backend app by -[running Backstage locally](../../getting-started/running-backstage-locally.md). +Start the frontend and the backend app by running `yarn dev` ## Configuration diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 090539a6b1..8c140f5b6c 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -286,10 +286,7 @@ Note: We recommend Python version 3.7 or higher. ## Running Backstage locally -Start the frontend and the backend app by -[running Backstage locally](../../getting-started/running-backstage-locally.md). - -Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/) +Start the frontend and the backend app by running `yarn dev`, this will launch [http://localhost:3000/](http://localhost:3000/) in your browser, from there you can navigate to [http://localhost:3000/docs/](http://localhost:3000/docs/) to see all your documentation sites. ## Additional reading diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index ba5050a73b..5169c07ee8 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -10,8 +10,8 @@ App. A Backstage App is a monorepo setup with `lerna` that includes everything you need to run Backstage in your own environment. -If you intend to develop a plugin or contribute to the Backstage project, you -may want to [Run Backstage Locally](./running-backstage-locally.md) instead. +If you intend to contribute a plugin, new feature, or bug fix to the Backstage project, you +may want to read the [Contributors](./contributors.md) guide instead. ## Create an app @@ -28,7 +28,7 @@ don't worry about the choice, it's easy to change later! Here is a The easiest way to run the create app package is with `npx`: ```bash -npx @backstage/create-app +npx @backstage/create-app@latest ``` This will create a new Backstage App inside the current folder. The name of the @@ -108,7 +108,7 @@ example [here](https://www.python.org/downloads/) to install it. Install yarn on your system with `npm install --global yarn` or for more details refer to the -[prerequisites](https://backstage.io/docs/getting-started/running-backstage-locally#prerequisites) +[prerequisites](https://backstage.io/docs/getting-started/#prerequisites) ## Run the app diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 2617cfb654..995413b2c5 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -14,9 +14,9 @@ This guide assumes a basic understanding of working on a Linux based operating system using tools like apt-get, npm, yarn, curl. Docker knowledge is also helpful for making the best use of your Backstage installation. -If you are planning to contribute plugins or the project in general, we advise +If you are planning to contribute plugins or to the project in general, we advise you to use the -[Getting Started for Contributors](https://backstage.io/docs/getting-started/running-backstage-locally) +[Contributors](https://backstage.io/docs/getting-started/contributors) guide to do a repository-based installation. ### Prerequisites diff --git a/docs/getting-started/running-backstage-locally.md b/docs/getting-started/running-backstage-locally.md deleted file mode 100644 index d56bdf7990..0000000000 --- a/docs/getting-started/running-backstage-locally.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -id: running-backstage-locally -title: Running Backstage Locally -description: Documentation on How to run Backstage Locally ---- - -To develop a plugin or contribute to the Backstage project, we recommend cloning -the Backstage repository and running locally in development mode. If you are not -trying to contribute, follow the instructions to -[Create an App](./create-an-app.md) instead. - -## Prerequisites - -- Node.js - -First make sure you are using Node.js with an [Active LTS Release](https://nodejs.org/en/about/releases/). -This is made easy with a version manager such as -[nvm](https://github.com/nvm-sh/nvm) which allows for version switching. - -```bash -# Installing current LTS release -nvm install --lts -> Installing latest LTS version. -> Downloading and installing node v16.16.0... -> Now using node v16.16.0 (npm v8.11.0) - -# Checking your version -node --version -> v16.16.0 -``` - -- Yarn - -Please refer to the -[installation instructions for Yarn](https://classic.yarnpkg.com/en/docs/install/). - -- Docker - -We use Docker for few of our core features. So, you will need Docker installed -locally to use features like Software Templates and TechDocs. Please refer to -the -[installation instructions for Docker](https://docs.docker.com/engine/install/). - -## Clone and Install - -To get up and running with a local Backstage to evaluate it, let's clone it off -of GitHub and run an initial install. - -```bash -# Start from your local development folder -git clone --depth 1 https://github.com/backstage/backstage.git -cd backstage - -# Install our dependencies -yarn install -``` - -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. These can both be launched -through the following command: - -```bash -# From your Backstage root directory, launches both the frontend and backend -yarn dev -``` - -If you prefer to run the frontend and backend separately, you can instead use `yarn start` -and `yarn start-backend` in two separate terminal windows. - -Which ever way you choose, you will now have a backend instance running on port 7007, -and the frontend running on port 3000. A browser window should also automatically open, -showing the frontend. - -## Authentication - -When Backstage starts, you can choose to enter as a Guest user and start -exploring. - -But you can also set up any of the available authentication methods. The easiest -option will be GitHub. To setup GitHub authentication in Backstage, see -[these instructions](https://github.com/backstage/backstage/tree/master/plugins/auth-backend#github). - ---- - -Congratulations! That should be it. Let us know how it went -[on discord](https://discord.gg/backstage-687207715902193673), file issues for any -[feature](https://github.com/backstage/backstage/issues/new?labels=help+wanted&template=feature_template.md) -or -[plugin suggestions](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME), -or -[bugs](https://github.com/backstage/backstage/issues/new?labels=bug&template=bug_template.md) -you have, and feel free to -[contribute](https://github.com/backstage/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. - -- [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) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index b3e6f07b0e..e4909deecd 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -34,7 +34,6 @@ "getting-started/index", "getting-started/configuration", "getting-started/create-an-app", - "getting-started/running-backstage-locally", { "type": "category", "label": "App configuration", diff --git a/mkdocs.yml b/mkdocs.yml index 4a75c3f67f..742b3e2ca6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,7 +23,6 @@ nav: - Getting Started: - Getting Started: 'getting-started/index.md' - Create an App: 'getting-started/create-an-app.md' - - Running Backstage locally: 'getting-started/running-backstage-locally.md' - App configuration: - Configuring App with plugins: 'getting-started/configure-app-with-plugins.md' - Customize the look-and-feel of your App: 'getting-started/app-custom-theme.md' From e89f0d7470773935ee3e9c8622bc16bbc8eba1f7 Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Thu, 13 Apr 2023 07:15:14 -0500 Subject: [PATCH 2/3] Added redirect Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- microsite/docusaurus.config.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/microsite/docusaurus.config.js b/microsite/docusaurus.config.js index 549974a168..4164a1c865 100644 --- a/microsite/docusaurus.config.js +++ b/microsite/docusaurus.config.js @@ -125,6 +125,10 @@ module.exports = { from: '/docs/features/search/search-overview', to: '/docs/features/search/', }, + { + from: '/docs/getting-started/running-backstage-locally', + to: '/docs/getting-started/', + }, ], }, ], From 3d809a66bf0469154aeb76867a82283a8c8f97ee Mon Sep 17 00:00:00 2001 From: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Date: Fri, 14 Apr 2023 12:39:23 -0500 Subject: [PATCH 3/3] Changes based on feedback Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> --- docs/features/kubernetes/installation.md | 4 ---- docs/features/techdocs/getting-started.md | 5 ----- docs/getting-started/create-an-app.md | 5 ++--- docs/getting-started/index.md | 4 +--- 4 files changed, 3 insertions(+), 15 deletions(-) diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index 89484ca01b..216c4db3f4 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -173,10 +173,6 @@ export default async function createPlugin( } ``` -## Running Backstage locally - -Start the frontend and the backend app by running `yarn dev` - ## Configuration After installing the plugins in the code, you'll need to then diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 8c140f5b6c..0ff5903a85 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -284,11 +284,6 @@ Note: We recommend Python version 3.7 or higher. > Python packages. The order is important to make sure we get correct version of > some of the dependencies. -## Running Backstage locally - -Start the frontend and the backend app by running `yarn dev`, this will launch [http://localhost:3000/](http://localhost:3000/) in your browser, from there you can navigate to [http://localhost:3000/docs/](http://localhost:3000/docs/) -to see all your documentation sites. - ## Additional reading - [Creating and publishing your docs](creating-and-publishing.md) diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 5169c07ee8..063eeb399f 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -106,9 +106,8 @@ example [here](https://www.python.org/downloads/) to install it. #### Could not execute command yarn install -Install yarn on your system with `npm install --global yarn` or for more details -refer to the -[prerequisites](https://backstage.io/docs/getting-started/#prerequisites) +Install Yarn on your system with `npm install --global yarn` or for more details +refer to the [prerequisites](index.md#prerequisites). ## Run the app diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 995413b2c5..7398e9a311 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -15,9 +15,7 @@ system using tools like apt-get, npm, yarn, curl. Docker knowledge is also helpful for making the best use of your Backstage installation. If you are planning to contribute plugins or to the project in general, we advise -you to use the -[Contributors](https://backstage.io/docs/getting-started/contributors) -guide to do a repository-based installation. +you to use the [Contributors](contributors.md) guide to do a repository-based installation. ### Prerequisites