Backstage: Spotify Developer Portal

By Kokil Thapa | Last reviewed: September 2026

Backstage: Spotify Developer Portal is the open-source platform Spotify released to solve a problem every growing engineering org hits: developers cannot find services, APIs, docs, or ownership fast enough. Scattered wikis, stale README files, and Slack archaeology waste hours every week. If you run a custom software team or maintain internal platforms, Backstage gives you a proven starting point instead of building a portal from scratch. This guide covers what it actually is, how the catalog works, and what production adoption looks like in 2026.

What is Backstage: Spotify Developer Portal and why did Spotify build it?

Backstage started inside Spotify around 2016. Their engineering org grew faster than their documentation culture could keep up. Teams owned hundreds of microservices, but there was no single place to answer basic questions: Who owns this API? Where is the repo? How do I run it locally? What is the on-call rotation?

Spotify built an internal portal and open-sourced it in 2020. Today the project lives at backstage.io with thousands of contributors. It is not a hosted SaaS product from Spotify. You clone the app, configure it, and run it on your infrastructure—similar in spirit to how teams self-host GitLab or Grafana.

The core value is consolidation. Backstage pulls metadata from GitHub, GitLab, Jenkins, Kubernetes, PagerDuty, and dozens of other systems into one React-based UI. Developers search once instead of opening six tabs. For agencies and product teams shipping REST APIs and microservices, that consolidation pays off quickly once you pass roughly 15–20 active repositories.

The three pillars every Backstage deployment shares

Every Backstage instance, whether at a fintech in Kathmandu or a global SaaS company, rests on three pillars:

• Software catalog — a graph of components, APIs, resources, systems, domains, and users defined in YAML and enriched by processors.
• Software templates — scaffolder actions that generate new repos, CI configs, and catalog entries from golden-path templates.
• TechDocs — documentation pulled from each repo's mkdocs.yml and rendered inside the portal, so docs live next to code.

Plugins extend all three. The Backstage GitHub repository ships core plugins, and the community adds hundreds more for Argo CD, Datadog, SonarQube, and local payment gateways you might wire into a Nepal fintech stack.

How do you install and set up Backstage locally?

Backstage is a Node.js application. The current scaffold targets Node.js 20 or 22 in most release branches; on greenfield setups in 2026, Node.js 26 LTS and npm 12 are sensible host choices even if you pin the Backstage app to an LTS version it officially supports. Always check the release notes for your chosen Backstage version before upgrading the runtime.

Create a new app with the official CLI:

npx @backstage/create-app@latest
cd my-backstage-portal
yarn install
yarn dev

The dev server starts on port 3000 by default. The backend API listens on 7007. You get a working shell with example catalog entities and a few demo plugins. That shell is your fork point—not something you expose to production users without hardening.

Minimum configuration files to understand

Three files dominate day-one setup:

1. app-config.yaml — base config for backend URL, database, auth providers, and catalog locations.
2. packages/app/src/App.tsx — frontend plugin registration and route wiring.
3. packages/backend/src/index.ts — backend plugin and catalog processor registration.

A minimal catalog location entry looks like this:

catalog:
  locations:
    - type: url
      target: https://github.com/my-org/platform-catalog/blob/main/catalog-info.yaml

Point that URL at a repo your Backstage backend can reach. Private repos need a GitHub App or token configured under integrations.github. A common first-week mistake is registering locations the backend cannot authenticate to; the catalog stays empty and teams assume Backstage is broken.

If you already explored portal concepts in our Backstage developer portal build guide, this Spotify-origin platform is the upstream project that guide references. The difference is scope: this article focuses on Backstage itself, not a Laravel-side implementation pattern.

How does the Backstage software catalog work?

The catalog is the heart of Backstage: Spotify Developer Portal. Entities are typed objects—Component, API, Resource, System, Domain, Group, User—each described by a catalog-info.yaml file, usually at the repo root.

Example component entity for a Laravel API:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: Order processing API for eCommerce checkout
  tags:
    - laravel
    - php
  links:
    - url: https://grafana.example.com/d/order
      title: Grafana Dashboard
  annotations:
    backstage.io/techdocs-ref: dir:.
    github.com/project-slug: my-org/order-service
spec:
  type: service
  lifecycle: production
  owner: group:platform-team
  system: checkout
  providesApis:
    - order-api

Processors ingest YAML from Git, HTTP, or custom providers. They validate schema, resolve relations, and write to the catalog database—PostgreSQL in production, SQLite for local dev. The frontend then renders dependency graphs, ownership badges, and API relationships.

Relations that matter for API-heavy teams

Define providesApis and consumesApis on components. Register standalone API entities with OpenAPI or AsyncAPI specs. Backstage's API docs plugin renders those specs inline. On production Laravel apps I've maintained, linking an OpenAPI file to the catalog cut "where is the contract?" Slack pings noticeably—because the answer became searchable.

Ownership via spec.owner should reference a Group entity synced from your identity provider. Google Workspace, Okta, and Azure AD integrations exist as community or core plugins. Without real group sync, ownership fields become fiction within a month.

Backstage vs custom developer portal: which should you choose?

Not every team needs Backstage. A ten-person agency shipping WordPress and WooCommerce sites for clients may get more value from good README templates and a shared Notion space. Backstage earns its keep when service count, team count, or compliance requirements cross a threshold.

For enterprise application teams in Nepal building booking systems, legal-tech portals, or multi-vendor marketplaces, the decision often hinges on headcount. If nobody owns the portal after launch, Backstage becomes shelfware—exactly like the wikis it replaces.

Custom portals still make sense when Backstage's opinionated entity model fights your domain. A law-firm client portal with matter-level permissions and document vaults is not a catalog problem; it is an application problem. Build that in Laravel with policies and Spatie Permission, not Backstage.

How do you deploy Backstage in production?

Local yarn dev is not production. A real deployment separates the frontend static bundle, the backend API, PostgreSQL, and optional Redis or Memcached 1.6.x for caching. Most teams containerise with Docker and deploy to Kubernetes, AWS ECS, or a single VM if the org is small.

Production checklist

1. Database — switch from SQLite to PostgreSQL 18 (or 17 if your host has not upgraded yet). Run migrations on deploy.
2. Auth — enable OAuth via GitHub, Google, or OIDC. Anonymous read access is rare in production; default to authenticated.
3. Secrets — store tokens in environment variables or a vault, never in Git. Rotate GitHub App keys on schedule.
4. Build pipeline — run yarn build:backend and yarn build in CI. Ship immutable images.
5. Observability — expose Prometheus metrics from the backend; alert on catalog sync failures.

Example Docker Compose service skeleton for the backend:

services:
  backstage-backend:
    image: my-org/backstage-backend:1.4.0
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_USER: backstage
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      AUTH_GITHUB_CLIENT_ID: ${GITHUB_CLIENT_ID}
      AUTH_GITHUB_CLIENT_SECRET: ${GITHUB_CLIENT_SECRET}
    ports:
      - "7007:7007"
    depends_on:
      - postgres

In my experience maintaining GitLab CI plus Deployer pipelines on Ubuntu servers, the same discipline applies here: pin Node versions in CI, cache Yarn dependencies, and treat catalog YAML changes as deploy triggers. Several sister legal-tech sites I deploy share a common CI pattern; Backstage fits that model if you add a platform engineer who owns the portal repo.

Hosting costs vary. A minimal production instance on a 2 vCPU VM with managed PostgreSQL runs roughly Rs 8,000–15,000/month (~USD 60–110) on mainstream cloud providers. That is cheaper than one week of developer time lost to portal hunting.

For JSON catalog exports or API spec debugging during setup, the JSON formatter tool on this site helps validate payloads before you paste them into scaffolder templates or test fixtures.

What plugins and extensions matter most for API and platform teams?

Backstage's plugin architecture splits frontend and backend packages. You install a plugin, register it in App.tsx and the backend index, then configure credentials in app-config.yaml. Start with a tight bundle; plugin sprawl confuses new users.

High-value plugins to enable first

• TechDocs — docs-as-code from Markdown in each repo.
• Catalog Graph — visual dependency map for onboarding.
• GitHub/GitLab — pull requests, workflows, and repo links on entity pages.
• Kubernetes — pod status for services running in clusters.
• Search — unified index across catalog, docs, and optionally Confluence.
• Scaffolder — template-driven service creation with PR automation.

API teams should add the OpenAPI plugin and publish specs as catalog entities or referenced files. Align spec versions with your API versioning policy so the portal never shows a deprecated contract as current.

Custom plugins when community options fall short

Nepal-specific integrations—eSewa webhook dashboards, Khalti settlement logs, or IRD VAT report jobs—will not appear as official plugins. Write a thin backend plugin that reads your internal API and a frontend card that mounts on the relevant Component entity page. Keep scope narrow. One card beats a monolithic plugin suite that breaks on every Backstage minor upgrade.

Teams building complex booking and supplier CRM platforms often juggle Laravel admin panels, supplier APIs, and cron-heavy reporting. Backstage does not replace those apps. It documents and links them so new engineers know which system owns trek availability versus payment reconciliation.

How do you keep Backstage accurate after launch?

The portal dies when catalog YAML lies. Enforce catalog files in CI the same way you enforce lint rules. Add a check that every repo with a package.json, composer.json, or Dockerfile must contain a valid catalog-info.yaml before merge.

Assign a platform owner— even 0.25 FTE—to triage plugin upgrades, handle Backstage security advisories, and curate templates. Without ownership, you recreate the wiki problem inside a fancier UI.

Measure adoption with simple metrics: weekly active users, search queries, scaffolder runs, and TechDocs page views. If engineers still ask in Slack what the portal already answers, improve discoverability before adding plugins.

Connect Backstage to your existing support and maintenance workflows so on-call runbooks linked from entity pages stay current. A link to a deleted runbook erodes trust faster than no link at all.

For broader platform context, read our guides on Ubuntu for developers, DigitalOcean for developers, and cybersecurity trends for developers in 2026. Auth hardening on a public-facing Backstage instance is non-negotiable.

Key Takeaways

• Backstage: Spotify Developer Portal is a self-hosted, plugin-driven platform—not a Spotify-managed SaaS—and it fits orgs with enough services to justify catalog discipline.
• Start with catalog YAML in every repo, TechDocs, Git integration, and search before chasing exotic plugins.
• Production requires PostgreSQL, real auth, container builds in CI, and a named platform owner who upgrades the app quarterly.
• Custom Laravel portals still win for client-facing or domain-specific workflows; Backstage wins for internal engineering visibility.
• Treat catalog-info.yaml as production code: review it in PRs, validate in CI, and sync ownership from your identity provider.
• Budget Rs 8,000–15,000/month (~USD 60–110) for a small HA setup plus engineer time to maintain templates and plugins.

People Also Ask

Is Backstage free to use?

Yes. Backstage is open source under the Apache 2.0 license. You pay for infrastructure, engineer time, and any commercial plugins or support contracts—not for a license from Spotify. Total cost scales with how many integrations and custom plugins you maintain.

Does Spotify still use Backstage internally?

Spotify continues to develop Backstage and publishes roadmap updates through the CNCF project. The public repo receives regular releases. Internal Spotify usage details beyond that are not fully public, but the active commit history confirms it remains their chosen portal foundation.

Can Backstage replace Confluence or Notion?

Partially. TechDocs covers technical documentation tied to repositories well. It does not replace product specs, HR policies, or meeting notes. Most successful adopters keep Confluence or Notion for general knowledge and use Backstage for service metadata, API contracts, runbooks, and engineering golden paths.

What skills do you need to run Backstage?

Comfort with TypeScript, React, Node.js, YAML, Docker, and PostgreSQL covers most tasks. Platform engineers who have shipped CI/CD pipelines and internal tools adapt fastest. Pure PHP or WordPress developers can contribute catalog YAML and TechDocs without touching the app shell.

Ship a portal your engineers will actually open

Backstage: Spotify Developer Portal gives you a battle-tested skeleton for internal developer experience—catalog, docs, templates, and plugins—without betting your roadmap on a proprietary vendor. It demands ownership, accurate YAML, and sober plugin choices. Get those right and onboarding time drops; get them wrong and you host an expensive empty dashboard.

If you want help scoping a Backstage pilot, a custom internal portal, or API catalog work alongside your product build, review our portfolio of shipped platforms and development services, then contact us with your service count and stack. We will tell you honestly whether Backstage fits—or whether a focused Laravel portal will serve your team better.