Platform Engineering with Backstage: The Developer Portal Teams Actually Want

Your development teams waste time hunting for documentation. They don't know which services own which databases. Nobody remembers the deployment process for the payments API. This is the problem Backstage solves—and it's not by adding another tool to your stack.

Backstage is Spotify's open-source developer portal, and it's fundamentally different from what came before. Instead of yet another dashboard, it gives teams a single source of truth for their services, infrastructure, and processes. The key: it's built by engineers, for engineers, with a plugin architecture that makes it actually useful in the real world.

Why Backstage Works Where Other Portals Fail

Traditional service catalogs treat documentation as a static problem. They create a spreadsheet or wiki, watch adoption crater, then wonder why nobody uses it. Backstage inverts this.

The Software Catalog as a Living System

Backstage's catalog isn't a database of information—it's a queryable, interconnected map of your entire system. You define components, services, resources, and dependencies once, then let them feed into a hundred different tools.

Here's a basic service definition:

yamlCopy
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-api
  description: Payment processing service
  links:
    - url: https://monitoring.company.com/payments
      title: Monitoring
spec:
  type: service
  lifecycle: production
  owner: platform-team
  dependsOn:
    - resource:postgres-primary

That single definition feeds documentation, deployment workflows, access control, and monitoring dashboards. When something changes, everything updates automatically.

Templates That Actually Save Time

Templates are where Backstage shows its engineering maturity. Instead of generating boilerplate code that needs manual cleanup, you create templates that wire everything together—repos, CI/CD, secrets, monitoring, documentation.

typescriptCopy
const template: Template = {
  apiVersion: 'backstage.io/v1beta2',
  kind: 'Template',
  metadata: {
    name: 'api-service',
    title: 'Create API Service',
  },
  spec: {
    parameters: [
      {
        title: 'Basic Info',
        properties: {
          name: { type: 'string', title: 'Service Name' },
          owner: { type: 'string', title: 'Team Owner' },
        },
      },
    ],
    steps: [
      {
        id: 'fetch',
        name: 'Fetch Template',
        action: 'fetch:template',
        input: {
          url: './template',
          values: {
            name: '${{ parameters.name }}',
          },
        },
      },
      {
        id: 'publish',
        name: 'Publish to GitHub',
        action: 'publish:github',
        input: {
          repoUrl: 'github.com?owner=myorg&repo=${{ parameters.name }}',
        },
      },
    ],
  },
};

A junior engineer runs this template once. They get a fully configured service with proper CI/CD, logging, and catalog integration. No manual setup. No forgotten steps.

Implementation Reality

Start Small

Don't try to catalog your entire estate on day one. Pick your most important 20 services and get them into Backstage. Prove value. Then expand.

bashCopy
npm create backstage-app@latest -- --skip-install
cd my-app
npm install
npm run dev

You're running locally in minutes. The real work is populating the catalog and building plugins for your specific needs.

Plugin Architecture Matters

Backstage's strength is extensibility. At LavaPi, we've built custom plugins that connect our clients' internal systems directly into their Backstage instances—cost tracking, compliance checks, deployment approvals. This turns your developer portal into a force multiplier.

You're not locked into what Spotify thought you'd need. You build what your teams actually need.

The Bottom Line

Backstage works because it respects engineers' time. It surfaces information in the tools teams already use. It automates repetitive work through templates. It integrates with your existing systems instead of replacing them.

The teams that adopt it don't talk about their portal. They just stop asking "who owns this service?" The portal becomes invisible because it's solved the real problem: making it frictionless to find what you need and get work done.

That's the kind of tool worth implementing.