Merge pull request #2414 from spotify/orkohunter/docs-improve-getting-started
Docs: Add proper getting started page on backstage.io/docs
This commit is contained in:
Himanshu Mishra
@@ -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
|
||||
|
||||
|
||||
@@ -1,84 +1,50 @@
|
||||
---
|
||||
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](./running-backstage-locally.md)
|
||||
guide to learn how to set up Backstage, and how to develop on the platform.
|
||||
|
||||
@@ -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)
|
||||
@@ -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",
|
||||
|
||||
+2
-1
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user