Tag 0: Das Gelände
Ziel: Node 24, eine frische Backstage-App aus
create-appund ein lokales Forgejo mit Demo-Repos aufbauen und das Portal zum ersten Mal starten. · Dauer: ca. 60 min · Voraussetzung: keine
Briefing
- Backstage ist kein fertiges Produkt zum Installieren.
create-apperzeugt ein eigenes Monorepo (Frontend + Backend), das du ab heute selbst pflegst. - Das Portal läuft lokal mit
yarn start: Frontend auf Port 3000, Backend auf 7007, Daten in SQLite-Dateien. - Git-Plattform ist Forgejo in Docker. Backstage
spricht es über die Gitea-Integration mit dem Bot-User
backstage-botan. up.sh,seed.sh,portal.shundcheck.shbauen, füllen, starten und prüfen das Gelände.
Laptop Docker (Colima)
┌─────────────────────────────────────┐ ┌───────────────────────────┐
│ ~/backstage-lab/ │ REST │ Container "bs-forgejo" │
│ portal/ Backstage 1.55.0 │ ──────► │ http://127.0.0.1:3300 │
│ Frontend http://localhost:3000 │ Token │ Org kranich │
│ Backend http://localhost:7007 │ │ sendungs-api │
│ data/ SQLite │ │ tracking-web │
│ setup/ env.sh up.sh portal.sh … │ │ lab-admin, backstage-bot│
│ Node 24, Yarn 4 (Corepack) │ └───────────────────────────┘
└─────────────────────────────────────┘
Drill 1: Werkzeuge prüfen
docker version --format '{{.Server.Version}}'
colima version | head -1
git --version
jq --version
yq --version
curl --version | head -1 | cut -d' ' -f1-2
python3 --version
brew --version | head -1Erwartet (kann je nach Version abweichen):
29.5.2
colima version 0.10.3
git version 2.56.0
jq-1.8.2
yq (https://github.com/mikefarah/yq/) version v4.54.1
curl 8.7.1
Python 3.14.8
Homebrew 7.0.9
yq (YAML auf der Kommandozeile, ab Tag 8 genutzt)
installierst du bei Bedarf mit brew install yq. Python
braucht create-app nur für native Node-Module
(node-gyp). Statt Colima geht auch Docker Desktop, solange
docker antwortet.
Jetzt Node. Backstage 1.55 verlangt Node 22 oder 24
("engines": { "node": "22 || 24" }), Node 25 ist zu neu.
Homebrew installiert node@24 „keg-only”, also neben einem
eventuell vorhandenen neueren node:
brew install node@24
export PATH="/opt/homebrew/opt/node@24/bin:$PATH"
node -v
corepack enable
yarn --versionErwartet:
v24.21.0
1.22.22
corepack enable gibt nichts aus. Es legt Shims für
yarn an, die in jedem Projekt die Version aus dem Feld
packageManager der package.json starten.
Außerhalb eines Projekts ist das noch Yarn 1, in der Backstage-App
gleich Yarn 4. Den export musst du nicht in deine
Shell-Konfiguration schreiben: Ab Drill 2 erledigt das
env.sh.
Tipp: Meldet die Shell
command not found: corepack, bringt dein Node-Build Corepack nicht mit. Dann hilftbrew install corepack(nicht live getestet).
Fortschritt speichern? Kostenlos registrieren
Drill 2: Arbeitsverzeichnis und Begleitcode
Den Begleitcode holst du einmal von GitHub nach
~/backstage-lab/code, die Setup-Skripte daraus kopierst du
nach ~/backstage-lab/setup:
mkdir -p ~/backstage-lab/tag00 && cd ~/backstage-lab
git clone https://github.com/thomaszachmann/backstage-zum-anfassen.git \
~/backstage-lab/code
cp -R ~/backstage-lab/code/setup ~/backstage-lab/setup
ls ~/backstage-lab/setup
ls ~/backstage-lab/setup/reposErwartet:
Cloning into '…/backstage-lab/code'...
check.sh env.sh mkrepo.sh portal.sh repos seed.sh up.sh
sendungs-api tracking-web
env.sh setzt alles, was die Skripte und die Befehle im
Buch brauchen – auch den PATH für Node 24:
grep '^export' ~/backstage-lab/setup/env.shErwartet:
export LAB="${LAB:-$HOME/backstage-lab}"
export PORTAL="${PORTAL:-$LAB/portal}"
export PATH="${NODE_BIN:-/opt/homebrew/opt/node@24/bin}:$PATH"
export FORGEJO_NAME="${FORGEJO_NAME:-bs-forgejo}"
export FORGEJO_PORT="${FORGEJO_PORT:-3300}"
export FORGEJO="http://127.0.0.1:$FORGEJO_PORT"
export ADMIN="lab-admin:lab-admin-pw-123" # Lab-Wert!
export FORGEJO_TOKEN="$(cat "$LAB/setup/forgejo-token" 2>/dev/null)"
export APP_PORT="${APP_PORT:-3000}"
export BACKSTAGE_PORT="${BACKSTAGE_PORT:-7007}"
export APP="http://localhost:$APP_PORT"
export BACKSTAGE="http://localhost:$BACKSTAGE_PORT"
export BACKSTAGE_TOKEN="lab-cli-token-0123456789abcdef" # Lab-Wert!
Dazu kommt die Funktion bs <api-pfad>: ein
curl gegen $BACKSTAGE/api/… mit dem Lab-Token.
Ab jetzt beginnt jede Terminal-Sitzung mit:
source ~/backstage-lab/setup/env.shFortschritt speichern? Kostenlos registrieren
Drill 3: Die App erzeugen
create-app fragt nach dem App-Namen. Antworte mit
portal:
cd ~/backstage-lab
npx @backstage/[email protected] --path ~/backstage-lab/portalErwartet (gekürzt, Testlauf vom 13.10.2026):
Prerequisites check...
Node version is: 24.21.0
Yarn version is: 1.22.22
Python version is: 3.14.8
? Enter a name for the app [required] portal
Creating the app...
...
Preparing files:
copying .dockerignore ✔
templating app-config.yaml.hbs ✔
templating backstage.json.hbs ✔
...
fetching yarn.lock seed ✔
Installing dependencies:
init git repository ✔
! Corepack is about to download https://repo.yarnpkg.com/4.13.0/packages/yarnpkg-cli/…
➤ YN0000: · Yarn 4.13.0
➤ YN0000: ┌ Resolution step
➤ YN0001: │ Error: got@patch:got@npm%3A11.8.2#~/.yarn/patches/got-npm-11.8.2-c1eb10545…
➤ YN0000: · Failed with errors in 1m 7s
executing yarn install ✖
Error: Could not execute command yarn install
🔥 Failed to create app!
Im Testlauf ist create-app gescheitert – die Dateien und
der erste Git-Commit liegen aber schon in
~/backstage-lab/portal. Endet deine Ausgabe stattdessen mit
einer Erfolgsmeldung, überspringst du den folgenden Kasten.
Achtung: Falls
yarn installmitgot@patch:got@npm%3A11.8.2 … ENOENTabbricht: Ursache ist das kaputt veröffentlichte Paket@yarnpkg/[email protected], das ein Patch-File erwartet, das es nicht gibt. Du pinnst die letzte gute Version überresolutionsin der Root-package.jsonund holst Installation und Typprüfung nach (das hättecreate-appals Nächstes getan):cd ~/backstage-lab/portal jq '.resolutions["@yarnpkg/core"] = "4.9.1"' package.json > package.json.neu \ && mv package.json.neu package.json git diff --stat yarn install yarn tsc
Erwartet (gekürzt):
package.json | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
➤ YN0000: · Yarn 4.13.0
➤ YN0000: ┌ Resolution step
➤ YN0085: │ + @backstage/backend-defaults@npm:0.18.0, @backstage/cli-defaults@npm:0.1…
...
➤ YN0060: │ react is listed by your project with version 18.3.1 (pd98da7), which does…
...
➤ YN0007: │ ssh2@npm:1.17.0 must be built because it never has been before or the last…
➤ YN0000: └ Completed in 35s 451ms
➤ YN0000: · Done with warnings in 1m 50s
yarn tsc meldet bei Erfolg nichts. Die
YN0060-/YN0002-Warnungen zu Peer-Dependencies
sind in jeder frischen Backstage-App normal. node_modules
belegt danach etwa 1,7 GB. Committe den Fix, damit er nicht verloren
geht:
git commit -qam "Pin @yarnpkg/core 4.9.1 (kaputtes 4.9.2)" && git log --onelineErwartet (Hashes weichen ab):
3f1c2ab Pin @yarnpkg/core 4.9.1 (kaputtes 4.9.2)
0a5bdc2 Initial commit
Fortschritt speichern? Kostenlos registrieren
Drill 4: Was hat create-app gebaut?
cd ~/backstage-lab/portal
ls -1
cat backstage.json
yarn --versionErwartet:
README.md
app-config.production.yaml
app-config.yaml
backstage.json
catalog-info.yaml
examples
node_modules
package.json
packages
playwright.config.ts
plugins
tsconfig.json
yarn.lock
{
"version": "1.55.0"
}
4.13.0
| Pfad | Inhalt |
|---|---|
packages/app |
Frontend (React), gestartet von backstage-cli |
packages/backend |
Backend (Node), alle Backend-Plugins |
plugins/ |
noch leer – hier landen eigene Plugins (Tag 11) |
app-config.yaml |
Konfiguration; *.local.yaml und
*.production.yaml überlagern |
examples/ |
Beispiel-Entities, -Gruppen und ein Template für den ersten Katalog |
backstage.json |
die Backstage-Release-Version, Basis für Upgrades (Tag 14) |
Das Frontend nutzt das neue Frontend-System: Plugins
sind Features, die createApp bekommt. Was auf welcher Seite
erscheint, steuerst du über Extensions in
app-config.yaml:
cat packages/app/src/App.tsx
grep -A3 '^ extensions:' app-config.yamlErwartet:
import { createApp } from '@backstage/frontend-defaults';
import catalogPlugin from '@backstage/plugin-catalog/alpha';
import { navModule } from './modules/nav';
import { homeModule } from './modules/home';
export default createApp({
features: [catalogPlugin, navModule, homeModule],
});
extensions:
- page:catalog:
config:
path: /Weitere Plugins findet die App selbst über
app.packages: all (alle Plugins aus
packages/app/package.json). Die Katalogseite liegt auf
/ statt auf /catalog – merk dir das für die
URLs im Buch. Das Backend nutzt das neue Backend-System, jedes Plugin
ist eine Zeile:
grep -c 'backend.add' packages/backend/src/index.ts
grep -o "import('[^']*')" packages/backend/src/index.ts | head -4Erwartet:
22
import('@backstage/plugin-app-backend')
import('@backstage/plugin-proxy-backend')
import('@backstage/plugin-scaffolder-backend')
import('@backstage/plugin-scaffolder-backend-module-github')
Fortschritt speichern? Kostenlos registrieren
Drill 5: Forgejo starten und füllen
up.sh ist idempotent: Es startet den Container
bs-forgejo (Image
codeberg.org/forgejo/forgejo:16.0.6-rootless, SQLite,
Volumes bs-forgejo-data und bs-forgejo-conf),
legt lab-admin und backstage-bot an und
schreibt den Bot-Token nach
~/backstage-lab/setup/forgejo-token (Rechte
600).
cd ~/backstage-lab/setup
./up.sh
docker ps --filter name=bs-forgejo --format '{{.Names}} {{.Status}} {{.Ports}}'Erwartet (beim allerersten Mal zieht Docker vorher das Image):
New user 'lab-admin' has been successfully created!
New user 'backstage-bot' has been successfully created!
✔ Forgejo läuft: http://127.0.0.1:3300 (lab-admin / lab-admin-pw-123)
bs-forgejo Up 2 seconds 2222/tcp, 127.0.0.1:3300->3000/tcp
Jetzt gibt es einen Token. env.sh neu laden und Forgejo
fragen, wer der Bot ist:
source ~/backstage-lab/setup/env.sh
curl -s "$FORGEJO/api/v1/version"; echo
curl -s -H "Authorization: token $FORGEJO_TOKEN" "$FORGEJO/api/v1/user" \
| jq -c '{login, is_admin}'Erwartet:
{"version":"16.0.6+gitea-1.22.0"}
{"login":"backstage-bot","is_admin":false}
Die Versionskennung +gitea-1.22.0 ist der Grund, warum
Backstage Forgejo über seine Gitea-Integration ansprechen kann.
seed.sh legt die Org kranich an, steckt den
Bot in deren Owners-Team und pusht die Demo-Repos aus
setup/repos/:
./seed.sh
curl -s -u "$ADMIN" "$FORGEJO/api/v1/repos/kranich/sendungs-api/contents" \
| jq -r '[.[].path] | join(" ")'Erwartet:
✔ kranich/sendungs-api angelegt (http://127.0.0.1:3300/kranich/sendungs-api)
✔ kranich/tracking-web angelegt (http://127.0.0.1:3300/kranich/tracking-web)
✔ Org kranich mit 2 Repos
catalog-info.yaml docs mkdocs.yml openapi.yaml package.json src
Ein zweiter Aufruf von ./seed.sh lässt vorhandene Repos
in Ruhe und meldet nur die letzte Zeile. ./seed.sh --reset
setzt beide Repos auf den Stand von Tag 0 zurück.
Im Browser:
http://127.0.0.1:3300/kranichöffnen.- Optional oben rechts Anmelden mit
lab-admin/lab-admin-pw-123(Lab-Wert).
Erwartet: die Org mit zwei Repos wie in der Abbildung. Forgejo zeigt die Oberfläche in der Sprache deines Browsers.
Sicherheit: Passwörter und Token sind Lab-Werte.
forgejo-tokengehört nie in ein Git-Repo und nie auf einen Screenshot.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Lab-Konfiguration
Backstage lädt app-config.yaml und danach
app-config.local.yaml. Die zweite Datei überlagert die
erste und steht per *.local.yaml in .gitignore
– der richtige Ort für alles Lokale. ${…} liest
Umgebungsvariablen, die env.sh setzt:
cat > ~/backstage-lab/portal/app-config.local.yaml <<'EOF'
app:
title: Kranich Entwicklerportal
organization:
name: Kranich Logistik
backend:
auth:
externalAccess:
- type: static
options:
token: ${BACKSTAGE_TOKEN}
subject: lab-cli
database:
client: better-sqlite3
connection:
directory: ${LAB}/data
integrations:
gitea:
- host: 127.0.0.1:3300
baseUrl: http://127.0.0.1:3300
username: backstage-bot
password: ${FORGEJO_TOKEN}
EOF
cd ~/backstage-lab/portal && git check-ignore -v app-config.local.yamlErwartet:
.gitignore:44:*.local.yaml app-config.local.yaml
Was die Blöcke tun:
externalAccessmittype: staticerlaubt Aufrufe mit dem festen Lab-Token als Subjektlab-cli– das nutztbs.databasemitdirectorylegt pro Plugin eine SQLite-Datei in~/backstage-lab/dataan. Der Katalog überlebt so einen Neustart (Standard ist:memory:).integrations.gitealässt Backstage Dateien aus Forgejo alsbackstage-botlesen (ab Tag 1).
Achtung: Startest du
yarn startvon Hand, muss vorherenv.shgeladen sein, sonst sind${LAB}und${FORGEJO_TOKEN}leer und das Backend startet nicht.portal.shlädtenv.shselbst.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Portal starten und einloggen
~/backstage-lab/setup/portal.sh startErwartet (der erste Start dauert etwas länger):
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
portal.sh startet yarn start im Hintergrund
und wartet, bis Backend-Readiness und Frontend antworten. Was dabei
passiert ist, steht im Log:
~/backstage-lab/setup/portal.sh logs 200 \
| grep -E 'Loaded config|Listening|initialization complete|warn'Erwartet (gekürzt):
Loaded config from app-config.yaml, app-config.local.yaml
2026-10-13T06:19:50.973Z rootHttpRouter info Listening on :7007
2026-10-13T06:19:51.211Z search warn Postgres search engine is not supported, skippi…
2026-10-13T06:19:51.529Z kubernetes warn Failed to initialize kubernetes backend: va…
2026-10-13T06:19:51.907Z backstage info Plugin initialization complete, newly initia…
2026-10-13T06:19:51.982Z catalog warn Event subscribe request failed with status 404…
Die Warnungen sind erwartet: Postgres-Suche gibt es erst mit
PostgreSQL (Tag 13), einen Cluster für das Kubernetes-Plugin erst an Tag
10. In ~/backstage-lab/data liegt jetzt eine SQLite-Datei
pro Plugin (catalog.sqlite, auth.sqlite,
…).
Im Browser:
http://localhost:3000öffnen.- Auf der Sign-in-Seite im Kasten Guest auf Enter klicken.
Erwartet: Die Sign-in-Seite trägt schon deinen Titel aus
app-config.local.yaml.
Nach Enter bist du
user:development/guest und landest im Katalog. Die
Überschrift kommt aus organization.name, der Inhalt aus
examples/entities.yaml: eine Component
example-website, Owner guests.
Der Filter steckt in der URL. Öffne
http://localhost:3000/?filters[kind]=template.
Erwartet: das Beispiel-Template aus
examples/template/template.yaml.
Die Forgejo-Repos sind noch nicht im Katalog – die registrierst du an Tag 1.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Katalog per API und Gelände prüfen
Alles, was die GUI zeigt, kommt aus der REST-API des Backends. Mit dem Lab-Token:
source ~/backstage-lab/setup/env.sh
bs catalog/entities | jq -r '.[] | "\(.kind)\t\(.metadata.name)"' | sort
bs 'catalog/entities?filter=kind=component' \
| jq -r '.[] | "\(.metadata.name) owner=\(.spec.owner)"'Erwartet (Location-Namen gekürzt):
API example-grpc-api
Component example-website
Group guests
Location generated-140e1a7b3ce8f40124d47e4aebe76bb99632925d
Location generated-58564e4f5d7af53b90d73f07e1590deb70111871
Location generated-9015f07fda6d49468cb95f3ee5412a7f7a4eafbb
System examples
Template example-nodejs-template
User guest
example-website owner=guests
Und ohne Token?
curl -s -o /dev/null -w '%{http_code}\n' "$BACKSTAGE/api/catalog/entities"
curl -s "$BACKSTAGE/api/catalog/entities" | jq -c '.error | {name, message}'
curl -s -H 'Authorization: Bearer falsch' "$BACKSTAGE/api/catalog/entities" \
| jq -r .error.messageErwartet:
401
{"name":"AuthenticationError","message":"Missing credentials"}
Illegal token
Das Backend lässt nur Benutzer-Token (aus dem Sign-in), Service-Token
anderer Plugins und die konfigurierten externalAccess-Token
durch. Zum Schluss der Gesamtcheck:
~/backstage-lab/setup/check.shErwartet:
✔ Docker läuft
✔ Node 24 (node -v)
✔ Yarn 4 über Corepack (im Portal)
✔ Forgejo erreichbar unter http://127.0.0.1:3300
✔ Bot-Token gültig (backstage-bot)
✔ Repo kranich/sendungs-api vorhanden (sonst: seed.sh)
✔ Backend bereit (http://localhost:7007)
✔ Frontend erreichbar (http://localhost:3000)
✔ Katalog-API mit Lab-Token
Der Exit-Code ist die Anzahl der ✘. Nach einem Laptop-Neustart
genügen ./up.sh und ./portal.sh start, dann
ist wieder alles grün. Ganz am Ende des Buchs räumst du so auf:
portal.sh stop, docker rm -f bs-forgejo,
docker volume rm bs-forgejo-data bs-forgejo-conf,
rm -rf ~/backstage-lab.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Die Datei liegt auch unter
~/backstage-lab/code/tag00/kontrollpunkt.sh.
source ~/backstage-lab/setup/env.sh
cd "$PORTAL"
[ "$(jq -r .version backstage.json)" = 1.55.0 ] && echo "✔ Backstage 1.55.0" \
|| echo "✘ falsche Backstage-Version"
jq -e '.resolutions["@yarnpkg/core"] == "4.9.1"' package.json >/dev/null \
&& echo "✔ @yarnpkg/core auf 4.9.1 gepinnt" || echo "✘ resolutions fehlt"
git check-ignore -q app-config.local.yaml && echo "✔ app-config.local.yaml ignoriert" \
|| echo "✘ app-config.local.yaml würde eingecheckt"
[ -s "$LAB/data/catalog.sqlite" ] && echo "✔ Katalog in SQLite ($LAB/data)" \
|| echo "✘ keine SQLite-Datei"
n=$(bs 'catalog/entities?filter=kind=component' | jq length)
[ "${n:-0}" -ge 1 ] && echo "✔ $n Component(s) im Katalog" || echo "✘ Katalog leer"
code=$(curl -s -o /dev/null -w '%{http_code}' "$BACKSTAGE/api/catalog/entities")
[ "$code" = 401 ] && echo "✔ ohne Token: 401" || echo "✘ ohne Token: $code"
"$LAB/setup/check.sh" >/dev/null && echo "✔ check.sh ohne Fehler" \
|| echo "✘ check.sh meldet Fehler"Erwartet:
✔ Backstage 1.55.0
✔ @yarnpkg/core auf 4.9.1 gepinnt
✔ app-config.local.yaml ignoriert
✔ Katalog in SQLite (/Users/<du>/backstage-lab/data)
✔ 1 Component(s) im Katalog
✔ ohne Token: 401
✔ check.sh ohne Fehler
Hast du den Stolperstein aus Drill 3 nicht erlebt, darf die zweite Zeile ✘ zeigen.
Challenge
Ändere den Portal-Titel auf „Kranich Entwicklerportal (Lab)“, starte das Portal neu und beweise ohne Browser, dass der neue Titel ausgeliefert wird. Danach stellst du den alten Titel wieder her.
Hinweis: Das Frontend liest seine Konfiguration nur
beim Start, und app.title landet im
<title> der ausgelieferten
index.html.
Lösung
source ~/backstage-lab/setup/env.sh
cd ~/backstage-lab/portal
sed -i '' 's/^ title: .*/ title: Kranich Entwicklerportal (Lab)/' \
app-config.local.yaml
head -2 app-config.local.yaml
~/backstage-lab/setup/portal.sh restart
curl -s "$APP" | grep -o '<title>[^<]*</title>'Erwartet:
app:
title: Kranich Entwicklerportal (Lab)
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
<title>Kranich Entwicklerportal (Lab)</title>
In einem privaten Browserfenster zeigt die Sign-in-Seite unter
http://localhost:3000 den neuen Titel.
Zurückstellen:
sed -i '' 's/^ title: .*/ title: Kranich Entwicklerportal/' app-config.local.yaml
~/backstage-lab/setup/portal.sh restartDas sed trifft nur app.title, weil es die
einzige Zeile mit genau zwei Leerzeichen vor title: ist.
sed -i '' ist die macOS-Schreibweise, unter Linux
sed -i.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Node-Version pinnen (
.nvmrc/mise.toml,engines, Basis-Image im Dockerfile) undyarn.lockimmer einchecken –create-appist ein Snapshot, kein Paket mit Updates. - Die App gehört in ein eigenes Repo mit CI (
yarn tsc,yarn test,yarn lint); Workarounds wie dieresolutionsdokumentiert und mit Ticket wieder entfernen. - Secrets nie in
app-config*.yamlschreiben, nur${VAR}aus Secret-Store bzw. Kubernetes-Secret;externalAccessmit statischem Token nur fürs Lab. - SQLite und Guest-Login sind Lab-Abkürzungen: produktiv PostgreSQL (Tag 13) und echter Login mit Berechtigungen (Tag 12).
- Backstage ist ein Produkt, kein Tool-Rollout: Es braucht ein Plattform-Team mit Roadmap, Upgrade-Takt (monatliche Releases) und Ownership für Katalog und Plugins.