Skip to main content
📬 Get weekly Production AI insightsPractical notes on Kubernetes, AI infrastructure and platform engineering. No spam.Subscribe free
Platform Engineering

Build an Internal Developer Portal: Platform

Build an internal developer portal with Backstage. Service catalog, templates, TechDocs, plugins, and developer experience metrics.

Luca Berton

· The Production AI Expert

Published ·2 min read

An Internal Developer Portal (IDP) is the user interface of your platform engineering strategy. It is where developers discover services, provision infrastructure, view documentation, and monitor their applications — all without filing tickets.

Why Build an IDP

Without an IDP, developers face:

  • Discovery problem: “Where is the API documentation for the payments service?”
  • Provisioning problem: “How do I get a new database? Who do I ask?”
  • Ownership problem: “Who owns this service? It is failing and I need help.”
  • Onboarding problem: “I joined the team, where do I start?”

An IDP solves all four by providing a single, self-service interface.

Backstage: The Leading Open-Source IDP

Backstage (by Spotify, now a CNCF project) is the most adopted IDP framework:

Core Features

  • Software Catalog: Registry of all services, libraries, and infrastructure
  • Templates: Scaffolding for new services (golden paths)
  • TechDocs: Documentation-as-code rendered in the portal
  • Search: Unified search across services, docs, and APIs
  • Plugins: Extensible with Kubernetes, CI/CD, monitoring, cost plugins

Setting Up Backstage

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

# Start in development
yarn dev

Software Catalog Entity

# catalog-info.yaml (in your service repo)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payment processing and billing
  tags:
    - java
    - spring-boot
  annotations:
    backstage.io/kubernetes-id: payment-service
    github.com/project-slug: my-org/payment-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: billing
  dependsOn:
    - component:user-service
    - resource:payments-db
  providesApis:
    - payment-api

Software Template (Golden Path)

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-service
  title: Spring Boot Microservice
  description: Create a production-ready Spring Boot service
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Service Details
      required: [name, owner]
      properties:
        name:
          title: Service Name
          type: string
        owner:
          title: Owner Team
          type: string
          ui:field: OwnerPicker
        database:
          title: Database Type
          type: string
          enum: [postgres, mysql, none]
  steps:
    - id: fetch
      name: Fetch Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
    - id: publish
      name: Create Repository
      action: publish:github
      input:
        repoUrl: github.com?owner=my-org&repo=${{ parameters.name }}
    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

Alternative IDP Platforms

PlatformTypeStrengths
BackstageOpen-sourceMost flexible, large plugin ecosystem
PortCommercialLow-code, fast setup
CortexCommercialScorecards, maturity tracking
HumanitecCommercialScore-based, platform orchestrator
OpsLevelCommercialService ownership, maturity model

What to Include in Your IDP

Day 1 (Minimum Viable Portal)

  • Software catalog with ownership info
  • Links to existing tools (CI/CD, monitoring, docs)
  • Service creation templates
  • Search across all registered services

Day 30 (Useful)

  • Kubernetes resource viewer
  • CI/CD pipeline status
  • TechDocs integration
  • API documentation browser

Day 90 (Indispensable)

  • Cost per service dashboard
  • Security scorecard per service
  • SLO/SLA tracking
  • Dependency graph visualization
  • Self-service database and queue provisioning

Measuring IDP Success

  • Adoption rate: % of teams actively using the portal weekly
  • Template usage: How many new services created through templates vs manually
  • Search queries: What developers are looking for (and not finding)
  • Time to productivity: New hire to first PR merged
  • Ticket volume: Reduction in platform-related support tickets

Free 30-min Production AI consultation

Book Now