Getting Started

For most Backstage installations, installing the standalone app will bring you the best and most streamlined experience. In this guide you will:

• Deploy Backstage Standalone with npm packages
• Run Backstage Standalone with a SQLite in-memory database and demo content

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 to the project in general, we advise you to use the Contributors guide to do a repository-based installation.

Prerequisites

• Access to a Unix-based operating system, such as Linux, MacOS or Windows Subsystem for Linux
• A GNU-like build environment available at the command line. For example, on Debian/Ubuntu you will want to have the make and build-essential packages installed. On MacOS, you will want to have run xcode-select --install to get the XCode command line build tooling in place.
• An account with elevated rights to install the dependencies
• curl or wget installed
• Node.js Active LTS Release installed using one of these methods:
  • Using nvm (recommended)
    • Installing nvm
    • Install and change Node version with nvm
  • Binary Download
  • Package manager
  • Using NodeSource packages
• yarn Installation
  • You will need to use Yarn classic to create a new project, but it can then be migrated to Yarn 3
• docker installation
• git installation
• If the system is not directly accessible over your network the following ports need to be opened: 3000, 7007. This is quite uncommon, unless when you're installing in a container, VM or remote system.

Create your Backstage App

To install the Backstage Standalone app, we make use of npx, a tool to run Node executables straight from the registry. This tool is part of your Node.js installation. Running the command below will install Backstage. The wizard will create a subdirectory inside your current working directory.

npx @backstage/create-app@latest

The wizard will ask you for the name of the app, which will also be the name of the directory

Run the Backstage app

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.

cd my-backstage-app
yarn dev

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. Please note that the in-memory database will be cleared when you restart the app, so you'll most likely want to carry on with the database steps.

In the next part of this tutorial, you'll learn how to change to a persistent database, configure authentication, and add your first integration. Continue with getting started: Configuring Backstage.

Share your experiences, comments, or suggestions with us: on discord, file issues for any feature or plugin suggestions, or bugs you have, and feel free to contribute!