# Backstage

> Open platform for building developer portals.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: backstage, postgresql
- Tags: backstage, developer-portal, spotify, catalog
- Source: https://docker.recipes/devops/backstage

## Overview

Backstage is Spotify's open-source developer portal platform that centralizes software components, documentation, and tooling in a single unified interface. Originally built to solve Spotify's internal chaos of thousands of microservices and repositories, Backstage provides a software catalog that automatically discovers and tracks all components across your infrastructure while offering scaffolding templates for consistent project creation. This configuration pairs Backstage with PostgreSQL to provide enterprise-grade persistence for the software catalog, user preferences, and plugin data. PostgreSQL's ACID compliance and robust JSON support make it ideal for storing Backstage's complex metadata relationships and dynamic plugin configurations. This stack transforms fragmented development workflows into a cohesive developer experience, enabling teams to discover existing services, understand dependencies, and maintain consistent development practices across the organization.

## Features

- Software Catalog with automatic service discovery and dependency mapping
- TechDocs integration for documentation-as-code using MkDocs format
- Software Templates for scaffolding new projects with organizational standards
- Plugin ecosystem with 100+ community integrations for GitHub, Kubernetes, and monitoring tools
- PostgreSQL backend with JSONB support for flexible plugin data storage
- Component ownership tracking and team management
- Search functionality across all registered software components
- API documentation aggregation from OpenAPI specifications

## Use cases

- Engineering organizations managing dozens of microservices and repositories
- Platform teams establishing developer self-service portals
- Companies implementing Inner Source programs with service discovery
- DevOps teams standardizing project scaffolding and deployment templates
- Organizations migrating from wikis to documentation-as-code workflows
- Teams requiring centralized API documentation and service dependency tracking
- Engineering managers needing visibility into team ownership and service health

## Prerequisites

- Minimum 2GB RAM for Backstage container and PostgreSQL database
- Port 7007 available for Backstage web interface access
- Database password configured in DB_PASSWORD environment variable
- Understanding of YAML for creating catalog-info.yaml component definitions
- Git repositories with proper access tokens for component discovery
- Basic knowledge of software catalog concepts and service ownership

## docker-compose.yml

```yaml
services:
  backstage:
    image: roadiehq/community-backstage-image:latest
    container_name: backstage
    restart: unless-stopped
    ports:
      - "7007:7007"
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_USER: backstage
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    depends_on:
      - postgres

  postgres:
    image: postgres:15-alpine
    container_name: backstage-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: backstage
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: backstage
    volumes:
      - backstage_db:/var/lib/postgresql/data

volumes:
  backstage_db:
```

## .env

```bash
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://backstage.io/docs/
- Access at http://localhost:7007
- Register components via catalog-info.yaml files in repos
- Software Templates for scaffolding new projects
- TechDocs for documentation-as-code (MkDocs format)
- Extend with 100+ community plugins (Kubernetes, GitHub, PagerDuty)

## Troubleshooting

- Backstage fails to start with database connection error: Ensure postgres container is fully initialized before backstage starts, add healthcheck or init delay
- Components not appearing in catalog: Verify catalog-info.yaml files are properly formatted and accessible via configured Git integrations
- TechDocs showing 404 errors: Check that MkDocs documentation follows proper mkdocs.yml structure and is committed to repository
- Plugin installation failures: Verify plugin compatibility with Roadie community image version and check for required environment variables
- Search returning no results: Rebuild search index through Backstage admin interface or restart container to refresh catalog
- Template scaffolding errors: Validate Cookiecutter template syntax and ensure all required parameters have default values

