May 1, 2022
 min read

Spotify's Backstage: A Simple Introductory Guide

What is Spotify's Backstage? Why did Spotify build it, and how can it help you? Is it the right solution for your team? We have the answers.

Spotify's Backstage is a recent addition to the developer portal community. It has a lot to offer a large engineering organization that needs a way to organize its internal tools and documentation. But is it the right portal for you? What are the pros and cons of Backstage's developer portal offering? 

Let's look at Backstage's features, what it takes to run it, and how you can decide if it's your best option for an engineering home base. 

What Is Spotify's Backstage: The Quick Definition

Backstage is a platform for creating developer portals. It gives you the tools you need to create a single place to keep your engineering team's documentation, tools, and other critical resources. 

You can use Backstage to: 

  • Share metadata across different teams.
  • Catalog your libraries, websites, models, and more.
  • Build a uniform view of your engineering tools.
  • Define software templates to drive consistency in your organization.
  • Monitor CI/CD status.

Backstage is an open-source offering that you need to download, install, and maintain yourself. Spotify donated it to the Cloud Native Computing Foundation (CNCF) and licensed it under the Apache 2.0 license, so it's free to use for commercial or personal purposes. 

Backstage Components

Plugins are what drive Spotify's Backstage functionality. They offer a variety of features and integrations. While there are more than 130 plugins available, three of them provide the portal's core offerings: the Software Catalog, Software templates, and Techdocs. Let's take a brief look at each one. 

Backstage Software Catalog

Backstage has a software catalog that acts as a centralized location for tracking internal applications, libraries, pipelines, and websites. Your engineering teams register entities in the catalog via YAML files that make up an explorable index of components, APIs, and resources. Backstage maintains the YAML files in git for you, so your catalog is backed up and recoverable with a complete history. 

The Software Catalog solves two big problems: 

  1. It's a way for teams to manage and maintain the software they own. Everyone gets a consistent view of all their software; services, libraries, websites, and models.
  2. Now all of the software in your company is indexed and discoverable.

Backstage Software Templates

One of the biggest challenges in a large engineering organization is making it easy for teams to maintain consistency and enforce standards across projects. Backstage's Software Templates help address that problem. 

You can create templates inside Backstage that, with the click of a button, create new projects in places like GitLab and Github. So, rather than legislating conventions and standards. You can make it easy for teams to start new projects on the right foot. 

Backstage TechDocs

Techdocs is a tool for storing your documentation with your code while still making it easy for engineers to view. 

Your engineers write their documentation in Markdown and store it in source control, right next to their code. An MkDocs build step creates a documentation website when your CI pipeline builds the code. Backstage pulls in the site and displays it in your portal. 

Why Do I Need a Software Catalog?

Your collection of software tools, libraries, and applications grows with your company. Every time your team writes some new code, signs up for a new cloud service, or adds a new API to the mix, they've created a new asset that you need to track. 

You need a single source of truth for tracking these assets. You need a catalog. 

The catalog acts as a knowledge management tool where your engineers can discover what tools are in use by the organization, where they are located, and who's responsible for them. 

A catalog solves and prevents several problems: 

  • If something goes wrong with an internal application, it's easy to find who can fix it.
  • When engineers need to solve a problem, they can find out if someone else already has a solution.
  • Before adding a new third-party tool or service, engineers can see if the organization has already adopted a similar solution, or perhaps even the same one.

Backstage History

Spotify describes Backstage as being "born out of necessity." Their infrastructure grew quickly, with development teams moving fast and distributed across several regions. As a result, their tools and processes were fragmented and hard to manage. 

So, their teams were spending more time figuring out how to get started than they were writing, building, and testing code. They experienced the problems described in the section above and needed a single source of truth for their infrastructure. 

They decided to build a layer that sat on top of their tools and infrastructure, making it easier to find, use, and manage their services and tooling. Spotify describes Backstage as a "developer portal powered by a centralized software catalog." 

Why Backstage?

Since you download, install, and build Backstage yourself, you can run it anywhere you wish. This means it can run on-premises or in your cloud infrastructure, so it's easy to tie it directly to your systems without having to worry about opening it up to the outside world. 

That makes Backstage's promise to "unify all your infrastructure tooling, services, and documentation" possible. Regardless of what you're running and where you're running it, you can make it available to Backstage's abstraction layer. 

Backstage's plugin architecture, and the 130 plugins already available, means it's remarkably powerful and extensible "out of the box." Backstage can talk to AWS Lambda, Azure Pipelines, Datadog, Github Actions, and many more third-party tools. 

So, Backstage has the power to fulfill its promises, but at what cost? 

Why Not Backstage?

Install and Maintenance Costs

Cost? But didn't we say the Backstage is free as in beer? Yes, it is. But, as we also said, you download, install, and build Backstage yourself. Building a Backstage portal requires a great deal of work, and it also requires considerable maintenance. 

Even though it's a CNCF offering, Backstage doesn't ship pre-built Docker containers. The installation requires Node.js and Yarn and, depending on your existing tech stack, may require additional resources. Backstage also requires a lot of customization and will likely need a dedicated team to maintain the systems and to keep the application up to date. 

Where do you want to focus your development efforts? Maintaining Backstage requires time and effort on tasks that don't add value to your clients. 

Architecture Limitations

Backstage acts as an abstraction layer over your existing services and tools. It reads YAML files and feeds describing your infrastructure, but it has few querying and reporting capabilities. In a way, it acts as an RSS reader, displaying a syndicated feed that describes your assets. 

A SaaS Alternative

configure8 offers a different approach to solving the developer experience problem. It's a hosted alternative to Backstage, so we maintain the infrastructure and operate the portal for you. You don't need to dedicate engineering staff to run your software catalog, and you can get up and running quickly without extensive preparation or design lead time. 

configure8 addresses Backstage's architectural limitations, too. It maps your data in a graph database so you can run ad hoc and pre-configured queries that let you analyze how your components are related and how they've changed over time. So, you can get an understanding of your assets and learn how to improve.  

Build Your Catalog Today

In this article, we looked at Spotify's Backstage and what it has to offer your organization. Its plugin architecture and built-in features make it a compelling offering. But it's not a great fit for all organizations: Backstage requires up-front configuration and ongoing maintenance. So, we talked about how a SaaS option may work better for you. 

Regardless of which solution you choose, a software and service catalog will help you manage your tools. Get started on one today! 

This post was written by Eric Goebelbecker. Eric has worked in the financial markets in New York City for 25 years, developing infrastructure for market data and financial information exchange (FIX) protocol networks. He loves to talk about what makes teams effective (or not so effective!).

Latest articles

Browse all