🎭 Backstage Developer Portal Setup on AlmaLinux 9: Complete Platform Engineering Guide

Welcome to the future of developer experience! 🎉 Today we’re going to learn how to set up Backstage on AlmaLinux 9, the amazing developer portal platform originally created by Spotify and now a CNCF project. Think of Backstage as your developer’s command center that unifies all tools, services, and documentation in one beautiful interface! 🚀✨

🤔 Why is Backstage Important?

Modern software development involves juggling countless tools, services, and documentation sources. Here’s why Backstage is a game-changer for developer productivity:

• 🎯 Single Pane of Glass - Unify all your tools, services, and infrastructure in one portal
• 📚 Centralized Documentation - Docs-as-code with automatic synchronization and discovery
• 🏗️ Software Templates - Standardize project creation with golden path templates
• 📊 Service Catalog - Discover and understand all services in your ecosystem
• 🔌 Plugin Ecosystem - Integrate with CI/CD, monitoring, security, and cloud tools
• 🎨 Self-Service Platform - Empower developers to create and manage their own resources

🎯 What You Need

Before we start our Backstage adventure, let’s make sure you have everything ready:

✅ AlmaLinux 9 system (fresh installation recommended)
✅ Root or sudo access for installing packages
✅ At least 8GB RAM (16GB recommended for production)
✅ 20GB free disk space for Node.js, dependencies, and data
✅ Internet connection for downloading packages and dependencies
✅ Basic terminal knowledge (don’t worry, we’ll explain everything!)
✅ Git repository access (GitHub, GitLab, or Bitbucket)
✅ Node.js 18+ experience (helpful but not required)

📝 Step 1: Update Your AlmaLinux System

Let’s start by making sure your system is up to date! 🚀

# Update all packages to latest versions
sudo dnf update -y

# Install essential development tools
sudo dnf groupinstall "Development Tools" -y

# Install helpful utilities we'll need
sudo dnf install -y curl wget git vim htop python3 python3-pip

Perfect! Your system is now ready for Backstage installation! ✨

🔧 Step 2: Install Node.js and Yarn

Backstage is built with Node.js and TypeScript. Let’s install the latest Node.js:

# Install Node.js 18 from NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo dnf install -y nodejs

# Verify Node.js installation
node --version  # Should show v18.x.x
npm --version   # Should show npm version

# Install Yarn package manager (recommended for Backstage)
sudo npm install -g yarn

# Verify Yarn installation
yarn --version

# Update npm to latest version
sudo npm install -g npm@latest

Awesome! Node.js and Yarn are ready for Backstage! 📦

🌟 Step 3: Create Backstage Application

Let’s create your Backstage application using the official scaffolding tool:

# Create directory for your Backstage installation
mkdir -p ~/backstage-setup
cd ~/backstage-setup

# Create a new Backstage app (this takes a few minutes)
npx @backstage/create-app@latest

# You'll be prompted for:
# - Application name: my-backstage-portal
# - Database type: SQLite (for development) or PostgreSQL (for production)

# Navigate into your new Backstage app
cd my-backstage-portal

# Install all dependencies
yarn install

# This will take several minutes to download and install all packages

Great! Your Backstage application is created! 🎭

✅ Step 4: Configure Basic Settings

Let’s configure Backstage with your organization details:

# Edit the app configuration file
cat > app-config.yaml << 'EOF'
app:
  title: My Company Developer Portal
  baseUrl: http://localhost:3000

organization:
  name: My Company

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  csp:
    connect-src: ["'self'", 'http:', 'https:']
  cors:
    origin: http://localhost:3000
    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
    credentials: true
  database:
    client: better-sqlite3
    connection: ':memory:'

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}  # We'll set this later

techdocs:
  builder: 'local'
  generator:
    runIn: 'local'
  publisher:
    type: 'local'

auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

scaffolder:
  github:
    token: ${GITHUB_TOKEN}
    visibility: public

catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location]
  locations:
    # Local example components
    - type: file
      target: ./examples/entities.yaml

    # Example GitHub discovery
    - type: url
      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all.yaml

    # Example template
    - type: url
      target: https://github.com/backstage/software-templates/blob/main/scaffolder-templates/react-ssr-template/template.yaml
      rules:
        - allow: [Template]
EOF

# Create example entities file
mkdir -p examples
cat > examples/entities.yaml << 'EOF'
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-website
  title: My Company Website
  description: Company marketing website built with React
  annotations:
    github.com/project-slug: mycompany/website
  tags:
    - react
    - website
    - frontend
  links:
    - url: https://my-company.com
      title: Production Site
    - url: https://staging.my-company.com  
      title: Staging Site
spec:
  type: website
  lifecycle: production
  owner: frontend-team
  system: public-websites

---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  title: User Management Service
  description: RESTful API for user authentication and management
  annotations:
    github.com/project-slug: mycompany/user-service
  tags:
    - api
    - nodejs
    - backend
spec:
  type: service
  lifecycle: production
  owner: backend-team
  system: core-platform
  providesApis:
    - user-api

---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: user-api
  title: User Management API
  description: REST API for user operations
spec:
  type: openapi
  lifecycle: production
  owner: backend-team
  system: core-platform
  definition:
    $text: |
      openapi: 3.0.0
      info:
        title: User API
        version: 1.0.0
      paths:
        /users:
          get:
            summary: List users
            responses:
              200:
                description: List of users
EOF

Your Backstage configuration is now ready! 🛠️

🔧 Step 5: Start Backstage Development Server

Let’s launch your Backstage portal:

# Start the development server (this runs both frontend and backend)
yarn dev

# This will start:
# - Backend server on port 7007
# - Frontend React app on port 3000

# Wait for both servers to start (takes 2-3 minutes)
# You'll see messages like:
# - "webpack compiled with 0 errors"  
# - "Backend started on port 7007"

Amazing! Your Backstage portal is now running! 🚀

Open your browser and visit: http://your-server-ip:3000 to see the beautiful Backstage interface! ✨

🌟 Step 6: Set Up GitHub Integration

Let’s integrate with GitHub to make Backstage really powerful:

# Stop the development server (Ctrl+C)

# Create a GitHub personal access token at:
# https://github.com/settings/tokens/new
# Select these scopes: repo, workflow, write:packages, read:packages

# Set environment variables for GitHub integration
cat >> ~/.bashrc << 'EOF'
export GITHUB_TOKEN="your_github_token_here"
export AUTH_GITHUB_CLIENT_ID="your_github_oauth_client_id"
export AUTH_GITHUB_CLIENT_SECRET="your_github_oauth_client_secret"
EOF

# Reload environment
source ~/.bashrc

# For GitHub OAuth (optional but recommended):
# 1. Go to GitHub Settings > Developer settings > OAuth Apps
# 2. Create new OAuth App with:
#    - Homepage URL: http://your-server:3000
#    - Callback URL: http://your-server:3000/api/auth/github/handler

# Restart Backstage with GitHub integration
yarn dev

Now you have GitHub integration with authentication! 🔗

🎮 Quick Examples

Let’s try some practical examples to see Backstage’s capabilities! 🚀

Example 1: Create a Software Template

# Create a custom template for new microservices
mkdir -p templates/microservice-template
cd templates/microservice-template

# Create template.yaml
cat > template.yaml << 'EOF'
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: microservice-template
  title: Node.js Microservice Template
  description: Create a new Node.js microservice with best practices
  tags:
    - nodejs
    - microservice
    - backend
spec:
  owner: platform-team
  type: service

  parameters:
    - title: Service Information
      required:
        - name
        - description
      properties:
        name:
          title: Name
          type: string
          description: Unique name for the microservice
          pattern: '^[a-zA-Z0-9-]+$'
        description:
          title: Description
          type: string
          description: What does this service do?
        owner:
          title: Owner
          type: string
          description: Team responsible for this service
          default: backend-team

  steps:
    - id: fetch-base
      name: Fetch Base Template
      action: fetch:template
      input:
        url: ./content
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}

    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        allowedHosts: ['github.com']
        description: ${{ parameters.description }}
        repoUrl: github.com/mycompany/${{ parameters.name }}
        defaultBranch: main

    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: '/catalog-info.yaml'

  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}
      - title: Open in catalog
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}
EOF

# Create template content
mkdir -p content
cat > content/catalog-info.yaml << 'EOF'
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name }}
  title: ${{ values.name | title }}
  description: ${{ values.description }}
  annotations:
    github.com/project-slug: mycompany/${{ values.name }}
  tags:
    - nodejs
    - microservice
spec:
  type: service
  lifecycle: experimental
  owner: ${{ values.owner }}
EOF

cat > content/package.json << 'EOF'
{
  "name": "${{ values.name }}",
  "version": "1.0.0",
  "description": "${{ values.description }}",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "nodemon": "^3.0.1",
    "jest": "^29.0.0"
  }
}
EOF

cat > content/index.js << 'EOF'
const express = require('express');
const app = express();
const port = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.json({
    service: '${{ values.name }}',
    description: '${{ values.description }}',
    status: 'healthy',
    timestamp: new Date().toISOString()
  });
});

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(port, () => {
  console.log(`${{ values.name }} listening on port ${port}`);
});
EOF

# Update app-config.yaml to include your template
cat >> ../../app-config.yaml << 'EOF'

    - type: file
      target: ./templates/microservice-template/template.yaml
      rules:
        - allow: [Template]
EOF

Now you have a custom software template for creating microservices! 🏗️

Example 2: Set Up TechDocs Documentation

# Go back to your Backstage root directory
cd ~/backstage-setup/my-backstage-portal

# Install TechDocs dependencies
pip3 install mkdocs-techdocs-core

# Create a documentation example
mkdir -p docs
cat > docs/index.md << 'EOF'
# Welcome to My Company Developer Portal

## What is this portal?

This is our centralized developer portal built with Backstage. Here you can:

- 🔍 Discover all our services and APIs
- 📚 Access up-to-date documentation
- 🚀 Create new projects from templates
- 🔗 Find links to all development tools

## Quick Start

### For New Developers

1. Browse the [Software Catalog](/catalog) to see all our services
2. Check out our [Software Templates](/create) to start new projects
3. Read the [API Documentation](/docs) for integration guides

### For Platform Engineers

1. Add your services to the catalog with `catalog-info.yaml`
2. Create templates for common patterns
3. Set up monitoring and alerting integrations

## Need Help?

- 💬 Join our Slack channel: #developer-platform
- 📧 Email: [email protected]
- 🐛 Report issues: [GitHub Issues](https://github.com/mycompany/backstage)
EOF

cat > mkdocs.yml << 'EOF'
site_name: 'My Company Developer Portal'
site_description: 'Developer documentation and guides'

nav:
  - Home: index.md

plugins:
  - techdocs-core

markdown_extensions:
  - admonition
  - codehilite
  - pymdownx.superfences
EOF

# Update your component to use TechDocs
cat >> examples/entities.yaml << 'EOF'

---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: developer-portal
  title: Developer Portal Documentation
  description: Central documentation for our developer platform
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: documentation
  lifecycle: production
  owner: platform-team
EOF

Your documentation is now integrated with Backstage! 📚

Example 3: Add Monitoring Dashboard Plugin

# Install a popular plugin for monitoring integration
yarn add --cwd packages/app @backstage/plugin-prometheus

# Add to your frontend app
cat >> packages/app/src/App.tsx << 'EOF'
// Add this import at the top
import { PrometheusPage } from '@backstage/plugin-prometheus';

// Add this route in your routes section
<Route path="/prometheus" element={<PrometheusPage />} />
EOF

# Configure Prometheus integration in app-config.yaml
cat >> app-config.yaml << 'EOF'

prometheus:
  proxyPath: /prometheus/api
  uiUrl: 'http://localhost:9090'
  serviceUrl: 'http://prometheus-server:9090'
EOF

Now you have monitoring integration in your developer portal! 📊

🚨 Fix Common Problems

Here are solutions to the most common Backstage issues you might encounter:

Problem 1: Build Failures or Dependencies Issues 🔧

Symptoms: “Module not found” or compilation errors

Solutions:

# Clear all caches and reinstall dependencies
rm -rf node_modules yarn.lock packages/*/node_modules
yarn cache clean
yarn install

# If using Node.js 18+, you might need legacy OpenSSL
export NODE_OPTIONS="--openssl-legacy-provider"

# Update all Backstage packages to latest versions
yarn backstage:versions:bump
yarn install

Problem 2: GitHub Integration Not Working 🔗

Symptoms: Can’t fetch repositories or authentication failures

Solutions:

# Verify your GitHub token has correct permissions
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

# Check required scopes: repo, workflow, write:packages, read:packages
# Update token permissions at: https://github.com/settings/tokens

# Test GitHub integration
yarn backstage:fetch:github --repo mycompany/myrepo

Problem 3: TechDocs Not Generating 📚

Symptoms: Documentation pages showing “Failed to build” or 404 errors

Solutions:

# Install missing Python dependencies
pip3 install mkdocs-techdocs-core

# Verify mkdocs.yml is valid
mkdocs serve --config-file mkdocs.yml

# Check TechDocs configuration in app-config.yaml
# Make sure techdocs.builder is set to 'local'

# Clear TechDocs cache
rm -rf ~/.cache/techdocs

Problem 4: High Memory Usage 💾

Symptoms: Development server using excessive RAM or crashing

Solutions:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"

# Use production build for lower memory usage
yarn tsc
yarn build:backend
yarn build:frontend

# Run in production mode
NODE_ENV=production yarn start:backend &
NODE_ENV=production yarn start:frontend

📋 Simple Commands Summary

Here’s your quick reference guide for Backstage:

💡 Tips for Success

Here are some pro tips to get the most out of Backstage! 🌟

🎯 Start with Service Catalog: Begin by cataloging your existing services - this provides immediate value and helps teams discover what’s available.

⚡ Use Software Templates: Create golden path templates for your common patterns (microservices, libraries, documentation sites) to standardize and speed up development.

📊 Integrate Everything: Connect Backstage to your existing tools (CI/CD, monitoring, security scanning) to create a true single pane of glass.

🔍 Implement Search: Configure search to index your services, documentation, and tools - developers will use this feature constantly.

💾 Plan Your Database: Switch from SQLite to PostgreSQL for production deployments to handle multiple users and better performance.

🚀 Customize the UI: Use your company’s branding, colors, and logo to make the portal feel like home for your developers.

🔗 Create API Documentation: Use the OpenAPI plugin to automatically generate and maintain API documentation from your service definitions.

🛡️ Set Up Authentication: Implement proper authentication with your identity provider (GitHub, Google, LDAP, SAML) for security and personalization.

🏆 What You Learned

Congratulations! You’ve successfully mastered Backstage Developer Portal! 🎉 Here’s everything you accomplished:

✅ Installed and configured Backstage on AlmaLinux 9 with Node.js and Yarn
✅ Set up service catalog with components, APIs, and systems
✅ Created software templates for standardized project creation
✅ Integrated with GitHub for repository discovery and OAuth authentication
✅ Configured TechDocs for centralized documentation management
✅ Added monitoring plugins for observability integration
✅ Built custom templates for microservice scaffolding
✅ Learned troubleshooting and performance optimization techniques
✅ Mastered production deployment strategies and best practices

🎯 Why This Matters

Backstage transforms the developer experience from chaos to clarity! 🚀 You can now:

🎭 Unify Developer Tools: Provide a single interface for all development tools, reducing context switching and improving productivity
📚 Centralize Knowledge: Keep documentation, APIs, and service information in one discoverable location
🏗️ Standardize Development: Use templates and golden paths to ensure consistency across teams and projects
🔍 Improve Discoverability: Help developers find services, APIs, and documentation quickly without asking around
⚡ Accelerate Onboarding: New team members can get up to speed faster with centralized information and self-service capabilities
📊 Gain Visibility: Get insights into your software ecosystem and identify improvement opportunities

You now have the skills to implement and manage a world-class developer portal that’s used by companies like Spotify, Netflix, and thousands of other organizations. Platform engineering and developer experience roles are in high demand, and Backstage expertise makes you incredibly valuable! ⭐

Keep building, keep improving, and remember - a great developer portal is the foundation of an exceptional engineering culture! 🙌✨