backstage/docs/getting-started/configuration.md

id, title, description

id	title	description
configuration	Getting Started, configuring Backstage	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 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
• 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's detailed instructions on how to install PostgreSQL to help you get started.

sudo apt-get install postgresql

Test if your database is working:

sudo -u postgres psql

You should see a very welcoming message, like:

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:

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:

# From your Backstage root directory
cd packages/backend
yarn 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.

backend:
  database:
-    client: sqlite3
-    connection: ':memory:'
+    # config options: https://node-postgres.com/api/client
+    client: pg
+    connection:
+      host: ${POSTGRES_HOST}
+      port: ${POSTGRES_PORT}
+      user: ${POSTGRES_USER}
+      password: ${POSTGRES_PASSWORD}
+      # https://node-postgres.com/features/ssl
+      #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
+        #ca: # if you have a CA file and want to verify it you can uncomment this section
+        #$file: <file-path>/ca/server.crt

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:

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's some helpful links:

• Configuring Plugin Databases
• Read more about Knex, which is the library we use for the database backend

Setting up authentication

There's multiple authentication providers available for you to use with Backstage, feel free to follow the instructions for adding authentication.

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.

Go to 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://127.0.0.1:3000. The Authorization callback URL will point to the auth backend, which will most likely be http://127.0.0.1:7007/api/auth/github/handler/frame.

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:

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

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:

import { githubAuthApiRef } from '@backstage/core-plugin-api';
import { SignInProviderConfig, SignInPage } from '@backstage/core-components';

const githubProvider: SignInProviderConfig = {
  id: 'github-auth-provider',
  title: 'GitHub',
  message: 'Sign in using GitHub',
  apiRef: githubAuthApiRef,
};

Search for const app = createApp({ in this file, and below apis, add:

components: {
   SignInPage: props => (
     <SignInPage
       {...props}
       auto
       provider={githubProvider}
     />
   ),
 },

That should be it. You can stop your Backstage App. When you start it again and go to your Backstage portal in your browser, you should have your login prompt!

To learn more about Authentication in Backstage, there's the following docs you could read:

• Adding Authentication
• Adding a new Authentication Provider
• Using authentication and identity
• Using organizational data from GitHub

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 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 the GitHub token creation page. 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.

Set the scope to your likings. For this tutorial, selecting "repo" should be enough.

In the app-config.yaml, search for integrations: and add your token, like we did in below example:

integrations:
  github:
    - host: github.com
      token: ghp_urtokendeinfewinfiwebfweb

That's settled. This information will be leveraged by other plugins.

Some helpful links, for if you want to learn more about:

• Other available integrations
• Using GitHub Apps instead of a Personal Access Token

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

• As URL use https://github.com/backstage/demo/blob/master/catalog-info.yaml. This is used by our demo site.

- Hit `Analyze` and review the changes. Apply them if correct

• You should receive a message that your entities have been added.
• If you go back to Home, you should be able to find demo. You should be able to click it and see the details

Create a new component using a software template

• Go to create and choose to create a website with the React SSR Template
• Type in a name, let's use tutorial
• Select the group group-a which will own this new website, and go to the next step

• For the location, we're going to use the default
• 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, file issues for any feature or plugin suggestions, or bugs you have, and feel free to contribute!