paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 21 Packages Projects Releases Wiki Activity

docs: start adding user roles to getting started documentation

Browse Source 
Following CNCF guidelines for improved Backstage documentation.

Signed-off-by: Aramis <sennyeyaramis@gmail.com>
This commit is contained in:
Aramis
2024-01-26 10:11:31 -05:00
committed by aramissennyeydd
parent 25adbdde2d
commit a33bd1f7a8
20 changed files with 584 additions and 568 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/config/authentication.md
+134
View File
@@ -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 => (
<SignInPage
{...props}
auto
provider={{
id: 'github-auth-provider',
title: 'GitHub',
message: 'Sign in using GitHub',
apiRef: githubAuthApiRef,
}}
/>
),
},
```
> 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)
docs/getting-started/config/database.md
+139
View File
@@ -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 `<secret>` 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 '<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.
### 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.
docs/getting-started/configuration.md
-328
View File
@@ -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: <file-path>/server.pem
# key:
# $file: <file-path>/client.key
# cert:
# $file: <file-path>/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 => (
<SignInPage
{...props}
auto
provider={{
id: 'github-auth-provider',
title: 'GitHub',
message: 'Sign in using GitHub',
apiRef: githubAuthApiRef,
}}
/>
),
},
```
> 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`
<!-- todo: Needs zoomable plugin -->
![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)!
docs/getting-started/create-a-component.md
+41
View File
@@ -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
docs/getting-started/create-an-app.md
-130
View File
@@ -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.
docs/getting-started/index.md
-96
View File
@@ -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)!
docs/getting-started/logging-in.md
+31
View File
@@ -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.
<!-- Would like to have more FAQs here for help instead of funneling to Discord -->
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).
docs/getting-started/register-a-component.md
+41
View File
@@ -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`
<!-- todo: Needs zoomable plugin -->
![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.
docs/getting-started/standalone-install.md
+169
View File
@@ -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)!