Merge branch 'backstage:master' into milliehartnt123-create-ui-doc
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