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.