Introduction
As organizations grow, managing software services, documentation, APIs, infrastructure resources, CI/CD pipelines, and development workflows becomes increasingly complex. Developers often waste valuable time searching for documentation, locating service ownership information, or understanding deployment processes across multiple tools.
This is where Internal Developer Platforms (IDPs) and Developer Portals come into play. One of the most popular open-source solutions in this space is Backstage.
Originally developed by Spotify and later donated to the Cloud Native Computing Foundation (CNCF), Backstage provides a centralized platform where development teams can discover services, manage software catalogs, access documentation, monitor deployments, and automate development workflows.
In this tutorial, you'll learn what Backstage is, how it works, and how to build an Internal Developer Portal from scratch.
What Is Backstage?
Backstage is an open-source platform for building developer portals that centralize software development resources and workflows.
Instead of switching between multiple tools, developers can access everything through a single interface.
Backstage helps organizations:
Manage software catalogs
Organize documentation
Track service ownership
Standardize development workflows
Automate project creation
Improve developer productivity
Reduce onboarding time
Many organizations use Backstage to create a "single pane of glass" for their engineering teams.
Why Organizations Need an Internal Developer Portal
In many companies, developers work with numerous systems:
GitHub or GitLab
Kubernetes
Jenkins
Azure DevOps
Jira
Monitoring platforms
Documentation systems
Cloud services
A typical workflow may look like this:
Developer
│
├── GitHub
├── Jenkins
├── Kubernetes
├── Jira
├── Confluence
└── Monitoring Tools
Finding information across these systems can become difficult.
With Backstage:
Developer
│
▼
Backstage Portal
│
├── Source Code
├── CI/CD
├── Documentation
├── Infrastructure
├── Monitoring
└── Service Catalog
Everything becomes accessible through one centralized platform.
Understanding Backstage Architecture
Backstage follows a modular architecture.
The main components include:
Frontend
The frontend provides the user interface developers interact with.
It includes:
Software catalog
Documentation portal
Service dashboards
Templates
Plugins
Backend
The backend manages:
Authentication
Plugin execution
Catalog synchronization
Database interactions
Software Catalog
The catalog acts as the source of truth for software assets.
Examples include:
Plugins
Plugins extend Backstage functionality.
Examples include:
GitHub Integration
Kubernetes Dashboard
Jenkins Integration
Azure DevOps Integration
Monitoring Integrations
Installing Backstage
Before starting, ensure the following prerequisites are installed:
Node.js
npm or Yarn
Docker (optional)
Git
Verify installation:
node --version
npm --version
Create a new Backstage project:
npx @backstage/create-app@latest
Provide an application name:
my-developer-portal
Navigate to the project:
cd my-developer-portal
Install dependencies:
yarn install
Start the application:
yarn dev
The portal becomes available at:
http://localhost:3000
Exploring the Default Backstage Portal
After startup, Backstage includes several built-in features.
Home Dashboard
Provides a central landing page.
Software Catalog
Displays registered services and applications.
TechDocs
Provides centralized documentation management.
Create Component
Allows developers to generate new projects using templates.
These features form the foundation of most Internal Developer Platforms.
Creating Your First Software Component
Backstage tracks software assets using YAML definitions.
Create a file called:
catalog-info.yaml
Example:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: order-service
description: Handles customer orders
spec:
type: service
lifecycle: production
owner: backend-team
Register the component in Backstage.
After synchronization, it appears in the Software Catalog.
Developers can now discover:
Ownership information
Documentation
Repository links
Dependencies
Managing Documentation with TechDocs
Documentation is often scattered across different systems.
TechDocs centralizes documentation directly inside Backstage.
Create a documentation file:
# Order Service
This service manages customer orders.
## Features
- Order Creation
- Order Processing
- Payment Integration
Add TechDocs configuration:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: order-service
annotations:
backstage.io/techdocs-ref: dir:.
Once published, documentation becomes searchable and accessible through the portal.
Creating Project Templates
One of Backstage's most powerful capabilities is software scaffolding.
Developers can generate new projects automatically.
Example template:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: aspnet-api-template
spec:
owner: platform-team
type: service
parameters:
- title: API Information
properties:
serviceName:
type: string
steps:
- id: generate
action: fetch:template
This enables teams to standardize project creation across the organization.
Integrating GitHub
Backstage can connect directly to GitHub repositories.
Example configuration:
integrations:
github:
- host: github.com
token: ${GITHUB_TOKEN}
Benefits include:
Repository visibility
Pull request tracking
Branch information
Deployment references
Developers no longer need to manually search across repositories.
Kubernetes Integration
Modern applications frequently run on Kubernetes.
Backstage can display Kubernetes workloads directly within the portal.
Example annotation:
metadata:
annotations:
backstage.io/kubernetes-id: order-service
Developers can view:
Pods
Deployments
Services
Health status
Without leaving the developer portal.
Building a Complete Internal Developer Platform
A mature Backstage implementation typically includes:
Backstage Portal
│
├── Software Catalog
├── TechDocs
├── GitHub Integration
├── Kubernetes Dashboard
├── CI/CD Pipelines
├── Monitoring
├── Cost Management
└── Service Ownership
This creates a unified developer experience across the organization.
Benefits of Using Backstage
Organizations adopting Backstage often experience:
Faster Developer Onboarding
New developers can quickly discover services and documentation.
Improved Service Ownership
Every application has clearly defined ownership.
Standardized Development Processes
Templates ensure consistency across projects.
Increased Developer Productivity
Developers spend less time searching for information.
Better Platform Visibility
Engineering teams gain insight into the entire software ecosystem.
Best Practices for Backstage Implementations
Start Small
Begin with the Software Catalog before adding complex integrations.
Maintain Accurate Metadata
Keep component definitions updated to ensure catalog reliability.
Standardize Templates
Create reusable templates for common project types.
Integrate Existing Tooling
Connect CI/CD, monitoring, source control, and cloud platforms.
Focus on Developer Experience
The portal should simplify workflows rather than introduce additional complexity.
Automate Catalog Registration
Automatically register services during deployment pipelines whenever possible.
Common Use Cases
Backstage is widely used for:
Internal Developer Platforms
Microservices management
Platform engineering initiatives
Documentation portals
Service ownership tracking
Kubernetes management
CI/CD visibility
Cloud resource discovery
Organizations with hundreds or thousands of services benefit significantly from a centralized developer experience.
Conclusion
Backstage has become one of the leading platforms for building Internal Developer Portals and modern platform engineering solutions. By centralizing software catalogs, documentation, infrastructure visibility, and development workflows, Backstage helps organizations improve developer productivity while reducing operational complexity.
Whether you're managing a small collection of services or a large enterprise-scale microservices ecosystem, Backstage provides a flexible foundation for creating a unified developer experience. With its plugin architecture, automation capabilities, and growing cloud-native ecosystem, Backstage enables development teams to focus more on building software and less on navigating fragmented tools and processes.