docs: split getting started section in readme into create-app vs clone
Co-authored-by: Ben Lambert <ben@blam.sh>
This commit is contained in:
Patrik Oldsberg
+29
-1
@@ -60,7 +60,35 @@ Have you started using Backstage? Adding your company to [ADOPTERS](ADOPTERS.md)
|
||||
|
||||
# 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) 👏🏻💯
|
||||
So...feel ready to jump in? Let's do this. 👏🏻💯
|
||||
|
||||
To run a Backstage app, you will need to have the following installed:
|
||||
|
||||
- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12
|
||||
- [yarn](https://classic.yarnpkg.com/en/docs/install)
|
||||
|
||||
After cloning this repo, open a terminal window and start the example app using the following commands from the project root:
|
||||
|
||||
```bash
|
||||
yarn install # Install dependencies
|
||||
|
||||
yarn start # Start dev server, use --check to enable linting and type-checks
|
||||
```
|
||||
|
||||
The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
|
||||
|
||||
Depending on the work you're doing, you often also want to run the example backend. Start the backend in a separate terminal session using the following:
|
||||
|
||||
```bash
|
||||
cd packages/backend
|
||||
|
||||
yarn start
|
||||
|
||||
yarn lerna run mock-data # Populate the backend with mock data
|
||||
```
|
||||
|
||||
And that's it! You are good to go 👍
|
||||
|
||||
If you need help, just jump into our [Discord chatroom](https://discord.gg/MUpMjP2).
|
||||
|
||||
|
||||
@@ -49,27 +49,33 @@ The Backstage platform consists of a number of different components:
|
||||
- [**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.
|
||||
|
||||
## Getting started
|
||||
## Getting Started
|
||||
|
||||
To run a Backstage app, you will need to have the following installed:
|
||||
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.
|
||||
|
||||
- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12
|
||||
- [yarn](https://classic.yarnpkg.com/en/docs/install)
|
||||
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.
|
||||
|
||||
After cloning this repo, open a terminal window and start the example app using the following commands from the project root:
|
||||
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
|
||||
yarn install # Install dependencies
|
||||
|
||||
yarn start # Start dev server, use --check to enable linting and type-checks
|
||||
npx @backstage/create-app
|
||||
```
|
||||
|
||||
The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
|
||||
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](docs/getting-started/create-an-app.md)
|
||||
|
||||
And that's it! You are good to go 👍
|
||||
### Contributing to Backstage
|
||||
|
||||
### Next step
|
||||
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](docs/getting-started/index.md) guide to learn how to set up Backstage, and how to develop on the platform.
|
||||
|
||||
@@ -77,15 +83,10 @@ Take a look at the [Getting Started](docs/getting-started/index.md) guide to lea
|
||||
|
||||
- [Main documentation](docs/README.md)
|
||||
- [Service Catalog](docs/features/software-catalog/index.md)
|
||||
- [Create a Backstage App](docs/getting-started/create-an-app.md)
|
||||
- [Architecture](docs/overview/architecture-terminology.md) ([Decisions](docs/architecture-decisions/index.md))
|
||||
- [Designing for Backstage](docs/dls/design.md)
|
||||
- [Storybook - UI components](http://storybook.backstage.io)
|
||||
|
||||
## Contributing
|
||||
|
||||
We would love your help in building Backstage! See [CONTRIBUTING](CONTRIBUTING.md) for more information.
|
||||
|
||||
## Community
|
||||
|
||||
- [Discord chatroom](https://discord.gg/MUpMjP2) - Get support or discuss the project
|
||||
|
||||
Reference in New Issue
Block a user