Learning Backstage

A comprehensive guide to learning Backstage for building Internal Developer Platforms (IDPs)

• References

Directory Structure

learning-backstage/
├── README.md
├── .gitignore
├── LICENSE
│
├── 100 - Introduction/
│   ├── 101 - What is Backstage/
│   ├── 102 - IDP Fundamentals/
│   ├── 103 - Use Cases and Benefits/
│   └── 104 - Architecture Overview/
│
├── 200 - Getting Started/
│   ├── 201 - Prerequisites/
│   │   ├── Node.js and npm/
│   │   ├── Docker and Containers/
│   │   └── Git Basics/
│   ├── 202 - Installation/
│   │   ├── Local Development Setup/
│   │   ├── Creating Your First App/
│   │   └── Running Backstage/
│   └── 203 - Initial Configuration/
│       ├── app-config.yaml/
│       └── Environment Variables/
│
├── 300 - Core Concepts/
│   ├── 301 - Software Catalog/
│   │   ├── Catalog Model/
│   │   ├── Entities (Components, APIs, Resources)/
│   │   ├── YAML Descriptors/
│   │   └── Entity Relationships/
│   ├── 302 - Software Templates/
│   │   ├── Template Basics/
│   │   ├── Scaffolder Actions/
│   │   ├── Template Parameters/
│   │   └── Custom Templates/
│   ├── 303 - TechDocs/
│   │   ├── Documentation as Code/
│   │   ├── MkDocs Integration/
│   │   └── Publishing Documentation/
│   └── 304 - Search/
│       ├── Search Architecture/
│       └── Search Collators/
│
├── 400 - Plugins/
│   ├── 401 - Core Plugins/
│   │   ├── Catalog Plugin/
│   │   ├── Scaffolder Plugin/
│   │   ├── TechDocs Plugin/
│   │   └── Search Plugin/
│   ├── 402 - Community Plugins/
│   │   ├── Kubernetes/
│   │   ├── GitHub/
│   │   ├── GitLab/
│   │   ├── Jenkins/
│   │   ├── Argo CD/
│   │   ├── SonarQube/
│   │   └── PagerDuty/
│   ├── 403 - Plugin Development/
│   │   ├── Creating a Plugin/
│   │   ├── Frontend Plugins/
│   │   ├── Backend Plugins/
│   │   ├── Plugin APIs/
│   │   └── Testing Plugins/
│   └── 404 - Plugin Integration/
│       ├── Installing Plugins/
│       └── Configuring Plugins/
│
├── 500 - Authentication and Authorization/
│   ├── 501 - Authentication/
│   │   ├── Authentication Providers/
│   │   ├── OAuth2/OIDC/
│   │   ├── Azure AD/Entra ID/
│   │   ├── GitHub OAuth/
│   │   └── Guest Access/
│   ├── 502 - Authorization/
│   │   ├── Permission Framework/
│   │   ├── RBAC (Role-Based Access Control)/
│   │   ├── Policy Definition/
│   │   └── Permission Plugins/
│   └── 503 - Security Best Practices/
│       ├── Secrets Management/
│       └── Security Hardening/
│
├── 600 - Integration/
│   ├── 601 - Source Control/
│   │   ├── GitHub Integration/
│   │   ├── GitLab Integration/
│   │   ├── Azure DevOps/
│   │   └── Bitbucket/
│   ├── 602 - CI/CD/
│   │   ├── GitHub Actions/
│   │   ├── GitLab CI/
│   │   ├── Jenkins/
│   │   └── Azure Pipelines/
│   ├── 603 - Cloud Providers/
│   │   ├── Azure/
│   │   ├── AWS/
│   │   └── Google Cloud/
│   ├── 604 - Kubernetes/
│   │   ├── Cluster Integration/
│   │   ├── Workload Visibility/
│   │   └── Resource Management/
│   └── 605 - Monitoring and Observability/
│       ├── Prometheus/
│       ├── Grafana/
│       └── Application Insights/
│
├── 700 - Database and Storage/
│   ├── 701 - Database Options/
│   │   ├── PostgreSQL/
│   │   ├── MySQL/
│   │   └── SQLite (Development)/
│   ├── 702 - Database Migrations/
│   └── 703 - Backup and Recovery/
│
├── 800 - Deployment/
│   ├── 801 - Container Images/
│   │   ├── Building Images/
│   │   └── Image Optimization/
│   ├── 802 - Kubernetes Deployment/
│   │   ├── Helm Charts/
│   │   ├── Manifests/
│   │   └── Resource Requirements/
│   ├── 803 - Cloud Deployment/
│   │   ├── Azure Container Apps/
│   │   ├── Azure Kubernetes Service/
│   │   ├── AWS EKS/
│   │   └── Google GKE/
│   └── 804 - High Availability/
│       ├── Scaling Strategies/
│       └── Load Balancing/
│
├── 900 - Customization/
│   ├── 901 - Theming/
│   │   ├── Custom Themes/
│   │   └── Branding/
│   ├── 902 - Homepage Customization/
│   └── 903 - Custom Pages/
│
├── 1000 - Advanced Topics/
│   ├── 1001 - Backend System/
│   │   ├── Service Architecture/
│   │   ├── Task Scheduling/
│   │   └── Event System/
│   ├── 1002 - Catalog Processing/
│   │   ├── Processors/
│   │   ├── Custom Processors/
│   │   └── Catalog Rules/
│   ├── 1003 - API Development/
│   │   ├── Backend APIs/
│   │   └── GraphQL Integration/
│   └── 1004 - Performance Optimization/
│       ├── Caching Strategies/
│       └── Query Optimization/
│
├── 1100 - DevSecOps Integration/
│   ├── 1101 - Security Scanning/
│   │   ├── SAST Integration/
│   │   ├── DAST Integration/
│   │   ├── Dependency Scanning/
│   │   └── Container Scanning/
│   ├── 1102 - Compliance/
│   │   ├── Policy as Code/
│   │   ├── Audit Logging/
│   │   └── Compliance Dashboards/
│   └── 1103 - Vulnerability Management/
│       ├── CVE Tracking/
│       └── Remediation Workflows/
│
├── 1200 - Best Practices/
│   ├── 1201 - IDP Strategy/
│   │   ├── Platform Engineering/
│   │   ├── Developer Experience/
│   │   └── Golden Paths/
│   ├── 1202 - Catalog Management/
│   │   ├── Entity Lifecycle/
│   │   ├── Ownership Model/
│   │   └── Metadata Standards/
│   ├── 1203 - Template Strategy/
│   │   ├── Template Library/
│   │   └── Template Governance/
│   └── 1204 - Documentation Strategy/
│       ├── Docs-as-Code/
│       └── Documentation Standards/
│
├── 1300 - Monitoring and Operations/
│   ├── 1301 - Application Monitoring/
│   ├── 1302 - Logging/
│   ├── 1303 - Metrics/
│   └── 1304 - Alerting/
│
├── 1400 - Migration and Adoption/
│   ├── 1401 - Migration Strategies/
│   ├── 1402 - Change Management/
│   ├── 1403 - User Onboarding/
│   └── 1404 - Training Materials/
│
├── 1500 - Case Studies/
│   ├── 1501 - Enterprise IDP/
│   ├── 1502 - Multi-Tenant Backstage/
│   ├── 1503 - Security-First IDP/
│   └── 1504 - Cloud-Native Platform/
│
├── 1600 - Troubleshooting/
│   ├── 1601 - Common Issues/
│   ├── 1602 - Debug Techniques/
│   └── 1603 - Performance Issues/
│
├── 1700 - Tools and Resources/
│   ├── 1701 - CLI Tools/
│   ├── 1702 - Development Tools/
│   ├── 1703 - Testing Tools/
│   └── 1704 - Useful Links/
│
├── 1800 - Examples/
│   ├── 1801 - Sample Configurations/
│   ├── 1802 - Template Examples/
│   ├── 1803 - Plugin Examples/
│   └── 1804 - Integration Examples/
│
└── 1900 - References/
    ├── 1901 - Official Documentation/
    ├── 1902 - API Reference/
    ├── 1903 - Community Resources/
    ├── 1904 - Video Tutorials/
    └── 1905 - Glossary/

About This Repository

This repository serves as a comprehensive learning resource for Backstage, Spotify’s open platform for building developer portals and Internal Developer Platforms (IDPs). The content is organized systematically to support both beginners and advanced users.

Learning Path

For Beginners

1. Start with 100 - Introduction to understand what Backstage is and why it matters
2. Move to 200 - Getting Started to set up your first Backstage instance
3. Explore 300 - Core Concepts to understand the fundamental building blocks
4. Work through 400 - Plugins to extend functionality

For Intermediate Users

1. Dive into 500 - Authentication and Authorization for security
2. Explore 600 - Integration to connect with your existing tools
3. Study 800 - Deployment for production readiness
4. Review 1200 - Best Practices for optimal implementation

For Advanced Users

1. Master 1000 - Advanced Topics for deep customization
2. Implement 1100 - DevSecOps Integration for security-first platforms
3. Learn from 1500 - Case Studies for real-world examples
4. Contribute to the community using 403 - Plugin Development

Key Features Covered

• Software Catalog: Central hub for all software assets
• Software Templates: Standardized project scaffolding
• TechDocs: Documentation as code
• Plugin Ecosystem: Extensible architecture
• Authentication & Authorization: Enterprise-grade security
• Cloud & Kubernetes Integration: Modern infrastructure support
• DevSecOps: Security scanning and compliance
• Multi-cloud Support: Azure, AWS, GCP

Prerequisites

Before diving into this learning path, you should be familiar with:

• Basic command line usage
• Git version control
• Docker and containerization concepts
• Basic JavaScript/TypeScript (for customization)
• Cloud computing fundamentals

Repository Structure

Each numbered directory (100, 200, 300, etc.) represents a major topic area. Within each:

• Subdirectories are numbered for sequential learning
• Each topic includes explanations, examples, and hands-on exercises
• Real-world use cases and best practices are provided

How to Use This Repository

1. Clone the repository

   git clone https://github.com/vanHeemstraSystems/learning-backstage.git
   cd learning-backstage

2. Follow the numbered structure - Start with lower numbers and progress sequentially

3. Hands-on practice - Set up your own Backstage instance and experiment

4. Reference documentation - Use the 1900 series for quick lookups

Contributing

Contributions are welcome! If you’d like to add content, fix errors, or suggest improvements:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-content)
3. Commit your changes (git commit -m 'Add new content on X')
4. Push to the branch (git push origin feature/new-content)
5. Open a Pull Request

Resources

• Official Backstage Documentation
• Backstage GitHub Repository
• Backstage Community
• CNCF Backstage Project

Related Learning Repositories

This repository is part of a series of technical learning resources:

• Learning Azure
• Learning Kubernetes
• Learning Docker

License

[Choose your license - MIT, Apache 2.0, etc.]

Author

Willem van Heemstra
Security Domain Expert | Cloud Engineer
GitHub

Acknowledgments

• Spotify for creating and open-sourcing Backstage
• The CNCF and Backstage community
• All contributors to this learning repository

---

Note: This is a living document. The structure and content will evolve as Backstage continues to develop and as new best practices emerge.

Last Updated: December 2025