Learn Backstage - Production Deployment & Adoption

#Introduction

Episode 20 made your Backstage transparent — every signal can be seen and monitored. Episode 21 takes it out of development and into a real environment. Here you'll learn the operational and cultural side: wrapping Backstage into a Docker image, deploying with a Helm chart on Kubernetes, setting up a CI/CD pipeline, keeping backups and restores, managing a weekly upgrade strategy with backstage-cli versions:bump, then closing with an adoption playbook so teams actually use the platform.

#Setting Up the Deployment

Before deploying, choose the deployment model that best fits your infrastructure:

Of the three, the Helm-on-Kubernetes combination is the most common choice for production Backstage deployments.

#The Docker Image

Backstage can be wrapped with a Docker multi-stage build: the build stage prepares dependencies and output, the runtime stage contains only the build results and production runtime:

FROM node:20-bookworm-slim AS build
WORKDIR /app
COPY package.json ./
COPY packages ./packages
RUN yarn install --frozen-lockfile --network-timeout 600000
RUN yarn backstage-cli repo build
 
FROM node:20-bookworm-slim
WORKDIR /app
COPY --from=build /app/packages/backend/dist ./packages/backend/dist
ENV NODE_ENV=production
EXPOSE 7007
CMD ["node", "packages/backend"]

The resulting image is small and contains only what the runtime needs. Tag the image with a release version — not just latest — so rollback is always possible.

#Helm Chart on Kubernetes

Backstage provides an official Helm chart in the backstage/charts repository. With the chart, deployment, service, ingress, and database connections are managed declaratively. A typical set of values:

backstage:
  image:
    repository: registry.internal/backstage
    tag: 1.53.0
  replicaCount: 3
  appConfig:
    app:
      baseUrl: https://backstage.example.com
    backend:
      baseUrl: https://backstage.example.com
      database:
        client: pg
        connection:
          host: postgres.internal
          password: ${POSTGRES_PASSWORD}
 
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: backstage.example.com

Secret configuration like the database password should come from Kubernetes Secrets or vault, not be written raw in the chart. Deploying:

helm repo add backstage https://backstage.github.io/charts
helm repo update
helm upgrade --install backstage backstage/backstage \
  --namespace backstage \
  --values values.yaml

#CI/CD Pipeline

A good CI/CD pipeline moves changes from commit to production automatically and audibly. The flow is roughly:

stages:
  - lint
  - test
  - build
  - docker-push
  - helm-upgrade
  - smoke-test

The order: lint and test run first to catch errors, then the image is built and pushed to the registry, followed by helm upgrade --install to staging, and finally a smoke test to confirm the new instance is healthy before promoting to production.

#Backup and Restore

Backstage's most valuable state lives in PostgreSQL: catalog entities, plugin data, and sessions. Source entities live in git repositories, but runtime data still needs backing up.

A sensible backup strategy:

• Regular database backups — dump PostgreSQL at an agreed interval.
• Configuration backups — store config files, chart values, and Secrets as code.
• Practice restores — test the restore procedure periodically, not only during a disaster.

Example database backup:

pg_dump -h postgres.internal -U backstage -d backstage \
  -F custom -f backstage-$(date +%Y%m%d).dump

#Upgrade Strategy

Backstage releases weekly — a new version every week. Following releases regularly is the safest way to maintain security and compatibility. The key tool is backstage-cli versions:bump, which updates all Backstage dependencies to the latest version consistently.

backstage-cli versions:check
backstage-cli versions:bump

The recommended strategy:

• Check the release and changelog before bumping.
• Run versions:bump on a separate branch and test on staging first.
• Set a cadence — for example every two weeks — so the gap between upgrades doesn't widen.
• Handle security fixes as soon as possible, not by waiting for the next schedule.

#The Adoption Playbook

Deployment is only half the work. The other half is making teams willing and able to use Backstage.

#The First Golden Path

Start with a golden path: one standard route desired for all new services. Realize it as a scaffolder template that includes ownership, documentation, CI, and correct security defaults. When the golden path is used, quality rises without being forced — because the correct path is the easiest one.

#Onboarding Teams

Onboarding isn't done with a single email. Prepare internal documentation, short workshops, and real examples. Appoint a champion per team who can answer early questions and act as a bridge to the platform team. The sooner teams feel the benefit — creating a new service in minutes — the faster adoption grows.

#Measuring Adoption

What isn't measured can't be improved. Some practical metrics:

• The number of registered entities and those with active owners.
• Scaffolder usage: how many templates are used, how many services are created per month.
• Search and TechDocs usage: how many searches and documentation reads.
• Analytics events (from episode 20) to see real usage flows.

#The Internal Platform Roadmap

Platform engineering isn't a once-and-done project. Put together a clear internal roadmap — the next golden path, new plugins, security integrations, and UX improvements — with real owners and deadlines. This roadmap is what keeps the platform alive and relevant as the organization grows.

#Conclusion

In this episode 21, you understood production Backstage deployment: the multi-stage Docker image, the Helm chart on Kubernetes, the CI/CD pipeline, database backup and restore, and the weekly upgrade strategy with backstage-cli versions:bump. You also learned the adoption playbook: the first golden path, team onboarding, measuring adoption, and the internal platform roadmap.

The key takeaways:

• Helm on Kubernetes is the production default — declarative, scalable, and reproducible.
• Backup and restore must be tested — a backup never restored is just hope.
• Small, regular upgrades win — follow the weekly releases with backstage-cli versions:bump so nothing piles up.
• Adoption is cultural work — golden path, onboarding, and measurement make the platform actually used.

In episode 22, the final episode of this series, we look ahead: the modern ecosystem & final reflection. You'll get to know Backstage 2026 features like the default New Frontend System and MCP integration for AI agents, compare Backstage with commercial alternatives, recap the whole journey from episodes 0 to 21, and put together a production-grade checklist for your platform.