Skip to content
Hands-on IT IT Drills

Foreword

Read little, type and click a lot. In this book you build an internal developer portal based on Backstage: from the empty app through the Software Catalog, Software Templates and TechDocs to login, permissions and running it with PostgreSQL. Everything runs on your laptop: the Backstage app on Node 24, a local Forgejo in Docker as the Git platform, and the fictional company Kranich Logistik GmbH with its services, APIs and teams.

Backstage is mostly user interface. That is why this book, unlike the other volumes in the series, shows a screenshot at every important step. All images come from real test runs with exactly the commands you type. What you see in the browser you can compare with the book side by side. Every check in the checkpoint still runs as a script against the Backstage API.

Why Forgejo and not GitHub? Because this way you work without a cloud account, an OAuth app or someone else’s organization. Backstage talks to Forgejo through its Gitea integration: it reads catalog-info.yaml from repositories, discovers new repos automatically, templates create real repositories, and on Day 12 Forgejo even serves as the login provider. Whatever is different on GitHub or GitLab is covered in a note or in the Enterprise Note.

The book is for platform engineers and DevOps and security people who want to introduce, run or extend a developer portal. Basic TypeScript knowledge helps on Days 6, 11 and 12, but is not required.

The Training Rules

  1. Type, don’t copy. Run every command yourself once.
  2. Compare with Expected. After every drill you will find what you should see, often with an image. If it differs, that is where the real lesson is.
  3. Pass the checkpoint. Only move on once the check script shows nothing but ✔.
  4. Solve the challenge on your own. First the hint, then the solution.
  5. Lab values stay in the lab. lab-admin-pw-123, lab-cli-token-0123456789abcdef, the bot token in ~/backstage-lab/setup/forgejo-token and all other lab-… values are practice data.

Warning: Backstage releases a new version every month. Menu items, texts in the user interface and package versions may look slightly different for you than in the screenshots. On Day 0 the book names the exact versions, and on Day 14 it shows you how to upgrade cleanly.

Structure of Each Training Day

Section Purpose
Briefing The essentials in a few bullet points
Drills Commands and click paths with the expected result
Checkpoint Check script: did everything work?
Challenge A task without instructions
Enterprise Note What is different in production

The Training Plan

Part Day Unit
Training ground 0 Node 24, create-app, Forgejo, lab configuration, check.sh
A – The Catalog 1 First tour
2 The data model
3 Filling and maintaining the catalog
4 Organization and ownership
B – Golden Paths 5 Software Templates
6 Advanced templates
7 TechDocs
8 Search and API docs
C – Building the Platform 9 Customizing the app
10 Installing plugins
11 A plugin of your own
12 Login and permissions
D – Operations and Practice 13 Running with PostgreSQL
14 Troubleshooting and upgrades
15 Competition: disaster drills
Appendix A Cheat Sheet
B Final Exam

Part A fills the catalog and makes visible who owns what. Part B builds golden paths on which new services come to life in minutes instead of days. Part C turns the template into your own portal. Part D takes it into operation and trains for the emergency.

Tip: Tested with Backstage 1.55.0 (@backstage/create-app 0.9.2) on Node 24.21.0 and Yarn 4, Forgejo 16.0.6 (image codeberg.org/forgejo/forgejo:16.0.6-rootless), PostgreSQL 16.4, Docker 29.5, kind 0.33 (Kubernetes 1.37) and Google Chrome. If something differs: backstage.io/docs and the changelog in the Backstage repository.

The Companion Code

All files from this book are publicly available on GitHub: https://github.com/thomaszachmann/backstage-zum-anfassen. Day 0 shows you how to get them.

Let’s go.

Thomas Zachmann, October 2026