Update create an app for feature issue 21913 (#31366)
* Update index.md rewritten as task-based steps Page has been rewritten and images have been updated/replaced. Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Updated create-app-output and portal graphics Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Updated name of backstage app in graphic Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md to add guest user login screen and graphic Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Add graphic for guest user login screen to app Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md rearranged guest login section Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md fixed some indenting issues Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md fix prettier errors Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md rearranged admin links at bottom of page Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md fix prettier errors Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md changed title and added prerequisites Made the isolated-vm module installed by everyone. Changed the title and sidebar_label. Added disc space size requirement and a note to the Linux requirement. Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md Add minimum of 4 GB memory as placeholder. Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md fix prettier errors Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update index.md added additional text and removed a graphic Updated tip from 'webpack compiled successfully' to "Rspack compiled successfully' Added selected output from 'yarn start' command to explain the sequence of calls that are being done when starting up the frontend and backend. Removed graphic that showed 'webpack compiled successfully'. Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Fix formatting issues in getting-started documentation Fixed prettier errors Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update system requirements for Backstage application Updated minimum memory and disk space requirements. Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Update docs/getting-started/index.md Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> * Fix spelling error in getting started documentation Corrected the spelling of 'initialized' in the documentation. Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> * Simplify frontend startup instructions Removed redundant information about waiting for the frontend to start. Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> --------- Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Co-authored-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
This commit is contained in:
milliehartnt123
@@ -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.
|
||||
|
||||
|
||||
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`.
|
||||
|
||||
|
||||
|
||||
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/"
|
||||
.
|
||||
.
|
||||
```
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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)
|
||||
|
||||
Reference in New Issue
Block a user