Backstage Overview and Expected Benefits
What is Backstage
Backstage is a platform originally built by Spotify as its internal developer portal, open-sourced in 2020, and now a CNCF (Cloud Native Computing Foundation) Incubating project.
In one sentence, it is "a framework for consolidating scattered development infrastructure, services, documentation, and tools into a single unified UI." Its defining characteristic is that Backstage is not a finished application but rather a foundation for building your own developer portal by combining plugins.
Terminology: Developer Portal vs IDP
| Term | Meaning | Relationship to Backstage |
|---|---|---|
| Developer Portal | A single entry point (UI) where developers access the information and tools they need | The primary value Backstage provides |
| IDP (Internal Developer Platform) | The overall foundation that lets developers self-serve infrastructure and environments | Backstage serves as the "UI / portal layer" of an IDP |
| Platform Engineering | The organizational practice of designing and operating an IDP "as a product" | The premise behind operating Backstage |
Backstage is not the entirety of an IDP. CI/CD, Kubernetes, and cloud platforms exist separately; Backstage acts as the window that surfaces and operates them in one place.
Delivery models
| Model | Examples | Characteristics |
|---|---|---|
| OSS (self-hosted) | backstage.io | Free, maximum flexibility, requires build/operate effort |
| Managed / commercial | Spotify Portal, Roadie | No build needed, supported, incurs cost |
These docs assume the OSS (self-hosted) edition.
Why adopt it (problems to solve)
As an organization grows and the number of services and teams increases, "cognitive load" problems become apparent.
Specifically:
- Lack of discoverability — "where is what" is unclear. Service, API, doc, and owner information is scattered across multiple tools.
- Slow onboarding — new members take a long time to become productive, relying on tribal knowledge and word-of-mouth.
- New-build boilerplate — every new service requires manually repeating repo creation, CI/CD setup, monitoring config, etc.
- Erosion of standards / best practices — recommended setups are written in docs but not followed, so reality drifts apart.
- Ambiguous ownership — during an incident, "whose is this?" is not immediately answerable.
Overview of core features
Backstage addresses the above primarily with the following features. Details of each are covered in Core Concepts.
| Feature | Role | Problem solved |
|---|---|---|
| Software Catalog | Centrally manages all services, APIs, resources, and owners | Discoverability / ownership |
| Software Templates (Scaffolder) | Auto-generates new projects from templates (golden paths) | Boilerplate / standardization |
| TechDocs | docs-as-code managed in the same repo as code | Documentation staleness |
| Search | Cross-cutting search of catalog and docs | Discoverability |
| Plugins | Integrated display of Kubernetes, CI/CD, cost, etc. | Tool sprawl |
Architecture overview
Backstage consists of a frontend (React) and a backend (Node.js), and you extend functionality by adding plugins to both.
- Plugin architecture — even core features are implemented as plugins, so you can add or swap capabilities.
- Data sources — each service's metadata is ingested from a
catalog-info.yamlplaced in the repo, or from external integrations. - Persistence — PostgreSQL is required in production (SQLite is fine for development).
For details on architecture and the data model, see Core Concepts.
Expected benefits after adoption
By adopting and embedding Backstage, you can expect the following.
| Benefit | Description |
|---|---|
| Faster onboarding | New members can self-serve from the catalog, TechDocs, and templates |
| Better ownership and visibility | Every service has an owner, making incident contacts clear |
| Golden paths | Recommended setups become templates, making "the right way the easiest way" |
| Quantified governance | Standard-compliance and catalog-coverage rates can be visualized via scorecards |
| Improved Developer Experience (DevEx) | Less cross-tool overhead lets developers focus on essential work |
A "golden path" makes the organization's recommended standard way the easiest option, via templates and automation. The goal is not coercion but "people follow it naturally because it's easier." See Best Practices for details.
ROI / measuring impact
Backstage is not "adopt and forget" but an internal product you grow while measuring impact. To support adoption and continuation decisions, set metrics like the following.
Example metrics to track
- Onboarding time — days until a new member merges their first PR
- Template usage rate — share of new services created via golden paths
- Catalog coverage — share of real services registered in the catalog
- DORA metrics — deployment frequency, lead time for changes, change failure rate, MTTR (see SRE Principles)
- Developer satisfaction — qualitative evaluation via surveys
Comparison against cost
| Cost element | Description |
|---|---|
| Build effort | Initial setup, auth integration, initial plugin installation |
| Operate effort | Upgrades, plugin maintenance, catalog quality upkeep |
| Infrastructure cost | Hosting, PostgreSQL, storage |
Evaluate whether the gains — "developer time saved," "faster incident response," "quality from standardization" — exceed these costs.
Phased adoption roadmap
For a detailed adoption strategy, see Best Practices.
Best Practices
- Start small — begin with a minimal catalog and one or two golden paths; prove value before expanding.
- Run it as a product — a dedicated platform team owns it, treats developers as users, and incorporates feedback.
- Value over mandate — make it "easier to use," not "you'll get scolded if you don't."
Common anti-patterns
- Going live without curating the catalog, so the information is inaccurate and loses trust.
- Adopting without a platform team, so no one maintains it.
- Only mandating usage without solving developers' problems.
See Backstage Adoption Best Practices for details.