diff --git a/docs/assets/getting-started/create-app-output.png b/docs/assets/getting-started/create-app-output.png index 1987ea41e1..305f2e001a 100644 Binary files a/docs/assets/getting-started/create-app-output.png and b/docs/assets/getting-started/create-app-output.png differ diff --git a/docs/assets/getting-started/login-to-app-as-guest-user.png b/docs/assets/getting-started/login-to-app-as-guest-user.png new file mode 100644 index 0000000000..79c897dcb6 Binary files /dev/null and b/docs/assets/getting-started/login-to-app-as-guest-user.png differ diff --git a/docs/assets/getting-started/portal.png b/docs/assets/getting-started/portal.png index b3133f2278..fd7d52d193 100644 Binary files a/docs/assets/getting-started/portal.png and b/docs/assets/getting-started/portal.png differ diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 876af4f0a5..9075afb82c 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -1,8 +1,8 @@ --- id: index -title: Creating your Backstage App -sidebar_label: Introduction -description: How to install Backstage for your own use. +title: Standalone Installation +sidebar_label: Standalone Installation +description: How to create and run a Standalone Backstage. --- Audience: Developers and Admins @@ -11,11 +11,11 @@ Audience: Developers and Admins It is not required, although recommended to have a basic understanding of [Yarn](https://www.pluralsight.com/guides/yarn-a-package-manager-for-node-js) and [npm](https://docs.npmjs.com/about-npm) before starting this guide. ::: -## Summary +## Overview -This guide walks through how to get started creating your very own Backstage customizable app. This is the first step in evaluating, developing on, or demoing Backstage. +This guide walks through how to create your own Backstage customizable app. This is the first step in evaluating, developing on, or demoing Backstage. -By the end of this guide, you will have a standalone Backstage installation running locally with a `SQLite` database and demo content. To be clear, this is not a production-ready installation, and it does not contain information specific to your organization. +By the end of this guide, you will have a standalone Backstage installation running locally with an in-memory `SQLite` database and demo content. To be clear, this is not a production-ready installation, and it does not contain information specific to your organization until you set up integrations with your specific data sources! :::note Contributors @@ -23,46 +23,9 @@ If you are planning to contribute a new feature or bug fix to the Backstage proj ::: -## Prerequisites +The instructions make use of `npx`. `npx` is a tool that comes preinstalled with Node.js and lets you run commands straight from `npm` or other registries. -This guide also assumes a basic understanding of working on a Linux based operating system and have some experience with the terminal, specifically, these commands: `npm`, `yarn`. - -- Access to a Unix-based operating system, such as Linux, macOS or - [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/) -- 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 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](../overview/versioning-policy.md#nodejs-releases) installed 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) - - Node 20 is a good starting point, this can be installed using `nvm install lts/iron` - - [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://yarnpkg.com/getting-started/install) - - Backstage currently uses Yarn 4.4.1, once you've ran `corepack enable` you'll want to then run `yarn set version 4.4.1` -- `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, 7007. This is quite uncommon, unless you're installing in a container, VM or remote system. - -## 1. Create your Backstage App - -:::caution - -The Backstage app we'll be creating will only have demo data until we set up integrations with your specific data sources! - -::: - -To install the Backstage Standalone app, we will make use of `npx`. `npx` is a tool that comes preinstalled with Node.js and lets you run commands straight from `npm` or other registries. Before we run the command, let's discuss what it does. - -This command will create a new directory with a Backstage app inside. The wizard will ask you for the name of the app. This name will be created as subdirectory in your current working directory. - -![create app](../assets/getting-started/create-app-output.png) +This command creates a new directory with a Backstage app inside. The wizard will ask you for the name of the app. This name will be created as a subdirectory in your current working directory. Inside that directory, it will generate all the files and folder structure needed for you to run your app. @@ -100,65 +63,122 @@ app and [TechDocs](https://backstage.io/docs/features/techdocs/) amongst other things. -Now, that we know what it does, let's run it! +## Prerequisites -```bash -npx @backstage/create-app@latest -``` +This guide also assumes a basic understanding of working on a Linux based operating system and have some experience with the terminal, specifically, these commands: `npm`, `yarn`. + +- A minimum of 20 GB disk space to run the standalone Backstage application with demo data. NOTE: As you add more modules and plugins to an installation, the disk space requirements will increase, accordingly. +- A minimum of 6 GB memory. +- Access to a Unix-based operating system, such as Linux, macOS or + [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/). The Linux version must support the required Node.js version. +- 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 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](../overview/versioning-policy.md#nodejs-releases) installed 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) + - Node 20 is a good starting point, this can be installed using `nvm install lts/iron` + - [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) +- Install the `isolated-vm` module, following their [requirements section](https://github.com/laverdet/isolated-vm#requirements). +- `yarn` [Installation](https://yarnpkg.com/getting-started/install) + - Backstage currently uses Yarn 4.4.1, once you've ran `corepack enable` you'll want to then run `yarn set version 4.4.1` +- `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, 7007. This is quite uncommon, unless you're installing in a container, VM or remote system. + +## Creating and running a Backstage application This may take a few minutes to fully install everything. Don't stress if the loading seems to be spinning nonstop, there's a lot going on in the background. -:::note +To create the application: -If this fails on the `yarn install` step, it's likely that you will need to install some additional dependencies which are used to configure `isolated-vm`. You can find out more in their [requirements section](https://github.com/laverdet/isolated-vm#requirements), and then run `yarn install` manually again after you've completed those steps. +1. Type the following command to install the Backstage application. -::: +```bash + npx @backstage/create-app@latest +``` -## 2. Run the Backstage app +2. If this is the first time that you are installing a Backstage application on this device, the following question is displayed. Enter `y` and select `Enter` to proceed with the installation. + +``` + Need to install the following packages: + @backstage/create-app@0.7.4 + ok to proceed? (y) +``` + +3. Enter the name for your application and select `Enter`. This is the root directory of your application. In this example, the name is set to `my-backstage-app`. + + ![create app](../assets/getting-started/create-app-output.png) Your Backstage app is fully installed and ready to be run! Now that the installation is complete, you can go to the application directory and start the app using the `yarn start` command. The `yarn start` command will run both the frontend and backend as separate processes (named `[0]` and `[1]`) in the same window. -```bash -cd my-backstage-app # your app name -yarn start +To run the application: + +1. Change to the root directory of your Backstage app. This is the same as the name of your application that you provided during the installation. In this example, it is `my-backstage-app`. + + ```bash + cd my-backstage-app + ``` + +2. Start the Backstage application. + + ```bash + yarn start + ``` + +As the frontend and backend are starting, you will see output similar to the following. The output shows that the app and backend are starting up with the configuration coming from `app-config.yaml`. You will see the plugins being initialized, and authorization and permissions being setup. In addition you will see a series of REST API calls for those plugins that use a service backend, such as the service catalog. + +``` +Starting app, backend +Loaded config from app-config.yaml +. +. +2025-10-15T12:26:41.564Z backstage info Plugin initialization started: 'app', 'proxy', 'scaffolder', 'techdocs', 'auth', 'catalog', 'permission', 'search', 'kubernetes', 'notifications', 'signals' type="initialization" +Rspack compiled successfully +. +. +2025-10-15T15:17:21.130Z auth info Created new signing key eec1a9e4-4395-4698-9a9f-f1b5cbcf152b component="token-factory" +2025-10-15T15:17:21.139Z auth info Issuing token for user:development/guest, with entities user:development/guest component="token-factory" +2025-10-15T15:17:21.223Z rootHttpRouter info [2025-10-15T15:17:21.223Z] "GET /api/auth/guest/refresh HTTP/1.1" 200 802 "http://localhost:3000/" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:143.0) Gecko/20100101 Firefox/143.0" type="incomingRequest" date="2025-10-15T15:17:21.223Z" method="GET" url="/api/auth/guest/refresh" status=200 httpVersion="1.1" userAgent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:143.0) Gecko/20100101 Firefox/143.0" contentLength=802 referrer="http://localhost:3000/" +. +. +2025-10-15T15:17:24.051Z rootHttpRouter info [2025-10-15T15:17:24.051Z] "GET /api/catalog/entities?fields=metadata,kind,spec.profile&filter=kind%3Dgroup%2Crelations.hasMember%3Duser%3Adevelopment%2Fguest HTTP/1.1" 304 0 "http://localhost:3000/" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:143.0) Gecko/20100101 Firefox/143.0" type="incomingRequest" date="2025-10-15T15:17:24.051Z" method="GET" url="/api/catalog/entities?fields=metadata,kind,spec.profile&filter=kind%3Dgroup%2Crelations.hasMember%3Duser%3Adevelopment%2Fguest" status=304 httpVersion="1.1" userAgent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:143.0) Gecko/20100101 Firefox/143.0" referrer="http://localhost:3000/" +. +. ``` -![Screenshot of the command output, with the message web pack compiled successfully](../assets/getting-started/startup.png) +Once the Backstage UI is displayed, you can start exploring the demo immediately. -Here again, there's a small wait for the frontend to start up. Once the frontend is built, your browser window should automatically open. +:::tip Browser window didn't open with yarn start -:::tip Browser window didn't open - -When you see the message `[0] webpack compiled successfully`, you can navigate directly to `http://localhost:3000` to see your Backstage app. +When you see the message `Rspack compiled successfully`, you can navigate directly to `http://localhost:3000` to see your Backstage app. ::: -You can start exploring the demo immediately. - ![Screenshot of the Backstage portal.](../assets/getting-started/portal.png) -## Recap - -This tutorial walked through how to deploy Backstage using the `npx @backstage/create-app@latest` command. That command created a new directory that holds your new Backstage app. That app is currently only configured for development purposes, as it is using an in-memory database and contains demo data. - ## Next steps Choose the correct next steps for your user role, if you're likely to be deploying and managing a Backstage instance for your organization, look through the [Admin](#admin) section. If you're likely to be developing on/for Backstage, take a look through the [Developer](#developer) section. ### Admin -- Deploying to production - +- Configuring Backstage - [Setting up authentication](./config/authentication.md) - [Configuring a database](./config/database.md) - - [Deploying with Docker](../deployment/docker.md) - - [Deploying with Kubernetes](../deployment/k8s.md) - -- Configuring Backstage - - [Adding plugins](./configure-app-with-plugins.md) - [Customizing Your App's UI](../conf/user-interface/index.md) - [Populating the homepage](./homepage.md) +- Deploying to production + - [Deploying with Docker](../deployment/docker.md) + - [Deploying with Kubernetes](../deployment/k8s.md) ### Developer @@ -171,8 +191,4 @@ Share your experiences, comments, or suggestions with us: [on discord](https://discord.gg/backstage-687207715902193673), 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/community-plugins/issues/new/choose), -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)! +[plugin suggestions](https://github.com/backstage/community-plugins/issues/new/choose)