Backstage by Example (Part 1)

A hands-on walk-through of installing and configuring a Backstage App for our use.

What is Backstage?

Backstage is an open platform for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly — without compromising autonomy.

Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

— What is Backstage?

Why Backstage?

Getting Started

The Backstage Getting Started document provides us with a Backstage App (project) with sample data. To understand the sample data, it is useful to examine the entity relationship diagram (ERD) and entities for Backstage.

There are the three “leaf” entities: Components, APIs, and Resources:

A component is a piece of software, for example a mobile feature, web site, backend service or data pipeline (list not exhaustive). A component can be tracked in source control, or use some existing open source or commercial software.

APIs form an important (maybe the most important) abstraction that allows large software ecosystems to scale. Thus, APIs are a first class citizen in the Backstage model and the primary way to discover existing functionality in the ecosystem.

Resources are the infrastructure a component needs to operate at runtime, like BigTable databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with components and systems will better allow us to visualize resource footprint, and create tooling around them.

The System and Domain entities are used in organizing the “leaf” entities.

With increasing complexity in software, systems form an important abstraction level to help us reason about software ecosystems. Systems are a useful concept in that they allow us to ignore the implementation details of a certain functionality for consumers, while allowing the owning team to make changes as they see fit (leading to low coupling).

While systems are the basic level of encapsulation for related entities, it is often useful to group a collection of systems that share terminology, domain models, metrics, KPIs, business purpose, or documentation, i.e. they form a bounded context.

— System Model

The Software Template entity does not have any relationships to other entities, but is rather used in the process to create Components.

The Software Templates part of Backstage is a tool that can help you create Components inside Backstage. By default, it has the ability to load skeletons of code, template in some variables, and then publish the template to some locations like GitHub or GitLab.

— Backstage Software Templates

The User and Group entities are used in building ownership relationships to other entities.

An ownership relation where the owner is usually an organizational entity (User or Group), and the other entity can be anything.

In Backstage, the owner of an entity is the singular entity (commonly a team) that bears ultimate responsibility for the entity, and has the authority and capability to develop and maintain it. They will be the point of contact if something goes wrong, or if features are to be requested. The main purpose of this relation is for display purposes in Backstage, so that people looking at catalog entities can get an understanding of to whom this entity belongs. It is not to be used by automated processes to for example assign authorization in runtime systems. There may be others that also develop or otherwise touch the entity, but there will always be one ultimate owner.

This relation is commonly generated based on spec.owner of the owned entity, where present.

— Well-known Relations between Catalog Entities

The remaining entity, Locations, does not appear to have any relationship with other entities and the documentation on it is scarce.

A Location reference that points to the source code of the entity (typically a Component). Useful when catalog files do not get ingested from the source code repository itself.

— Well-known Annotations on Catalog Entities

Getting Started, configuring Backstage

The Backstage Getting Started, configuring Backstage document walks us through several common configuration tasks.

Install and configure PostgreSQL

In the Getting Started document, we used a temporary SQLite database to support the Backstage App; in this document we transition to using a permanent PostgreSQL database.

Rather than installing PostgreSQL onto our workstation, it is easier to run it in a Docker container. Here we can create a file, docker-compose.yml, in the Backstage App folder. This file is based off the instructions provided for the official postgres Docker image; except here we also expose the PostgreSQL database to our workstation on port 5432.

e

We start PostgresSQL by typing:

$ docker-compose up -d

We can continue through the document through updating the app-config.yaml file with the updated database configuration. Because it bad practice to commit secrets into source control, we can create a new file, environment.sh, in the Backstage App folder as follows and add it to the .gitignore file in the same folder.

We can set the environment variables and start the Backstage App using the following commands.

$ source environment.sh
$ yarn dev

Going forward, when we start the Backstage App, we will use these commands.

Setting up authentication

Following the document, we will use GitHub for authentication. Here, however, we use a GitHub Organization account instead of a Personal account.

Your team can collaborate on GitHub by using an organization account. Each person that uses GitHub signs into a user account. Multiple user accounts can collaborate on shared projects by joining the same organization account, which owns the repositories. A subset of these user accounts can be given the role of organization owner, which allows those people to granularly manage access to the organization’s resources using sophisticated security and administrative features.

— About organizations

When creating the GitHub OAuth App, we be sure to use localhost instead of 127.0.0.1 in the URLs; the document is inconsistent in this regard.

Also instead of adding the Client Id and Secret to the app-config.yaml, we rather add it to environment.sh file as follows.

We then update app-config.yaml; updating the root auth key.

The last step, a bit unusual, requires us to modify the React code to support GitHub authentication. Once done, we start the Backstage App and find that we have to authenticate now.

Observations:

• We first observe that by using the Settings menu option, we can see who we are logged in with; presumably seeing our name (and maybe avatar image)
• The list of sample User entities does not list ourselves
• It is easy to miss, but before we enabled authentication we saw that we owned a number of Components as we were associated with the guest User entity. After we enabled authentication, we own no Components; thus we are not associated with the guest User entity

Setting up a GitHub Integration

Continuing to follow the document, we setup an integration to our GitHub organization. As we have a GitHub Organization account, we will use a GitHub App instead of a Personal Access Token.

Backstage can be configured to use GitHub Apps for backend authentication. This comes with advantages such as higher rate limits and that Backstage can act as an application instead of a user or bot account.

— GitHub Apps for Backend Authentication

We follow the steps in Using the CLI (public GitHub only) and Including in Integrations Config in the documentation; GitHub Apps for Backend Authentication.

We, additionally, update the GitHub App permissions.

App permissions is not managed by Backstage. They’re created with some simple default permissions which you are free to change as you need, but you will need to update them in the GitHub web console, not in Backstage right now. The permissions that are defaulted are metadata:read and contents:read.

— GitHub Apps for Backend Authentication

The full list of required App permissions is provided.

Login and Backstage and check profile

After starting the Backstage App, we can finish up by following the instructions Login to Backstage and check profile.

Next Steps

In the next article, Backstage by Example (Part 2), we clean-up the Backstage App for our use.