Skip to content
Hands-on IT IT Drills

Day 1: First Tour

Goal: You find your way around the portal, register the first Forgejo repos in the Software Catalog and read the same data via the API. · Duration: approx. 90 min · Prerequisite: Day 0

Briefing

  • The Software Catalog is the heart of Backstage: every entity (Component, API, Group …) comes from a YAML file, usually catalog-info.yaml in the repo.
  • A Location points to such a file. Backstage reads it, processes the entities and refreshes them periodically.
  • Everything the user interface shows is delivered by the catalog API at /api/catalog.
Forgejo repo                  Backstage backend                    Frontend
catalog-info.yaml ─► Location ─► Processing ─► Entities ─► /api/catalog ─► catalog page
        ▲                           │ every ~2 min or via refresh
        └───────────────────────────┘

Drill 1: Guest Login, Sidebar and Filters

The starting point is the end of Day 0: Forgejo is running, the org kranich is filled, app-config.local.yaml exists and the portal is started.

source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
~/backstage-lab/setup/check.sh | tail -3

Expected:

✔ 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
  1. Open http://localhost:3000 and click Enter for the Guest provider.
  2. Click Settings at the bottom of the sidebar. Under Profile it says user:development/guest – that is your identity until Day 12.
  3. Go through the sidebar from top to bottom.
Entry Path Purpose
Home /home Home page with widgets (on / from Day 9 on)
Catalog / Software Catalog – the start page here
Create /create Software Templates (Day 5)
APIs /api-docs all API entities
Catalog Graph /catalog-graph Relations as a graph
Docs /docs TechDocs (Day 7)
Register Existing Component /catalog-import Register a location
Visualizer /visualizer Extension tree (from Day 9 on “App-Struktur”)

The catalog lives at / because app-config.yaml configures the extension page:catalog with path: /. That is why http://localhost:3000/catalog on its own returns 404; entity pages are still at /catalog/<namespace>/<kind>/<name>.

Now the filters on the left of the catalog page:

  1. Click Catalog. Expected: the catalog page as in the figure, with Kind Component and exactly one example component, example-website.
  2. Set Kind to API – example-grpc-api appears. Try Template, Group and User, then go back to Component.
  3. Under Lifecycle select the value experimental, under Owner the value guests. Watch the address bar.
Catalog page with the filter bar and the example component

Expected: “All Components (1)” and in the address bar (decoded, wrapped):

/?filters[kind]=component&filters[owners]=group:default/guests
  &filters[lifecycles]=experimental&filters[user]=all&limit=20

Why? Every filter ends up in the URL – filtered views can be shared as a link. The example data comes from examples/ (static catalog.locations in app-config.yaml, Day 3).

Save your progress? Sign up for free

Drill 2: Register Existing Component

The file catalog-info.yaml in kranich/sendungs-api describes a Component and an API. In the GUI you register it with the Forgejo URL of the file (…/src/branch/main/… is the Forgejo counterpart to GitHub’s …/blob/main/…).

  1. Click Register Existing Component in the sidebar.
  2. Enter under URL: http://127.0.0.1:3300/kranich/sendungs-api/src/branch/main/catalog-info.yaml
Select URL step with the Forgejo URL of catalog-info.yaml
  1. Click ANALYZE. Expected: the Review step lists the location and three entities – API sendungs-api, Component sendungs-api and a Location generated-….
Review step with the three entities found
  1. Click IMPORT. Expected: the Finish step with VIEW COMPONENT and REGISTER ANOTHER.
Finish step after the import

Why does this work without a plugin? Backstage reads the file via the integrations.gitea entries from app-config.local.yaml with the token of backstage-bot. The “GitHub only” note on the right only applies to the repository variant (search the whole repo and create a pull request if needed) – for Forgejo you always enter the full file URL.

Warning: VIEW COMPONENT jumps to the first entity in the file – here to the API sendungs-api, not to the Component. Look for API • openapi at the top.

Save your progress? Sign up for free

Drill 3: The Entity Page

  1. Click Catalog in the sidebar and then sendungs-api in the table.
  2. Expected: the entity page as in the figure – header with Component • service, Lifecycle and Owner, below it the tabs Overview, TechDocs and APIs.
Entity page of the component sendungs-api with a warning and the About card

The parts of the page:

  • About card: description, owner, system, tags, kind, type, lifecycle from the YAML file. VIEW SOURCE opens the repo in Forgejo, the circular arrow schedules a refresh (Drill 8), the pencil (Edit Metadata) opens catalog-info.yaml in the Forgejo editor.
  • Provided APIs: the relation providesApis: [sendungs-api] as a table.
  • Relations (further down): the same relations as a mini graph.
  • APIs tab: provided and consumed APIs on a page of their own. We set up the TechDocs tab on Day 7.

The yellow warning “This entity has relations to other entities, which can’t be found in the catalog. Entities not found are: group:default/team-sendung” is intended: owner: team-sendung refers to a group that does not exist yet. You create the groups on Day 4 – then the warning disappears.

Save your progress? Sign up for free

Drill 4: The API Page with OpenAPI

  1. In the Provided APIs card, click sendungs-api (puzzle icon).
  2. Click the Documentation tab and then Definition in the menu.
  3. Expected: the OpenAPI view as in the figure, with the endpoint GET /sendungen/{id}. The Raw sub-tab shows the raw YAML.
Definition of the API sendungs-api as an OpenAPI view

Why is the specification in the catalog? catalog-info.yaml contains definition: { $text: ./openapi.yaml } – the catalog loads the file relative to the location and stores it in spec.definition. The Overview view shows the same definition plus Consumers and Providers. APIs in the sidebar gives you all APIs at a glance.

Save your progress? Sign up for free

Drill 5: Registering a Second Component via the API

What IMPORT does in the GUI is a single API call. You register tracking-web like this with the lab token (bs from 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}'

Expected (hash differs):

{
  "location": "location:default/generated-db94e7dc525bf019d6d06a7c893a31005721c2c9",
  "entities": []
}

entities is empty because processing runs asynchronously. A few seconds later:

bs 'catalog/entities?filter=kind=component' | jq -r '.[].metadata.name' | sort
bs catalog/locations | jq -r '.[].data.target'

Expected:

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

Tip: With ?dryRun=true on catalog/locations, Backstage checks the file without creating anything – handy in CI pipelines.

Save your progress? Sign up for free

Drill 6: Catalog Graph and Favorites

tracking-web declares consumesApis: [sendungs-api]. The Catalog Graph shows the connection:

  1. Open the entity page of the component sendungs-api and click View graph in the Relations card.
  2. The graph page opens with MAX DEPTH 1 – only the API is visible. Set MAX DEPTH to 2.
  3. Expected: three nodes as in the figure. The root entity is highlighted in red.
Catalog Graph with tracking-web, the API and the component sendungs-api

Clicking a node makes it the new root; Shift-click opens its entity page. Now the favorite:

  1. Go back to the component sendungs-api and click the star at the top right (Add to favorites).
  2. Click Catalog and, on the left under PERSONAL, Starred.
  3. Expected: “Starred Components (1)” as in the figure.
Catalog with the Starred filter active

Why? Stars are personal settings of the identity user:development/guest. The backend plugin user-settings stores them in data/user-settings.sqlite – so they survive switching browsers and restarts. Owned stays at 0 because the guest does not belong to any group – Day 4 changes that.

Save your progress? Sign up for free

Drill 7: The Same Data via the API

Filters in the URL correspond to the catalog API. Within one filter, AND applies (comma); the API combines multiple filter parameters with OR.

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)"'

Expected:

{"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

You fetch a single entity via the entity reference kind/namespace/name:

bs catalog/entities/by-name/component/default/sendungs-api | jq '{
  description: .metadata.description,
  relations: [.relations[] | "\(.type) -> \(.targetRef)"] }'

Expected:

{
  "description": "REST-API für den Sendungsstatus",
  "relations": [
    "ownedBy -> group:default/team-sendung",
    "providesApi -> api:default/sendungs-api"
  ]
}

The counters in the filter bar come from the facets:

bs 'catalog/entity-facets?facet=kind' | jq -c '.facets.kind[] | [.value, .count]'

Expected:

["API",2]
["Component",3]
["Group",1]
["Location",5]
["System",1]
["Template",1]
["User",1]

Five locations: three from app-config.yaml, two registered by you. With facet=spec.owner or facet=metadata.tags you get the values of the other filters.

Save your progress? Sign up for free

Drill 8: Refresh in the GUI and via the API

Backstage rereads every location roughly every two minutes. A refresh is faster. First a change 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.description

Expected – the catalog still knows the old state (“REST API for the shipment status”):

REST-API für den Sendungsstatus
  1. Open the component sendungs-api.
  2. In the About card, click the circular arrow (Schedule entity refresh). Expected: the message “Refresh scheduled”.
  3. Reload the page after a few seconds. Expected: DESCRIPTION shows “REST-API für Sendungsstatus und Zustellprognose” (“REST API for shipment status and delivery forecast”).

The same via the API, this time with a new tag for 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.tags

Expected:

200
["web","kunde"]

Why? A refresh moves the entity to the front of the processing queue. Backstage rereads the source file in the process. The repo itself is the source of truth – the catalog has no editing in the GUI.

Save your progress? Sign up for free

Checkpoint

cat > ~/backstage-lab/tag01/kontrolle.sh <<'EOF'
#!/usr/bin/env bash
# kontrolle.sh – checkpoint Day 1 (✔/✘). Exit code = number of failures.
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.sh

Expected:

✔ 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

Create the repo kranich/zustell-worker from ~/backstage-lab/code/tag01/zustell-worker, register it in the GUI via Register Existing Component, and then use the API to find all components with lifecycle experimental.

Hint: mkrepo.sh from setup/ creates the repo; the filter combines kind and spec.lifecycle with a comma.

Solution

~/backstage-lab/setup/mkrepo.sh kranich/zustell-worker \
  ~/backstage-lab/code/tag01/zustell-worker

Expected:

✔ kranich/zustell-worker angelegt (http://127.0.0.1:3300/kranich/zustell-worker)

In the GUI: Register Existing Component → URL http://127.0.0.1:3300/kranich/zustell-worker/src/branch/main/catalog-info.yaml → ANALYZE → IMPORT. The Review step shows “Entities: 2” (Component and Location). Then:

F='fields=metadata.name,spec.owner'
bs "catalog/entities?filter=kind=component,spec.lifecycle=experimental&$F" | jq -c '.[]'

Expected:

{"metadata":{"name":"zustell-worker"},"spec":{"owner":"team-sendung"}}
{"metadata":{"name":"example-website"},"spec":{"owner":"guests"}}

In the GUI, Lifecycle experimental returns the same two rows. In the Catalog Graph of the API, zustell-worker now hangs as a second consumer.

Save your progress? Sign up for free

Enterprise Note

  • “Register Existing Component” is meant for individual cases. In production, entity providers discover all repos of an org automatically (Gitea provider on Day 3, for GitHub/GitLab the respective discovery modules).
  • Who may register in the GUI is governed by permissions (catalog.location.create, Day 12). Otherwise anyone can have arbitrary URLs ingested.
  • The integration only needs read access. For the catalog, a token with read:repository is enough. Only the Scaffolder needs write permissions.
  • File URLs on other platforms: GitHub …/<org>/<repo>/blob/main/catalog-info.yaml, GitLab …/<gruppe>/<repo>/-/blob/main/catalog-info.yaml. The wizard offers the repository variant with an automatic pull request only for GitHub.
  • The refresh interval (catalog.processingInterval) and API rate limits of the Git platform are related. With thousands of repos, prefer webhooks/events over short intervals.