Why Backstage

Developers rarely spend all day writing code. Instead, they juggle a variety of tools:

1. A Single Developer Portal

Imagine all your tools available on one site. A unified portal lets developers log in, find everything they need, and focus on writing code instead of searching for links.

2. Unified Service Documentation

Service docs spread across Confluence, Google Docs, GitHub Pages, or internal wikis create friction.

Backstage’s software catalog stores metadata and docs together—searchable, versioned, and always up to date.

3. Clear Ownership and Faster Answers

Outdated docs force developers to track down service owners:

Even after finding someone, they may have moved on:

Common frustrations:

1. Hours spent hunting for documentation
2. Difficulty identifying service owners
3. Time lost coordinating contacts

Backstage solves this by displaying ownership details alongside documentation in a central hub:

4. Visualizing Service Dependencies

Updating a service without insight into downstream dependencies can cause failures:

A portal that visualizes these relationships helps you see which applications rely on your service before deploying changes.

5. Debugging Third-Party Integrations

Troubleshooting email delivery often starts with SendGrid:

import os
import sendgrid
from sendgrid.helpers.mail import Mail, Email, To, Content

SENDGRID_API_KEY = os.getenv("SENDGRID_API_KEY")
SENDER_EMAIL = os.getenv("SENDER_EMAIL")
RECEIVER_EMAIL = "[email protected]"
SUBJECT = "Welcome to Our Application!"
BODY = "Thank you for using our app! We are glad to have you onboard."

if not SENDGRID_API_KEY or not SENDER_EMAIL:
    raise EnvironmentError("Missing SendGrid configuration. Check environment variables.")

sg = sendgrid.SendGridAPIClient(api_key=SENDGRID_API_KEY)
from_email = Email(SENDER_EMAIL)
to_email = To(RECEIVER_EMAIL)
content = Content("text/plain", BODY)
mail = Mail(from_email, to_email, SUBJECT, content)

try:
    response = sg.send(mail)
    print(f"Email sent successfully! Status Code: {response.status_code}")
except Exception as e:
    print(f"Failed to send email: {e}")

If that fails, you might switch to SMTP:

import os
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart

SMTP_SERVER = os.getenv("SMTP_SERVER")
SMTP_PORT = int(os.getenv("SMTP_PORT", 587))
SENDER_EMAIL = os.getenv("SENDER_EMAIL")
SENDER_PASSWORD = os.getenv("SENDER_PASSWORD")
RECEIVER_EMAIL = "[email protected]"
SUBJECT = "Welcome to Our Application!"
BODY = "Thank you for using our app! We are glad to have you onboard."

if not SMTP_SERVER or not SENDER_EMAIL or not SENDER_PASSWORD:
    raise EnvironmentError("Missing SMTP configuration. Check environment variables.")

message = MIMEMultipart()
message["From"] = SENDER_EMAIL
message["To"] = RECEIVER_EMAIL
message["Subject"] = SUBJECT
message.attach(MIMETText(BODY, "plain"))

try:
    with smtplib.SMTP(SMTP_SERVER, SMTP_PORT) as server:
        server.starttls()
        server.login(SENDER_EMAIL, SENDER_PASSWORD)
        server.sendmail(SENDER_EMAIL, RECEIVER_EMAIL, message.as_string())
        print("Email sent successfully!")
except Exception as e:
    print(f"Failed to send email: {e}")

Without dependency tracking, downstream services can break. Backstage’s graphing prevents these surprises.

6. Automating New Project Scaffolding

Launching a new service manually requires many steps:

• Creating a GitHub repository
• Provisioning Kubernetes clusters
• Setting up linting, formatting, tests, and CI/CD
• Configuring repository permissions
• Creating databases and DNS entries
• Deploying to production

Backstage templates automate all of this with a single button click:

Template Benefits

• Centralized template management
• Enforced best practices
• Language- and framework-specific scaffolds

7. Self-Service Infrastructure Requests

Filing tickets for S3 buckets or VMs can take days:

With Backstage, developers fill out a form:

The infra team reviews, approves, and the portal provisions resources automatically with correct policies.

8. Internal Developer Portals (IDPs)

All these scenarios led to Internal Developer Portals—central hubs that aggregate tools, documentation, and resources so teams can build, test, and deploy software efficiently.

Core IDP Features

Key Benefits

• Streamlined access and searchability
• Consistent, up-to-date documentation
• Enhanced collaboration and community
• Faster development with pre-built code samples
• Quicker onboarding for new team members
• Self-service provisioning with guardrails
• Governance via policies and templates

Backstage: Your Open Source IDP Framework

Backstage is an open source platform for building Internal Developer Portals. It provides:

• A software catalog with metadata and search
• Built-in support for Markdown, MkDocs, and TechDocs
• An extensible plugin architecture
• Scaffolding tools for project templates
• Role-based access control and policy enforcement

We’ll dive into Backstage’s architecture, core plugins, and best practices for running your own portal.

Links and References

• Backstage Documentation
• Backstage Plugin Marketplace
• Internal Developer Portal Concept