Software Architecture/Engineering  

Best Practices for Setting Up Internal Developer Portals

Introduction

Modern software development teams are growing rapidly, and managing services, tools, documentation, and workflows has become complex. Developers often waste time searching for the right resources instead of building features.

This is where an Internal Developer Portal (IDP) becomes important.

An Internal Developer Portal is a centralized platform where developers can:

  • Discover services and APIs

  • Access documentation

  • Manage deployments

  • Follow standard development workflows

Backstage, created by Spotify, is one of the most popular open-source platforms for building Internal Developer Portals.

In this article, you will learn how to set up an Internal Developer Portal using Backstage, along with best practices, real-world examples, and detailed explanations.

What is an Internal Developer Portal (IDP)?

An Internal Developer Portal is a self-service platform designed to improve developer productivity by centralizing tools, services, and documentation.

IDP = A single place where developers find everything they need to build, deploy, and manage applications.

Key Features of an IDP

  • Service catalog

  • Documentation hub

  • CI/CD integration

  • Infrastructure visibility

  • Access control

Real-Life Example

In a large company:

  • 100+ microservices exist

  • Developers struggle to find service owners

  • Documentation is scattered

With IDP:

  • All services are listed in one place

  • Ownership is clear

  • Documentation is easily accessible

What is Backstage?

Backstage is an open-source platform for building developer portals. It provides a plugin-based architecture that allows teams to integrate tools and services easily.

Key Features of Backstage

  • Software catalog for service management

  • Plugin system for integrations

  • TechDocs for documentation

  • Scaffolder for creating new services

Why Backstage?

  • Highly customizable

  • Strong community support

  • Used by companies like Spotify, Airbnb, and American Airlines

Core Components of Backstage

Understanding these components is essential before setup.

1. Software Catalog

Stores metadata about services, APIs, and resources.

Example:

  • Service name

  • Owner

  • Repository link

2. TechDocs

Documentation system integrated into Backstage.

Example:

  • Architecture docs

  • API guides

3. Scaffolder

Helps create new services using predefined templates.

Example:

  • Create a new microservice in one click

4. Plugins

Extend functionality.

Examples:

  • GitHub integration

  • Kubernetes dashboard

Step-by-Step Setup of Backstage

Step 1: Install Node.js and Yarn

Backstage requires Node.js and Yarn.

npm install -g yarn

Step 2: Create Backstage App

npx @backstage/create-app

Step 3: Run the Application

yarn dev

Step 4: Configure Software Catalog

Add services using YAML configuration.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
spec:
  type: service
  owner: team-a

Step 5: Add Plugins

Install plugins like GitHub, Kubernetes, etc.

yarn add @backstage/plugin-github

Best Practices for Building IDP using Backstage

1. Start Small and Scale Gradually

Do not try to build everything at once.

Example:

  • Start with service catalog

  • Add documentation later

2. Maintain Accurate Service Catalog

Ensure all services have:

  • Owner

  • Description

  • Repository link

3. Standardize Templates

Use scaffolder templates to maintain consistency.

Example:

  • Standard microservice template

  • Pre-configured CI/CD

4. Integrate CI/CD Pipelines

Connect tools like GitHub Actions or Jenkins.

Benefits:

  • Faster deployments

  • Better visibility

5. Focus on Developer Experience

Keep UI simple and intuitive.

6. Implement Role-Based Access Control

Control who can access what.

Example:

  • Admin vs Developer roles

7. Keep Documentation Updated

Use TechDocs to keep docs close to code.

8. Monitor and Improve

Use feedback from developers to improve portal.

Real-World Use Cases

1. Microservices Management

  • Track all services in one place

  • Identify dependencies

2. Onboarding New Developers

  • Easy access to documentation

  • Faster learning curve

3. DevOps Visibility

  • View deployments and pipelines

4. Platform Engineering

  • Provide self-service infrastructure

Advantages of Using Backstage IDP

  • Improved developer productivity

  • Centralized information

  • Faster onboarding

  • Standardized workflows

  • Better collaboration

Disadvantages

  • Initial setup effort

  • Requires maintenance

  • Learning curve for teams

Common Mistakes to Avoid

  • Overcomplicating the portal

  • Not maintaining service catalog

  • Ignoring developer feedback

  • Lack of documentation

When Should You Use IDP?

Use IDP when:

  • You have multiple teams

  • You use microservices architecture

  • You want to improve developer efficiency

Conclusion

Internal Developer Portals built using Backstage can significantly improve developer productivity and streamline workflows.

By following best practices and focusing on developer experience, organizations can build a powerful and scalable developer platform.

Backstage is not just a tool—it is a foundation for modern platform engineering.

Membership not found