Backstage.io Tutorial: Build an Internal Developer Portal Step by Step

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:

Service catalog management
Technical documentation
Software templates
API discovery
Kubernetes visibility
CI/CD integration
Developer self-service workflows

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:

Node.js
npm or Yarn
Git

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:

Viewing deployments
Monitoring workloads
Checking pod health
Accessing cluster information

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.