Platform Engineering with Backstage.io: Building an Internal Developer Portal

The Developer Experience Crisis

In a scaling organisation, developers face an explosion of cognitive load. Every team has its own tools: Jira for tracking, Confluence for docs, Jenkins or GitHub Actions for CI, SonarQube for quality, Datadog for monitoring, Vault for secrets. A junior developer joining the company must learn dozens of URLs, credentials, and workflows before deploying their first service.

This tool sprawl has a real cost: DORA research shows that poor developer experience can reduce deployment frequency by 40 %. Platform Engineering is the organisational response: create a dedicated platform team that builds and maintains internal tooling, allowing product teams to focus on business value.

What is an Internal Developer Portal?

An Internal Developer Portal (IDP) is the single entry point for everything a developer needs: service catalogue, documentation, new-project templates, team performance metrics, and CI/CD pipeline access. Backstage.io, created by Spotify and donated to the CNCF in 2020, has become the de-facto standard for building an IDP.

• Software Catalog: inventory of all services, libraries, APIs, and resources in the organisation
• Software Templates (Scaffolder): create new projects in a few clicks from predefined templates
• TechDocs: documentation-as-code generated from Git repositories and centralised in Backstage
• Plugins: integrations with GitHub, PagerDuty, Datadog, Kubernetes, Vault, etc.

Backstage Architecture

Backstage is a full-stack Node.js application composed of two parts:

backstage-app/
  ├── packages/
  │   ├── app/          # React frontend (what developers see)
  │   └── backend/      # Node.js API + backend plugin engine
  ├── plugins/          # Custom plugins developed internally
  └── app-config.yaml   # Main configuration

Backstage's core is extensible through a plugin system. Each plugin can add frontend pages, backend APIs, and integrations with third-party services. The ecosystem now has more than 200 open-source plugins maintained by the community.

Kubernetes Deployment with Helm

Move2Cloud recommends deploying Backstage on Kubernetes via the official Helm chart. Here is an example configuration for an EKS cluster:

# values.yaml for the backstage chart
backstage:
  image:
    registry: ghcr.io
    repository: your-org/backstage
    tag: "1.28.0"
  extraEnvVarsSecrets:
    - backstage-secrets   # K8s Secret containing GITHUB_TOKEN, POSTGRES_PASSWORD
  appConfig:
    app:
      baseUrl: https://backstage.your-company.com
    backend:
      baseUrl: https://backstage.your-company.com
      database:
        client: pg
        connection:
          host: ${POSTGRES_HOST}
          port: 5432
          user: backstage
          password: ${POSTGRES_PASSWORD}
postgresql:
  enabled: true
ingress:
  enabled: true
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  host: backstage.your-company.com
  tls: true

helm repo add backstage https://backstage.github.io/charts
helm upgrade --install backstage backstage/backstage   -f values.yaml   --namespace platform   --create-namespace

Defining Entities in the Catalog

Each service, API, or resource is described by a catalog-info.yaml file at the root of the Git repository. Backstage automatically discovers these files via its GitHub/GitLab integrations.

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Payment service handling Stripe transactions
  annotations:
    github.com/project-slug: move2cloud/payment-service
    backstage.io/techdocs-ref: dir:.
    datadog.com/site: datadoghq.eu
    pagerduty.com/service-id: P1234AB
  tags:
    - payment
    - critical
    - nodejs
spec:
  type: service
  lifecycle: production
  owner: group:team-payments
  providesApis:
    - payment-api
  dependsOn:
    - component:postgres-payment
    - resource:aws-sqs-payment-queue

Software Templates: Create a Microservice in One Click

Software Templates (Scaffolder) let developers create a new pre-configured service by filling in a form in the Backstage UI. The template generates the Git repository, configures CI/CD, adds the catalog-info.yaml, and registers the service in the catalog.

# template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-microservice
  title: Node.js Microservice
  description: Creates a Node.js microservice with GitHub Actions CI/CD
spec:
  owner: group:platform-team
  type: service
  parameters:
    - title: Service Information
      properties:
        name:
          title: Service Name
          type: string
          pattern: '^[a-z0-9-]+$'
        owner:
          title: Owning Team
          type: string
          ui:field: OwnerPicker
  steps:
    - id: fetch-template
      name: Fetch Template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
    - id: create-repo
      name: Create GitHub Repo
      action: publish:github
      input:
        repoUrl: github.com?owner=move2cloud&repo=${{ parameters.name }}
        defaultBranch: main
    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['create-repo'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

GitHub Integration for Automatic Discovery

Backstage can automatically scan your entire GitHub organisation to discover catalog-info.yaml files. Configure the integration in app-config.yaml:

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

catalog:
  providers:
    github:
      move2cloud-org:
        organization: move2cloud
        catalogPath: /catalog-info.yaml
        filters:
          branch: main
          repository: '.*'   # All repositories
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

Tech Radar: Technology Governance

The Tech Radar plugin lets the platform team communicate technology recommendations (Adopt/Trial/Assess/Hold) to the whole organisation directly in Backstage. It is a powerful tool for standardising technology choices and preventing the proliferation of unsupported technologies.

ROI and DORA Metrics

Companies that have deployed a Backstage-based IDP report significant improvements in DORA metrics:

• Deployment Frequency: +60 % thanks to standardised templates that eliminate manual configuration
• Lead Time for Changes: -50 % because developers find documentation and runbooks immediately
• Time to Onboard: from 2 weeks to 2 days for a new developer
• Cognitive Load: measurable reduction in the number of tools a developer needs to know (from 15+ to 1 portal)

At Move2Cloud, we have guided several clients through Backstage deployments. The initial investment (2–3 weeks for an MVP) is quickly offset within months by the reduction in time spent searching for documentation or configuring new projects.

Conclusion

Platform Engineering with Backstage is not a technical project — it is an organisational one. Success depends as much on developer adoption as on technical quality. Start with an MVP covering the catalog and TechDocs, measure adoption, then expand with templates and integrations. The platform team must treat developers as customers and iterate based on their feedback.