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:

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

Real-Life Example

In a large company:

With IDP:

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

Why Backstage?

Core Components of Backstage

Understanding these components is essential before setup.

1. Software Catalog

Stores metadata about services, APIs, and resources.

Example:

2. TechDocs

Documentation system integrated into Backstage.

Example:

3. Scaffolder

Helps create new services using predefined templates.

Example:

4. Plugins

Extend functionality.

Examples:

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:

2. Maintain Accurate Service Catalog

Ensure all services have:

3. Standardize Templates

Use scaffolder templates to maintain consistency.

Example:

4. Integrate CI/CD Pipelines

Connect tools like GitHub Actions or Jenkins.

Benefits:

5. Focus on Developer Experience

Keep UI simple and intuitive.

6. Implement Role-Based Access Control

Control who can access what.

Example:

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

2. Onboarding New Developers

3. DevOps Visibility

4. Platform Engineering

Advantages of Using Backstage IDP

Disadvantages

Common Mistakes to Avoid

When Should You Use IDP?

Use IDP when:

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.