Backstage Documentation

What Backstage is

Backstage is an open source framework for building developer portals. It started inside Spotify, was accepted into the Cloud Native Computing Foundation in September 2020 and moved to the Incubating maturity level in March 2022. The idea is simple: instead of engineers hunting through wikis, dashboards and repositories to find who owns a service or how to start a new one, the portal puts all of that in one place, driven by a central software catalog.

What the docs cover

• Software Catalog: how every service, library, website, data pipeline and API is described in a catalog-info.yaml file that lives next to the code, and how ownership, systems and dependencies are modelled.
• Software Templates: scaffolding new projects from a template, so a new service starts with your organisation's CI, logging and conventions already wired in.
• TechDocs: a "docs like code" approach where Markdown in the repository is built and shown inside the portal.
• Plugins and integrations: the plugin system, the frontend and backend systems, auth, permissions, search and integrations with GitHub, GitLab and other providers.
• Deployment and configuration: running Backstage beyond your laptop, with app-config.yaml and a real database.

Is it worth learning?

If you are heading towards platform engineering, yes. Internal developer portals are one of the most visible things a platform team ships, and Backstage is the open source option most of them evaluate first. Even if your company buys a commercial portal later, the concepts the docs teach (a catalog of owned entities, templates as golden paths, docs next to code) carry straight over.

Prerequisites and time

Backstage apps are TypeScript and React on the frontend and Node.js on the backend, managed with Yarn workspaces. The getting started guide recommends a basic understanding of Yarn and npm, and it uses npx to create an app. Following it gives you a standalone portal running locally with an in-memory SQLite database and demo content in an evening. Registering your own services, writing a template and adding a plugin is a weekend. Running it for a whole organisation is an ongoing project, and the docs are honest that the local install is not production ready.

Free or paid?

Backstage itself is free and open source. Some companies sell hosted or extended versions; the docs cover the open source framework.

Common questions

Do I need to know Kubernetes? No, although the Kubernetes plugin is one of the popular ones. The catalog and templates work with any infrastructure.

Is it a finished product? It is a framework. You build and maintain your own app on top of it, which is its strength and also the main cost to weigh.

What can I do after it? Stand up a portal, model real services and owners in the catalog, write a template that creates a working repository, and explain the trade-offs of a developer portal to your team.

Best for: platform and DevOps engineers, and backend engineers who want to understand how internal developer platforms are put together.