Cheat notes · Module 09 · Ship it

Ship it: an image, production config and an upgrade

A five-minute review for when you have done this module and want it back in your head. Open the full module for the steps and the lab, or the full text to print.

The idea

Production is one Node process that serves the built frontend and the API, configured by environment variables. Whatever the portal reads from disk (catalog files, templates) or runs (MkDocs) must be in the image. Upgrades are part of shipping: small and monthly.

Remember

Host build: yarn build:backend builds frontend and backend on your machine; the Dockerfile only copies the result in. yarn build-image tags it backstage.
One port: in production the backend serves the frontend, so app.baseUrl and backend.baseUrl are the same URL (7007).
Config layering: the container starts with --config app-config.yaml --config app-config.production.yaml. Objects merge; lists such as catalog.locations are replaced, so the production file repeats every location (paths relative to /app).
What goes in the image: COPY the catalog and templates folders, and install MkDocs (mkdocs-techdocs-core) for runIn: local; there is no Docker in the container.
A release is a set of package versions: yarn backstage-cli versions:bump --release X moves every @backstage/* package together. Check the upgrade helper for changes to generated files.

Pitfalls

Trimming a COPY line that "only copies YAML": sign-in fails with unable to resolve user identity because the catalog has no Users. The log says file /app/catalog/org.yaml does not exist.
Testing an image against an old database: entities survive there and hide what is missing. Smoke-test against an empty database.
Giving Docker 2 GB: the build runs out of memory. Give it at least 4 GB.

Commands

`yarn install --immutable && yarn tsc && yarn build:backend`	Build on the host
`yarn build-image`	Build the `backstage` image
`docker run --rm -p 7007:7007 -e POSTGRES_HOST=... -e PORTAL_API_TOKEN ... backstage`	Run it; variables without `=` pass through from your shell
`yarn backstage-cli versions:bump --release 1.56.3`	Upgrade every Backstage package to one release
`jq -r .version backstage.json`	Which release the app is on

Test yourself

Answer in your head first, then open the answer.

You list catalog.locations in app-config.production.yaml. What happens to the ones in app-config.yaml?

They are replaced. The production list is the only list.

Why did the broken image work fine against the old database?

Entities stay in the database; only a fresh database showed the gap.

How should you upgrade Backstage?

Run versions:bump regularly, check the upgrade helper, then build and test.

Where module 09 leaves you: A backstage image that runs the whole portal on one port, with your catalog, template and docs, on Backstage 1.56.3.