Backstage & developer portals
Self-service (7.3) needs a front door — a single place where developers find the golden paths and use them. That front door is the developer portal, and Backstage is the name you'll hear most. But this lesson opens with the most important and most-missed distinction in the whole field: the portal is not the platform. Confusing the two is how companies "deploy Backstage" and then wonder why nothing improved.
IDP vs portal: the storefront and the warehouse
Two terms share the initials and get blurred constantly:
- An Internal Developer Platform (IDP) is the whole toolchain underneath — the IaC modules, Kubernetes, pipelines, provisioning logic, policy, and golden paths. It's everything that actually does the work. This is the warehouse, the supply chain, the machinery.
- An Internal Developer Portal is the UI surface — the web app developers open to discover and use what the platform offers. This is the storefront.
The storefront-and-warehouse image makes the relationship exact: a beautiful storefront with an empty warehouse sells nothing. A portal is only as good as the platform behind it. You can have a real platform with no portal (developers drive it via CLI or pull requests) — but you cannot have a portal that magically is a platform.
:::tip The single most common platform-engineering mistake "We deployed Backstage" is not platform engineering. Standing up a portal with no golden paths, no real provisioning, and no developer research behind it produces an empty storefront — a catalog pointing at nothing self-service. The portal is the last 10% you put on top of a real platform, not the first thing you build. If you remember one sentence from this chapter, make it this one. (It's the 7.1 non-adoption trap in its most seductive form.) :::
Backstage: the open-source portal
Backstage is the open-source developer-portal framework originally built at Spotify and donated to the CNCF (the Cloud Native Computing Foundation — the open-source home of Kubernetes and friends). It has become the de-facto open standard for building a developer portal. It's a framework, not a turnkey product: you assemble and customize it with plugins, which gives huge flexibility but also means a Backstage deployment is itself a real engineering project to build and maintain.
Three Backstage capabilities define what a portal is, regardless of vendor:
1. The software catalog
The software catalog (or service catalog) is a single inventory of everything the org runs — every service, library, website, and the systems they form — each with an owner, links, docs, and dependencies. It answers the questions that haunt every growing org:
- What services do we even have?
- Who owns this one? (so you know who to page at 3 a.m.)
- What depends on it, and what does it depend on?
In Backstage, each entity is described by a small YAML file (a catalog-info.yaml) that lives in the service's own repo, so the catalog stays accurate as a by-product of normal development rather than rotting in a wiki. The catalog is the portal's backbone — it's the map of your software estate.
2. Software templates (the scaffolder)
A software template (run by the scaffolder) is the "create a new service" button. Pick a template — "Java + Postgres microservice," "React frontend" — fill in a name and a couple of inputs, and the scaffolder generates a brand-new, ready-to-go repository: starter code, a Dockerfile, Kubernetes manifests, a CI/CD pipeline, the catalog-info.yaml, and observability wiring — all to the organization's reviewed standard.
This is the golden path of 7.2 made clickable. The opinionated, secure-by-default workflow is no longer a document someone must follow correctly; it's a template that generates the correct thing. Scaffolding is where "make the right thing the easy thing" becomes literally one form and a button.
3. TechDocs
TechDocs is Backstage's docs-as-code system: documentation written as Markdown in each service's repo, then rendered inside the portal right next to that service in the catalog. Because the docs live with the code and ship through the same pull requests, they stay current instead of drifting into a stale wiki nobody trusts. The payoff: a developer finds a service in the catalog and its real, up-to-date docs are right there.
Backstage vs Port: build-it vs buy-it portals
Backstage is powerful but is a framework you build on — months of engineering to stand up and ongoing effort to maintain. That cost created a market for buy-it alternatives:
- Port is a popular SaaS developer portal — you configure rather than build, so it's far faster to stand up, at the cost of less open-ended customization and a vendor dependency.
- Roadie is a managed/hosted Backstage — you get Backstage's model without operating the framework yourself.
This is a specific instance of the build-vs-buy decision that runs through the whole IDP question (covered fully in 7.6 and the checkpoint): build (Backstage) buys you control and fit at the cost of months to set up and years to maintain; buy (Port, Roadie) buys you speed at the cost of flexibility and a vendor relationship. The right answer depends on your org's size, constraints, and how much your platform needs differ from everyone else's — not on which is "better" in the abstract.
:::note Keep the principle, isolate the tool Durable: a portal provides a catalog (what we run + who owns it), scaffolding (create the right thing easily), and docs in context. Dated: whether you get those from Backstage, Port, Roadie, or next year's entrant. Learn the three jobs a portal does; treat the specific product as replaceable. :::
Common pitfalls
- Portal-as-platform confusion. Believing the portal is the IDP. It's the UI on top; without golden paths and real self-service behind it, it's an empty storefront. This is the #1 trap — see the tip above.
- A catalog that rots. If catalog entries are maintained by hand in a central place, they go stale and developers stop trusting the catalog. Keep
catalog-info.yamlin each repo so accuracy is a by-product of normal work. - Scaffolding raw complexity. A template that just dumps unopinionated Kubernetes/Terraform onto the developer scaffolds the cognitive load, not a golden path. Templates must encode the opinionated, secure defaults (7.2).
- Underestimating Backstage's cost. "We'll just deploy Backstage" hides a real, ongoing engineering investment. Budget for it as the product it is — or choose a buy-it option deliberately.
- A portal nobody opens. A portal is only adopted if it's the easiest way to get real work done. If the underlying self-service isn't there, no amount of UI saves it.
Why it matters
The portal is the storefront; the platform is the warehouse — an Internal Developer Portal (Backstage, Port) is the UI surface, while the Internal Developer Platform is the whole toolchain underneath, and conflating them ("we deployed Backstage") is the field's most common, most expensive mistake. A real portal does three durable jobs: a software catalog (what we run + who owns it), software templates / a scaffolder (the clickable golden path that generates the right service), and TechDocs (docs-as-code shown in context). Whether you build that on Backstage or buy Port/Roadie is a size-and-constraints trade-off, not an absolute. Next we go below the storefront to the platform primitive that makes safe self-service possible at all — the Kubernetes reconciliation pattern and the abstractions built on it.