Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 0: Das Gelände

Ziel: Node 24, eine frische Backstage-App aus create-app und 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-app erzeugt 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-bot an.
  • up.sh, seed.sh, portal.sh und check.sh bauen, 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 -1

Erwartet (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 --version

Erwartet:

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 hilft brew 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/repos

Erwartet:

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.sh

Erwartet:

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.sh

Fortschritt 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/portal

Erwartet (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 install mit got@patch:got@npm%3A11.8.2 … ENOENT abbricht: 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 über resolutions in der Root-package.json und holst Installation und Typprüfung nach (das hätte create-app als 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 --oneline

Erwartet (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 --version

Erwartet:

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.yaml

Erwartet:

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 -4

Erwartet:

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:

  1. http://127.0.0.1:3300/kranich öffnen.
  2. 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.

Die Organisation kranich in Forgejo mit den beiden Demo-Repos

Sicherheit: Passwörter und Token sind Lab-Werte. forgejo-token gehö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.yaml

Erwartet:

.gitignore:44:*.local.yaml  app-config.local.yaml

Was die Blöcke tun:

  • externalAccess mit type: static erlaubt Aufrufe mit dem festen Lab-Token als Subjekt lab-cli – das nutzt bs.
  • database mit directory legt pro Plugin eine SQLite-Datei in ~/backstage-lab/data an. Der Katalog überlebt so einen Neustart (Standard ist :memory:).
  • integrations.gitea lässt Backstage Dateien aus Forgejo als backstage-bot lesen (ab Tag 1).

Achtung: Startest du yarn start von Hand, muss vorher env.sh geladen sein, sonst sind ${LAB} und ${FORGEJO_TOKEN} leer und das Backend startet nicht. portal.sh lädt env.sh selbst.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Portal starten und einloggen

~/backstage-lab/setup/portal.sh start

Erwartet (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:

  1. http://localhost:3000 öffnen.
  2. 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.

Sign-in-Seite mit dem Guest-Provider

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 erste Katalog mit den Beispieldaten aus create-app

Der Filter steckt in der URL. Öffne http://localhost:3000/?filters[kind]=template.

Erwartet: das Beispiel-Template aus examples/template/template.yaml.

Katalog gefiltert auf Templates

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.message

Erwartet:

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.sh

Erwartet:

✔ 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.

Sign-in-Seite mit geändertem Titel

Zurückstellen:

sed -i '' 's/^  title: .*/  title: Kranich Entwicklerportal/' app-config.local.yaml
~/backstage-lab/setup/portal.sh restart

Das 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) und yarn.lock immer einchecken – create-app ist ein Snapshot, kein Paket mit Updates.
  • Die App gehört in ein eigenes Repo mit CI (yarn tsc, yarn test, yarn lint); Workarounds wie die resolutions dokumentiert und mit Ticket wieder entfernen.
  • Secrets nie in app-config*.yaml schreiben, nur ${VAR} aus Secret-Store bzw. Kubernetes-Secret; externalAccess mit 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.