Backstage: printable course notes

Create a Backstage app and run it: how to think about Backstage, config and secrets, Postgres, the catalog model, GitHub discovery and rules, GitHub sign-in, software templates, a custom scaffolder action, TechDocs, a production image and upgrades, and a capstone.

These pages are the same content as the interactive course, on one page per module, for reading and printing.

Four pieces

Piece	What it is
See the end result	Not the first step: a 30-minute preview of the finished portal (catalog, sign-in, a template, docs) with few explanations. Useful to know where you are heading.
Full course	11 modules from `create-app` to a shipped image: config, catalog, discovery, sign-in, templates, a custom action, TechDocs, upgrades and a capstone.
Reference repo	The finished portal and the `checkout` repo, plus one-page summaries of the docs. You copy from it.
Your two repos	`portal` (platform team) and `checkout` (team-checkout). You create them in modules 01 and 03.

Your setup

Commands in these notes use these values (shared with the interactive course, stored only in this browser).

GitHub userWorkspace folder

Outline

Module	Part	Time	You are	You will
00 Orientation: how to think about Backstage	Orientation	20 min	Platform and product	Know what Backstage is (a framework you build an app with), its main parts, who owns what, and what you will build. Tell the course who you are so every command is yours.
01 Create the app and find your way around	The portal and its catalog	45 min	Platform team	Generate a Backstage app with a pinned version, push it to your own repo, run it, and find the same four things in the UI and in the code.
02 Configuration, secrets and Postgres	The portal and its catalog	45 min	Platform team	Name the portal, move it to Postgres, keep secrets out of Git with environment variables, and give scripts an API token.
03 The catalog: teams, systems and a real service	The portal and its catalog	60 min	Platform and product	Replace the example data with Acme's teams and systems, describe the `checkout` service in its own repo, and read the relations the catalog builds from it.
04 Catalog at scale: let it find the repos	The portal and its catalog	45 min	Platform team	Replace hand-registered URLs with GitHub discovery, so every repo with a `catalog-info.yaml` on `main` shows up on its own, and limit what a team repo may add.
05 Sign in with GitHub	The portal and its catalog	45 min	Platform team	Replace guest sign-in with GitHub, so every person in the portal is a User entity with real team memberships.
06 Golden paths with software templates	Golden paths and docs	60 min	Platform team	Publish a `node-service` template that creates a repo with code, docs and a `catalog-info.yaml`, test it with a dry run, and use it as team-checkout.
07 Your own scaffolder action	Golden paths and docs	60 min	Platform team	Write, test and use an `acme:team:lookup` action that checks the owner is a real team and gives the template its display name.
08 Docs next to the code with TechDocs	Golden paths and docs	30 min	Platform and product	Show `checkout`'s and `cart`'s docs in the portal, update them from Git, and know how they are built.
09 Ship it: an image, production config and an upgrade	Ship it	60 min	Platform team	Build the portal as a Docker image with its catalog, templates and MkDocs, run it with production config and Postgres, and upgrade Backstage.
10 Capstone: onboard team-payments	Ship it	60 min	Platform and product	Onboard a new team, team-payments, end to end without the steps: catalog, sign-in, a new service from the template, docs, and a new image.

Where the portal runs

Everything runs on your laptop with Node, Yarn and Docker.

Between you and production

A company identity provider: Sign-in with Entra ID, Okta or a GitHub App for the organisation, and an org provider that imports Users and Groups.
Permission policies: Replace the allow-all policy: who may register, delete, run templates and read what.
TLS and a real hostname: `app.baseUrl` and `backend.baseUrl` on HTTPS, behind your ingress or load balancer.
Managed Postgres with backups: One database server per environment, backed up and monitored.
Secrets from a store: Vault or a cloud secret manager injects the tokens and client secrets as environment variables.
TechDocs built in CI: `techdocs-cli` in each repo's pipeline, published to a bucket; the portal only reads.
CI for the portal: tsc, tests, `config:check --strict`, a template dry run and an image smoke test on every pull request.
Monthly upgrades: `versions:bump` on a fixed day, with the upgrade helper and release notes read.
A GitHub App for integrations: Higher rate limits and no personal token behind discovery and `publish:github`.
Observability: Backend logs, catalog warnings and scheduler failures shipped to your log platform with alerts.