Vorwort
Wenig lesen, viel tippen und klicken. Dieses Buch baut mit dir ein internes Entwicklerportal auf Basis von Backstage: von der leeren App über den Software Catalog, Software Templates und TechDocs bis zu Login, Berechtigungen und dem Betrieb mit PostgreSQL. Alles läuft auf deinem Laptop: die Backstage-App unter Node 24, ein lokales Forgejo in Docker als Git-Plattform und die fiktive Kranich Logistik GmbH mit ihren Services, APIs und Teams.
Backstage ist zum großen Teil Oberfläche. Deshalb zeigt dieses Buch, anders als die übrigen Bände der Reihe, an jedem wichtigen Schritt einen Screenshot. Alle Bilder stammen aus echten Testläufen mit genau den Befehlen, die du tippst. Was du im Browser siehst, kannst du im Buch daneben vergleichen. Jede Prüfung im Kontrollpunkt läuft trotzdem skriptbar über die Backstage-API.
Warum Forgejo und nicht GitHub? Weil du so ohne Cloud-Konto,
OAuth-App oder fremde Organisation arbeitest. Backstage spricht Forgejo
über seine Gitea-Integration an: Es liest catalog-info.yaml
aus Repositories, entdeckt neue Repos automatisch, Templates legen echte
Repositories an, und Forgejo dient an Tag 12 sogar als Login-Provider.
Was auf GitHub oder GitLab anders ist, steht jeweils in einem Hinweis
oder in der Enterprise-Notiz.
Das Buch richtet sich an Platform Engineers, DevOps- und Security-Leute, die ein Entwicklerportal einführen, betreiben oder erweitern wollen. TypeScript-Grundkenntnisse helfen an den Tagen 6, 11 und 12, sind aber nicht Voraussetzung.
Die Trainingsregeln
- Tippen, nicht kopieren. Jeder Befehl einmal selbst.
- Erwartet vergleichen. Nach jedem Drill steht, was du sehen solltest, oft mit Bild. Weicht es ab, findest du dort die eigentliche Lektion.
- Kontrollpunkt bestehen. Erst wenn das Prüfskript nur ✔ zeigt, geht es weiter.
- Challenge allein lösen. Erst den Hinweis, dann die Lösung.
- Lab-Werte bleiben im Lab.
lab-admin-pw-123,lab-cli-token-0123456789abcdef, der Bot-Token in~/backstage-lab/setup/forgejo-tokenund alle anderenlab-…-Werte sind Übungsdaten.
Achtung: Backstage erscheint jeden Monat in neuer Version. Menüpunkte, Texte in der Oberfläche und Paketversionen können bei dir leicht anders aussehen als auf den Screenshots. Das Buch nennt an Tag 0 die exakten Versionen und zeigt an Tag 14, wie du sauber aktualisierst.
Aufbau jedes Trainingstags
| Abschnitt | Zweck |
|---|---|
| Briefing | Das Nötigste in wenigen Stichpunkten |
| Drills | Befehle und Klickpfade mit erwartetem Ergebnis |
| Kontrollpunkt | Prüfskript: hat alles geklappt? |
| Challenge | Eine Aufgabe ohne Anleitung |
| Enterprise-Notiz | Was in Produktion anders ist |
Der Trainingsplan
| Teil | Tag | Einheit |
|---|---|---|
| Gelände | 0 | Node 24, create-app, Forgejo, Lab-Konfiguration,
check.sh |
| A – Der Katalog | 1 | Erster Rundgang |
| 2 | Das Datenmodell | |
| 3 | Katalog füllen und pflegen | |
| 4 | Organisation und Ownership | |
| B – Golden Paths | 5 | Software Templates |
| 6 | Templates für Fortgeschrittene | |
| 7 | TechDocs | |
| 8 | Suche und API-Doku | |
| C – Plattform bauen | 9 | Die App anpassen |
| 10 | Plugins installieren | |
| 11 | Ein eigenes Plugin | |
| 12 | Login und Berechtigungen | |
| D – Betrieb und Praxis | 13 | Betrieb mit PostgreSQL |
| 14 | Fehlersuche und Upgrades | |
| 15 | Wettkampf: Desaster-Drills | |
| Anhang | A | Spickzettel |
| B | Abschlussprüfung |
Teil A füllt den Katalog und macht sichtbar, wem was gehört. Teil B baut Golden Paths, auf denen neue Services in Minuten statt Tagen entstehen. Teil C macht aus der Vorlage dein eigenes Portal. Teil D bringt es in den Betrieb und trainiert den Ernstfall.
Tipp: Getestet mit Backstage 1.55.0 (
@backstage/create-app0.9.2) unter Node 24.21.0 und 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) und Google Chrome. Weicht etwas ab:backstage.io/docsund das Changelog im Backstage-Repository.
Der Begleitcode
Alle Dateien aus diesem Buch liegen öffentlich auf GitHub: https://github.com/thomaszachmann/backstage-zum-anfassen. Wie du sie holst, zeigt Tag 0.
Los geht’s.
Thomas Zachmann, Oktober 2026