What It Is and Why You Need It

• Your codebase: Who owns what? What's the tech stack?

• Your services: Is the API running? How is it performing?

• Your infrastructure: What cluster is this service deployed to?

• Your company's knowledge: A centralised place for documentation, how-to guides, and runbooks.

• Your automated processes: Best of all, A simple UI to spin up a new microservice, create a new cloud resource, or onboard a new hires, offloading or speeding up work from your platform team.

Pros and Cons

• Offloads repetitive tasks from platform engineers: Your senior engineers will thank you for giving them back their time. Backstage automates the "grunt work" like creating new repos or setting up CI/CD pipelines.

• Batteries included: Backstage comes with core components like a software catalog, documentation system, UI components (MaterialUI) and software templates.

• Enforces standards and best practices: It's easier to ensure every new service adheres to company-wide standards when the "easy button" to create one is a Backstage template that already has everything configured.

• Requires full-stack web development skills: This isn't just a configuration project. Backstage is a React/Node.js application. To create advanced, custom features, you need a team with frontend and backend development experience.

• Large upfront investment: Getting a full-fledged IDP off the ground takes time and dedicated resources. It's a long-term strategic investment, not a quick fix.

• ‘Just another standard’ risk: If not integrated well or holistically, it can lead to just another tool to maintain that doesn’t really solve it’s core problem.

Getting Started: Test On Your Local

1. Pull the code into your desired repo:

# Use NodeJS 20 or above!
npx @backstage/create-app

1. Install and run

yarn install

yarn dev

# Access on localhost:3000

• App.tsx: This is your main React component. It's the file where you configure what plugins and layouts your users see. If you want to add a new page or change the main navigation, this is where you do it.

• app-config.yaml: This is the main configuration file for your Backstage instance. It defines everything from the application's title to connections for different plugins. Make sure you genuinely understand this one

• app-config.production.yaml: A key concept to grasp is configuration overrides. This file is loaded in a production environment and will override any settings in app-config.yaml. If something is used for local and prod, put it in app-config.yaml

Deploying Backstage CI/CD

1. Dockerize Everything: Dockerize both the Backstage frontend and backend as separate images. While you could run them as a single image, separating them simplifies scaling and debugging.

# Frontend

FROM node:20-bookworm as build

WORKDIR /app

# This will save you a bunch of headaches
ENV NODE_OPTIONS="--no-node-snapshot"

COPY package.json yarn.lock ./

RUN yarn install --frozen-lockfile

COPY packages/ packages/

RUN yarn --cwd packages/app/ build

FROM node:20-bookworm

COPY --from=build /app/packages/app/build /usr/share/nginx/html

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

# Backend

FROM node:20-bookworm

WORKDIR /app

# This will save you a bunch of headaches
ENV NODE_OPTIONS="--no-node-snapshot"

COPY package.json yarn.lock ./

# Install dependencies
RUN yarn install --frozen-lockfile

COPY packages/backend/ packages/backend/
COPY plugins/ plugins/

RUN yarn --cwd packages/backend/ build

EXPOSE 7007

CMD ["node", "packages/backend", "--config", "app-config.yaml"]

1. Build with GitHub Actions: Set up a GitHub Actions workflow to automatically build and push these Docker images to a container registry like AWS Elastic Container Registry (ECR) on git pushes. Use the Git SHA as the image tag to ensure immutability and easy rollbacks. This is assuming you have a github repo storing your Backstage code and you have an AWS ECR ready, here’s a guide for that: https://spacelift.io/blog/terraform-ecr

name: Build and Push Docker Images

on:
  push:
    branches:
      - main

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Login to ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v1

      - name: Build and push backend image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: backstage-backend
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

      - name: Build and push frontend image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: backstage-frontend
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -f Dockerfile.frontend -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

1. GitOps with ArgoCD: This is the core of your deployment strategy. ArgoCD is a declarative GitOps tool that ensures the state of your Kubernetes cluster always matches the state defined in a Git repository.
First, you need to set up your EKS cluster with ArgoCD. For a great guide on how to do this, check out this article: https://aws.plainenglish.io/gitops-made-easy-automate-kubernetes-deployments-with-argo-cd-on-aws-eks-02dbd37b4a0b

# Helm chart

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: backstage-{{ $name }}
  namespace: argocd
spec:
  project: default
  source:
    repoURL: {{ $app.source.repoURL }}
    targetRevision: {{ $app.source.targetRevision }}
    path: {{ $app.source.path }}
    helm:
      values: |
        {{- $app.values | toYaml | nindent 8 }}
  destination:
    server: {{ $.Values.destination.server }}
    namespace: {{ $app.destination.namespace }}
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
{{- end }}

# values.yaml

destination:
  server: 'https://kubernetes.default.svc'

applications:
  backstage-backend:
    source:
      repoURL: 'https://github.com/your-org/backstage-app.git' # The original Backstage application repo
      targetRevision: main
      path: 'k8s/helm-chart/backstage-backend' # Path to a separate backend helm chart
    destination:
      namespace: backstage
    values:
      image:
        repository: 1234567890.dkr.ecr.us-east-1.amazonaws.com/backstage-backend # Your ECR registry
        tag: 'my-image-12345' # This is where the backend image tag is updated
      resources:
        requests:
          cpu: 100m
          memory: 256Mi
        limits:
          cpu: 250m
          memory: 512Mi
      env:
        - name: DATABASE_HOST
          value: 'backstage-db-host' # The hostname of your PostgreSQL DB you'll deploy later
        - name: DATABASE_PORT
          value: '5432'
      secrets:
        - name: GITHUB_TOKEN
          secretKey: github_token
  
  backstage-frontend:
    source:
      repoURL: 'https://github.com/your-org/backstage-app.git'
      targetRevision: main
      path: 'k8s/helm-chart/backstage-frontend'
    destination:
      namespace: backstage
    values:
      image:
        repository: 1234567890.dkr.ecr.us-east-1.amazonaws.com/backstage-frontend
        tag: 'my-image-4567' # This is where the frontend image tag is updated
      ingress:
        enabled: true
        host: backstage.your-company.com

1. Last Cloud resources: You'll need a few other pieces of infrastructure to make Backstage production-ready, I recommend doing all of this with Terraform IaC.
• PostgreSQL Database: While Backstage can run on an in-memory database locally, for any production use, you need a persistent, reliable database. A managed service like AWS RDS is a great option. Start with a really small instance since you can always scale up later.
• Load Balancer and Ingress: To expose your Backstage frontend and backend services to the internet, you need a load balancer. You have a few options:
• One for the cluster: A single load balancer for the entire cluster (e.g., an AWS Application Load Balancer) is cheaper but can be more complex to manage, especially if you have many different services.
• One per pod with Ingress: A better approach is to use an Ingress Controller (like the AWS Load Balancer Controller) that can automatically provision a new load balancer for each service or manage a single, shared load balancer with intelligent routing.
• DNS: You'll need a DNS record pointing to your load balancer so users can access Backstage via a human-readable URL (e.g., backstage.your-company.com).
• Secret Management Kubernetes secrets are a "gotcha" waiting to happen. If a secret changes, you have to restart the pod for the change to take effect. This is a mess. The Fix: Use the External Secrets Operator (ESO). It's a Kubernetes operator that fetches secrets from a dedicated secrets manager (like AWS Secrets Manager) and injects them as environment variables or files directly into your pods. This means when a secret changes, EOSO automatically updates it in the pod, no redeployment or downtime required. Learn more here: https://external-secrets.io/latest/

1. Authentication and User Management
Backstage is an IDP, so knowing who is using it is critical, you’ll likely already have a github org setup with various permissions and accesses so let’s leverage that and SSO login
• GitHub App for SSO: Backstage has a robust authentication system with many providers. If your organization uses GitHub Enterprise, setting up a GitHub App for SSO is a powerful way to authenticate users and scrape existing permissions (e.g., team memberships). This requires a GitHub Enterprise license.
• Alternative: If you're not on GitHub Enterprise, you can authenticate users in any way you like, with plugins for other identity providers or nothing at all if you swing that way

Developing the Backstage App

Workflow Types: A Common Confusion

1. Software Templates (The "Fire-and-Forget" Approach)
• What they are: These are YAML-based templates that use the Scaffolder plugin to run a series of steps. They're ideal for "one-way" operations like creating a new GitHub repository, setting up a CI pipeline, or provisioning cloud infrastructure.
• How they work: A user fills out a form in the Backstage UI (Backstage provides all this for you). The Scaffolder takes that input and executes a YAML workflow. The workflow might call a GitHub Action, a Terraform script, or an external API. The user gets a simple success or failure message and can then move on.
• Best for: Tasks where the outcome is predictable, and you don't need real-time feedback or complex user interaction. Think of it as hitting "send" on a well-crafted email.
• Trap: It’s very quick to setup and you may feel encouraged to perform all sorts of tasks this way. It’s good if you need quick deployments but it’s hard to scale and manage after a certain point

2. Custom Plugins (The "Interactive" Approach)
• What they are: These are full-fledged frontend and backend extensions. You can build a complete UI, handle complex state, and get real-time feedback from the user.
• How they work: You use the Backstage CLI to create new frontend and backend modules. The frontend plugin might display a wizard-like form, while the backend handles the complex business logic, routing and talks to various services. The user gets a dynamic, responsive experience.
• Best for: Complex, multi-step workflows or business operations that require a custom UI and more user interaction. For example, an onboarding process where you need to check multiple systems, fetch data throughout the process or a custom deployment dashboard.
• Trap: This will require web dev skills (React) which not all platform engineers will have or have to a level that they can confidently build and maintain such a system

Creating Your First Software Template

1. Scaffolder Frontend: Already part of the default application.

2. Scaffolder Backend: Handles the execution of the template steps.

3. GitHub Integration: You need to configure Backstage to talk to GitHub.

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN} 
      # Optional: set a separate PAT for the Scaffolder to use (must have repo/workflow scope)
      proxy:
        /scaffolder-github-action:
          target: https://api.github.com
          headers:
            Authorization: 'Bearer ${GITHUB_ACTIONS_TOKEN}'

apiVersion: backstage.io/v1alpha1
kind: Template
metadata:
  name: github-repo-starter
  title: GitHub Repository Starter
  description: Creates a new GitHub repository with a basic boilerplate.
  tags:
    - github
    - starter
    - repository
spec:
  owner: user:guest
  type: service # Define the type of entity this template creates

  parameters:
    - title: Repository Details
      required:
        - repoName
        - repoDescription
        - owner
      properties:
        repoName:
          title: Repository Name
          type: string
          description: The name of the new repository (e.g., my-new-service).
          ui:autofocus: true
        repoDescription:
          title: Repository Description
          type: string
          description: A short description for the GitHub repository.
        owner:
          title: Repository Owner/Team
          type: string
          description: The GitHub owner or team that will manage this repo (e.g., engineering-team).
          ui:field: OwnerPicker # Backstage helper for picking registered teams/users

  steps:
    - id: create-repo
      name: Create GitHub Repository
      action: github:repo:create
      input:
        repoUrl: "github.com?repo={{ parameters.repoName }}&owner={{ parameters.owner }}"
        description: "{{ parameters.repoDescription }}"
        visibility: public # or private, internal

    - id: checkout-repo-content
      name: Fetch Skeleton Code
      action: fetch:template
      input:
        url: ./skeleton
        targetPath: ./tmp-repo

    - id: publish-to-github
      name: Push Initial Code
      action: publish:github
      input:
        repoUrl: "github.com?repo={{ parameters.repoName }}&owner={{ parameters.owner }}"
        sourcePath: ./tmp-repo
        branchName: main
        commitMessage: "Initial commit of generated repository structure"

  output:
    remoteUrl: '{{ steps.create-repo.output.remoteUrl }}'
    entityRef: 'template:default/{{ parameters.repoName }}'

Creating Your First Custom Plugin (Frontend UI and Backend Endpoint)

1. Frontend (React): The user interface (UI) where the user interacts.

2. Backend (Node.js/Express): The API that handles communication with external systems (like GitHub's API) and business logic.

• plugins/github-onboarder (Frontend)

• plugins/github-onboarder-backend (Backend)

import { Router } from 'express';
import { Logger } from 'winston';
import { Config } from '@backstage/config';

export interface RouterOptions {
  logger: Logger;
  config: Config;
}

export async function createRouter(
  options: RouterOptions,
): Promise<Router> {
  const { logger, config } = options;
  const router = Router();
  router.use(require('cookie-parser')());
  router.use(require('express-urlrewrite')('/github-onboarder/api'));
  router.use(require('body-parser').json());

  the external GitHub API proxy
  const githubApiUrl = 'https://api.github.com';

  router.get('/check-user', async (req, res) => {
    const { username } = req.query;
    logger.info(`Checking existence of GitHub user: ${username}`);
    
   
    if (username === 'existing-dev') {
      res.status(200).send({ exists: true, message: `User ${username} is already an active member.` });
    } else if (username === 'new-hire') {
      res.status(200).send({ exists: false, message: `User ${username} not found. Please fill out the onboarding form.` });
    } else {
       res.status(200).send({ exists: false, message: `User ${username} not found. Please fill out the onboarding form.` });
    }
  });

  router.post('/onboard', async (req, res) => {
    const { username, email, team } = req.body;
    logger.info(`Starting onboarding process for ${username} to team ${team}`);
    
    res.status(201).send({ success: true, message: `Onboarding process started for ${username}. A ticket has been created.` });
  });

  return router;
}
```

# packages/backend/src/index.ts

import { createRouter as createGithubOnboarderRouter } from '@internal/plugin-github-onboarder-backend';

async function main() {
  const logger = root.child({ scope: 'backend' });
  const apiRouter = Router();
  apiRouter.use('/github-onboarder', await createGithubOnboarderRouter({ logger, config }));
}

main().catch(error => {
  logger.error('Backend failed to start', error);
  process.exit(1);
});

import React, { useState } from 'react';
import { 
  Content, 
  Header, 
  Page, 
  HeaderContent, 
  Progress, 
  Alert 
} from '@backstage/core-components';
import { useApi, configApiRef } from '@backstage/core-plugin-api';
import { Button, TextField, Box, Card, CardContent, Typography } from '@material-ui/core';

export const OnboarderComponent = () => {
  const [username, setUsername] = useState('');
  const [email, setEmail] = useState('');
  const [team, setTeam] = useState('');
  const [status, setStatus] = useState<'idle' | 'checking' | 'onboarding'>('idle');
  const [result, setResult] = useState<{ message: string; exists?: boolean; success?: boolean } | null>(null);

  const configApi = useApi(configApiRef);
  const baseUrl = configApi.getString('backend.baseUrl') + '/github-onboarder';

  const handleCheckUser = async () => {
    setStatus('checking');
    setResult(null);

    try {
      const response = await fetch(`${baseUrl}/check-user?username=${username}`);
      const data = await response.json();
      setResult(data);
    } catch (error) {
      setResult({ message: 'Error checking user status.', exists: false });
    } finally {
      setStatus('idle');
    }
  };

  const handleOnboardUser = async () => {
    setStatus('onboarding');
    setResult(null);

    try {
      const response = await fetch(`${baseUrl}/onboard`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ username, email, team }),
      });
      const data = await response.json();
      setResult(data);
    } catch (error) {
      setResult({ success: false, message: 'Failed to initiate onboarding workflow.' });
    } finally {
      setStatus('idle');
    }
  };

  const showForm = result?.exists === false;
  const isChecking = status === 'checking';
  const isSubmitting = status === 'onboarding';

  return (
    <Page themeId="tool">
      <Header title="GitHub Onboarder" subtitle="Quickly onboard new developers to GitHub">
        <HeaderContent />
      </Header>
      <Content>
        <Card>
          <CardContent>
            <Typography variant="h5" component="h2" gutterBottom>
              Check User Status
            </Typography>
            <Box mb={2}>
              <TextField
                label="GitHub Username"
                fullWidth
                value={username}
                onChange={(e) => setUsername(e.target.value)}
                disabled={isChecking}
              />
            </Box>
            <Button 
              variant="contained" 
              color="primary" 
              onClick={handleCheckUser}
              disabled={!username || isChecking}
            >
              {isChecking ? <Progress size={20} /> : 'Check User'}
            </Button>

            {result && (
              <Box mt={3}>
                <Alert severity={result.exists ? 'success' : 'info'}>
                  {result.message}
                </Alert>
              </Box>
            )}

            {showForm && (
              <Box mt={4} p={3} style={{ border: '1px solid #ccc', borderRadius: '4px' }}>
                <Typography variant="h6" gutterBottom>
                  Onboarding Request Form
                </Typography>
                <TextField
                  label="Email Address"
                  fullWidth
                  margin="normal"
                  value={email}
                  onChange={(e) => setEmail(e.target.value)}
                />
                <TextField
                  label="Target Team (e.g., 'platform-engineering')"
                  fullWidth
                  margin="normal"
                  value={team}
                  onChange={(e) => setTeam(e.target.value)}
                />
                <Button 
                  variant="contained" 
                  color="secondary" 
                  onClick={handleOnboardUser}
                  disabled={isSubmitting || !email || !team}
                  style={{ marginTop: '16px' }}
                >
                  {isSubmitting ? <Progress size={20} /> : 'Submit Onboarding Request'}
                </Button>
              </Box>
            )}
          </CardContent>
        </Card>
      </Content>
    </Page>
  );
};

# packages/app/src/App.tsx

import { githubOnboarderPlugin, GithubOnboarderPage } from '@internal/plugin-github-onboarder';

const routes = (
  <FlatRoutes>
    <Route path="/github-onboarder" element={<GithubOnboarderPage />} />
  </FlatRoutes>
);

const navItem = (
  <SidebarItem icon={AssignmentIndIcon} to="github-onboarder" text="GitHub Onboarder" />
);

# If you want the page added to the Navbar
const sidebar = (
  <Sidebar>
    {navItem} 
  </Sidebar>
);