Building a Developer Portal with Backstage.io: Enterprise Lessons

At Lloyds Banking Group, we faced a common enterprise challenge: dozens of teams working across hundreds of services with no unified way to discover, understand, or manage them. New developers spent weeks just figuring out which services existed and who owned them. Backstage.io transformed our developer experience.

The Problem We Faced

Large enterprises suffer from fragmentation:

• Service discovery: "Which service handles payments?" required asking around
• Ownership ambiguity: When something broke, finding the responsible team was a treasure hunt
• Documentation chaos: Docs lived in wikis, READMEs, SharePoint, and people's heads
• Inconsistent tooling: Each team had different CI/CD, monitoring, and deployment approaches
• Onboarding friction: New developers took months to become productive

Why Backstage?

After evaluating options including custom-built portals, we chose Backstage.io for several reasons:

Single Pane of Glass

Backstage aggregates information from multiple systems into one interface:

• Service catalog with ownership and metadata
• API documentation alongside the services that provide them
• CI/CD status from Jenkins, GitHub Actions, or Azure DevOps
• Monitoring dashboards from Prometheus/Grafana
• Cloud resource costs from AWS or Azure

Plugin Architecture

Backstage's plugin system enables customization without forking:

• Core plugins for common needs (catalog, TechDocs, Kubernetes)
• Community plugins for popular tools (PagerDuty, Datadog, Snyk)
• Custom plugins for organization-specific workflows
• Backend plugins for integrations requiring secrets or complex logic

Software Catalog

The catalog became our system of record for services:

• Every service registered with ownership, lifecycle stage, and dependencies
• Automatic discovery from Kubernetes, GitHub, or other sources
• Entity relationships (service depends on API, team owns service)
• Custom entity types for our specific needs (data products, ML models)

Strong Community

Spotify's backing and the CNCF community provide:

• Regular releases with new features and fixes
• Active Slack community for questions and best practices
• Conference talks and case studies from other adopters
• Growing ecosystem of plugins and integrations

Implementation Strategy

Rolling out Backstage to 50+ teams required careful planning.

Phase 1: Foundation (Months 1-2)

Deploy Core Backstage

• Set up infrastructure (Kubernetes deployment, PostgreSQL database)
• Configure authentication (integrated with our Azure AD)
• Establish CI/CD for Backstage itself

Populate Software Catalog

• Import existing services from our CMDB
• Define catalog-info.yaml templates for teams
• Create entity relationships (ownership, dependencies)

Early Adopters

• Partner with 3 enthusiastic teams
• Gather feedback intensively
• Iterate on catalog schema and workflows

Phase 2: Documentation (Months 3-4)

TechDocs Setup

• Configure TechDocs with our documentation standards
• Migrate high-value documentation from Confluence
• Establish docs-as-code workflow (Markdown in repos, published via TechDocs)

API Documentation

• Integrate OpenAPI specifications
• Create AsyncAPI docs for event-driven services
• Link API docs to owning services in catalog

Phase 3: Custom Plugins (Months 5-6)

Security Dashboard Plugin

• Integrated Snyk vulnerability data
• Showed security posture for each service
• Linked to remediation workflows

Cost Attribution Plugin

• Pulled AWS cost data by service
• Enabled teams to see their cloud spend
• Motivated optimization efforts

Deployment Plugin

• Unified view of deployment pipelines
• One-click deployment triggers
• Deployment history and rollback options

Phase 4: Scaling (Months 7-12)

Organization-Wide Rollout

• Mandated catalog registration for all production services
• Training sessions for all development teams
• Champions program for ongoing support

Advanced Features

• Software Templates for scaffolding new services
• Search improvements for large catalog
• Custom scorecards for service maturity

Adoption Metrics

After 12 months of operation:

Developer Experience

• 60% reduction in developer onboarding time: New developers became productive faster with self-service documentation and discovery
• 200+ developers using the platform daily: High engagement indicated genuine value
• 50+ services catalogued with clear ownership: Every service has an accountable team

Operational Improvements

• 40% reduction in "who owns this?" questions: The catalog answered ownership questions definitively
• 30% faster incident response: Knowing who to contact and where to find runbooks accelerated resolution
• Standardized 12 core service patterns: Software Templates ensured consistency

Documentation Quality

• 300+ TechDocs pages published: Documentation moved from scattered wikis to centralized, versioned docs
• API documentation coverage from 40% to 85%: Clear standards and tooling drove adoption

Technical Architecture

Deployment

We deployed Backstage on Kubernetes with:

• 3 replicas for high availability
• PostgreSQL for catalog and auth state
• Redis for caching
• Azure Blob Storage for TechDocs assets

Authentication

Integrated with Azure AD using the built-in Microsoft auth provider:

• SSO with existing enterprise credentials
• Group-based permissions (who can modify catalog entities)
• Audit logging for compliance

Plugin Development

Our custom plugins followed consistent patterns:

• Frontend plugins in React/TypeScript
• Backend plugins in Node.js for integrations needing secrets
• Shared design system for visual consistency

Lessons Learned

Start Small, Iterate Fast

Don't try to solve everything at once. We started with the catalog and docs, proved value, then expanded.

Invest in Custom Plugins

The most valued features were organization-specific. Generic capabilities come from core Backstage; differentiation comes from custom plugins tailored to your workflows.

Documentation-as-Code Drives Adoption

Making TechDocs the only supported documentation platform forced migration. Developers preferred writing Markdown in their repos over maintaining wiki pages.

Make It the Default, Not Optional

Backstage succeeded because leadership mandated its use. Optional tools get optional adoption.

Catalog Quality Requires Governance

Without enforcement, catalog data rots. We established:

• Required fields for production services
• Automated validation in CI pipelines
• Quarterly audits of catalog accuracy

Community Engagement Pays Off

We contributed bug fixes and plugins back to the community. This built relationships with other adopters and influenced roadmap priorities.

Future Plans

Our Backstage journey continues:

• AI-assisted search: Using LLMs to answer natural language questions about our services
• Automated service scoring: Calculating maturity scores based on test coverage, documentation, and security posture
• Self-service infrastructure: Integrating Terraform modules for teams to provision their own resources
• Cost optimization recommendations: AI-driven suggestions for reducing cloud spend

Recommendations for Others

1. Executive sponsorship is essential: Developer portals need organizational commitment to succeed
2. Start with the catalog: It's the foundation everything else builds on
3. Invest in content migration: Great tooling with poor content delivers poor outcomes
4. Plan for customization: Budget time for custom plugins from the start
5. Measure and communicate value: Track metrics and share wins to maintain momentum