Introduction
As organizations grow, managing applications, services, documentation, APIs, cloud resources, and development workflows becomes increasingly challenging. Developers often spend significant time searching for information spread across multiple tools and platforms instead of focusing on building software.
Backstage is an open-source platform created by Spotify to solve this problem. It provides a centralized developer portal where teams can discover services, manage documentation, create new projects, and streamline development workflows.
In this Backstage tutorial, you'll learn what Backstage is, its core architecture, key features, and how to build and run your first Backstage developer portal step by step.
What Is Backstage?
Backstage is an open-source Internal Developer Portal (IDP) that helps organizations organize their software ecosystem in a single place.
Instead of switching between various tools for documentation, source code repositories, CI/CD pipelines, monitoring systems, and cloud resources, developers can access everything through a unified interface.
Some common capabilities include:
Backstage acts as a central hub for development teams.
Why Organizations Use Backstage
As the number of applications and microservices increases, maintaining visibility becomes difficult.
Common challenges include:
Service Discovery Problems
Developers often struggle to identify who owns a service or where documentation is located.
Inconsistent Documentation
Project documentation may be stored across multiple platforms, making it difficult to find.
Slow Onboarding
New team members spend significant time learning development processes and locating resources.
Tool Fragmentation
Organizations typically use Git repositories, cloud platforms, monitoring tools, and deployment systems from different vendors.
Backstage addresses these challenges by providing a single developer experience.
Backstage Architecture Overview
Backstage follows a modular architecture.
The major components include:
Frontend
The frontend provides the user interface where developers can:
Browse services
View documentation
Access APIs
Create projects
Backend
The backend handles:
Authentication
Catalog management
Plugin integrations
Data processing
Software Catalog
The catalog serves as the central inventory of software assets.
Examples include:
Applications
Services
APIs
Libraries
Teams
Plugins
Plugins extend Backstage functionality and integrate external systems.
Examples include:
GitHub integration
Kubernetes dashboards
CI/CD pipelines
Monitoring platforms
This plugin-based architecture makes Backstage highly customizable.
Prerequisites
Before installing Backstage, ensure the following tools are available:
Verify your installation:
node --version
npm --version
git --version
If all commands return version numbers, you're ready to proceed.
Creating a New Backstage Application
Backstage provides a command-line tool that creates a complete starter project.
Run:
npx @backstage/create-app@latest
You'll be prompted to provide an application name.
Example:
? Enter a name for the app: company-portal
The scaffolding process may take several minutes because it installs dependencies and generates the project structure.
After completion, move into the project directory:
cd company-portal
Running Backstage Locally
Start the application:
yarn dev
Backstage launches both the frontend and backend services.
Once started, open:
http://localhost:3000
You should see the default Backstage portal dashboard.
At this point, you have a working Internal Developer Portal running locally.
Understanding the Software Catalog
The Software Catalog is one of Backstage's most important features.
It helps organizations maintain a centralized inventory of software assets.
A catalog entity is defined using YAML.
Example:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: Handles payment processing
spec:
type: service
owner: backend-team
lifecycle: production
This entry represents a service within the organization.
Once registered, developers can search and discover the service from the portal.
Adding Technical Documentation
Backstage includes TechDocs, which enables documentation-as-code.
Create a documentation file:
# Payment Service
This service processes customer payments.
## Features
- Payment authorization
- Refund processing
- Transaction tracking
Store the documentation alongside the source code.
Backstage automatically generates and displays documentation through the portal.
This approach ensures documentation remains version-controlled and easy to maintain.
Using Software Templates
Software Templates allow teams to standardize project creation.
For example, instead of manually creating repositories and folder structures, developers can use predefined templates.
Example template:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: nodejs-service-template
spec:
owner: platform-team
type: service
Developers can launch new projects directly from the Backstage interface using approved organizational standards.
This significantly improves consistency.
Integrating GitHub Repositories
One of the most common Backstage integrations is GitHub.
A GitHub plugin can provide:
Repository visibility
Pull request information
Commit history
Ownership tracking
Developers can access repository-related information without leaving the portal.
This creates a more unified developer experience.
Kubernetes Integration
Backstage can connect to Kubernetes clusters.
Benefits include:
This visibility helps developers understand the operational status of their applications.
Real-World Use Cases
Microservices Management
Organizations running hundreds of services can maintain a centralized service catalog.
Developer Onboarding
New developers can quickly discover applications, documentation, and team ownership information.
Self-Service Development
Teams can create projects and resources using predefined templates.
Platform Engineering
Platform teams can provide standardized workflows while reducing manual support requests.
Documentation Portals
Organizations can centralize technical documentation across multiple teams.
Best Practices
Keep Catalog Information Updated
Outdated ownership and service information reduces the value of the portal.
Use Documentation as Code
Store documentation alongside application source code whenever possible.
Start with Core Plugins
Begin with essential integrations before adding large numbers of plugins.
Define Clear Ownership
Every service should have a clearly defined owner or team.
Standardize Templates
Create reusable templates to improve consistency across projects.
Focus on Developer Experience
The primary goal of Backstage is to make development easier and more efficient.
Conclusion
Backstage has become one of the most popular Internal Developer Portal platforms because it helps organizations simplify software management and improve developer productivity. By centralizing service catalogs, documentation, APIs, and development workflows, Backstage provides a single source of truth for engineering teams.
Its extensible plugin architecture, support for documentation-as-code, software templates, and integrations with modern development tools make it a valuable solution for organizations adopting platform engineering practices. Whether you're managing a handful of applications or hundreds of microservices, Backstage can significantly improve visibility, consistency, and the overall developer experience.