Backstage

Key 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

Common Use Cases

• 1Engineering organizations managing dozens of microservices and repositories
• 2Platform teams establishing developer self-service portals
• 3Companies implementing Inner Source programs with service discovery
• 4DevOps teams standardizing project scaffolding and deployment templates
• 5Organizations migrating from wikis to documentation-as-code workflows
• 6Teams requiring centralized API documentation and service dependency tracking
• 7Engineering 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

1services: 
2  backstage: 
3    image: roadiehq/community-backstage-image:latest
4    container_name: backstage
5    restart: unless-stopped
6    ports: 
7      - "7007:7007"
8    environment: 
9      POSTGRES_HOST: postgres
10      POSTGRES_USER: backstage
11      POSTGRES_PASSWORD: ${DB_PASSWORD}
12    depends_on: 
13      - postgres
14
15  postgres: 
16    image: postgres:15-alpine
17    container_name: backstage-db
18    restart: unless-stopped
19    environment: 
20      POSTGRES_USER: backstage
21      POSTGRES_PASSWORD: ${DB_PASSWORD}
22      POSTGRES_DB: backstage
23    volumes: 
24      - backstage_db:/var/lib/postgresql/data
25
26volumes: 
27  backstage_db: 

.env Template

1DB_PASSWORD=changeme

Usage Notes

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

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

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  backstage:
5    image: roadiehq/community-backstage-image:latest
6    container_name: backstage
7    restart: unless-stopped
8    ports:
9      - "7007:7007"
10    environment:
11      POSTGRES_HOST: postgres
12      POSTGRES_USER: backstage
13      POSTGRES_PASSWORD: ${DB_PASSWORD}
14    depends_on:
15      - postgres
16
17  postgres:
18    image: postgres:15-alpine
19    container_name: backstage-db
20    restart: unless-stopped
21    environment:
22      POSTGRES_USER: backstage
23      POSTGRES_PASSWORD: ${DB_PASSWORD}
24      POSTGRES_DB: backstage
25    volumes:
26      - backstage_db:/var/lib/postgresql/data
27
28volumes:
29  backstage_db:
30EOF
31
32# 2. Create the .env file
33cat > .env << 'EOF'
34DB_PASSWORD=changeme
35EOF
36
37# 3. Start the services
38docker compose up -d
39
40# 4. View logs
41docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/backstage/run | bash

Troubleshooting