What is Backstage.io?

Backstage is an open-source platform for building internal developer portals, originally created by Spotify. It helps organizations centralize services, documentation, infrastructure, and workflows into a single interface, improving developer productivity and consistency. Instead of developers navigating multiple tools and dashboards, Backstage provides a unified “front door” to your engineering ecosystem. This tutorial walks through setting up Backstage, customizing it, and using it as the foundation of a platform engineering strategy.

The first step is preparing your environment. You’ll need Node.js (preferably LTS), Yarn, Git, and a Unix-like system (macOS, Linux, or WSL on Windows). Backstage projects can be resource-intensive, so ensure your machine has at least 6GB of RAM. Once ready, you can scaffold a new Backstage app using the official CLI. Run npx @backstage/create-app@latest, choose a name, and let it generate a full-stack application with both frontend and backend components preconfigured.

After scaffolding, navigate into your project folder and start the development server using yarn start. This launches the frontend (typically on port 3000) and backend (on port 7007). When you open the app in your browser, you’ll see a default portal with example components and documentation. At this stage, it’s helpful to explore the UI and understand how Backstage organizes software components, APIs, and resources in its catalog.

The next step is understanding the Backstage architecture. It consists of a React-based frontend and a Node.js backend, with plugins powering most features. The Software Catalog is a core component that stores metadata about services, libraries, and systems. These are defined using YAML files (usually catalog-info.yaml) that describe ownership, lifecycle, and dependencies. Adding your own service to the catalog involves creating one of these files and registering it with the Backstage backend.

A key feature of Backstage is the Scaffolder, which enables developers to generate new projects from templates. You can define templates using YAML, specifying inputs, steps, and actions. For example, a template might create a new microservice repository, add CI/CD configuration, and register the service in the catalog automatically. This reduces repetitive setup and enforces best practices across teams, forming the basis of “golden paths” in platform engineering.

To make Backstage useful in a real environment, you’ll need to integrate it with external systems. Common integrations include Git providers (like GitHub or GitLab), CI/CD tools, and cloud platforms. These integrations allow Backstage to display repository data, build status, and deployment information directly in the portal. Configuring integrations typically involves adding credentials and endpoints to the app-config.yaml file and enabling the corresponding plugins.

Another important area is authentication and access control. By default, Backstage runs with minimal security, but in production you should integrate it with an identity provider such as OAuth, SAML, or OpenID Connect. This ensures that only authorized users can access the platform and that ownership metadata in the catalog maps correctly to real teams. Proper authentication also enables role-based access to templates and resources.

Backstage’s plugin system is what makes it powerful and extensible. There are many community and official plugins for features like documentation (TechDocs), Kubernetes visibility, and monitoring dashboards. You can also build custom plugins tailored to your organization’s needs. For example, you might create a plugin that visualizes internal APIs or tracks service reliability metrics, integrating with systems like Kubernetes or observability tools.

For production deployment, you’ll need to replace the default SQLite database with a more robust option like PostgreSQL and configure persistent storage for documentation. You should also containerize the Backstage app and deploy it to a cloud environment or Kubernetes cluster. Using infrastructure tools like Terraform can help automate this setup and ensure consistency across environments.

Finally, treat Backstage as a product rather than a one-time installation. Continuously improve it based on developer feedback, add new templates and integrations, and refine workflows to reduce friction. Over time, Backstage becomes the central hub of your platform engineering ecosystem, enabling developers to build, deploy, and manage software efficiently while maintaining organizational standards.