Introduction to Backstage

Backstage is the leading open-source framework for building developer portals, originally created by Spotify and now a CNCF incubating project. It's the foundation that most organizations choose when building their Internal Developer Platform.

Why Backstage?

Spotify built Backstage to solve a common problem: with hundreds of microservices, engineers were spending too much time searching for information about services, documentation, and owners. Backstage became their "single pane of glass" for all engineering.

Before Backstage:
┌─────────────┬─────────────┬─────────────┐
│    Wiki     │   GitHub    │  Confluence │
├─────────────┼─────────────┼─────────────┤
│  PagerDuty  │    Jira     │    Slack    │
├─────────────┼─────────────┼─────────────┤
│  Datadog    │   Grafana   │   Jenkins   │
└─────────────┴─────────────┴─────────────┘
"Where do I find information about service X?"
"Who owns this? Is there documentation?"

After Backstage:
┌─────────────────────────────────────────┐
│              BACKSTAGE                   │
│  ┌─────────────────────────────────────┐│
│  │ Service X                           ││
│  │ Owner: Team Alpha                   ││
│  │ Docs: [link] | On-call: [link]     ││
│  │ APIs: 3 | Dependencies: 5          ││
│  └─────────────────────────────────────┘│
│  Everything in one place                │
└─────────────────────────────────────────┘

Backstage Core Features

Backstage provides four core capabilities:

Feature	Description	Value
Software Catalog	Registry of all services, APIs, and resources	Know what exists
Software Templates	Scaffolding for new projects	Consistent creation
TechDocs	Documentation-as-code	Docs where devs look
Plugins	Extensible architecture	Integrate everything

Architecture Overview

Backstage has a three-tier architecture:

┌─────────────────────────────────────────────────────────┐
│                      FRONTEND                            │
│                    (React SPA)                           │
│  ┌──────────┬──────────┬──────────┬──────────┐          │
│  │ Catalog  │ Scaffolder│ TechDocs │ Plugins  │          │
│  │   UI     │    UI    │    UI    │    UI    │          │
│  └──────────┴──────────┴──────────┴──────────┘          │
├─────────────────────────────────────────────────────────┤
│                      BACKEND                             │
│                  (Node.js + Express)                     │
│  ┌──────────┬──────────┬──────────┬──────────┐          │
│  │ Catalog  │ Scaffolder│ TechDocs │  Auth    │          │
│  │  API     │   API    │   API    │   API    │          │
│  └──────────┴──────────┴──────────┴──────────┘          │
├─────────────────────────────────────────────────────────┤
│                      DATA LAYER                          │
│  ┌──────────────────┬───────────────────────┐           │
│  │    PostgreSQL    │    External APIs      │           │
│  │  (catalog data)  │  (GitHub, K8s, etc.)  │           │
│  └──────────────────┴───────────────────────┘           │
└─────────────────────────────────────────────────────────┘

Installation

Get Backstage running locally:

# Prerequisites: Node.js 18+, Yarn 1.x
node --version  # Should be 18+
yarn --version  # Should be 1.x (Classic)

# Create a new Backstage app
npx @backstage/create-app@latest

# Follow the prompts:
# ? Enter a name for the app (e.g., acme-backstage)
# Creating the app...

# Navigate to the app directory
cd acme-backstage

# Start in development mode
yarn dev

# Backstage is now running at:
# Frontend: http://localhost:3000
# Backend: http://localhost:7007

Configuration Basics

Backstage configuration lives in app-config.yaml:

# app-config.yaml
app:
  title: Acme Developer Portal
  baseUrl: http://localhost:3000

organization:
  name: Acme Corp

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  database:
    client: better-sqlite3
    connection: ':memory:'  # Use PostgreSQL for production

# Authentication (example: GitHub)
auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}

# Catalog locations (where to find catalog-info.yaml files)
catalog:
  import:
    entityFilename: catalog-info.yaml
  locations:
    # Local example data
    - type: file
      target: ../../examples/entities.yaml
    # GitHub organization
    - type: github-org
      target: https://github.com/acme-corp

Key Concepts

Understanding these concepts is essential:

# Core Backstage Concepts
concepts:

  entities:
    description: "Things tracked in the catalog"
    types:
      - Component (services, websites, libraries)
      - API (REST, GraphQL, gRPC)
      - Resource (databases, buckets, queues)
      - System (collection of components)
      - Domain (business capability)
      - Group (team)
      - User (person)

  plugins:
    description: "Extend Backstage functionality"
    examples:
      - kubernetes: "Show pod status"
      - github-actions: "Show CI/CD status"
      - pagerduty: "Show on-call schedule"
      - techdocs: "Render documentation"

  templates:
    description: "Scaffolders for new projects"
    actions:
      - fetch:template
      - publish:github
      - catalog:register