An Overview of Spotify Backstage

You may have heard of Spotify Backstage, an open platform for building developer portals. In this article, we answer your questions — like what can Backstage do, and who is it for?

January 1, 2022

You might have heard of Spotify Backstage (, a newer option in the developer portal ecosystem. This article will help answer your questions about Backstage and explain important considerations to think about if you’re deciding whether to adopt this open-source tool.

Introduction to Backstage

What is Spotify Backstage?

Spotify Backstage is an open platform for building developer portals to create, manage, and explore software from a single UX layer. Backstage was originally developed at Spotify as an internal tool and then was open-sourced in 2020. Its functionality includes a software catalog, software templates, docs like code, and a variety of plugins that can extend the platform.

Why did Spotify create and open source Backstage?

Backstage began as an internal project called “System Z” at Spotify to help engineers discover and understand all the company’s software, services, docs, APIs, and tools. This project provided a UX layer to help engineers quickly answer questions about software ownership, deployment, and dependencies. With its internal success, Spotify believed open-sourcing Backstage would help development teams everywhere navigate their internal infrastructure more easily.

The Rise of the Developer Portal & Service Catalog

Why are companies turning to developer portals and service catalogs? We’ve identified several contributing trends:

  • Growing complexity of engineering organizations. Spotify has almost five hundred engineering teams with twenty thousand deployments a day across thousands of microservices. As more high-growth “unicorn” tech companies emerge, there’s an increasing need for tools that help manage this complexity.
  • Autonomous teams. The popular “Spotify Model” involves having small “squads” of engineers, around 7-10 people, that own projects end-to-end. Developer portals and service catalogs help teams maintain their independence while enforcing standardization and ease of discovery.
  • Rise of developer tools. There’s been an explosion in developer tools in recent years, because every company is now a software company, and because increasing developer productivity can make a huge impact on a business’s bottom line. Developer portals and service catalogs are developer tools — and they also help organize the growing number of developer tools that teams use internally.

How Spotify Backstage Solves Problems for Engineering Teams

Creating a streamlined end-to-end development environment

With a single, searchable UX for your internal software ecosystem, you can get up to speed on new features, find redundancies or breakages, and foster better cross-org collaboration across your org while improving the developer experience. Backstage Scaffolder, developers can easily set up work environments that resemble production more faithfully, resulting in less friction and fewer surprises along the development path.

Removing complexities in shipping new products and building applications from scratch

Engineers can use Backstage to quickly create new software that’s aligned with the team’s best practices. Templates ensure that software meets your requirements around security or compliance from the very beginning. With plugins, engineers can incorporate pre-built solutions, shared patterns, and see preferred tools, helping them get up to speed.

Reducing silos between teams

Teams and leadership get visibility into projects, documentation, and integrations from one central place. There’s no need to message colleagues on Slack to figure out who owns a piece of code or where to find a runbook. With the ability to easily explore infrastructure via a UX layer, engineers can discover new ways to reuse code or collaborate with other teams. Leadership can identify projects in need of investment or services without owners.

Challenges of Working with Backstage

While Backstage provides many advantages, there are challenges to be aware of when working with this tool, primarily because it involves a significant engineering investment. As Backstage is an open-source tool, the deployment, configuration, and maintenance falls on the end-user. There is documentation, but direct support may be limited and is not guaranteed.

The tool is still in early stages and under continual development, with many features still in the alpha or beta stage. It will be important to have engineering resources dedicated to keeping up-to-date with any changes and their impact on your Backstage implementation.

Unlike other CNCF projects, Backstage does not come with pre-built Docker containers to deploy and will require an investment of development hours to create the Backstage app, apply customizations, and deploy to production. It’s important to note that Backstage is built using Node.js and Yarn, and depending on your tech stack, additional expertise and work to integrate these technologies may be needed.

Backstage Features — Out of the Box

Backstage includes several features for organizing software and related documentation:

Backstage Software Catalog

Currently in alpha, the Backstage Software Catalog is a unified source of metadata and ownership information about all the software that your team works on, like microservices, APIs, data pipelines, libraries, and more. The catalog is based on metadata YAML files. You can track third-party software, too, so you have one place to view all the external tools you use to manage your code.

Backstage Software Templates

Currently in beta, Backstage Software Templates let you define a code skeleton with variables that can be filled in. Then, you can push your template to GitHub or GitLab, where it can be used by the team to standardize the creation of new services (or even something like an onboarding guide).

Backstage Search

Also in alpha, Backstage Search lets you choose from modular frontend and backend components to build the right search tool for your organization. In addition to searching your software catalog, you can add support for other sources like your plugins, wiki, or even Stack Overflow. All these results will show up directly in Backstage to reduce context-switching.

Backstage TechDocs

Backstage TechDocs allows engineers to write technical documentation as Markdown files that live together with the code. The idea is to remove all the friction to creating docs and make them really easy to find, so docs actually get used. A Backstage plugin will automatically create and render a docs site + metadata, using MkDocs.

Backstage Plugins

As an open-source project, Backstage has a growing number of plugins that can help you customize the platform to your needs. Plugins are React components that are added to each service’s page. It’s possible to build your own plugin — we built a plugin that lets you add Cortex Scorecards to Backstage.

Backstage & Containers, Clusters and Services

Backstage is vendor-agnostic and can be hosted on a variety of cloud platforms, e.g. AWS vs. Google Cloud. Data can be ingested from any arbitrary source. These advantages, however, can be a double-edged sword. Backstage does not come with pre-built Docker containers to deploy, so teams will need to create a Backstage app, make customizations on it, build a Docker image from it, and then deploy to a Kubernetes environment. This will require the following technologies:

As explained here, your Kubernetes deployment will also need to be configured to access a database—Backstage supports PostgreSQL or Sqlite as the built-in database options.

Getting Started with Backstage

To get started with Backstage, we recommend reviewing the following resources:

How Does Backstage Compare to Cortex?

Backstage offers plenty of customization for teams and can be a powerful UX abstraction layer for the software development process. However, there will be significant upfront investment to deploy the tool, and your team will be responsible for ongoing maintenance such as implementing security patches, adding new features, and making pull requests to upgrade versions. With Backstage, teams need to put a large amount of dedicated resources into setting up and managing this SaaS tool long term.

Cortex is a cloud-native hosted and on-premises alternative to Backstage. Cortex has a Service Catalog providing a single pane of glass for your infrastructure, Scorecards to enforce best practices and accountability, Service Creation for scaffolding and getting new microservices up and running quickly, and a home for cross-team collaboration. Compared to Backstage, the advantages of Cortex are a lower TCO, faster setup time, and higher overall ease-of-use.

To get started with Cortex, check out our demo here.

What's driving urgency for IDPs?