Backstage Developer Portal: Complete Implementation Guide

What is Backstage?

Backstage is an open‑source developer portal platform originally created by Spotify. It provides a unified frontend for managing all your infrastructure, services, documentation, and developer workflows. Think of it as a single pane of glass that brings together everything a developer needs: service catalogs, CI/CD pipelines, monitoring dashboards, API documentation, and much more.

At its core, Backstage is built around a plugin architecture. Each plugin can represent a service, a tool, or a piece of infrastructure. The platform provides a rich set of core features – such as a software catalog, tech docs, and software templates – that can be extended with hundreds of community and custom plugins.

Core Concepts

Software Catalog – A centralized registry of all your components (services, websites, libraries, etc.) with metadata like ownership, lifecycle, and dependencies.
Software Templates – Pre‑defined scaffolds that let developers bootstrap new projects with the right structure, CI/CD, and documentation.
TechDocs – Built‑in documentation engine that renders Markdown files in a consistent, searchable interface.
Plugins – Modular pieces that add functionality, e.g., a CircleCI plugin, a Datadog dashboard, or a custom internal tool.
Backend & Frontend – Backstage uses a Node.js backend (Express) and a React frontend (Material‑UI).

Why Backstage Matters

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

In a typical engineering organization, developers waste hours navigating between different tools: Jenkins, GitHub, PagerDuty, Datadog, Confluence, etc. Each tool has its own UI, authentication, and context. Backstage eliminates that fragmentation by providing a consistent, personalized interface.

Key benefits include:

Developer Productivity – “Golden Path” templates reduce setup time from days to minutes.
Standardization – Enforce consistent practices across services (naming, CI/CD, observability).
Discoverability – Engineers can easily find who owns a service, what it depends on, and where its docs live.
Security & Compliance – Centralized ownership and metadata make audits and security reviews straightforward.
Extensibility – Build internal tools once as plugins and share them across the whole organization.

Backstage is not just a dashboard; it’s a platform that grows with your company. Many enterprises (Netflix, Uber, Zalando) have adopted it to manage hundreds of microservices and thousands of engineers.

How to Use Backstage – Complete Implementation Guide

Prerequisites

Node.js 18+ and Yarn
Docker (optional, for local PostgreSQL)
Git
Basic knowledge of React and Node.js

1. Scaffold a Backstage App

The quickest way to start is using the Backstage CLI. Open your terminal and run:

npx @backstage/create-app@latest --name my-backstage

This creates a folder my-backstage with a fully working Backstage application. The structure looks like this:

my-backstage/
├── app-config.yaml
├── packages/
│   ├── app/          (React frontend)
│   ├── backend/      (Node.js backend)
│   └── common/
├── plugins/          (custom plugins)
└── yarn.lock

2. Configure the App

Edit app-config.yaml to set basic settings. Here’s a minimal example:

app:
  title: My Developer Portal
  baseUrl: http://localhost:3000

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  database:
    client: better-sqlite3
    connection: ':memory:'

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

You can also use PostgreSQL in production – just change the database client and connection string.

3. Run the Application

From the project root, run:

yarn install
yarn dev

This starts both the frontend (port 3000) and the backend (port 7007). Open http://localhost:3000 and you’ll see the default Backstage home page with a sample catalog.

4. Add a Plugin

Plugins are the heart of Backstage. To add the popular @backstage/plugin-techdocs, run:

yarn add --cwd packages/app @backstage/plugin-techdocs
yarn add --cwd packages/backend @backstage/plugin-techdocs-backend

Then register the frontend plugin in packages/app/src/App.tsx:

import { TechDocsPage } from '@backstage/plugin-techdocs';

const routes = (
  <FlatRoutes>
    ...
    <Route path="/docs" element={<TechDocsPage />}></Route>
  </FlatRoutes>
);

And add the backend plugin in packages/backend/src/index.ts:

import { techdocsPlugin } from '@backstage/plugin-techdocs-backend';

const backend = createBackend();
backend.add(techdocsPlugin());
backend.start();

Restart the dev server – you now have a full documentation system!

5. Create a Software Template

Software Templates let developers create new services with a few clicks. Create a YAML file in templates/service-template/template.yaml:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: node-service
  title: Node.js Service
  description: Create a new Node.js microservice
spec:
  owner: team-alpha
  type: service

  parameters:
    - title: Basic Info
      properties:
        serviceName:
          title: Service Name
          type: string
          pattern: '^[a-z0-9-]+$'
        owner:
          title: Owner
          type: string

  steps:
    - id: fetch-template
      name: Fetch Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.serviceName }}
          owner: ${{ parameters.owner }}

    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        repoUrl: github.com?repo=${{ parameters.serviceName }}&owner=my-org

    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        catalogInfoUrl: https://github.com/my-org/${{ parameters.serviceName }}/blob/main/catalog-info.yaml

Then register this template in app-config.yaml:

scaffolder:
  actions: