PlatformEngr® Backstage course

Cheat notes · Module 00 · Orientation

Orientation: how to think about Backstage

A five-minute review for when you have done this module and want it back in your head. Open the full module for the steps and the lab, or the full text to print.

The idea

Backstage is a framework, not a product: your platform team owns a TypeScript app built with it. Every feature hangs off the Software Catalog, so the portal is only as good as the data in it, and that data lives in Git next to the code.

Remember

  • A framework: @backstage/create-app generates a monorepo (React frontend, Node backend) that you own, upgrade and ship like any service.
  • The catalog is the product: who owns what, what depends on what. A wrong catalog makes every page wrong.
  • Git is the source: teams describe their software in catalog-info.yaml next to their code. The portal reads it; it does not own it.
  • Config before code: most behaviour is app-config.yaml (where the catalog reads, how people sign in). Code is for what config cannot do.
  • Who owns what: the platform team owns the portal repo (app, config, image, catalog/ with teams and systems, templates, custom actions). team-checkout owns what checkout is: its catalog-info.yaml and docs/.

Pitfalls

  • Spending weeks on plugins while half the components have no real owner. Rollouts stall on the catalog, not the code.
  • Fixing a wrong owner on the page. Pages render catalog data: fix the field in that service's catalog-info.yaml.

Test yourself

Answer in your head first, then open the answer.

What do you get from @backstage/create-app?

A TypeScript monorepo with a frontend and a backend that your team owns, builds and upgrades.

Where should the facts about checkout (owner, APIs, docs) live?

In the checkout repo next to the code, owned by team-checkout.

A page shows the wrong owner for a service. What is most likely wrong?

The catalog data: the owner field in that service's catalog-info.yaml.

Where module 00 leaves you: Nothing is running yet. Your details are saved in the course, every tool is checked, and the reference repo is on your laptop to copy from.