diff --git a/docs/assets/getting-started/create-app-output.png b/docs/assets/getting-started/create-app-output.png new file mode 100644 index 0000000000..1987ea41e1 Binary files /dev/null and b/docs/assets/getting-started/create-app-output.png differ diff --git a/docs/assets/getting-started/create-app_output.png b/docs/assets/getting-started/create-app_output.png deleted file mode 100644 index 875ad05122..0000000000 Binary files a/docs/assets/getting-started/create-app_output.png and /dev/null differ diff --git a/docs/backend-system/building-plugins-and-modules/01-index.md b/docs/backend-system/building-plugins-and-modules/01-index.md index 168646afab..b2f0f09a5c 100644 --- a/docs/backend-system/building-plugins-and-modules/01-index.md +++ b/docs/backend-system/building-plugins-and-modules/01-index.md @@ -16,7 +16,7 @@ backend _features_, and are the building blocks that adopters add to their ## Creating a new Plugin -This guide assumes that you already have a Backend project set up. Even if you only want to develop a single plugin for publishing, we still recommend that you do so in a standard Backstage monorepo project, as you often end up needing multiple packages. For instructions on how to set up a new project, see our [getting started](../../getting-started/index.md#prerequisites) documentation. +This guide assumes that you already have a Backend project set up. Even if you only want to develop a single plugin for publishing, we still recommend that you do so in a standard Backstage monorepo project, as you often end up needing multiple packages. For instructions on how to set up a new project, see our [getting started](../../getting-started/standalone-install.md#prerequisites) documentation. To create a Backend plugin, run `yarn new`, select `backend-plugin`, and fill out the rest of the prompts. This will create a new package at `plugins/-backend`, which will be the main entrypoint for your plugin. diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index 675a8de947..534c217337 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -16,7 +16,7 @@ are stateless, so for a production deployment you will want to set up and connect to an external PostgreSQL instance where the backend plugins can store their state, rather than using SQLite. -This section assumes that an [app](https://backstage.io/docs/getting-started/create-an-app) +This section assumes that an [app](https://backstage.io/docs/getting-started/standalone-install) has already been created with `@backstage/create-app`, in which the frontend is bundled and served from the backend. This is done using the `@backstage/plugin-app-backend` plugin, which also injects the frontend diff --git a/docs/features/kubernetes/installation.md b/docs/features/kubernetes/installation.md index bdd14098ff..f3e46fab68 100644 --- a/docs/features/kubernetes/installation.md +++ b/docs/features/kubernetes/installation.md @@ -8,7 +8,7 @@ The Kubernetes feature is a plugin to Backstage, and it is exposed as a tab when viewing entities in the software catalog. If you haven't setup Backstage already, read the -[Getting Started](../../getting-started/index.md) guide. +[Getting Started](../../getting-started/standalone-install.md) guide. ## Adding the Kubernetes frontend plugin diff --git a/docs/features/search/getting-started.md b/docs/features/search/getting-started.md index 7989b60ae2..599189d192 100644 --- a/docs/features/search/getting-started.md +++ b/docs/features/search/getting-started.md @@ -8,7 +8,7 @@ Search functions as a plugin to Backstage, so you will need to use Backstage to use Search. If you haven't setup Backstage already, start -[here](../../getting-started/index.md). +[here](../../getting-started/standalone-install.md). > If you used `npx @backstage/create-app`, and you have a search page defined in > `packages/app/src/components/search`, skip to diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index eaa6c2de72..29419e44f4 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -8,7 +8,7 @@ TechDocs functions as a plugin to Backstage, so you will need to use Backstage to use TechDocs. If you haven't setup Backstage already, start -[here](../../getting-started/index.md). +[here](../../getting-started/standalone-install.md). > If you used `npx @backstage/create-app`, TechDocs may already be present. > diff --git a/docs/frontend-system/building-plugins/01-index.md b/docs/frontend-system/building-plugins/01-index.md index f8d80f9382..b6dc6d9308 100644 --- a/docs/frontend-system/building-plugins/01-index.md +++ b/docs/frontend-system/building-plugins/01-index.md @@ -14,7 +14,7 @@ frontend _features_, and what you install to build up a Backstage frontend [app] ## Creating a new plugin -This guide assumes that you already have a Backstage project set up. Even if you only want to develop a single plugin for publishing, we still recommend that you do so in a standard Backstage monorepo project, as you often end up needing multiple packages. For instructions on how to set up a new project, see our [getting started](../../getting-started/index.md#prerequisites) documentation. +This guide assumes that you already have a Backstage project set up. Even if you only want to develop a single plugin for publishing, we still recommend that you do so in a standard Backstage monorepo project, as you often end up needing multiple packages. For instructions on how to set up a new project, see our [getting started](../../getting-started/standalone-install.md#prerequisites) documentation. To create a frontend plugin, run `yarn new`, select `plugin`, and fill out the rest of the prompts. This will create a new package at `plugins/`, which will be the main entrypoint for your plugin. diff --git a/docs/getting-started/config/authentication.md b/docs/getting-started/config/authentication.md new file mode 100644 index 0000000000..39b1f7d306 --- /dev/null +++ b/docs/getting-started/config/authentication.md @@ -0,0 +1,134 @@ +--- +id: authentication +title: Authentication +description: How to set up authentication into your Backstage installation +--- + +Audience: Admins or Developers + +### Setting up authentication + +There are multiple authentication providers available for you to use with +Backstage, feel free to follow +[the instructions for adding authentication](../../auth/index.md). + +For this tutorial we choose to use GitHub, a free service most of you might be +familiar with. For other options, see +[the auth provider documentation](../../auth/github/provider.md#create-an-oauth-app-on-github). + +Go to +[https://github.com/settings/applications/new](https://github.com/settings/applications/new) +to create your OAuth App. The `Homepage URL` should point to Backstage's +frontend, in our tutorial it would be `http://localhost:3000`. The +`Authorization callback URL` will point to the auth backend, which will most +likely be `http://localhost:7007/api/auth/github/handler/frame`. + +![Screenshot of the GitHub OAuth creation page](../../assets/getting-started/gh-oauth.png) + +Take note of the `Client ID` and the `Client Secret`. Open `app-config.yaml`, +and add your `clientId` and `clientSecret` to this file. It should end up +looking like this: + +```yaml title="app-config.yaml" +auth: + # see https://backstage.io/docs/auth/ to learn about auth providers + environment: development + providers: + github: + development: + clientId: YOUR CLIENT ID + clientSecret: YOUR CLIENT SECRET +``` + +### Add sign-in option to the frontend + +Backstage will re-read the configuration. If there's no errors, that's great! We +can continue with the last part of the configuration. The next step is needed to +change the sign-in page, this you actually need to add in the source code. + +Open `packages/app/src/App.tsx` and below the last `import` line, add: + +```typescript title="packages/app/src/App.tsx" +import { githubAuthApiRef } from '@backstage/core-plugin-api'; +import { SignInPage } from '@backstage/core-components'; +``` + +Search for `const app = createApp({` in this file, and below `apis,` add: + +```tsx title="packages/app/src/App.tsx" +components: { + SignInPage: props => ( + + ), +}, +``` + +> Note: The default Backstage app comes with a guest Sign In Resolver. This resolver makes all users share a single "guest" identity and is only intended as a minimum requirement to quickly get up and running. You can read more about how [Sign In Resolvers](../../auth/identity-resolver.md#sign-in-resolvers) play a role in creating a [Backstage User Identity](../../auth/identity-resolver.md#backstage-user-identity) for logged in users. + +Restart Backstage from the terminal, by stopping it with `Control-C`, and starting it with `yarn dev` . You should be welcomed by a login prompt! + +> Note: Sometimes the frontend starts before the backend resulting in errors on the sign in page. Wait for the backend to start and then reload Backstage to proceed. + +To learn more about Authentication in Backstage, here are some docs you +could read: + +- [Authentication in Backstage](../../auth/index.md) +- [Using organizational data from GitHub](../../integrations/github/org.md) + +### Setting up a GitHub Integration + +The GitHub integration supports loading catalog entities from GitHub or GitHub +Enterprise. Entities can be added to static catalog configuration, registered +with the catalog-import plugin, or discovered from a GitHub organization. Users +and Groups can also be loaded from an organization. While using [GitHub Apps](../../integrations/github/github-apps.md) +might be the best way to set up integrations, for this tutorial you'll use a +Personal Access Token. + +Create your Personal Access Token by opening +[the GitHub token creation page](https://github.com/settings/tokens/new). Use a +name to identify this token and put it in the notes field. Choose a number of +days for expiration. If you have a hard time picking a number, we suggest to go +for 7 days, it's a lucky number. + +![Screenshot of the GitHub Personal Access Token creation page](../../assets/getting-started/gh-pat.png) + +Set the scope to your likings. For this tutorial, selecting `repo` and `workflow` is required as the scaffolding job in this guide configures a GitHub actions workflow for the newly created project. + +For this tutorial, we will be writing the token to `app-config.local.yaml`. This file might not exist for you, so if it doesn't go ahead and create it alongside the `app-config.yaml` at the root of the project. +This file should also be excluded in `.gitignore`, to avoid accidental committing of this file. + +In your `app-config.local.yaml` go ahead and add the following: + +```yaml title="app-config.local.yaml" +integrations: + github: + - host: github.com + token: ghp_urtokendeinfewinfiwebfweb # this should be the token from GitHub +``` + +That's settled. This information will be leveraged by other plugins. + +If you're looking for a more production way to manage this secret, then you can do the following with the token being stored in an environment variable called `GITHUB_TOKEN`. + +```yaml title="app-config.local.yaml" +integrations: + github: + - host: github.com + token: ${GITHUB_TOKEN} # this will use the environment variable GITHUB_TOKEN +``` + +> Note: If you've updated the configuration for your integration, it's likely that the backend will need a restart to apply these changes. To do this, stop the running instance in your terminal with `Control-C`, then start it again with `yarn dev`. Once the backend has restarted, retry the operation. + +Some helpful links, for if you want to learn more about: + +- [Other available integrations](../../integrations/index.md) +- [Using GitHub Apps instead of a Personal Access Token](../../integrations/github/github-apps.md#docsNav) diff --git a/docs/getting-started/config/database.md b/docs/getting-started/config/database.md new file mode 100644 index 0000000000..64bff231d4 --- /dev/null +++ b/docs/getting-started/config/database.md @@ -0,0 +1,139 @@ +--- +id: database +title: Database +description: How to set up PostgreSQL for your Backstage instance. +--- + +Audience: Admins + +### Summary + +This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Standalone Install](../standalone-install.md) guide. + +By the end of this tutorial, you will have a working PostgreSQL database hooked up to your Backstage install. + +### Prerequisites + +This guide assumes a basic understanding of working on a Linux based operating system and have some experience with the terminal, specifically, these commands: `apt-get`, `psql`, `yarn`. + +- Access to a Linux-based operating system, such as Linux, MacOS or + [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/) +- An account with elevated rights to install prerequisites on your operating + system +- If the database is not hosted on the same server as the Backstage app, the + PostgreSQL port needs to be accessible (the default is `5432` or `5433`) + +### 1. Install and configure PostgreSQL + +:::tip Already configured your database? + +If you've already installed PostgreSQL and created a schema and user, you can skip to [Step 2](#2-configuring-backstage-pg-client). + +::: + +Let's install PostgreSQL and get it set up for our Backstage app. First, we'll need to actually install the SQL server. + +:::caution + +The command below is for Linux. If you're not on Linux or having issues with package managers, check out [how to install PostgreSQL](https://www.postgresql.org/download/) to help you get sorted. + +::: + +```shell +sudo apt-get install postgresql +``` + +To test if your database is working: + +```shell +sudo -u postgres psql +``` + +You should see a very welcoming message, like: + +```shell +psql (12.9 (Ubuntu 12.9-0ubuntu0.20.04.1)) +Type "help" for help. + +postgres=# +``` + +For this tutorial we're going to use the existing postgres user. The next step is to set the password for this user. You'll want to replace the `` with a real password in the command below. Keep note of the password you choose here, you'll need it later. + +```shell +postgres=# ALTER USER postgres PASSWORD ''; +``` + +That's enough database administration to get started. Type `\q`, followed by +pressing the enter key. Then again type `exit` and press enter. Next, you need +to install and configure the client. + +### 2. Configuring Backstage `pg` Client + +Go to the root directory of your freshly installed Backstage +App. Run the following to install the PostgreSQL client into your backend: + +```bash +# From your Backstage root directory +yarn add --cwd packages/backend pg +``` + +Use your favorite editor to open `app-config.yaml` and add your PostgreSQL +configuration in the root directory of your Backstage app using the credentials from the previous steps. + +```yaml title="app-config.yaml" +backend: + database: + # highlight-remove-start + client: better-sqlite3 + connection: ':memory:' + # highlight-remove-end + # highlight-add-start + # config options: https://node-postgres.com/apis/client + client: pg + connection: + host: ${POSTGRES_HOST} + port: ${POSTGRES_PORT} + user: ${POSTGRES_USER} + password: ${POSTGRES_PASSWORD} + # highlight-add-end +``` + +The `${...}` syntax denotes environment variables, specifically, + +1. `POSTGRES_HOST` - The URL/IP to access your PostgreSQL database at. If you've installed PostgreSQL locally, this will likely be 127.0.0.1. +2. `POSTGRES_PORT` - The port to access your PostgreSQL database on. If you've installed PostgreSQL locally, this will be `5432` or `5433`. +3. `POSTGRES_USER` - The user from the SQL command above, `postgres`. +4. `POSTGRES_PASSWORD` - The password you set in the SQL command above. + +When filling these out, you have 2 choices, + +1. Use environment variables when you launch Backstage, either using an environment variable injector like [`dotenv-cli`](https://www.npmjs.com/package/dotenv-cli) or [`env-cmd`](https://www.npmjs.com/package/env-cmd) or loading the variables directly with `EXPORT POSTGRES_...=...`. +2. Replacing the entire `${POSTGRES_...}` string with the value you identified earlier. This is the less secure option, but worth doing if you don't have much experience with environment variables. + +:::danger + +If you opt for the second option of replacing the entire string, take care to not commit your `app-config.yaml` to source control. It may contain passwords that you don't want leaked. + +::: + +[Start the Backstage app](../standalone-install.md#2-run-the-backstage-app): + +```shell +yarn dev +``` + +After the Backstage frontend launches, you should notice that nothing has changed. This is a good sign. If everything is setup correctly above, this means that the data is flowing from the demo data files directly into your database! + +We've now made your data persist in your Backstage database. + +## Next Steps + +We recommend you read [Setting up authentication](./authentication.md) next. + +## Further Reading + +If you want to read more about the database configuration, here are some helpful links: + +- [Configuring Plugin Databases](../tutorials/configuring-plugin-databases.md#privileges) +- [Read more about Knex](http://knexjs.org/), the database wrapper that we use. diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md deleted file mode 100644 index 0c813b1aee..0000000000 --- a/docs/getting-started/configuration.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -id: configuration -title: Getting Started, configuring Backstage -description: Getting started with your initial Backstage configuration ---- - -This is part two of the Getting Started documentation of Backstage. The steps in -this tutorial assume you've installed Backstage app from the npm repository, -like in the [Getting Started guide](./index.md) and want to configure Backstage. - -At the end of this tutorial, you can expect: - -- Backstage to use a PostgreSQL database -- You'll authenticate using one of the auth providers -- The Backstage GitHub integration to be configured -- You're able to use Software Templates - -### Prerequisites - -- Access to a Linux-based operating system, such as Linux, MacOS or - [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/) -- An account with elevated rights to install prerequisites on your operating - system -- If the database is not hosted on the same server as the Backstage app, the - PostgreSQL port needs to be accessible (the default is 5432 or 5433) - -### Install and configure PostgreSQL - -These instructions can be skipped if you already have a PostgreSQL server -installed and created a schema and user. The example below is for Linux, but -luckily there are detailed instructions on how to -[install PostgreSQL](https://www.postgresql.org/download/) to help you get -started. - -```shell -sudo apt-get install postgresql -``` - -Test if your database is working: - -```shell -sudo -u postgres psql -``` - -You should see a very welcoming message, like: - -```shell -psql (12.9 (Ubuntu 12.9-0ubuntu0.20.04.1)) -Type "help" for help. - -postgres=# -``` - -For this tutorial we're going to use the existing postgres user. The next step -is to set the password for this user: - -```shell -postgres=# ALTER USER postgres PASSWORD 'secret'; -``` - -That's enough database administration to get started. Type `\q`, followed by -pressing the enter key. Then again type `exit` and press enter. Next, you need -to install and configure the client. - -Stop Backstage, and go to the root directory of your freshly installed Backstage -App. Use the following commands to start the PostgreSQL client installation: - -```bash -# From your Backstage root directory -yarn --cwd packages/backend add pg -``` - -Use your favorite editor to open `app-config.yaml` and add your PostgreSQL -configuration in the root directory of your Backstage app using the credentials -from the previous steps. - -```yaml title="app-config.yaml" -backend: - database: - # highlight-remove-start - client: better-sqlite3 - connection: ':memory:' - # highlight-remove-end - # highlight-add-start - # config options: https://node-postgres.com/apis/client - client: pg - connection: - host: ${POSTGRES_HOST} - port: ${POSTGRES_PORT} - user: ${POSTGRES_USER} - password: ${POSTGRES_PASSWORD} - # https://node-postgres.com/features/ssl - # ssl: - # host is only needed if the connection name differs from the certificate name. - # This is for example the case with CloudSQL. - # host: servername in the certificate - # ca: - # $file: /server.pem - # key: - # $file: /client.key - # cert: - # $file: /client-cert.pem - # highlight-add-end -``` - -You'll use the connection details from the previous step. You can either set the -`POSTGRES_` environment variables prior to launching Backstage, or remove the -`${...}` values and set actual values in this configuration file. - -The default port for PostgreSQL is `5432` or `5433`, and the host name could be -`127.0.0.1` if installed locally. A word of caution: In general, using -connection details in a configuration file is not recommended. - -Start the Backstage app: - -```shell -yarn dev -``` - -After Backstage is completely started you'll notice the catalog is populated -with the information, still coming from the configuration files. If you add a -new component, or register an existing one it will be saved in the database. -Later in this tutorial you'll add a service, and you can test if it's persistent -as advertised. - -If you want to read more about the database configuration, here are some helpful -links: - -- [Configuring Plugin Databases](../tutorials/configuring-plugin-databases.md#privileges) -- [Read more about Knex](http://knexjs.org/), which is the library we use for - the database backend - -### Setting up authentication - -There are multiple authentication providers available for you to use with -Backstage, feel free to follow -[the instructions for adding authentication](../auth/index.md). - -For this tutorial we choose to use GitHub, a free service most of you might be -familiar with. For other options, see -[the auth provider documentation](../auth/github/provider.md#create-an-oauth-app-on-github). - -Go to -[https://github.com/settings/applications/new](https://github.com/settings/applications/new) -to create your OAuth App. The `Homepage URL` should point to Backstage's -frontend, in our tutorial it would be `http://localhost:3000`. The -`Authorization callback URL` will point to the auth backend, which will most -likely be `http://localhost:7007/api/auth/github/handler/frame`. - -![Screenshot of the GitHub OAuth creation page](../assets/getting-started/gh-oauth.png) - -Take note of the `Client ID` and the `Client Secret`. Open `app-config.yaml`, -and add your `clientId` and `clientSecret` to this file. It should end up -looking like this: - -```yaml title="app-config.yaml" -auth: - # see https://backstage.io/docs/auth/ to learn about auth providers - environment: development - providers: - github: - development: - clientId: YOUR CLIENT ID - clientSecret: YOUR CLIENT SECRET -``` - -### Add sign-in option to the frontend - -Backstage will re-read the configuration. If there's no errors, that's great! We -can continue with the last part of the configuration. The next step is needed to -change the sign-in page, this you actually need to add in the source code. - -Open `packages/app/src/App.tsx` and below the last `import` line, add: - -```typescript title="packages/app/src/App.tsx" -import { githubAuthApiRef } from '@backstage/core-plugin-api'; -import { SignInPage } from '@backstage/core-components'; -``` - -Search for `const app = createApp({` in this file, and below `apis,` add: - -```tsx title="packages/app/src/App.tsx" -components: { - SignInPage: props => ( - - ), -}, -``` - -> Note: The default Backstage app comes with a guest Sign In Resolver. This resolver makes all users share a single "guest" identity and is only intended as a minimum requirement to quickly get up and running. You can read more about how [Sign In Resolvers](../auth/identity-resolver.md#sign-in-resolvers) play a role in creating a [Backstage User Identity](../auth/identity-resolver.md#backstage-user-identity) for logged in users. - -Restart Backstage from the terminal, by stopping it with `Control-C`, and starting it with `yarn dev` . You should be welcomed by a login prompt! - -> Note: Sometimes the frontend starts before the backend resulting in errors on the sign in page. Wait for the backend to start and then reload Backstage to proceed. - -To learn more about Authentication in Backstage, here are some docs you -could read: - -- [Authentication in Backstage](../auth/index.md) -- [Using organizational data from GitHub](../integrations/github/org.md) - -### Setting up a GitHub Integration - -The GitHub integration supports loading catalog entities from GitHub or GitHub -Enterprise. Entities can be added to static catalog configuration, registered -with the catalog-import plugin, or discovered from a GitHub organization. Users -and Groups can also be loaded from an organization. While using [GitHub Apps](../integrations/github/github-apps.md) -might be the best way to set up integrations, for this tutorial you'll use a -Personal Access Token. - -Create your Personal Access Token by opening -[the GitHub token creation page](https://github.com/settings/tokens/new). Use a -name to identify this token and put it in the notes field. Choose a number of -days for expiration. If you have a hard time picking a number, we suggest to go -for 7 days, it's a lucky number. - -![Screenshot of the GitHub Personal Access Token creation page](../assets/getting-started/gh-pat.png) - -Set the scope to your likings. For this tutorial, selecting `repo` and `workflow` is required as the scaffolding job in this guide configures a GitHub actions workflow for the newly created project. - -For this tutorial, we will be writing the token to `app-config.local.yaml`. This file might not exist for you, so if it doesn't go ahead and create it alongside the `app-config.yaml` at the root of the project. -This file should also be excluded in `.gitignore`, to avoid accidental committing of this file. - -In your `app-config.local.yaml` go ahead and add the following: - -```yaml title="app-config.local.yaml" -integrations: - github: - - host: github.com - token: ghp_urtokendeinfewinfiwebfweb # this should be the token from GitHub -``` - -That's settled. This information will be leveraged by other plugins. - -If you're looking for a more production way to manage this secret, then you can do the following with the token being stored in an environment variable called `GITHUB_TOKEN`. - -```yaml title="app-config.local.yaml" -integrations: - github: - - host: github.com - token: ${GITHUB_TOKEN} # this will use the environment variable GITHUB_TOKEN -``` - -> Note: If you've updated the configuration for your integration, it's likely that the backend will need a restart to apply these changes. To do this, stop the running instance in your terminal with `Control-C`, then start it again with `yarn dev`. Once the backend has restarted, retry the operation. - -Some helpful links, for if you want to learn more about: - -- [Other available integrations](../integrations/index.md) -- [Using GitHub Apps instead of a Personal Access Token](../integrations/github/github-apps.md#docsNav) - -### Explore what we've done so far - -## Login to Backstage and check profile - -Open your Backstage frontend. You should see your login screen if you're not -logged in yet. As soon as you've logged in, go to Settings, you'll see your -profile. Hopefully you'll recognize the profile picture and name on your screen, -otherwise something went terribly wrong. - -## Register an existing component - -- Register a new component, by going to `create` and choose - `Register existing component` - - - - ![Software template main screen, with a blue button to add an existing component](../assets/getting-started/b-existing-1.png) - -- As URL use `https://github.com/backstage/backstage/blob/master/catalog-info.yaml`. - This is used in our [demo site](https://demo.backstage.io) catalog. - - ![Register a new component wizard, asking for an URL to the existing component YAML file](../assets/getting-started/b-existing-2.png) - -- Hit `Analyze` and review the changes. Apply them if correct. - - ![Register a new component wizard, showing the metadata for the component YAML we use in this tutorial](../assets/getting-started/b-existing-3.png) - -- You should receive a message that your entities have been added. -- If you go back to `Home`, you should be able to find `backstage`. You should be - able to click it and see the details - -## Create a new component using a software template - -> Note: if you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to -> use the templates feature. -> One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage: -> `export NODE_OPTIONS=--no-node-snapshot` - -- Go to `create` and choose to create a website with the `Example Node.js Template` -- Type in a name, let's use `tutorial` and click `Next Step` - -![Software template deployment input screen asking for a name](../assets/getting-started/b-scaffold-1.png) - -- You should see the following screen: - -![Software template deployment input screen asking for the GitHub username, and name of the new repo to create](../assets/getting-started/b-scaffold-2.png) - -- For host, it should default to github.com -- As owner, type your GitHub username -- For the repository name, type `tutorial`. Go to the next step - -- Review the details of this new service, and press `Create` if you want to - deploy it like this. -- You can follow along with the progress, and as soon as every step is - finished, you can take a look at your new service - -Achievement unlocked. You've set up an installation of the core Backstage App, -made it persistent, and configured it so you are now able to use software -templates. - -Let us know how your experience was: [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/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)! diff --git a/docs/getting-started/create-a-component.md b/docs/getting-started/create-a-component.md new file mode 100644 index 0000000000..13d4fb103d --- /dev/null +++ b/docs/getting-started/create-a-component.md @@ -0,0 +1,41 @@ +--- +id: create-a-component +title: Create a Component +description: Leverage the scaffolder to start creating components with best practices. +--- + +Audience: Developers + +## Summary + +This guide will walk you through how to use Software Templates to create new components with baked in best practices. + +## Prerequisites + +:::note + +If you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to use the templates feature. One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage: `export NODE_OPTIONS=--no-node-snapshot` + +::: + +You should already have [a standalone app](./standalone-install.md). + +## Creating your component + +- Go to `create` and choose to create a website with the `Example Node.js Template` +- Type in a name, let's use `tutorial` and click `Next Step` + +![Software template deployment input screen asking for a name](../assets/getting-started/b-scaffold-1.png) + +- You should see the following screen: + +![Software template deployment input screen asking for the GitHub username, and name of the new repo to create](../assets/getting-started/b-scaffold-2.png) + +- For host, it should default to github.com +- As owner, type your GitHub username +- For the repository name, type `tutorial`. Go to the next step + +- Review the details of this new service, and press `Create` if you want to + deploy it like this. +- You can follow along with the progress, and as soon as every step is + finished, you can take a look at your new service diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md deleted file mode 100644 index 9c6f34dd2c..0000000000 --- a/docs/getting-started/create-an-app.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -id: create-an-app -title: Create an App -description: Documentation on Creating an App ---- - -To get set up quickly with your own Backstage project you can create a Backstage -App. - -A Backstage App is a monorepo setup with `lerna` that includes everything you -need to run Backstage in your own environment. - -If you intend to contribute a plugin, new feature, or bug fix to the Backstage project, you -may want to read the [Contributors](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) guide instead. - -## Create an app - -To create a Backstage app, you will need to have -Node.js [Active LTS Release](https://nodejs.org/en/about/releases/) installed. - -Backstage provides a utility for creating new apps. It guides you through the -initial setup of selecting the name of the app and a database for the backend. -The database options are either SQLite or PostgreSQL, where the latter requires -you to set up a separate database instance. If in doubt, choose SQLite, but -don't worry about the choice, it's easy to change later! Here is a -[tutorial](../tutorials/switching-sqlite-postgres.md) for it. - -The easiest way to run the create app package is with `npx`: - -```bash -npx @backstage/create-app@latest -``` - -This will create a new Backstage App inside the current folder. The name of the -app-folder is the name that was provided when prompted. - -![create app](../assets/getting-started/create-app_output.png) - -Inside that directory, it will generate all the files and folder structure -needed for you to run your app. - -### General folder structure - -Below is a simplified layout of the files and folders generated when creating an -app. - -``` -app -├── app-config.yaml -├── catalog-info.yaml -├── lerna.json -├── package.json -└── packages -   ├── app -   └── backend -``` - -- **app-config.yaml**: Main configuration file for the app. See - [Configuration](https://backstage.io/docs/conf/) for more information. -- **catalog-info.yaml**: Catalog Entities descriptors. See - [Descriptor Format of Catalog Entities](https://backstage.io/docs/features/software-catalog/descriptor-format) - to get started. -- **lerna.json**: Contains information about workspaces and other lerna - configuration needed for the monorepo setup. -- **package.json**: Root package.json for the project. _Note: Be sure that you - don't add any npm dependencies here as they probably should be installed in - the intended workspace rather than in the root._ -- **packages/**: Lerna leaf packages or "workspaces". Everything here is going - to be a separate package, managed by lerna. -- **packages/app/**: An fully functioning Backstage frontend app, that acts as a - good starting point for you to get to know Backstage. -- **packages/backend/**: We include a backend that helps power features such as - [Authentication](https://backstage.io/docs/auth/), - [Software Catalog](https://backstage.io/docs/features/software-catalog/), - [Software Templates](https://backstage.io/docs/features/software-templates/) - and [TechDocs](https://backstage.io/docs/features/techdocs/) - amongst other things. - -### Troubleshooting - -The create app command doesn't always work as expected, this is a collection of -some of the commonly encountered issues and solutions. - -#### Couldn't find any versions for "file-saver" - -You may encounter the following error message: - -```text -Couldn't find any versions for "file-saver" that matches "eligrey-FileSaver.js-1.3.8.tar.gz-art-external" -``` - -This is likely because you have a globally configured npm proxy, which breaks -the installation of the `material-table` dependency. This is a known issue and -being worked on in `material-table`, but for now you can work around it using -the following: - -```bash -NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx @backstage/create-app -``` - -#### Can't find Python executable "python" - -The install process may also fail if no Python installation is available. Python -is commonly available in most systems already, but if it isn't you can head for -example [here](https://www.python.org/downloads/) to install it. - -#### Could not execute command yarn install - -Install Yarn on your system with `npm install --global yarn` or for more details -refer to the [prerequisites](index.md#prerequisites). - -## Run the app - -When the installation is complete you can open the app folder and start the app. - -```bash -cd my-backstage-app -yarn dev -``` - -The `yarn dev` command will run both the frontend and backend as separate -processes (named `[0]` and `[1]`) in the same window. When the command finishes -running, it should open up a browser window displaying your app. If not, you can -open a browser and directly navigate to the frontend at `http://localhost:3000`. - -Now you're free to hack away on your own Backstage installation! - -As you get more experienced with the app, in future you can run just the -frontend with `yarn start` in one window, and the backend with -`yarn start-backend` in a different window. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md deleted file mode 100644 index 11de12feb9..0000000000 --- a/docs/getting-started/index.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -id: index -title: Getting Started -description: Documentation on How 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: - -- 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](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) guide to do a repository-based installation. - -### Prerequisites - -- 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 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](https://nodejs.org/en/about/previous-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) - - [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) - - You will need to use Yarn classic to create a new project, but it can then be [migrated to Yarn 3](../tutorials/yarn-migration.md) -- `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 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. - -```bash -npx @backstage/create-app@latest -``` - -> Note: 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. - -The wizard will ask you for the name of the app, which will also be the name of the directory - -![Screenshot of the wizard asking for a name for the app.](../assets/getting-started/wizard.png) - -### 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. - -```bash -cd my-backstage-app -yarn dev -``` - -![Screenshot of the command output, with the message web pack compiled successfully](../assets/getting-started/startup.png) - -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. - -![Screenshot of the Backstage portal.](../assets/getting-started/portal.png) - -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](configuration.md). - -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/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)! diff --git a/docs/getting-started/logging-in.md b/docs/getting-started/logging-in.md new file mode 100644 index 0000000000..cb7de7faef --- /dev/null +++ b/docs/getting-started/logging-in.md @@ -0,0 +1,31 @@ +--- +id: logging-in +title: Logging into Backstage +description: Getting up and running with Backstage and your identity provider +--- + +Audience: All + +## Summary + +This guide will provide a quick tutorial on how to log in to your Backstage instance. It should be used as both an introduction to Backstage's authentication system as well as a debugging guide for any issues you may have while logging in. + +## Prerequisites + +You should have already [have a standalone app](./standalone-install.md) and completed the Github OAuth app setup defined in [the authentication tutorial](./config/authentication.md). + +## 1. Login to Backstage and check profile + +Run your Backstage app with `yarn dev`. Navigate to `http://localhost:3000`. + +If you're not already logged in, you should see a login screen like this, + +To login, you should choose the "Github" provider and click the "Sign in" button. This will redirect you to a Github OAuth page. Verify that the scopes mentioned on that page match the setup you did in [the authentication tutorial](./config/authentication.md). Once you click "Confirm", you will be brought back to the Backstage interface and signed in! + +If you are already logged in, you will be automatically brought to your Backstage instance. + +Once you've logged in, find the "Settings" item in the navigation bar to the left. Click it and you will see your profile. If you see your profile picture and name from Github here, congratulations! You've successfully set up a Github authentication integration. + + + +If you don't see your profile picture and name, check that you followed all of the steps in [the authentication tutorial](./config/authentication.md). If you have, search for similar issues on [the Discord server](https://discord.gg/backstage-687207715902193673). diff --git a/docs/getting-started/register-a-component.md b/docs/getting-started/register-a-component.md new file mode 100644 index 0000000000..c882c4c05f --- /dev/null +++ b/docs/getting-started/register-a-component.md @@ -0,0 +1,41 @@ +--- +id: register-a-component +title: Registering a Component +description: Start populating your Backstage app with your data. +--- + +Audience: Developers + +## Summary + +This guide will walk you through how to pull Backstage data from other locations manually. There are integrations that will automatically do this for you. + +## Prerequisites + +You should have already [have a standalone app](./standalone-install.md). + +## 1. Finding our template + +Register a new component, by going to `create` and choose `Register existing component` + + + +![Software template main screen, with a blue button to add an existing component](../assets/getting-started/b-existing-1.png) + +## 2. Filling out the template + +For repository URL, use `https://github.com/backstage/backstage/blob/master/catalog-info.yaml`. This is used in our [demo site](https://demo.backstage.io) catalog. + +![Register a new component wizard, asking for an URL to the existing component YAML file](../assets/getting-started/b-existing-2.png) + +Hit `Analyze` and review the changes. + +## 3. Import the entity + +If the changes from `Analyze` are correct, click `Apply`. + +![Register a new component wizard, showing the metadata for the component YAML we use in this tutorial](../assets/getting-started/b-existing-3.png) + +You should receive a message that your entities have been added. + +If you go back to `Home`, you should be able to find `backstage`. You can click it and see the details for this new entity. diff --git a/docs/getting-started/standalone-install.md b/docs/getting-started/standalone-install.md new file mode 100644 index 0000000000..dd730183b5 --- /dev/null +++ b/docs/getting-started/standalone-install.md @@ -0,0 +1,169 @@ +--- +id: standalone-install +title: Installing a standalone server (Developer or Admin) +description: How to install Backstage for your own use. +--- + +Audience: All + +## Summary + +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. + +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. + +:::note Contributors + +If you are planning to contribute a new feature or bug fix to the Backstage project, we advise you to follow the [Contributors](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#get-started) guide instead to do a repository-based installation. + +::: + +## Prerequisites + +This guide 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 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](https://nodejs.org/en/about/previous-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) + - [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) + - You will need to use Yarn classic to create a new project, but it can then be [migrated to Yarn 3](../tutorials/yarn-migration.md) +- `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 jump in to running the command, let's chat about 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 sub directory in your current working directory. + +![create app](../assets/getting-started/create-app-output.png) + +Inside that directory, it will generate all the files and folder structure +needed for you to run your app. + +### General folder structure + +Below is a simplified layout of the files and folders generated when creating an app. + +``` +app +├── app-config.yaml +├── catalog-info.yaml +├── package.json +└── packages +   ├── app +   └── backend +``` + +- **app-config.yaml**: Main configuration file for the app. See + [Configuration](https://backstage.io/docs/conf/) for more information. +- **catalog-info.yaml**: Catalog Entities descriptors. See + [Descriptor Format of Catalog Entities](https://backstage.io/docs/features/software-catalog/descriptor-format) + to get started. +- **package.json**: Root package.json for the project. _Note: Be sure that you + don't add any npm dependencies here as they probably should be installed in + the intended workspace rather than in the root._ +- **packages/**: Lerna leaf packages or "workspaces". Everything here is going + to be a separate package, managed by lerna. +- **packages/app/**: An fully functioning Backstage frontend app, that acts as a + good starting point for you to get to know Backstage. +- **packages/backend/**: We include a backend that helps power features such as + [Authentication](https://backstage.io/docs/auth/), + [Software Catalog](https://backstage.io/docs/features/software-catalog/), + [Software Templates](https://backstage.io/docs/features/software-templates/) + and [TechDocs](https://backstage.io/docs/features/techdocs/) + amongst other things. + +Now, that we know what it does, let's run it! + +```bash +npx @backstage/create-app@latest +``` + +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 + +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. + +::: + +## 2. Run the Backstage app + +You 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 dev` command. 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 # your app name +yarn dev +``` + +![Screenshot of the command output, with the message web pack compiled successfully](../assets/getting-started/startup.png) + +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 + +When you see the message `[0] webpack 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 a production server + - [Deploying with Docker](../deployment/docker.md) + - [Deploying with Kubernetes](../deployment/k8s.md) + - [Deploying with AWS Lightsail](../deployment/backstage-deploy/aws.md) +- Configuring Backstage + - [Database](./config/database.md) + - [Authentication](./config/authentication.md) + - [Plugins](./configure-app-with-plugins.md) + - [Theme](./app-custom-theme.md) + - [Homepage](./homepage.md) + +### Developer + +- [Logging into Backstage](./logging-in.md) +- Register a component +- Create a new component + +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/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)! diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index 461fab8af8..858968f462 100644 --- a/docs/integrations/github/discovery.md +++ b/docs/integrations/github/discovery.md @@ -95,7 +95,7 @@ You can check the official docs to [configure your webhook](https://docs.github. ## Configuration To use the discovery provider, you'll need a GitHub integration -[set up](locations.md) with either a [Personal Access Token](../../getting-started/configuration.md#setting-up-a-github-integration) or [GitHub Apps](./github-apps.md). +[set up](locations.md) with either a [Personal Access Token](../../getting-started/config/authentication.md) or [GitHub Apps](./github-apps.md). Then you can add a `github` config to the catalog providers configuration: @@ -294,7 +294,7 @@ export default async function createPlugin( ## Configuration To use the discovery processor, you'll need a GitHub integration -[set up](locations.md) with either a [Personal Access Token](../../getting-started/configuration.md#setting-up-a-github-integration) or [GitHub Apps](./github-apps.md). +[set up](locations.md) with either a [Personal Access Token](../../getting-started/config/authentication.md) or [GitHub Apps](./github-apps.md). Then you can add a location target to the catalog configuration: diff --git a/microsite/docusaurus.config.js b/microsite/docusaurus.config.js index 34d882c110..9e45e01d7e 100644 --- a/microsite/docusaurus.config.js +++ b/microsite/docusaurus.config.js @@ -69,8 +69,8 @@ module.exports = { ], ], markdown: { - preprocessor({ fileContent }) { - // Replace all HTML comments with emtpy strings as these are not supported by MDXv2. + preprocessor({ filePath, fileContent }) { + // Replace all HTML comments with empty strings as these are not supported by MDXv2. return fileContent.replace(//gs, ''); }, format: 'md', @@ -152,6 +152,18 @@ module.exports = { from: '/docs/overview/glossary', to: '/docs/references/glossary', }, + { + from: '/docs/getting-started/create-an-app', + to: '/docs/getting-started/standalone-install' + }, + { + from: '/docs/getting-started/configuration', + to: '/docs/getting-started/standalone-install#next-steps' + }, + { + from: '/docs/getting-started', + to: '/docs/getting-started/standalone-install' + }, ], }, ], diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 146d8db059..5055572ed7 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -40,18 +40,21 @@ "overview/logos" ], "Getting Started": [ - "getting-started/index", - "getting-started/configuration", - "getting-started/create-an-app", + "getting-started/standalone-install", { "type": "category", - "label": "App configuration", + "label": "Configuring Backstage (Admin)", "items": [ + "getting-started/config/database", + "getting-started/config/authentication", "getting-started/configure-app-with-plugins", "getting-started/app-custom-theme", "getting-started/homepage" ] }, + "getting-started/logging-in", + "getting-started/register-a-component", + "getting-started/create-a-component", "getting-started/keeping-backstage-updated", "getting-started/concepts", "getting-started/contributors",