Skip to main content

Backstage

Edit on GitHubStar

📚 Learning Resources​

📖 Essential Documentation​

📝 Specialized Guides​

🎥 Video Tutorials​

🎓 Professional Courses​

📚 Books​

🛠️ Interactive Tools​

🚀 Ecosystem Tools​

  • Roadie - Managed Backstage platform
  • Humanitec - Platform orchestration
  • Port - Developer portal alternative
  • Cortex - Internal developer portal

🌐 Community & Support​

Understanding Backstage: Spotify's Developer Portal Platform​

Backstage is an open platform for building developer portals, created by Spotify and donated to the CNCF. It provides a centralized hub where developers can discover services, access documentation, and create new projects from standardized templates.

How Backstage Works​

At its core, Backstage provides a software catalog that maintains a real-time inventory of all services, libraries, data pipelines, and other software components in your organization. Each component is described by a YAML file that includes metadata, ownership information, and relationships to other components.

The platform uses a plugin architecture where each feature is a self-contained React application. Core plugins include the software catalog, TechDocs for documentation, scaffolder for project templates, and integrations with CI/CD systems. Organizations extend Backstage by building custom plugins for their specific needs.

The Backstage Ecosystem​

Backstage integrates with existing tools rather than replacing them. It connects to source control systems to discover components, CI/CD platforms to display build status, monitoring tools to show service health, and cloud providers to track resources. This creates a unified view of your entire technical ecosystem.

The plugin ecosystem is rapidly growing, with contributions for Kubernetes monitoring, cost tracking, security scanning, and feature flags. Major tech companies like Netflix, American Airlines, and Expedia have adopted and extended Backstage for their platforms.

Why Backstage Dominates Platform Engineering​

Backstage addresses the cognitive overload developers face in modern microservices architectures. Instead of juggling dozens of tools and dashboards, developers have one place to understand their technical landscape. It standardizes how teams create new services, document their work, and discover what already exists.

For platform teams, Backstage provides a foundation for building golden paths - prescribed ways to build and deploy services that embed best practices. This accelerates development while ensuring consistency and compliance.

Mental Model for Success​

Think of Backstage like a shopping mall directory for your technology organization. Just as a mall directory shows you where every store is located, what they sell, and their hours, Backstage shows you every service, who owns it, and its current status. The scaffolder templates are like mall kiosks that help you quickly set up new stores (services) with everything you need. TechDocs is like having the instruction manual for every store readily available at the information desk.

Where to Start Your Journey​

  1. Deploy the demo instance - Explore Backstage features in a sandbox environment
  2. Install Backstage locally - Use create-app to spin up your own instance
  3. Import your first service - Add catalog-info.yaml to an existing repository
  4. Create a software template - Build a template for your standard service architecture
  5. Enable TechDocs - Set up documentation as code for your services
  6. Build a custom plugin - Extend Backstage with organization-specific features

Key Concepts to Master​

  • Software catalog - Component model and entity relationships
  • Catalog ingestion - Discovery processors and static locations
  • Software templates - Scaffolder actions and template syntax
  • Plugin architecture - Frontend and backend plugin development
  • Authentication - Identity providers and permission framework
  • TechDocs - MkDocs integration and documentation workflow
  • API definitions - OpenAPI and AsyncAPI integration
  • Search platform - Indexing and custom search providers

Start by populating your software catalog, then progressively add templates, documentation, and custom plugins. Remember that Backstage is a platform for building your developer portal, not a turnkey solution - investment in customization yields the best results.

📡 Stay Updated​

Release Notes: Backstage Releases • Changelog • Roadmap

Project News: Backstage Blog • CNCF Blog • Engineering Blog Posts

Community: BackstageCon • Community Sessions • Adopters