Don't Panic: Backstage Fundamentals

Backstage is the application you assemble when a collection of repositories, dashboards, documentation sites, and forms has become an expedition. It puts a shared front door in front of them. It does not replace them, command them, or teach them manners. The portal is the map, not the territory, and maps become embarrassing when they show a bridge that vanished three migrations ago.

The load-bearing idea is the Software Catalog. It is a graph of things such as Components, APIs, Resources, Groups, Systems, and Templates. A component page becomes useful because it can connect a service to its documentation, source code, related systems, and owner. That last link matters more than the page furniture. An entity with no usable owner is a well-formatted note pinned to a locked door.

Catalog records commonly begin as catalog-info.yaml beside the code. Backstage discovers and processes those files, then stores the results for the UI, Search, and other plugins. That does not make Backstage the authority on everything it displays. Source control remains responsible for source code. Deployment systems remain responsible for live deployment state. Copying every changing fact into a catalog is how a tidy portal becomes a confident collector of yesterday's news.

The other major moving part is the Software Template. It runs through the create route: collect parameters, perform actions, publish material to source control, register the entity, and report the task result. This can encode a real golden path. It can also produce a glossy form that starts a manual queue. The latter is still organized, which is pleasant, but the queue has noticed no difference.

Plugins are how an App grows. Catalog, TechDocs, Search, and Scaffolder are familiar examples. Frontend plugins change what people see. Backend plugins run services and integrations. Modules extend an existing backend plugin through extension points. Each addition carries credentials, configuration, upgrade work, permissions, and an eventual broken Tuesday, so a plugin needs an owner and a purpose.

The surprising bit is security. Authentication answers who made a request. Authorization answers whether that identity may do the requested thing. Backstage endpoints are not protected by default. A hidden button is a decor decision, not an authorization policy. Put the policy in the backend that serves the data or action.

Start with the Intro for the architecture and catalog flow. Use Slides when the relationships need a compact map. Keep Cheatsheet nearby while reading descriptors, templates, TechDocs, and permissions. The practice reference and exercise turn the local App into a catalog experiment. The Field Notes covers the operational bills that arrive after the portal's welcome screen has made its polite introductions.

Don't Panic: Backstage Fundamentals

Relevant careers