Skip to content

Backstage for Mere Mortals

Plain-language guides to Backstage: the open-source internal developer portal that answers "who owns this service, where are its docs, and how do I make a new one correctly." Written for people who run real systems — no CS degree required.

No jargon without an explanation. No "it's simple, just..." Every concept starts with the idea, then the practice.

Start here

  1. What Backstage Is — the portal idea, and why Spotify built it.
  2. The Software Catalog — the heart of Backstage: every service, owner, and dependency in one place.
  3. Software Templates — scaffolding new services from approved "golden paths."

The pieces

  1. TechDocs — documentation as code, living with the service.
  2. Plugins — the ecosystem: Kubernetes, ArgoCD, PagerDuty, and hundreds more.
  3. Running Backstage — from create-app to production, honestly.
  4. Backstage and GitOps — how the portal relates to GitOps tooling (neighbor, not resident).

Reference

  1. Adoption Pitfalls — what goes wrong, and when not to adopt it.
  2. Glossary — quick definitions, A to Z.

Writing criteria

Every guide follows the same writing criteria: plain words, no hype, honest limits, and checkable steps.