Imagine you're a new developer on a team. On your first day, you're handed a list. You need to get access to the code on GitHub, find the right deployment pipeline in Jenkins, locate the API documentation on a separate wiki, and figure out who owns the database service you need to connect to. Each tool has a different interface, and the information is scattered everywhere.

This kind of complexity is common in growing engineering organizations. It slows developers down and creates friction. To solve this, Spotify created an internal tool to organize their whole tech ecosystem. It worked so well that they released it as an open-source project called Backstage.

Backstage is a framework for building an Internal Developer Portal (IDP). Think of it as a single front door for your entire engineering world. Instead of developers hunting for tools and information, they go to one place to find everything they need. It streamlines workflows, improves discoverability, and creates a more consistent and productive experience for developers.

Backstage is built around a few key concepts that form its foundation. These features work together to create a unified view of your software ecosystem.

Software Catalog The Software Catalog is the heart of Backstage. It’s a centralized system that keeps track of all the software in your organization—microservices, libraries, websites, machine learning models, and more. Each piece of software is treated as a component.

Crucially, the catalog defines ownership. For any component, you can immediately see which team owns it, how to contact them, and where its source code and documentation live. It ends the frustrating search for the right person or team to talk to about a service. It acts as a single source of truth for all your technical assets.

Software Templates Creating a new project often involves tedious boilerplate setup: creating a repository, setting up a CI/CD pipeline, configuring monitoring, and adding standard libraries. Software Templates automate this entire process.

With a few clicks in the Backstage UI, a developer can spin up a new service that conforms to all of your organization's best practices. This ensures consistency across your projects and dramatically speeds up the time it takes to go from an idea to a running application. It's like having a project starter kit on demand.

TechDocs Documentation is useless if no one can find it or if it's out of date. TechDocs solves this by treating documentation like code.

Developers write documentation in Markdown files and store them alongside the source code in the same repository. Backstage automatically finds these files, renders them as a beautiful, easy-to-navigate website, and makes them available right within the developer portal. This keeps documentation close to the code it describes, making it much more likely to be kept up to date.

By combining a searchable catalog, automated project creation, and a centralized documentation system, Backstage provides a powerful foundation for improving developer productivity and happiness. It creates a single pane of glass through which developers can view, manage, and create software, turning organizational complexity into a streamlined, discoverable experience.

Now that you understand what Backstage is and its core components, you're ready to see how these pieces fit together in a practical setup.

Let's check your understanding of these foundational ideas.