# Backstage Developer Portal

> Open-source developer portal for building developer platforms with plugin ecosystem.

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

## Overview

Backstage is Spotify's open-source developer portal platform that centralizes software catalog management, documentation, and tooling into a unified developer experience. Originally built to solve Spotify's internal developer platform challenges, Backstage provides service discovery, technical documentation, deployment pipelines, and monitoring dashboards through an extensible plugin architecture. The platform has gained significant adoption among enterprises seeking to reduce cognitive load on development teams and standardize their internal tooling ecosystem.

This stack combines Backstage with PostgreSQL for persistent metadata storage, Redis for caching and session management, and NGINX for production-grade load balancing and SSL termination. PostgreSQL handles Backstage's service catalog data, user permissions, and plugin configurations with full ACID compliance, while Redis accelerates authentication sessions and caches frequently accessed catalog information. NGINX provides reverse proxy capabilities, enabling blue-green deployments and handling static asset delivery efficiently.

Platform engineering teams building internal developer platforms will find this configuration particularly valuable, as it addresses the complete infrastructure needs for a production Backstage deployment. The stack supports organizations with 50-5000+ developers who need centralized service discovery, automated documentation generation, and standardized deployment workflows across multiple engineering teams.

## Features

- Backstage Software Templates for scaffolding new services with organizational standards and best practices built-in
- TechDocs integration with PostgreSQL storage for automated documentation generation from markdown files in service repositories
- Redis-powered authentication caching for faster login experiences and reduced database load during peak usage
- Service catalog with PostgreSQL-backed relationships, ownership tracking, and dependency mapping across microservices
- Plugin ecosystem support including Kubernetes monitoring, CI/CD pipeline visualization, and cost tracking integrations
- NGINX reverse proxy configuration enabling multiple Backstage instances for staging and production environments
- PostgreSQL JSON fields for flexible plugin configuration storage without schema migrations
- Redis pub/sub messaging for real-time updates to service catalog changes and deployment notifications

## Use cases

- Platform engineering teams establishing developer self-service portals for service creation and lifecycle management
- Organizations consolidating scattered internal tools (wikis, monitoring, CI/CD) into a single developer interface
- Engineering managers needing visibility into service ownership, dependencies, and documentation coverage across teams
- Companies implementing standardized deployment pipelines and security scanning through Backstage Software Templates
- DevOps teams providing developers with Kubernetes cluster access and resource monitoring without kubectl complexity
- Enterprises migrating from proprietary developer portals to open-source solutions with vendor independence
- Startups scaling beyond 20-30 services where manual service discovery and documentation becomes unsustainable

## Prerequisites

- Minimum 4GB RAM available (1GB for Backstage, 1GB+ for PostgreSQL, 512MB for Redis, 256MB for NGINX)
- Node.js 18+ and Yarn package manager for Backstage application building and customization
- Understanding of Backstage's app-config.yaml structure for plugin configuration and authentication setup
- Basic knowledge of PostgreSQL schema management for Backstage database migrations and backups
- Familiarity with NGINX reverse proxy configuration for SSL certificates and custom domain setup
- Git repository access for integrating Backstage with GitHub, GitLab, or Bitbucket for service catalog discovery

## docker-compose.yml

```yaml
services:
  backstage:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
      - "7007:7007"
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      APP_CONFIG_app_baseUrl: http://localhost:3000
      APP_CONFIG_backend_baseUrl: http://localhost:7007
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - backstage-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: backstage
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backstage-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - backstage-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - backstage
    networks:
      - backstage-net
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

networks:
  backstage-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL Configuration
POSTGRES_USER=backstage
POSTGRES_PASSWORD=secure_postgres_password

# Backstage Configuration
GITHUB_TOKEN=ghp_xxxx
BACKSTAGE_BASE_URL=http://localhost:3000
```

## Usage notes

- Create Backstage app: npx @backstage/create-app
- Build Docker image from your Backstage app
- Frontend at http://localhost:3000
- Backend API at http://localhost:7007

## Troubleshooting

- Backstage frontend shows 'Failed to load catalog' errors: Check PostgreSQL connection and verify POSTGRES_HOST environment variable matches service name
- Authentication sessions expire immediately: Ensure Redis is accessible from Backstage container and check Redis connection in app-config.yaml
- NGINX returns 502 Bad Gateway: Verify Backstage backend is running on port 7007 and update upstream configuration in nginx.conf
- PostgreSQL connection refused during startup: Add depends_on with health check condition and increase PostgreSQL startup timeout values
- Backstage plugins fail to load: Check plugin configuration in app-config.yaml and ensure required environment variables are set for external integrations
- TechDocs generation fails: Verify PostgreSQL has sufficient disk space and check techdocs.builder configuration in Backstage app-config

