Module 00 · Orientation · 20 min · You are: Platform and product

Orientation: how to think about Backstage

Most people meet Backstage as a website: a catalog, a Create button, some docs. That hides the most important fact: Backstage is a framework. Your platform team owns a TypeScript app built with it, and the portal is only as good as the data in its catalog. In this course you play the platform team, who build and run the portal, and team-checkout, a product team that uses it.

Open this module in the interactive course to track progress.

Concepts

A framework, not a product

@backstage/create-app generates a monorepo: a React frontend and a Node backend. You own it, upgrade it and ship it like any other service.

The catalog is the product

Every feature hangs off the Software Catalog: who owns what, what depends on what. A wrong catalog makes every page wrong.

Git is the source

Teams describe their software in catalog-info.yaml next to their code. The portal reads it; it does not own it.

Config before code

Most behaviour is app-config.yaml: where the catalog reads from, how people sign in. Code is for what config cannot do.

This course and the next

Here you run a portal and use its core features. Backstage plugin development then builds frontend and backend plugins in the same app.

Who owns what in this course

The platform team owns the portal. Product teams own the facts about their own software.

Files to know

Where you are heading, in five minutes. These pages summarise Backstage and link to backstage.io for the detail. Click Quick look on each: it opens the real file right here, with numbered circles on the lines that matter.

Open them in your editor or on GitHub; the bullets say what to look at.

• docs/mental-model.md (reference, your repo): How to think about Backstage, in one page.
  1. The one idea to get right first L6–11
  2. The main parts, each with a link to the official docs L15–22
  3. How to work with it day to day L24–34
• docs/architecture.md (reference, your repo): The pieces of a Backstage app and how they talk.
  1. One frontend, one backend process, many plugins L6–10
  2. Where each piece lives in the repo L13–19
  3. Ports 3000 and 7007: you will see both today L21–23
• README.md (reference, your repo): The map of the reference repo.
  1. The folders, and who owns each L10–17
  2. Every version is pinned, and how it gets bumped L21–28
  3. What the course simplifies on purpose L51–55

Steps

1. Tell the course who you are

Your GitHub user (or organisation) and a folder for your repos and the reference clone. Every command and link uses them. They stay in your browser.

Set your GitHub user and workspace folder in the interactive course or the form at the top of the notes index; these notes then show your values.

2. Check your tools

Paste this into a terminal. Each tool reports ok (with its version), MISSING (with where to get it) or PROBLEM (installed but not usable yet, like Docker not running or gh not logged in). Install what is missing, then run it again until it says All set. Node.js must be 22 or 24. Any Yarn works: the app brings its own Yarn 4. Give Docker at least 4 GB of memory: building the image in module 09 needs it.

check() {  # tool, works-check, version, problem, where-to-get-it, optional
  if ! command -v "$1" >/dev/null 2>&1; then
    if [ -n "$6" ]; then printf '  optional  %-22s not installed (%s)\n' "$1" "$5"
    else printf '  MISSING   %-22s install it: %s\n' "$1" "$5"; bad=$((bad+1)); fi
  elif ! eval "$2" >/dev/null 2>&1; then printf '  PROBLEM   %-22s %s\n' "$1" "$4"; [ -n "$6" ] || bad=$((bad+1))
  else printf '  ok        %-22s %s\n' "$1" "$(eval "$3" 2>&1 | head -n 1)"; fi
}
bad=0
check 'git' 'git --version' 'git --version' 'installed, but it does not run' 'https://git-scm.com/downloads'
check 'node' "node -v | grep -Eq '^v(22|24)[.]'" 'node -v' 'found, but Backstage 1.56 needs Node.js 22 or 24' 'https://nodejs.org/en/download'
check 'yarn' 'yarn --version' 'yarn --version' 'installed, but it does not run' 'https://yarnpkg.com/getting-started/install (or: corepack enable)'
check 'docker' 'docker info' "docker version --format '{{.Server.Version}}'" 'installed, but the Docker daemon is not running: start Docker Desktop (or the docker service)' 'https://docs.docker.com/get-docker/'
check 'gh' 'gh auth status' 'gh --version' 'installed, but not logged in: run gh auth login' 'https://cli.github.com/'
check 'jq' 'jq --version' 'jq --version' 'installed, but it does not run' 'https://jqlang.org/download/'
check 'curl' 'curl --version' 'curl --version' 'installed, but it does not run' 'your package manager (it ships with macOS and most Linux distributions)'
check 'perl' 'perl -v' "perl -e 'print qq(perl $^V)'" 'installed, but it does not run' 'your package manager (it ships with macOS and most Linux distributions)'
check 'openssl' 'openssl version' 'openssl version' 'installed, but it does not run' 'your package manager (it ships with macOS and most Linux distributions)'
if [ "$bad" -eq 0 ]; then echo "All set: every tool is ready."; else echo "$bad tool(s) need attention. Install or fix them, then run this check again."; fi

3. Clone the reference repo

The finished implementation. You copy from it; you never push to it.

mkdir -p ~/work && git clone -q https://github.com/platformengr/backstage-workshop.git ~/work/backstage-workshop

Check that it arrived. You should see checkout, docs and portal: one folder per thing you will build or read.

ls ~/work/backstage-workshop

Quiz

1. What do you get from @backstage/create-app?
   • A TypeScript monorepo with a frontend and a backend that your team owns, builds and upgrades
   • A hosted portal account where you click plugins on and off, with upgrades done for you by the vendor
   • A Helm chart that installs a fixed Backstage build, configured only through values
2. Where should the facts about the checkout service (owner, APIs, docs) live?
   • In the portal database, typed in through a form so the platform team can review them
   • In the checkout repo, next to the code, owned by team-checkout
   • In a shared spreadsheet that the portal imports every night
3. A page in the portal shows the wrong owner for a service. What is most likely wrong?
   • The frontend cache, which needs clearing in every browser
   • The plugin that renders the page, which needs upgrading
   • The catalog data: the owner field in that service's catalog-info.yaml

Field note

Every Backstage rollout I have seen stall stalled on the catalog, not on the code. Teams spent weeks on plugins while half the components had no real owner. Get the data true first; the rest is easy.

Report a problem with this module