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
- Type, don’t copy. Run every command yourself once.
- 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.
- Pass the checkpoint. Only move on once the check script shows nothing but ✔.
- Solve the challenge on your own. First the hint, then the solution.
- Lab values stay in the lab.
lab-admin-pw-123,lab-cli-token-0123456789abcdef, the bot token in~/backstage-lab/setup/forgejo-tokenand all otherlab-…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-app0.9.2) on Node 24.21.0 and Yarn 4, Forgejo 16.0.6 (imagecodeberg.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/docsand 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