Let's talk Backstage — Part 1

6 min readJan 31, 2023

Hey, welcome or welcome back. If you have landed here, you are probably wondering what is backstage or if your interest is in learning something new.

My team was recently asked to set up backstage for a client. The first thing that occurred to me was what in the world is backstage? Continue reading if you have a similar question :)

Now that I know, let me tell you about it.

Backstage is one of the most well-known and active initiatives within the CNCF (Cloud Native Compute Foundation). It is the Developer Portal Platform that was born out of Spotify. Backstage offers a structure and place to start for what eventually becomes your highly specialized developer portal, built in a way that makes sense for the teams in your company. For developer portals, Backstage offers the framework and plugin system as well as a number of universal and crucial features.

To summarize, Backstage is the single portal that your developers need to get their work done. It allows you to look at dependencies, CICD, Kubernetes, technical documentation and so much more at a single place.

Benefits

For engineering managers, it allows you to maintain standards and best practices across the organization and can help you manage your whole tech ecosystem, from migrations to test certification.
For end users (developers), it makes it fast and simple to build software components in a standardized way, and it provides a central place to manage all projects and documentation.
For platform engineers, it enables extensibility and scalability by letting you easily integrate new tools and services (via plugins), as well as extending the functionality of existing ones.
For everyone, it’s a single, consistent experience that ties all your infrastructure tooling, resources, standards, owners, contributors, and administrators together in one place.

Getting Started

Well, just to get the idea of what backstage looks like, you can use the quickest way to see a sample Backstage environment through the public demo that can be accessed here. However, it will be limited to the actions that you can perform. If you want more, you can install your own instance of Backstage as follows.

Prerequisite:

An account with elevated rights to install the dependencies
curl or wget installed
yarn Installation
git installation
Required ports for a default setup: 3000, 7007

STEPS

1. Open the terminal and execute the below command, you will be asked for the name of the app, which will also be the name of the directory. Ex: my-backstage-app

npx @backstage/create-app@latest

2. Move to your app and run yarn dev

cd my-backstage-app
yarn dev

Access the application on localhost:3000 in your browser. Now, let's change to a persistent database.

3. Install Postgres and set a password.

sudo apt-get install postgresql
sudo -u postgres psql

postgres=# ALTER USER postgres PASSWORD '<type password>';

Type \q, followed by pressing the enter key. Then again type exit and press enter. Next, you need to install and configure the client.

# From your Backstage root directory
yarn add --cwd packages/backend pg

4. 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.

  database:
    client: pg
    connection:
      host: localhost
      port: 5432
      user: postgres
      password: <password you choose in step 3>

Start the Backstage app:

yarn dev

It's done, now we will Set up GitHub authentication. there is various authentication available other than GitHub, you can explore them here.

5. Go to https://github.com/settings/applications/new to create your OAuth App. They Homepage URL should point to the Backstage's frontend, in this article 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.

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:
  environment: development
  providers:
    github:
      development:
        clientId: <YOUR CLIENT ID>
        clientSecret: <YOUR CLIENT SECRET>

6. Add a new sign-in option to the front end.

Open packages/app/src/App.tsx and below the last import line, add:

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:

components: {
  SignInPage: props => (
    <SignInPage
      {...props}
      auto
      provider={{
        id: 'github-auth-provider',
        title: 'GitHub',
        message: 'Sign in using GitHub',
        apiRef: githubAuthApiRef,
      }}
    />
  ),
},

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 like in the screenshot below.

Click on the SIGN IN button and you will be landed on the backstage home screen. If you want to see the GitHub profile by which you are logged in, click on settings in the bottom left. See the screenshot for reference.

Note: Sometimes the front end starts before the backend resulting in errors on the sign-in page. Wait for the backend to start and then reload Backstage to proceed.

You have now deployed a backstage app — made it persistent and enabled GitHub authentication. The next step is to set up GitHub integration to support loading catalog entities from GitHub.

7. Go to your GitHub account and create a personal access token. Once done, add it to app-config.yaml as shown below:

integrations:
  github: 
    - host: github.com
      token: <your token>

you can do the above with the token being stored in an environment variable called GITHUB_TOKENfor a production-ready solution.

Read here to use GitHub Apps instead of the personal access token.

Re-start the Backstage app:

yarn dev

If you have followed all the steps above, you should see a similar page on localhost:3000

Next is to create a new component.

8. Click on CREATE -> choose a template(Example Node.js Template) -> fill in the details and click create. If you get an error like below, there is something wrong with step no 7. Check that!

If not, you will get successful results like the below:

9. Go back to your Backstage app and click on Home. You will see the component created in the last step. Click on it and notice the tabs available at the top(Screenshot for reference).

You will see default options such as CICD, API, DEPENDENCIES, and DOCS. These tabs will be empty because none of them are yet present in our component. Backstage includes a number of additional plugins that, like the default ones, can be enabled and accessed. It is also possible to create a custom plugin. More information can be found here.

That's it for this article.

Wrap Up

Thank you for continuing to read this far. I hope you enjoyed learning as much as I did writing this. Part 2 will introduce the Kubernetes plugin and how to integrate it to see workloads backstage. I’ll see you later.

Keep learning!