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.

Join the conversation! Your thoughts help the community grow.