August 24, 2026
9 min read
Table of Contents
By Kokil Thapa | Last reviewed: August 2026
Engineering teams waste hours every week hunting for API documentation, service owners, and deployment runbooks scattered across wikis and repositories. Using Backstage: Build a Developer Portal solves this fragmentation by providing a unified interface for your entire infrastructure ecosystem. If you are managing microservices or complex APIs, implementing this platform is often the difference between chaotic onboarding and streamlined developer productivity. For teams evaluating internal tooling strategies alongside Laravel API best practices, Backstage provides the necessary metadata layer to make those APIs discoverable and manageable at scale.
Quick answer: To use Backstage: Build a Developer Portal, deploy the Node.js application with a PostgreSQL backend, configure YAML-based software catalogs for service discovery, and integrate plugins for CI/CD and API documentation. This creates a centralized Internal Developer Platform (IDP) that standardizes how engineers create, maintain, and consume internal services.
What is Backstage and why build a developer portal?
Backstage is an open-source framework originally created by Spotify and now hosted by the Cloud Native Computing Foundation (CNCF). It is not a turnkey SaaS product but a toolkit for constructing custom Internal Developer Platforms. When organizations decide to use Backstage: Build a Developer Portal, they are essentially creating a single pane of glass that aggregates infrastructure abstraction, documentation, and service metadata.
In my experience working on production systems with distributed architectures, the primary value proposition is cognitive load reduction. Developers do not need to memorize Jenkins URLs, Kubernetes namespaces, or Swagger locations. Instead, the portal presents a unified entity model. The core of this system is the Software Catalog, which treats services, websites, libraries, and resources as first-class entities defined in YAML. This declarative approach aligns well with modern GitOps workflows and ensures that the portal reflects the actual state of your codebase rather than stale wiki pages.
For Nepali tech companies or outsourcing firms managing multiple client projects, this centralization reduces context switching. Instead of maintaining separate documentation standards for each client, you can enforce consistent metadata schemas through the portal. This is particularly relevant when coordinating teams across different time zones or when onboarding junior developers who need clear guardrails around service ownership and API contracts.
How do you configure the software catalog in Backstage?
The Software Catalog is the backbone of any Backstage implementation. It imports metadata from YAML files stored in your source control repositories. Understanding this configuration is mandatory before you attempt to add custom plugins or integrations.
Defining component entities
Every service, website, or library needs a catalog-info.yaml file in its repository root. This file declares the entity type, lifecycle stage, and ownership. In practice, getting this schema right prevents downstream issues with search and filtering.
<!-- catalog-info.yaml example -->
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service-np
description: Handles eSewa and Khalti payment callbacks
annotations:
github.com/project-slug: my-org/payment-service
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
owner: team-fintech
system: payment-gateway
providesApis:
- payment-api-v2The annotations block is critical. These key-value pairs link the abstract catalog entity to concrete infrastructure. Without the correct GitHub or GitLab annotation, the source code browsing and CI/CD plugins will fail silently. I have seen deployments stall because teams used the wrong annotation format for their specific SCM provider.
Registering entities statically vs dynamically
You can register entities manually via the UI, but production deployments should use static configuration or discovery processors. Static registration in app-config.yaml ensures the portal always knows about core infrastructure even if dynamic scanning fails.
- Static: Best for foundational services and shared libraries that rarely change location.
- Discovery: Use GitHub/GitLab discovery processors to scan organizations for
catalog-info.yamlfiles automatically. - LDAP/Cloud: Import users and groups to map ownership correctly.
When scaling to hundreds of services, rely on discovery processors with appropriate rate limiting. Hitting GitHub API limits during catalog refresh is a common failure mode for new installations. Configure caching aggressively in your backend to reduce external API calls.
Which plugins are essential for a functional developer portal?
Backstage ships with a minimal core; functionality comes from plugins. Choosing the right plugin set determines whether your portal becomes a useful daily tool or abandoned shelfware. Based on real-world implementations, these categories deliver immediate ROI.
| Plugin Category | Recommended Plugin | Primary Function | Complexity |
|---|---|---|---|
| Source Control | @backstage/plugin-github-actions | View workflow runs and PR status directly in portal | Low |
| API Documentation | @backstage/plugin-api-docs | Renders OpenAPI/Swagger specs with interactive try-out | Medium |
| Documentation | @backstage/plugin-techdocs | Markdown-to-HTML docs co-located with code | Medium |
| Kubernetes | @backstage/plugin-kubernetes | Shows pod status, logs, and resource usage per service | High |
| Scaffolding | @backstage/plugin-scaffolder | Self-service template creation for new services | High |
TechDocs deserves special attention. Unlike external wikis, TechDocs uses a "docs-like-code" approach where documentation lives in the same repository as the service. The backend transforms Markdown into static HTML during build time. This eliminates drift between code and docs. For agencies managing client handovers, this ensures documentation version-matches the deployed artifact exactly.
The Scaffolder plugin enables self-service. Engineers select a template (e.g., "Laravel Microservice" or "React Dashboard"), fill in metadata, and the system generates a repository with CI/CD pipelines, Dockerfiles, and catalog entries pre-configured. This enforces organizational standards without manual intervention. For teams adopting modern Laravel architecture, creating a standardized template ensures every new service starts with correct logging, error handling, and security baselines.
How do you deploy and secure Backstage in production?
Running Backstage locally with SQLite is fine for evaluation, but production requires PostgreSQL and proper authentication. Deployment complexity scales with your security requirements and infrastructure maturity.
Database and backend configuration
PostgreSQL is the only recommended database for production Backstage instances. SQLite lacks concurrency support and will bottleneck during catalog refreshes. Configure connection pooling using PgBouncer if running on Kubernetes to prevent connection exhaustion.
# app-config.production.yaml excerpt
backend:
database:
client: pg
connection:
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
ssl:
require: true
rejectUnauthorized: false
pool:
min: 5
max: 20Environment variables should never be committed to source control. Use Kubernetes Secrets, AWS Parameter Store, or HashiCorp Vault depending on your infrastructure. For Nepal-based deployments using local VPS providers, ensure your PostgreSQL instance has automated backups configured; managed databases are preferable if available within budget constraints.
Authentication and authorization
Backstage supports multiple auth providers: GitHub, GitLab, Google Workspace, Microsoft Entra ID, and generic OAuth2/OIDC. For most organizations, integrating with your existing identity provider is mandatory. The newer Permission Framework allows granular access control beyond simple authentication.
Define permission policies in code rather than UI configuration. This enables review processes and version control for access rules. A common pattern is restricting scaffolder templates to senior engineers while allowing read-only catalog access to all authenticated users. Never expose a Backstage instance publicly without authentication; the catalog contains sensitive infrastructure metadata that aids attackers.
Deployment strategies
Docker is the standard packaging format. Build separate images for frontend and backend to optimize caching and scaling. The frontend is a static React app served by Nginx; the backend is a Node.js process. On Kubernetes, use Helm charts provided by the Backstage community as a starting point, but customize resource requests based on your catalog size.
For smaller teams or single-server deployments, Docker Compose works adequately. Ensure you mount persistent volumes for TechDocs storage if not using object storage. Monitor Node.js heap usage; large catalogs with many plugins can exceed default memory limits. Setting NODE_OPTIONS=--max-old-space-size=4096 prevents OOM crashes during intensive catalog processing.
What are common pitfalls when adopting Backstage?
Adoption failures usually stem from organizational issues rather than technical ones. Backstage exposes existing documentation debt and unclear service ownership. Addressing these prerequisites is as important as the installation itself.
Premature customization: Resist building custom plugins in the first three months. Use community plugins and adapt processes to fit the tool initially. Custom development creates maintenance burden and upgrade friction. Only build custom plugins when you have validated that no existing solution meets a critical business requirement.
Catalog hygiene neglect: A portal with stale data loses trust immediately. Implement automated validation in CI pipelines to reject catalog-info.yaml changes that violate schema rules. Set up alerts for entities without owners or missing annotations. Treat catalog metadata with the same rigor as application code.
Ignoring developer experience: The portal must be faster than alternatives. If searching for a service takes longer than asking in Slack, adoption will fail. Invest in search tuning and ensure TechDocs builds complete within minutes. Profile your backend regularly; slow API responses kill engagement.
For teams also managing client websites, consider how Backstage integrates with broader web development services. The portal can document client-specific deployment procedures, SLA definitions, and escalation contacts, making it valuable beyond pure engineering tooling.
Moving forward with your developer portal
Implementing Backstage: Build a Developer Portal is an iterative process that matures alongside your engineering culture. Start with the software catalog and TechDocs to establish immediate value before expanding to scaffolding and complex integrations. Measure success through developer satisfaction surveys and time-to-onboarding metrics rather than feature count. If your team struggles with service discovery or fragmented documentation, this platform offers a proven path to consolidation. For guidance on structuring the underlying APIs that populate your portal, review our REST API development guide to ensure your services are designed for discoverability from day one. Ready to streamline your internal tooling? Contact me to discuss your developer portal strategy or infrastructure assessment.
Frequently Asked Questions
Backstage is an open-source framework by CNCF for building internal developer portals. It centralizes service catalogs, documentation, APIs, and infrastructure tooling into one UI to reduce cognitive load and improve developer experience across engineering teams.
The software is free, but implementation costs vary. A basic setup runs Rs 300,000–500,000 (USD 2,200–3,700) for initial configuration. Ongoing maintenance typically requires 10–20 hours monthly at senior engineer rates of Rs 3,000–5,000 per hour in Nepal.
No. While designed for cloud-native environments, Backstage works with any infrastructure. I have deployed it for clients using traditional VMs and PHP applications. The service catalog supports manual registration, making it viable for hybrid or legacy stacks without Kubernetes.
PostgreSQL 16 or 17 is the recommended production database. MySQL 8.0 and 8.4 LTS are supported but receive less community testing. SQLite is only for local development. On client projects, I always use PostgreSQL for better JSONB support and plugin compatibility.
Use the Entity API to register services via YAML descriptors or custom processors. For Laravel apps, create a backstage-plugin-backend module that reads your service metadata from composer.json or a dedicated config file. This avoids rewriting existing PHP code while maintaining catalog accuracy.
Backstage requires Node.js 22 LTS as of early 2026. Node 20 LTS still works but reaches end-of-life in April 2026. Always pin your .nvmrc to 22.x for new installations. I have encountered subtle test failures when mixing Node versions across CI and local environments.
Backstage is designed for internal portals, not public docs. Exposing it externally requires significant authentication hardening and removes the zero-trust assumption. For public API docs, use Redoc, Scalar, or Stoplight alongside Backstage. Keep internal and external documentation systems separate for security.
A minimal viable portal with service catalog and TechDocs takes 4–6 weeks for one senior engineer. Full production rollout with custom plugins, SSO integration, and team onboarding typically spans 3–4 months. Timeline depends heavily on existing infrastructure documentation quality and stakeholder alignment.
File permissions on /var/lib/backstage often cause startup failures after updates. Always run as a dedicated system user, not root. Ensure opcache is disabled for the Backstage process since it serves dynamic bundles. On Ubuntu 24.04, verify systemd unit files reference the correct Node binary path.
Backstage offers maximum customization but demands engineering resources. Port provides faster time-to-value with managed hosting at higher licensing costs. Cortex focuses specifically on service maturity scoring. Choose Backstage if you need deep integration with existing tooling and have dedicated platform engineers to maintain it.
Backstage assumes a trusted internal network by default. Production deployments require RBAC via the permission framework, SSO integration, and network segmentation. Never expose the backend API without authentication. Audit plugin permissions carefully, as third-party plugins may bypass default access controls. Treat it like any privileged internal tool.
Pin exact versions in package.json and test upgrades in staging first. Backstage releases monthly; skip minor versions if stable. Custom plugins should follow the official plugin SDK patterns to minimize breakage. I maintain a changelog review checklist for every upgrade. Breaking changes are documented but easy to miss in large release notes.
Yes. The @backstage/plugin-gitlab-actions plugin displays pipeline status directly in service entity pages. Configure a GitLab personal access token with read_api scope in app-config.yaml. For self-managed GitLab instances, set the baseUrl parameter explicitly. Webhook integration enables real-time status updates without polling overhead.
Minimum 4 CPU cores and 8GB RAM for small teams under 100 services. Scale to 8 cores and 16GB for larger catalogs or heavy TechDocs usage. Database needs separate provisioning with at least 4GB RAM. On AWS EC2, this translates to t3.large or m6i.xlarge depending on workload patterns.
Skip Backstage if your team has fewer than 15 engineers or lacks dedicated platform engineering capacity. The maintenance burden outweighs benefits for small teams. Also avoid if you need a solution within two weeks. Consider simpler alternatives like Notion wikis, ReadMe, or static site generators until organizational complexity justifies the investment.
