Backstage — Open Source Developer Portal by Spotify

Introduction

Backstage is an open platform for building developer portals. At Spotify (where it was created), it serves as the single frontend for all infrastructure, giving developers one place to find services, read docs, create new projects, check CI/CD status, and manage infrastructure — reducing cognitive load and improving developer productivity.

With over 33,000 GitHub stars and as a CNCF Incubating project, Backstage is adopted by companies like Spotify, Netflix, American Airlines, HP, IKEA, and hundreds of engineering organizations. It provides a unified developer experience across fragmented tooling.

What Backstage Does

Backstage provides three core features: a Software Catalog (registry of all services, libraries, and infrastructure), Software Templates (self-service scaffolding for new projects), and TechDocs (docs-as-code integrated into the catalog). Its plugin architecture lets you integrate any tool or service.

Architecture Overview

[Backstage Frontend (React)]
        |
   [Plugin System]
+-------+-------+-------+
|       |       |       |
[Software  [Software  [TechDocs]
Catalog]   Templates]  Docs-as-code
All services Scaffolding MkDocs
and owners  Golden paths integration
        |
[Additional Plugins (200+)]
Kubernetes | PagerDuty | GitHub
Jenkins | Argo CD | SonarQube
Grafana | Datadog | Custom
        |
   [Backstage Backend (Node.js)]
   Plugin backends
   Authentication
   Database (PostgreSQL)
        |
   [External Systems]
   GitHub, GitLab, K8s,
   CI/CD, monitoring, etc.

Self-Hosting & Configuration

# catalog-info.yaml — register a service
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  description: My microservice
  annotations:
    github.com/project-slug: myorg/my-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  owner: team-backend
  lifecycle: production
  system: payments
  dependsOn:
    - resource:payments-db
  providesApis:
    - payments-api

# template.yaml — software template for new services
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: node-service
  title: Node.js Microservice
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Service Info
      properties:
        name:
          type: string
        owner:
          type: string
          ui:field: OwnerPicker
  steps:
    - id: fetch
      name: Fetch Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
    - id: register
      name: Register in Catalog
      action: catalog:register

Key Features

• Software Catalog — centralized registry of all services, APIs, and resources
• Software Templates — golden paths for creating new projects
• TechDocs — documentation-as-code integrated into the catalog
• Plugin Architecture — 200+ community plugins for any tool
• Search — unified search across all catalog entities and docs
• Ownership — clear service ownership with team directories
• Kubernetes — view K8s workload status per service
• API Documentation — OpenAPI and AsyncAPI specs rendered inline

Comparison with Similar Tools

FAQ

Q: When should I adopt Backstage? A: When your engineering org has 50+ services and developers struggle to find information, understand ownership, or follow consistent practices. Below that scale, simpler wikis and docs may suffice.

Q: Is Backstage hard to set up? A: The initial setup is straightforward (npx create-app). The ongoing investment is in populating the catalog, building templates, and customizing plugins for your organization. Plan for a dedicated platform team.

Q: Can I use Backstage without Kubernetes? A: Yes. The K8s plugin is optional. Backstage works with any infrastructure — VMs, serverless, PaaS. The core value is the software catalog and developer portal, not K8s integration.

Q: How do I get buy-in from developers? A: Start with immediate value: populate the catalog with existing services, add TechDocs, and create templates for the most common project types. Developers adopt Backstage when it saves them time finding information.

Sources

• GitHub: https://github.com/backstage/backstage
• Documentation: https://backstage.io/docs
• Plugin Marketplace: https://backstage.io/plugins
• Created by Spotify, CNCF Incubating Project
• License: Apache-2.0