From 4bc9a33a3c6c9a6b85f116c7d7e67de591eebcca Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 12 Aug 2020 14:19:22 +0200 Subject: [PATCH] docs: split getting started section in readme into create-app vs clone Co-authored-by: Ben Lambert --- CONTRIBUTING.md | 30 +++++++++++++++++++++++++++++- README.md | 35 ++++++++++++++++++----------------- 2 files changed, 47 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf7622d692..9981493868 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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). diff --git a/README.md b/README.md index 56932a1741..fa8151cbfa 100644 --- a/README.md +++ b/README.md @@ -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