Tag 1: Erster Rundgang
Ziel: Du findest dich im Portal zurecht, registrierst die ersten Forgejo-Repos im Software Catalog und liest dieselben Daten per API. · Dauer: ca. 90 min · Voraussetzung: Tag 0
Briefing
- Der Software Catalog ist das Herz von Backstage:
Jede Entity (Component, API, Group …) stammt aus einer YAML-Datei, meist
catalog-info.yamlim Repo. - Eine Location zeigt auf so eine Datei. Backstage liest sie, verarbeitet die Entities und frischt sie periodisch auf.
- Alles, was die Oberfläche zeigt, liefert die Katalog-API unter
/api/catalog.
Forgejo-Repo Backstage-Backend Frontend
catalog-info.yaml ─► Location ─► Processing ─► Entities ─► /api/catalog ─► Katalogseite
▲ │ alle ~2 min oder per Refresh
└───────────────────────────┘
Drill 1: Gast-Login, Sidebar und Filter
Ausgangslage ist das Ende von Tag 0: Forgejo läuft, die Org
kranich ist befüllt, app-config.local.yaml ist
angelegt und das Portal gestartet.
source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
~/backstage-lab/setup/check.sh | tail -3Erwartet:
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
✔ Backend bereit (http://localhost:7007)
✔ Frontend erreichbar (http://localhost:3000)
✔ Katalog-API mit Lab-Token
- Öffne
http://localhost:3000und klicke beim Guest-Provider auf Enter. - Klicke unten in der Sidebar auf Settings. Unter
Profile steht
user:development/guest– das ist deine Identität bis Tag 12. - Fahre die Sidebar von oben nach unten ab.
| Eintrag | Pfad | Wofür |
|---|---|---|
| Home | /home |
Startseite mit Widgets (ab Tag 9 auf /) |
| Catalog | / |
Software Catalog – hier die Startseite |
| Create | /create |
Software Templates (Tag 5) |
| APIs | /api-docs |
alle API-Entities |
| Catalog Graph | /catalog-graph |
Beziehungen als Graph |
| Docs | /docs |
TechDocs (Tag 7) |
| Register Existing Component | /catalog-import |
Location registrieren |
| Visualizer | /visualizer |
Extension-Baum (ab Tag 9 „App-Struktur“) |
Der Katalog liegt auf /, weil
app-config.yaml die Extension page:catalog mit
path: / konfiguriert.
http://localhost:3000/catalog allein liefert deshalb 404,
Entity-Seiten liegen trotzdem unter
/catalog/<namespace>/<kind>/<name>.
Jetzt die Filter links auf der Katalogseite:
- Klicke auf Catalog. Erwartet: die Katalogseite wie
in der Abbildung, mit Kind
Componentund genau einer Beispiel-Componentexample-website. - Stelle Kind auf
API– es erscheintexample-grpc-api. ProbiereTemplate,GroupundUser, dann zurück aufComponent. - Wähle unter Lifecycle den Wert
experimental, unter Owner den Wertguests. Beobachte die Adresszeile.
Erwartet: „All Components (1)” und in der Adresszeile (dekodiert, umbrochen):
/?filters[kind]=component&filters[owners]=group:default/guests
&filters[lifecycles]=experimental&filters[user]=all&limit=20
Warum? Jeder Filter landet in der URL – gefilterte Ansichten lassen
sich als Link weitergeben. Die Beispieldaten stammen aus
examples/ (statische catalog.locations in
app-config.yaml, Tag 3).
Fortschritt speichern? Kostenlos registrieren
Drill 2: Register Existing Component
Die Datei catalog-info.yaml in
kranich/sendungs-api beschreibt eine Component und eine
API. Im GUI registrierst du sie mit der Forgejo-URL der Datei
(…/src/branch/main/… ist das Forgejo-Gegenstück zu GitHubs
…/blob/main/…).
- Klicke in der Sidebar auf Register Existing Component.
- Trage bei URL ein:
http://127.0.0.1:3300/kranich/sendungs-api/src/branch/main/catalog-info.yaml
- Klicke auf ANALYZE. Erwartet: Schritt
Review listet die Location und drei Entities – API
sendungs-api, Componentsendungs-apiund eine Locationgenerated-….
- Klicke auf IMPORT. Erwartet: Schritt Finish mit VIEW COMPONENT und REGISTER ANOTHER.
Warum funktioniert das ohne Plugin? Backstage liest die Datei über
die integrations.gitea-Einträge aus
app-config.local.yaml mit dem Token von
backstage-bot. Der Hinweis „GitHub only” rechts betrifft
nur die Repository-Variante (ganzes Repo durchsuchen und bei Bedarf
einen Pull Request anlegen) – für Forgejo gibst du immer die
vollständige Datei-URL an.
Achtung: VIEW COMPONENT springt zur ersten Entity der Datei – hier zur API
sendungs-api, nicht zur Component. Achte oben aufAPI • openapi.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Die Entity-Seite
- Klicke in der Sidebar auf Catalog und dann in der
Tabelle auf
sendungs-api. - Erwartet: die Entity-Seite wie in der Abbildung – Kopf mit
Component • service, Lifecycle und Owner, darunter die Tabs Overview, TechDocs und APIs.
Die Teile der Seite:
- About-Karte: Beschreibung, Owner, System, Tags,
Kind, Type, Lifecycle aus der YAML-Datei. VIEW SOURCE
öffnet das Repo in Forgejo, der Kreispfeil plant einen Refresh (Drill
8), der Stift (Edit Metadata) öffnet
catalog-info.yamlim Forgejo-Editor. - Provided APIs: die Relation
providesApis: [sendungs-api]als Tabelle. - Relations (weiter unten): dieselben Beziehungen als Mini-Graph.
- Tab APIs: Provided und Consumed APIs auf einer eigenen Seite. Tab TechDocs bauen wir an Tag 7 auf.
Die gelbe Warnung „This entity has relations to other entities, which
can’t be found in the catalog. Entities not found are:
group:default/team-sendung” ist gewollt:
owner: team-sendung verweist auf eine Group, die es noch
nicht gibt. Die Gruppen legst du an Tag 4 an – dann verschwindet die
Warnung.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Die API-Seite mit OpenAPI
- Klicke in der Karte Provided APIs auf
sendungs-api(Puzzle-Symbol). - Klicke auf den Tab Documentation und im Menü auf Definition.
- Erwartet: die OpenAPI-Ansicht wie in der Abbildung, mit dem Endpunkt
GET /sendungen/{id}. Der Untertab Raw zeigt die rohe YAML.
Warum steht die Spezifikation im Katalog? In
catalog-info.yaml steht
definition: { $text: ./openapi.yaml } – der Katalog lädt
die Datei relativ zur Location nach und speichert sie in
spec.definition. Die Ansicht Overview
zeigt dieselbe Definition plus Consumers und
Providers. Alle APIs auf einen Blick liefert
APIs in der Sidebar.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Zweite Component per API registrieren
Was IMPORT im GUI tut, ist ein einziger API-Aufruf.
tracking-web registrierst du so mit dem Lab-Token
(bs aus env.sh):
URL=$FORGEJO/kranich/tracking-web/src/branch/main/catalog-info.yaml
bs catalog/locations -X POST -H 'Content-Type: application/json' \
-d "{\"type\":\"url\",\"target\":\"$URL\"}" \
| jq '{location: .location.entityRef, entities}'Erwartet (Hash abweichend):
{
"location": "location:default/generated-db94e7dc525bf019d6d06a7c893a31005721c2c9",
"entities": []
}
entities ist leer, weil die Verarbeitung asynchron
läuft. Ein paar Sekunden später:
bs 'catalog/entities?filter=kind=component' | jq -r '.[].metadata.name' | sort
bs catalog/locations | jq -r '.[].data.target'Erwartet:
example-website
sendungs-api
tracking-web
http://127.0.0.1:3300/kranich/sendungs-api/src/branch/main/catalog-info.yaml
http://127.0.0.1:3300/kranich/tracking-web/src/branch/main/catalog-info.yaml
Tipp: Mit
?dryRun=trueancatalog/locationsprüft Backstage die Datei, ohne etwas anzulegen – praktisch in CI-Pipelines.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Catalog Graph und Favoriten
tracking-web deklariert
consumesApis: [sendungs-api]. Den Zusammenhang zeigt der
Catalog Graph:
- Öffne die Entity-Seite der Component
sendungs-apiund klicke in der Karte Relations auf View graph. - Die Graph-Seite öffnet sich mit MAX DEPTH
1– nur die API ist zu sehen. Setze MAX DEPTH auf2. - Erwartet: drei Knoten wie in der Abbildung. Die Root-Entity ist rot hervorgehoben.
Ein Klick auf einen Knoten macht ihn zur neuen Wurzel, Shift-Klick öffnet seine Entity-Seite. Jetzt der Favorit:
- Gehe zurück zur Component
sendungs-apiund klicke oben rechts auf den Stern (Add to favorites). - Klicke auf Catalog und links unter PERSONAL auf Starred.
- Erwartet: „Starred Components (1)” wie in der Abbildung.
Warum? Sterne sind persönliche Einstellungen der Identität
user:development/guest. Das Backend-Plugin
user-settings speichert sie in
data/user-settings.sqlite – sie überleben also
Browserwechsel und Neustarts. Owned bleibt bei 0, weil
der Gast keine Gruppe besitzt – das ändert Tag 4.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Dieselben Daten per API
Filter in der URL entsprechen der Katalog-API. Innerhalb eines
filter gilt UND (Komma), mehrere
filter-Parameter verknüpft die API mit ODER.
F='fields=metadata.name,spec.owner'
bs "catalog/entities?filter=kind=component,spec.lifecycle=production&$F" | jq -c '.[]'
bs 'catalog/entities?filter=kind=api&filter=spec.type=website' \
| jq -r '.[] | "\(.kind) \(.metadata.name)"'Erwartet:
{"metadata":{"name":"sendungs-api"},"spec":{"owner":"team-sendung"}}
{"metadata":{"name":"tracking-web"},"spec":{"owner":"team-web"}}
API example-grpc-api
API sendungs-api
Component tracking-web
Component example-website
Eine einzelne Entity holst du über die Entity-Referenz
kind/namespace/name:
bs catalog/entities/by-name/component/default/sendungs-api | jq '{
description: .metadata.description,
relations: [.relations[] | "\(.type) -> \(.targetRef)"] }'Erwartet:
{
"description": "REST-API für den Sendungsstatus",
"relations": [
"ownedBy -> group:default/team-sendung",
"providesApi -> api:default/sendungs-api"
]
}Die Zähler der Filterleiste liefern die Facetten:
bs 'catalog/entity-facets?facet=kind' | jq -c '.facets.kind[] | [.value, .count]'Erwartet:
["API",2]
["Component",3]
["Group",1]
["Location",5]
["System",1]
["Template",1]
["User",1]
Fünf Locations: drei aus app-config.yaml, zwei von dir
registriert. Mit facet=spec.owner oder
facet=metadata.tags bekommst du die Werte der übrigen
Filter.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Refresh im GUI und per API
Backstage liest jede Location ungefähr alle zwei Minuten neu. Schneller geht es mit einem Refresh. Zuerst eine Änderung in Forgejo:
mkdir -p ~/backstage-lab/tag01 && cd ~/backstage-lab/tag01
git clone -q http://lab-admin:[email protected]:3300/kranich/sendungs-api.git
cd sendungs-api
sed -i '' \
's/REST-API für den Sendungsstatus/REST-API für Sendungsstatus und Zustellprognose/' \
catalog-info.yaml
git -c user.name="Lab Admin" -c [email protected] \
commit -qam "Beschreibung erweitert" && git push -q origin main
bs catalog/entities/by-name/component/default/sendungs-api | jq -r .metadata.descriptionErwartet – der Katalog kennt noch den alten Stand:
REST-API für den Sendungsstatus
- Öffne die Component
sendungs-api. - Klicke in der About-Karte auf den Kreispfeil (Schedule entity refresh). Erwartet: die Meldung „Refresh scheduled”.
- Lade die Seite nach ein paar Sekunden neu. Erwartet: DESCRIPTION zeigt „REST-API für Sendungsstatus und Zustellprognose”.
Dasselbe per API, diesmal mit einem neuen Tag für
tracking-web:
cd ~/backstage-lab/tag01
git clone -q http://lab-admin:[email protected]:3300/kranich/tracking-web.git
cd tracking-web
sed -i '' 's/tags: \[web\]/tags: [web, kunde]/' catalog-info.yaml
git -c user.name="Lab Admin" -c [email protected] \
commit -qam "Tag kunde" && git push -q origin main
bs catalog/refresh -X POST -H 'Content-Type: application/json' \
-d '{"entityRef":"component:default/tracking-web"}' -w '%{http_code}\n'
sleep 3
bs catalog/entities/by-name/component/default/tracking-web | jq -c .metadata.tagsErwartet:
200
["web","kunde"]
Warum? Refresh setzt die Entity in der Verarbeitungsschlange nach vorn. Backstage liest dabei die Quelldatei neu. Das Repo selbst ist die Wahrheit – Änderungen im GUI gibt es im Katalog nicht.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
cat > ~/backstage-lab/tag01/kontrolle.sh <<'EOF'
#!/usr/bin/env bash
# kontrolle.sh – Kontrollpunkt Tag 1 (✔/✘). Exit-Code = Anzahl Fehler.
source ~/backstage-lab/setup/env.sh
fail=0
t() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"
else echo "✘ $1"; fail=$((fail+1)); fi; }
e() { bs "catalog/entities/by-name/$1"; }
t "Component sendungs-api im Katalog" "e component/default/sendungs-api"
t "API sendungs-api im Katalog" "e api/default/sendungs-api"
t "Component tracking-web im Katalog" "e component/default/tracking-web"
t "tracking-web konsumiert die API" \
"e component/default/tracking-web | jq -e '.relations[] |
select(.type==\"consumesApi\" and .targetRef==\"api:default/sendungs-api\")'"
t "Neue Beschreibung angekommen (Refresh)" \
"e component/default/sendungs-api | jq -e '.metadata.description | test(\"Zustell\")'"
t "Zwei Forgejo-Locations registriert" \
"[ \$(bs catalog/locations | jq '[.[].data.target | select(test(\"/kranich/\"))]
| length') -ge 2 ]"
exit "$fail"
EOF
bash ~/backstage-lab/tag01/kontrolle.shErwartet:
✔ Component sendungs-api im Katalog
✔ API sendungs-api im Katalog
✔ Component tracking-web im Katalog
✔ tracking-web konsumiert die API
✔ Neue Beschreibung angekommen (Refresh)
✔ Zwei Forgejo-Locations registriert
Challenge
Lege aus ~/backstage-lab/code/tag01/zustell-worker das
Repo kranich/zustell-worker an, registriere es per
Register Existing Component im GUI und finde danach per
API alle Components mit Lifecycle experimental.
Hinweis: mkrepo.sh aus
setup/ legt das Repo an, der Filter kombiniert
kind und spec.lifecycle mit Komma.
Lösung
~/backstage-lab/setup/mkrepo.sh kranich/zustell-worker \
~/backstage-lab/code/tag01/zustell-workerErwartet:
✔ kranich/zustell-worker angelegt (http://127.0.0.1:3300/kranich/zustell-worker)
Im GUI: Register Existing Component →
URL
http://127.0.0.1:3300/kranich/zustell-worker/src/branch/main/catalog-info.yaml
→ ANALYZE → IMPORT. Der Review-Schritt
zeigt „Entities: 2” (Component und Location). Dann:
F='fields=metadata.name,spec.owner'
bs "catalog/entities?filter=kind=component,spec.lifecycle=experimental&$F" | jq -c '.[]'Erwartet:
{"metadata":{"name":"zustell-worker"},"spec":{"owner":"team-sendung"}}
{"metadata":{"name":"example-website"},"spec":{"owner":"guests"}}
Im GUI liefert Lifecycle experimental
dieselben zwei Zeilen. Im Catalog Graph der API hängt
zustell-worker nun als zweiter Consumer.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- „Register Existing Component” ist für Einzelfälle gedacht. In Produktion entdecken Entity-Provider alle Repos einer Org automatisch (Gitea-Provider an Tag 3, bei GitHub/GitLab die jeweiligen Discovery-Module).
- Wer im GUI registrieren darf, regeln Berechtigungen
(
catalog.location.create, Tag 12). Sonst kann jeder beliebige URLs einlesen lassen. - Die Integration braucht nur Lesezugriff. Für den Katalog reicht ein
Token mit
read:repository. Schreibrechte braucht erst der Scaffolder. - Datei-URLs anderer Plattformen: GitHub
…/<org>/<repo>/blob/main/catalog-info.yaml, GitLab…/<gruppe>/<repo>/-/blob/main/catalog-info.yaml. Die Repository-Variante mit automatischem Pull Request bietet der Wizard nur für GitHub an. - Der Refresh-Takt (
catalog.processingInterval) und API-Rate-Limits der Git-Plattform hängen zusammen. Bei Tausenden Repos lieber Webhooks/Events nutzen statt kurzer Intervalle.