diff --git a/docs/assets/getting-started/bs-getting-started-portal.png b/docs/assets/getting-started/bs-getting-started-portal.png new file mode 100644 index 0000000000..f16ad44757 Binary files /dev/null and b/docs/assets/getting-started/bs-getting-started-portal.png differ diff --git a/docs/assets/getting-started/bs-getting-started-startup.png b/docs/assets/getting-started/bs-getting-started-startup.png new file mode 100644 index 0000000000..626f7b1297 Binary files /dev/null and b/docs/assets/getting-started/bs-getting-started-startup.png differ diff --git a/docs/assets/getting-started/bs-wizard.png b/docs/assets/getting-started/bs-wizard.png new file mode 100644 index 0000000000..679878e252 Binary files /dev/null and b/docs/assets/getting-started/bs-wizard.png differ diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index b01afac5c3..3367fa2572 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -4,49 +4,87 @@ title: Getting Started description: Documentation on How to get started with Backstage --- -There are two different ways to get started with Backstage: +For most Backstage installations, installing the standalone app will bring +you the best and most streamlined experience. In this guide you will: -- **Recommended:** Create a standalone app -- **Contributors:** Clone the Backstage repository +- Deploy Backstage Standalone with npm packages +- Run Backstage Standalone with a SQLite in-memory database and demo content -Creating a standalone app makes it simpler to customize the application for your -needs and stay up to date with the project. You will depend on `@backstage` -packages from npm, making your app much smaller. This is the recommended -approach for most installations. +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 want to contribute plugins or to the project in general, it's easier to -fork and clone the repository. The `@backstage` packages will be included in the -clone. That will let you stay up to date with the latest changes, and give you -an easier path to make Pull Requests. +If you are planning to contribute plugins or the project in general, we advise +you to use the [Getting Started for Contributers](https://backstage.io/docs/getting-started/running-backstage-locally) guide to +do a repository-based installation. + +### Prerequisites + +- Access to a linux based operating system +- An account with elevated rights (eg. via sudo) +- `curl` or `wget` installed +- Node.js Active LTS Release installed (currently v14) using one of these methods: + - Using `nvm` (recommended) + - [Installing nvm](https://github.com/nvm-sh/nvm#install--update-script) + - [Install and change Node version with nvm](https://nodejs.org/en/download/package-manager/#nvm) + - [Binary Download](https://nodejs.org/en/download/) + - [Package manager](https://nodejs.org/en/download/package-manager/) + - [Using NodeSource packages](https://github.com/nodesource/distributions/blob/master/README.md) +- `yarn` [Installation](https://classic.yarnpkg.com/en/docs/install) +- `docker` [installation](https://docs.docker.com/engine/install/) +- `git` [installation](https://github.com/git-guides/install-git) +- If the system is not directly accessible over your network, the following + ports need to be opened: 3000, 7000 ### Create your Backstage App -Backstage provides the `@backstage/create-app` package to scaffold standalone -instances of Backstage. You will need to have -[Node.js](https://nodejs.org/en/download/) Active LTS Release installed -(currently v14) 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: +To install the Backstage Standalone app, we make use of `npx`, a tool to run Node executables +straight from the registry. Running the command below will install Backstage. The wizard will +create a subdirectory inside your current working directory. ```bash npx @backstage/create-app ``` -You will be taken through a wizard to create your app. You can read more about -this process in [Create an app](./create-an-app.md). +The wizard will ask you -### Contributing to Backstage +- The name of the app, which will also be the name of the directory +- The database type to use for the backend. For this guide, you'll be using the SQLite option. -If you intend to make changes to the core project's packages, certain plugins, -or project documentation, then you can fork and clone -[https://github.com/backstage/backstage](https://github.com/backstage/backstage). +

+ Screenshot of the wizard asking for a name for the app, and a selection menu for the database. +

-This will let you run the latest code off of the `master` branch, fix bugs or -contribute new features, run test suites, etc. +### Run the Backstage app -You can read more in our -[CONTRIBUTING](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) -guide, which can help you get setup with a Backstage development environment. +When the installation is complete you can go to the application directory and start the app. The `yarn dev` command will run both the frontend and backend as separate processes (named `[0]` and `[1]`) in the same window. + +```bash +cd my-backstage-app +yarn dev +``` + +

+ Screenshot of the command output, with the message webpack compiled successfully. +

+ +It might take a little while, but as soon as the message `[0] webpack compiled successfully` appears, you can open a browser and directly navigate to +your freshly installed Backstage portal at `http://localhost:3000`. You can start exploring the demo immediately. + +

+ Screenshot of the Backstage portal homescreen. +

+ +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/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)! + +The most common next steps are to configure Backstage, add a plugin and moving to a more persistend database: + +- [Setting up Authentication](https://github.com/backstage/backstage/tree/master/plugins/auth-backend#github) +- [Switching from SQLite to PostgresQL](https://backstage.io/docs/tutorials/switching-sqlite-postgres) +- [Adding a plugin](https://backstage.io/docs/getting-started/configure-app-with-plugins)