Appendix A: Cheat Sheet
State of the book: Backstage 1.55.0
(@backstage/[email protected], new frontend and backend
system) on Node 24 LTS (24.21.0) with Yarn 4 via Corepack, Forgejo
16.0.6 (rootless) in Docker, PostgreSQL 16.4. Names match the lab: org
kranich, app ~/backstage-lab/portal. All
passwords and tokens are lab values.
Lab environment
source ~/backstage-lab/setup/env.sh # LAB, PORTAL, PATH, FORGEJO, tokens, bs()
~/backstage-lab/setup/check.sh # check the training ground, exit code = number of ✘
~/backstage-lab/setup/up.sh # start Forgejo, admin, bot, bot token
~/backstage-lab/setup/seed.sh # org kranich + sendungs-api, tracking-web
~/backstage-lab/setup/seed.sh --reset # both repos back to the Day 0 state
~/backstage-lab/setup/mkrepo.sh kranich/org ~/backstage-lab/tag04/org
~/backstage-lab/setup/portal.sh start # yarn start in the background, waits
~/backstage-lab/setup/portal.sh restart # after yarn add / app-config*.yaml
~/backstage-lab/setup/portal.sh stop|status
~/backstage-lab/setup/portal.sh logs 300 # last 300 lines of portal.log
docker start bs-postgres # from Day 13 on, before every start
env.sh defines bs – a curl
against the Backstage API with the lab token:
bs() { local p="$1"; shift; curl -sf -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
"$@" "$BACKSTAGE/api/$p"; }
bs catalog/entities?limit=1 # GET
bs catalog/refresh -X POST -H 'Content-Type: application/json' -d '{…}'
bs uses curl -f and swallows error texts.
For the error message, use
curl -s -H "Authorization: Bearer $BACKSTAGE_TOKEN" …
directly and jq .error.message.
env.sh grows: from Day 7
export PATH="$LAB/venv/bin:$PATH", from Day 12 it loads
setup/oidc-client, from Day 13
tag13/pg.env.
portal.sh start overwrites portal.log.
Remove color codes: sed 's/\x1b\[[0-9;]*m//g'. If you start
yarn start by hand, load env.sh first
(otherwise ${LAB}, ${FORGEJO_TOKEN} are empty
and there is no mkdocs).
- All
sed -i '' in the book are macOS syntax; on Linux
use sed -i.
Ports, URLs and lab values
| What |
Value in the lab |
| Frontend (dev) / backend |
http://localhost:3000 /
http://localhost:7007 |
| Production operation (Day 13) |
everything on http://localhost:7007 |
| Forgejo web / API |
http://127.0.0.1:3300 / …/api/v1 |
| Forgejo container, volumes |
bs-forgejo, bs-forgejo-data,
bs-forgejo-conf |
| Forgejo admin |
lab-admin / lab-admin-pw-123, in
env.sh as $ADMIN |
| Bot |
backstage-bot, token in
~/backstage-lab/setup/forgejo-token |
| Forgejo users (Day 12) |
anna.berger, thomas.zachmann /
lab-user-pw-123 |
| Lab token (service) |
lab-cli-token-0123456789abcdef, subject
lab-cli |
| Read-only token (Day 12) |
lab-ro-token-0123456789abcdef, subject
lab-readonly |
| PostgreSQL (Day 13) |
bs-postgres, 127.0.0.1:5432,
backstage / lab-pg-pw-123 |
| kind (Day 10) |
cluster backstage-lab,
~/backstage-lab/tag10/kubeconfig |
| SQLite (until Day 12) |
~/backstage-lab/data/<plugin>.sqlite |
| Guest identity |
user:development/guest; Days 4–11
user:default/thomas.zachmann |
| Page |
Path |
| Catalog |
/ until Day 8, /catalog from Day 9 (then
/ = home page) |
| Entity page |
/catalog/<namespace>/<kind>/<name> |
| Catalog filtered |
/?filters[kind]=template (from Day 9
/catalog?…) |
| Templates, wizard, task |
/create,
/create/templates/default/<name>,
/create/tasks/<id> |
| APIs, graph, docs |
/api-docs, /catalog-graph,
/docs |
| TechDocs of an entity |
/docs/default/component/<name> |
| Register, search |
/catalog-import, /search?query=… |
| Visualizer |
/visualizer (from Day 9 the entry is called
App-Struktur) |
Forgejo file URL for the catalog:
http://127.0.0.1:3300/kranich/<repo>/src/branch/main/catalog-info.yaml
(GitHub …/blob/main/…, GitLab
…/-/blob/main/…). OIDC callback:
http://localhost:7007/api/auth/oidc/handler/frame.
Repos in kranich: sendungs-api,
tracking-web (Day 0), zustell-worker (Day 1),
sendungsverfolgung (Day 2), katalog,
zustell-app (Day 3), org (Day 4),
templates, lager-api,
lager-worker, tour-api (Day 5),
lager-scanner, lager-etiketten,
paket-api (Day 6).
Forgejo one-liners
GIT=http://lab-admin:[email protected]:3300 # lab value!
git clone -q $GIT/kranich/sendungs-api.git
git -c user.name="Lab Admin" -c [email protected] commit -qam "…"
R=$FORGEJO/api/v1/repos/kranich/lager-api
curl -sf -u "$ADMIN" "$R" | jq '{full_name, default_branch, private}'
curl -sf -u "$ADMIN" "$R/contents" | jq -r '.[].path'
curl -sf -u "$ADMIN" "$R/raw/catalog-info.yaml"
curl -s -H "Authorization: token $FORGEJO_TOKEN" "$FORGEJO/api/v1/user" | jq .login
docker exec "$FORGEJO_NAME" forgejo admin user create --username anna.berger \
--password lab-user-pw-123 --email [email protected] \
--must-change-password=false
curl -s "$FORGEJO/.well-known/openid-configuration" | jq .issuer
Entity kinds
Every entity has apiVersion, kind,
metadata, spec; separate multiple entities per
file with ---. The catalog sets uid,
etag and relations (Day 2).
| Kind |
apiVersion |
spec in the book |
Day |
| Component |
backstage.io/v1alpha1 |
type, lifecycle, owner
(required), system |
1, 2 |
| API |
backstage.io/v1alpha1 |
type, lifecycle, owner,
system, definition |
1, 8 |
| System |
backstage.io/v1alpha1 |
owner, domain |
2 |
| Domain |
backstage.io/v1alpha1 |
owner |
2 |
| Resource |
backstage.io/v1alpha1 |
type, owner, system |
2, 3 |
| Group |
backstage.io/v1alpha1 |
type, parent, profile,
children (required) |
4 |
| User |
backstage.io/v1alpha1 |
profile (displayName, email),
memberOf |
4 |
| Location |
backstage.io/v1alpha1 |
targets (relative to the file) |
3, 5 |
| Template |
scaffolder.backstage.io/v1beta3 |
owner, type, parameters,
steps, output |
5 |
metadata.name: sequences of [a-zA-Z0-9],
separated by -_., at most 63 characters; uppercase letters
allowed, spaces not (Day 2).
spec.type is free-form (service,
website, database,
external-service, organization,
department, team); API types with their own
view: openapi, asyncapi, graphql,
grpc, trpc – everything else as text (Day
8).
definition inline as a | block (Day 2) or
definition: { $text: ./openapi.yaml } relative to
catalog-info.yaml (Days 1, 8).
- Group: maintain only
parent, leave
children: []; members via user memberOf or
group members (Day 4).
| Metadata field |
Effect (Day 2) |
metadata.title |
Display name instead of name |
metadata.description |
Description in the About card and search |
metadata.tags |
Chips and the Tags filter; only
a-z0-9+#, joined with - |
metadata.labels |
Labels card, your own with a company prefix
(kranich.de/…) |
metadata.links |
Links card: url, title,
icon (dashboard, docs, …) |
metadata.annotations |
Interface to plugins |
metadata.namespace |
Default default |
Annotations
| Annotation |
Meaning |
Day |
backstage.io/techdocs-ref: dir:. |
mkdocs.yml is next to
catalog-info.yaml |
7 |
backstage.io/kubernetes-id: <id> |
Kubernetes tab, label selector in the cluster |
2, 10 |
backstage.io/kubernetes-label-selector |
Alternative for name collisions |
10 |
backstage.io/managed-by-location |
Location the entity comes from (catalog) |
2, 3 |
backstage.io/managed-by-origin-location |
Originally registered location |
3 |
backstage.io/source-location |
Source for View Source (catalog) |
2 |
backstage.io/edit-url, …/view-url |
Pencil and View Source (catalog) |
2 |
backstage.io/orphan: "true" |
Entity without a source (catalog) |
3 |
Relations
Field in spec |
Relation |
Reverse direction |
owner |
ownedBy |
ownerOf |
system, domain |
partOf |
hasPart |
dependsOn |
dependsOn |
dependencyOf |
providesApis |
providesApi |
apiProvidedBy |
consumesApis |
consumesApi |
apiConsumedBy |
parent (Group) |
childOf |
parentOf |
memberOf (User), members (Group) |
memberOf |
hasMember |
Queries and the UI work with relations, not with spec
(Day 4). Catalog Graph: starts with MAX DEPTH 1; with
Simplified off it shows both directions (Day 2).
Include indirect ownership follows
parentOf downward (Day 4).
Entity references
| Form |
Example |
Where |
kind:namespace/name |
group:default/team-sendung |
Relations, filters, tokens |
kind:name |
resource:sendungs-db |
dependsOn (kind required) |
name |
team-sendung |
owner (→ group), system,
domain |
kind/namespace/name |
component/default/sendungs-api |
API path by-name/… |
- The catalog adds the namespace
default and the field’s
default kind (Day 2).
- In API filters, only the full form works:
relations.dependsOn=resource:default/sendungs-db finds
something, resource:sendungs-db doesn’t (Day 2).
OwnerPicker and EntityPicker return full
references; the generated repo then contains
owner: group:default/team-sendung (Days 5, 6).
Catalog API
bs catalog/entities | jq -r '.[] | "\(.kind)\t\(.metadata.name)"'
bs 'catalog/entities?filter=kind=component'
bs 'catalog/entities?filter=kind=component,spec.lifecycle=production' # AND
bs 'catalog/entities?filter=kind=api&filter=spec.type=website' # OR
bs 'catalog/entities?filter=kind=group,kind=user&fields=kind,metadata.name'
bs 'catalog/entities?filter=spec.system=sendungsverfolgung'
bs 'catalog/entities?filter=relations.ownedBy=group:default/team-web'
bs 'catalog/entities?filter=relations.dependsOn=resource:default/sendungs-db'
bs 'catalog/entities?filter=metadata.annotations.backstage.io/orphan=true'
bs 'catalog/entities?fields=kind,metadata.name,status' \
| jq '.[] | select(.status.items)' # processing errors
bs catalog/entities/by-name/component/default/sendungs-api
bs catalog/entities/by-name/component/default/tracking-web/ancestry
bs catalog/entities/by-uid/$uid -X DELETE -w '%{http_code}\n' # 204
bs catalog/entities/by-refs -X POST -H 'Content-Type: application/json' \
-d '{"entityRefs":["group:default/it"],"fields":["kind"]}' # missing: null
bs 'catalog/entity-facets?facet=kind' # also spec.owner, metadata.tags,
bs 'catalog/entity-facets?facet=relations.ownedBy' # relations.…
bs catalog/refresh -X POST -H 'Content-Type: application/json' \
-d '{"entityRef":"component:default/tracking-web"}'
bs catalog/locations | jq -r '.[].data | "\(.id) \(.type) \(.target)"'
bs catalog/locations -X POST -H 'Content-Type: application/json' \
-d "{\"type\":\"url\",\"target\":\"$URL\"}" # entities: [] = asynchronous
curl -s -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
-H 'Content-Type: application/json' -X POST \
"$BACKSTAGE/api/catalog/locations?dryRun=true" \
-d "{\"type\":\"url\",\"target\":\"$URL\"}" | jq -r '.error.message // "ok"'
bs catalog/locations/$id -X DELETE -w '%{http_code}\n' # 204
catalog/locations lists only locations registered via
API/GUI, not those from the configuration or from the provider (Day
3).
- Delete of an entity helps only briefly: the
location brings it back with a new
uid. It is gone for good
only together with the location (Unregister Location)
(Day 3).
- Errors of an entity:
.status.items[] | .error.cause.message (Day 2).
More API endpoints
bs scaffolder/v2/actions | jq -r '.[].id'
bs scaffolder/v2/templating-extensions | jq -r '.filters | keys[]'
bs 'scaffolder/v2/tasks?limit=1' # .tasks[0].status, .createdBy
bs 'scaffolder/v2/tasks?createdBy=user:default/thomas.zachmann'
bs 'scaffolder/v2/tasks?limit=3&order=desc:created_at'
bs scaffolder/v2/tasks -X POST -H 'Content-Type: application/json' -d @auftrag.json
bs scaffolder/v2/tasks/$ID # status, spec.parameters
bs scaffolder/v2/tasks/$ID/events | jq -r '.[].body.message'
bs scaffolder/v2/tasks/$ID/cancel -X POST # {"status":"cancelled"}
bs scaffolder/v2/dry-run -X POST -H 'Content-Type: application/json' -d @-
bs techdocs/sync/default/component/sendungs-api -N # build log as SSE
bs techdocs/metadata/techdocs/default/component/sendungs-api | jq .etag
bs techdocs/static/docs/default/component/sendungs-api/index.html
bs 'search/query?term=sendung&types%5B0%5D=software-catalog&filters%5Bkind%5D=API'
bs kubernetes/clusters | jq -c '.items[]'
bs kubernetes/services/sendungs-api -X POST -H 'Content-Type: application/json' \
-d '{"entity":{"kind":"Component","metadata":{"name":"sendungs-api"}}}'
bs proxy/forgejo/orgs/kranich/repos | jq -r '.[].full_name'
bs 'bereitschaft/heute?team=team-sendung' # your own plugin (Day 11)
curl -s -H 'X-Requested-With: XMLHttpRequest' "$BACKSTAGE/api/auth/guest/refresh" \
| jq .backstageIdentity.identity # .token = guest token
curl -s "$BACKSTAGE/.backstage/health/v1/readiness" # without login
bs catalog/entities/unprocessed/pending | jq '.entities | length' # Day 14
bs catalog/entities/unprocessed/failed | jq '.entities | length'
bs devtools/info | jq -r .backstageVersion
bs devtools/config | jq .config.integrations # secrets as <secret>
| Endpoint |
Body or note |
Day |
POST scaffolder/v2/tasks |
templateRef, values, optional
secrets |
6 |
POST scaffolder/v2/dry-run |
template (JSON), values,
directoryContents (base64) |
6 |
POST permission/authorize |
{"items":[{"id","permission":{"type":"basic","name"}}]} |
12 |
GET auth/oidc/start?env=development |
302 to Forgejo /login/oauth/authorize |
12 |
Without a token, every plugin responds with 401
Missing credentials; with a wrong token,
Illegal token (Days 0, 11). Tasks via the lab token have
createdBy: null, and in the GUI the owner is
Unknown (Day 6).
app-config: files and merging
| Rule |
Day |
app-config.yaml (checked in) <
app-config.local.yaml (local via
.gitignore) |
0 |
| Objects are merged key by key, lists are replaced
completely |
3, 9 |
No duplicate top-level keys: append new blocks, otherwise
yq -i |
4, 7 |
${VAR} from the environment; if it is missing, the key
silently disappears |
0, 13 |
${VAR:-default} fallback value, $$ a real
dollar sign |
13 |
--config a.yaml --config b.yaml: the later one
wins |
13 |
APP_CONFIG_<path> with _ as
separator, value as JSON or text; always wins |
13 |
app.extensions only in app-config.yaml,
never in the local file |
9 |
Sequence: change → config:check →
portal.sh restart |
14 |
config:print masks visibility: secret as
<secret>; --with-secrets shows plain
text |
14 |
cd ~/backstage-lab/portal
yarn backstage-cli config:print --lax | grep -A5 '^techdocs:' # merged
yarn backstage-cli config:print --frontend --format json 2>/dev/null \
| jq -r '.app.extensions[] | keys[0]' # what the browser sees
yarn backstage-cli config:print --config app-config.yaml \
--config app-config.local.yaml --config app-config.production.yaml \
2>/dev/null | yq '.backend.database' # secrets: <secret>
yarn backstage-cli config:check # schema, YAML
yarn backstage-cli config:check --strict --config app-config.yaml \
--config k.yaml # also unknown keys (false alarms possible)
yarn backstage-cli config:schema --merge --format json > schema.json # into a file!
grep -c '^auth:' app-config.local.yaml # 1 = no duplicate
yq -i 'del(.auth)' app-config.local.yaml
app-config: catalog
catalog:
processingInterval: { seconds: 20 } # default random 100–150 s (Day 3)
# orphanStrategy: keep # default delete; cleanup job every 30 s
rules:
- allow: [Component, System, API, Resource, Location, Domain]
- allow: [Template] # global, but only from this repo (Day 5)
locations:
- type: url
pattern: http://127.0.0.1:3300/kranich/templates/**
locations: # replaces the list from app-config.yaml!
- type: file # relative to packages/backend
target: ../../examples/entities.yaml
- type: url
target: http://127.0.0.1:3300/kranich/katalog/src/branch/main/locations.yaml
- type: url
target: http://127.0.0.1:3300/kranich/org/src/branch/main/org.yaml
rules: # applies only to exactly this file
- allow: [User, Group]
- type: url
target: http://127.0.0.1:3300/kranich/templates/src/branch/main/templates.yaml
providers:
gitea:
kranich: # task gitea-provider:kranich:refresh
host: 127.0.0.1:3300 # must match integrations.gitea
organization: kranich
branch: main # default main
catalogPath: catalog-info.yaml # default catalog-info.yaml
schedule: # required
frequency: { minutes: 1 }
timeout: { minutes: 1 }
- create-app allows only
Component, System, API, Resource, Location;
rules on a location do not apply to its
targets – hence pattern (Days 2, 5).
type: file reads from the backend’s file system;
${LAB} works (Day 3).
- Collection repos (
katalog, templates)
deliberately don’t use catalog-info.yaml, so that the
provider doesn’t ingest them under the global rules (Days 3, 5).
- Removing a provider deletes its entities
(
orphanProviderStrategy, default delete) (Day
3).
app-config: integration, backend, auth
integrations:
gitea:
- host: 127.0.0.1:3300
baseUrl: http://127.0.0.1:3300
username: backstage-bot
password: ${FORGEJO_TOKEN}
backend:
auth:
externalAccess:
- type: static
options:
token: ${BACKSTAGE_TOKEN}
subject: lab-cli # service principal: bypasses the policy
- type: static
options:
token: lab-ro-token-0123456789abcdef
subject: lab-readonly
accessRestrictions: # plugin, permission, permissionAttribute
- plugin: catalog
permissionAttribute: { action: read }
cors:
origin: http://localhost:3000 # from app-config.yaml; matches app.baseUrl
logger: # Day 14, takes effect without restart
overrides:
- matchers: { plugin: catalog } # value or regex in /…/
level: debug
database: # until Day 12: SQLite, one file per plugin
client: better-sqlite3
connection:
directory: ${LAB}/data
auth:
environment: development
session:
secret: ${AUTH_SESSION_SECRET} # required for OIDC (Day 12)
providers:
guest: {} # Day 4: userEntityRef: user:default/…
oidc:
development: # name from auth.environment
metadataUrl: http://127.0.0.1:3300/.well-known/openid-configuration
clientId: ${OIDC_CLIENT_ID}
clientSecret: ${OIDC_CLIENT_SECRET}
signIn:
resolvers: # tried in order
- resolver: emailMatchingUserEntityProfileEmail
- resolver: emailLocalPartMatchingUserEntityName
From Day 13 on, in the local file and in
app-config.production.yaml:
backend:
database:
client: pg # pluginDivisionMode: database (default)
connection:
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
Guest provider keys: userEntityRef (default
user:development/guest), ownershipEntityRefs,
dangerouslyAllowOutsideDevelopment (Days 4, 13). OIDC
module: metadataUrl, clientId,
clientSecret, optionally prompt,
additionalScopes (Day 12).
app-config: TechDocs, search, Kubernetes, proxy, permission
techdocs: # template: runIn: 'docker'
builder: local # CI setup: external
generator:
runIn: local # mkdocs from the PATH (venv)
publisher:
type: local # object storage: awsS3, googleGcs
search:
collators: # default PT10M
catalog:
schedule:
frequency: { minutes: 1 }
timeout: { minutes: 5 }
techdocs:
schedule:
frequency: { minutes: 1 }
timeout: { minutes: 5 }
kubernetes:
serviceLocatorMethod:
type: multiTenant
clusterLocatorMethods:
- type: config
clusters:
- name: backstage-lab
url: $K8S_URL # substituted by the shell when appending
authProvider: serviceAccount
serviceAccountToken: $K8S_TOKEN
caData: $K8S_CA # lab alternative: skipTLSVerify: true
skipMetricsLookup: true # kind has no metrics-server
proxy:
endpoints:
/forgejo: # → /api/proxy/forgejo/…
target: http://127.0.0.1:3300/api/v1
headers:
Authorization: token ${FORGEJO_TOKEN}
allowedMethods: [GET] # credentials: require is the default
permission:
enabled: true # already in app-config.yaml
devTools: # Day 14
scheduledTasks:
plugins: [catalog, search]
bereitschaft: # your own plugin (Day 11)
teams:
team-sendung: [anna.berger, ben.kraus]
Software Templates
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: node-service
title: Node.js-Service
spec:
owner: plattform
type: service
parameters: # one wizard step per list entry
- title: Service
required: [name, description, owner]
properties:
name:
type: string
pattern: '^[a-z][a-z0-9-]{2,30}$'
ui:autofocus: true
description:
type: string
owner:
type: string
ui:field: OwnerPicker
ui:options:
catalogFilter: { kind: Group, spec.type: team }
- title: Repository
required: [repoUrl]
properties:
repoUrl:
type: string
ui:field: RepoUrlPicker # → 127.0.0.1:3300?owner=kranich&repo=x
ui:options:
allowedHosts: ['127.0.0.1:3300']
allowedOwners: [kranich]
steps:
- id: fetch
action: fetch:template
input:
url: ./skeleton
values:
name: ${{ parameters.name }}
description: ${{ parameters.description }}
owner: ${{ parameters.owner }}
- id: publish
action: publish:gitea
input:
repoUrl: ${{ parameters.repoUrl }}
description: ${{ parameters.description }}
defaultBranch: main
- id: register
action: catalog:register
input:
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
catalogInfoPath: catalog-info.yaml # without a leading /
output:
links:
- title: Repository in Forgejo
url: ${{ steps.publish.output.repoContentsUrl }}
- title: Im Katalog öffnen
icon: catalog
entityRef: ${{ steps.register.output.entityRef }}
text:
- title: Nächste Schritte
content: "**${{ parameters.name }}** ist angelegt."
| Action |
Inputs in the book |
Outputs / note |
Day |
fetch:template |
url, values, optional
targetPath |
renders Nunjucks |
5 |
fetch:template:file |
url, targetPath (required),
values |
a single file |
6 |
fetch:plain |
url, targetPath |
copies without rendering |
6 |
debug:log |
message, listWorkspace |
log line |
6 |
publish:gitea |
repoUrl, description (required),
defaultBranch, repoVisibility,
gitCommitMessage, gitAuthorName,
gitAuthorEmail |
remoteUrl, repoContentsUrl,
commitHash |
5 |
catalog:register |
repoContentsUrl, catalogInfoPath |
entityRef |
5 |
kranich:ticket:create |
title, team, token,
delaySeconds |
ticketId (your own action) |
6 |
| Field or key |
Effect |
Day |
OwnerPicker + catalogFilter |
Groups from the catalog, returns group:default/… |
5 |
EntityPicker |
catalogFilter, defaultKind,
allowArbitraryValues: false |
6 |
EntityNamePicker |
Checks only the format, not whether the name is free |
6 |
RepoUrlPicker |
allowedHosts, allowedOwners; type from
integrations |
5 |
ui:field: Secret |
Value in ${{ secrets.<name> }}, ***
in the log |
6 |
ui:widget: checkboxes |
type: array, items.enum,
uniqueItems |
6 |
each: ${{ parameters.liste }} |
One step per entry, value in ${{ each.value }} |
6 |
if: ${{ parameters.ci }} |
Otherwise “Skipping step … if condition was false” |
6 |
Nunjucks: ${{ values.name }},
${{ values.description | dump }} (JSON string, safe for
YAML/JSON), {% if … %}…{% endif %}, {%- if %}
(removes the line break before it),
${{ 'a' if x else 'b' }}. Filters in the book:
parseRepoUrl, parseEntityRef,
pick('name'), projectSlug, dump,
join(', ') (Days 5, 6). Re-read templates:
bs catalog/refresh … template:default/<name> or
location:default/kranich-templates (Days 5, 6).
GUI under Create: tabs Tasks,
Actions, Templating Extensions,
Template Editor (cards Load Template
Directory – Chrome/Edge only –, Template Form
Playground, Custom Field Explorer); task page:
Cancel, START OVER, HIDE
LOGS (Days 5, 6).
TechDocs
# mkdocs.yml next to catalog-info.yaml
site_name: Sendungs-API
nav:
- Überblick: index.md
- Betrieb: betrieb.md
plugins:
- techdocs-core
python3 -m venv ~/backstage-lab/venv
~/backstage-lab/venv/bin/pip install -q mkdocs-techdocs-core # 1.7.1 (Day 7)
mkdocs build -q -d "$(mktemp -d)" # check locally
npx -y @techdocs/[email protected] generate --no-docker # → ./site
npx @techdocs/[email protected] publish --publisher-type awsS3 \
--storage-name kranich-techdocs --entity default/component/sendungs-api \
--directory ./site # CI, not tested live
- Flow: prepare (Git state) → generate
(
mkdocs build) → publish; the local publisher
writes to
node_modules/@backstage/plugin-techdocs-backend/static/docs/.
- Building happens on read: the tab calls
techdocs/sync;
it only builds on a new commit (etag), checked at most once
per minute per entity (Day 7).
- Admonitions
!!! note, !!! warning,
!!! tip work, Mermaid doesn’t (Day 7).
- The search collator reads
search/search_index.json of
built docs (Day 8).
Search
| Topic |
Fact |
Day |
| Engine with SQLite |
Lunr in RAM; log
Postgres search engine is not supported |
8 |
| Engine with Postgres |
search-backend-module-pg, table
documents |
13 |
| Collators |
search_index_software_catalog,
search_index_techdocs |
8 |
| Lunr after restart |
approx. 30 s HTTP 500 MissingIndexError |
8 |
| Lunr quirks |
A filter makes the search term optional; up to 2 typos |
8 |
| Result fields |
type, document (title,
text, kind, location …),
rank |
8 |
The search modal opens only by clicking Search in
the sidebar; there is no keyboard shortcut (Day 8).
Frontend system
app.packages: all includes every frontend plugin from
packages/app/package.json automatically
(role: frontend-plugin with a feature export);
include:/exclude: restrict that (Days 10, 11).
Extension IDs: <kind>:<plugin>/<name>,
visible in the Visualizer (Tree,
Detailed, Text, Show
Disabled) (Day 9).
app:
extensions: # maintain only in app-config.yaml
- page:home:
config:
path: /
defaultConfig: # applies until the user's first EDIT
- component: GettingStarted
column: 0
row: 2
width: 6
height: 5
- home-page-widget:home/random-joke: false # disable
- page:app-visualizer:
config:
title: App-Struktur # page title and sidebar
- entity-card:catalog/about: true # order of the list
- entity-card:catalog-graph/relations:
config:
type: info # right column
title: Beziehungen
height: 280
- entity-card:org/ownership:
config:
initialRelationAggregation: aggregated
- api:home/visits: true # off out of the box
- app-root-element:home/visit-listener: true
| Extension ID |
Role |
Day |
page:catalog, page:catalog/entity |
Catalog, entity page |
0, 9 |
page:home |
Home page (/home, from Day 9 /) |
9 |
page:catalog-import, page:scaffolder,
page:techdocs |
Sidebar pages |
9 |
page:search, page:notifications,
page:user-settings |
Pages |
9 |
page:app-visualizer |
Visualizer / App-Struktur |
9 |
home-page-widget:home/toolkit |
config.tools[]: url, label,
icon |
9 |
home-page-widget:home/world-clock |
config.clockConfigs[]: label,
timeZone |
9 |
home-page-widget:home/random-joke |
External API, off in the book |
9 |
entity-content:catalog/overview |
Overview tab, input cards |
9, 11 |
entity-content:kubernetes/kubernetes |
Kubernetes tab |
10 |
entity-card:catalog/about,
…catalog-graph/relations |
Cards |
9 |
entity-card:org/ownership |
Ownership card |
4, 9 |
entity-card:bereitschaft/heute |
Your own card, config.type: info |
11 |
theme:app/light, theme:app/dark,
theme:app/kranich |
Themes |
9 |
sign-in-page:app |
Sign-in page (default only guest) |
12 |
api:home/visits,
app-root-element:home/visit-listener |
Visit history |
9 |
Home layout components: HomePageSearchBar,
HomePageToolkit, HomePageWorldClock,
HomePageStarredEntities,
HomePageRecentlyVisited, HomePageMostVisited
and your own via HomePageWidgetBlueprint
(params.name) (Day 9).
| Building block |
Package |
Day |
createFrontendModule,
createFrontendPlugin, ApiBlueprint |
@backstage/frontend-plugin-api |
9, 11, 12 |
HomePageWidgetBlueprint |
@backstage/plugin-home-react/alpha |
9 |
ThemeBlueprint, SignInPageBlueprint |
@backstage/plugin-app-react |
9, 12 |
EntityCardBlueprint (filter,
loader) |
@backstage/plugin-catalog-react/alpha |
11 |
createUnifiedTheme, genPageTheme,
palettes |
@backstage/theme |
9 |
OAuth2.create |
@backstage/core-app-api |
12 |
- Modules go in
packages/app/src/App.tsx under
createApp({ features: […] }). A module only overrides
extensions of its own plugin (pluginId: 'app' for theme and
sign-in) (Days 9, 12).
- Sidebar order in
modules/nav/Sidebar.tsx:
nav.take('page:…'), the rest with
nav.rest({ sortBy: 'title' }); logo in
LogoFull.tsx/LogoIcon.tsx (Day 9).
yarn start reloads frontend code on save; errors in
extension IDs appear only in the browser console (Day 9).
Plugins and your own code
cd ~/backstage-lab/portal
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-gitea
yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-gitea
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-oidc-provider \
@backstage/backend-plugin-api
yarn --cwd packages/app add @backstage/theme@^0.7.3
yarn --cwd packages/app add @backstage/core-app-api
yarn new # interactive menu
yarn new --select backend-plugin --option pluginId=bereitschaft
yarn new --select scaffolder-backend-module --option moduleId=kranich
grep -n 'backend.add' packages/backend/src/index.ts
| Pattern |
Result |
Day |
backend.add(import('<package>')); |
Backend plugin or module active |
3, 5 |
backend.add(import('./modules/forgejoAuth')); |
Your own module from src/modules |
12 |
yarn new backend-plugin |
plugins/<id>-backend, entry in
index.ts, API /api/<id> |
11 |
yarn new frontend-plugin |
plugins/<id>, only a dependency of
packages/app |
11 |
| Package name |
@internal/backstage-plugin-<id>[-backend],
workspace:^ |
11 |
| Backend building block |
Package |
Day |
createBackendPlugin, createBackendModule,
coreServices |
@backstage/backend-plugin-api |
6, 11, 12 |
createTemplateAction,
scaffolderActionsExtensionPoint |
@backstage/plugin-scaffolder-node |
6 |
authProvidersExtensionPoint,
createOAuthProviderFactory |
@backstage/plugin-auth-node |
12 |
PermissionPolicy, policyExtensionPoint
(/alpha) |
@backstage/plugin-permission-node |
12 |
catalogConditions,
createCatalogConditionalDecision |
@backstage/plugin-catalog-backend/alpha |
12 |
InputError (400), NotFoundError (404) |
@backstage/errors |
11 |
startTestBackend, mockServices,
mockCredentials |
@backstage/backend-test-utils |
11 |
- Modules in the book:
pluginId/moduleId =
scaffolder/kranich,
auth/forgejo-oidc,
permission/kranich-policy (Days 6, 12).
coreServices.rootConfig, .logger,
.httpRouter (mounts under
/api/<pluginId>), .userInfo
(ownershipEntityRefs) (Days 11, 12).
- Open routes only deliberately:
httpRouter.addAuthPolicy({ path: '/health', allow: 'unauthenticated' })
(Day 11).
- In the frontend,
fetchApi with
plugin://<pluginId>/… – the user’s token is attached;
config is readable there only with @visibility frontend
(Day 11).
CI=true yarn test plugins/bereitschaft # without watch mode, both packages
yarn tsc # types, no output without errors
yarn --cwd packages/app lint # no-undeclared-imports
yarn lint:all # yarn lint only checks the diff to origin
yarn backstage-cli versions:bump # upgrade (Day 14)
Login and permissions
| Permission (name) |
Effect in the book |
Day |
catalog.entity.read |
Guest: ALLOW |
12 |
catalog.entity.delete |
Only group:default/plattform |
12 |
catalog.location.delete |
Only Plattform (Unregister deletes the location) |
12 |
scaffolder.task.create |
Only Plattform, otherwise no Choose |
12 |
catalog.entity.refresh |
Challenge: only the owner (isEntityOwner) |
12 |
catalog.location.create |
Registering in the GUI |
1 |
- Allow-all policy from create-app:
@backstage/plugin-permission-backend-module-allow-all-policy
– replace with
backend.add(import('./modules/permissionPolicy')) (Day
12).
- The policy is never asked for service principals
(
lab-cli): restrict them only via
accessRestrictions; permission/authorize
rejects service credentials (Day 12).
- The frontend asks
POST /api/permission/authorize in
advance and hides or locks (aria-disabled); the real
barrier is the backend (403) (Day 12).
- Forgejo reports
email_verified only in the ID token –
your own auth module with profileTransform instead of the
default OIDC module (not both with providerId: 'oidc') (Day
12).
- Sign Out only ends the Backstage session; to switch
users, use a private window (Day 12).
Operations
source ~/backstage-lab/tag13/pg.env # POSTGRES_HOST/PORT/USER/PASSWORD
docker run -d --name bs-postgres -p "127.0.0.1:$POSTGRES_PORT:5432" \
-v bs-postgres-data:/var/lib/postgresql/data \
-e POSTGRES_USER -e POSTGRES_PASSWORD postgres:16.4-alpine
docker exec bs-postgres pg_isready -h 127.0.0.1 -U backstage
docker exec bs-postgres psql -U backstage -lqt | cut -d'|' -f1 | grep backstage
sql() { docker exec bs-postgres psql -U backstage -d "$1" -Atc "$2"; }
sql backstage_plugin_catalog 'select count(*) from final_entities'
sql backstage_plugin_search 'select type, count(*) from documents group by 1'
docker exec bs-postgres pg_dump -U backstage -Fc backstage_plugin_catalog \
> catalog.dump # stop the portal first
docker exec -i bs-postgres pg_restore -U backstage -d backstage_plugin_catalog \
< catalog.dump
yarn tsc && yarn build:backend # → packages/backend/dist/bundle.tar.gz
cd ~/backstage-lab/release && tar xzf ../portal/packages/backend/dist/bundle.tar.gz
cp -c -R ../portal/node_modules . # APFS clone instead of installing
nohup node packages/backend --config app-config.yaml \
--config app-config.local.yaml --config app-config.production.yaml \
> ~/backstage-lab/prod.log 2>&1 & echo $! > ~/backstage-lab/prod.pid
APP_CONFIG_app_title='Kranich Portal (Prod)' node packages/backend … # override
NODE_ENV=production node packages/backend … # logs as JSON
kill $(cat ~/backstage-lab/prod.pid)
yarn build-image # only described (Day 13)
| Topic |
Fact |
Day |
| Databases |
One per plugin backstage_plugin_<id>, DB user
needs CREATEDB |
13 |
Without CREATEDB |
backend.database.pluginDivisionMode: schema |
13 |
| Catalog tables |
final_entities, refresh_state,
relations, locations, search |
13 |
| Lost when switching DB |
Stars, notifications, old tasks |
13 |
| Production |
app.baseUrl = backend.baseUrl =
http://localhost:7007 |
13 |
file locations |
Relative to the working directory: dev
packages/backend, prod root |
13 |
| Image |
node:24-trixie-slim, .dockerignore
excludes *.local.yaml |
13 |
| Endpoint |
Meaning |
Day |
/.backstage/health/v1/liveness |
Process is alive |
13 |
/.backstage/health/v1/readiness |
Started (otherwise 503), does not check the DB |
0, 13 |
Troubleshooting and upgrade
~/backstage-lab/setup/portal.sh logs 2000 | sed 's/\x1b\[[0-9;]*m//g' \
| awk '$3=="warn" || $3=="error" {print $2, $3}' | sort | uniq -c # plugin, level
LOG_LEVEL=debug ~/backstage-lab/setup/portal.sh restart # error|warn|info|debug
yarn backstage-cli info # versions for tickets
curl -s -D - -o /dev/null -H "Origin: $APP" "$BACKSTAGE/api/catalog/entities" \
| grep -i '^access-control-allow-origin' # check CORS
lsof -nP -iTCP:7007 -sTCP:LISTEN # who is using the port?
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: token $FORGEJO_TOKEN" \
$FORGEJO/api/v1/user # bot token valid?
| Symptom |
Layer |
Tool (Day 14) |
| Page empty, login fails |
Frontend↔︎Backend |
Browser console (F12),
curl -H Origin |
| Portal doesn’t start |
Configuration |
config:check, portal.sh logs |
| Entity stale, red card |
Catalog |
status.items, Inspect entity, log |
| Entity missing entirely |
Catalog |
Unprocessed Entities, log |
| 401/403/“not allowed” |
Integration |
Dry run, token against Forgejo |
| Task red |
Scaffolder |
Task log, tasks/<id>/events – the first error
counts |
- Background noise in the lab:
Event subscribe request failed with status 404,
does not contain a catalog-info.yaml (katalog, org,
templates), Postgres search engine is not supported,
Index for techdocs was not created (Day 14).
- DevTools (
@backstage/plugin-devtools,
…-devtools-backend) and Unprocessed Entities
(@backstage/plugin-catalog-unprocessed-entities,
…-catalog-backend-module-unprocessed): tabs
Info, Config, Scheduled
Tasks (Trigger), Unprocessed Entities with
Pending (never arrived) and Failed
(last run without a result). Permissions devtools.*,
catalog.entities.unprocessed.read (Day 14).
- Scheduled task Idle does not mean error-free: the
Gitea provider catches errors itself (Day 14).
cd ~/backstage-lab/portal
git add -A && git commit -qm "Stand vor Upgrade"
cat backstage.json # current release
curl -s https://versions.backstage.io/v1/tags/main/manifest.json | jq -r .releaseVersion
yarn backstage-cli versions:bump --release 1.55.3 --skip-install
git diff --stat
yarn install && yarn tsc && yarn --cwd packages/app lint && CI=true yarn test
yarn backstage-cli config:check && ~/backstage-lab/setup/portal.sh restart
What changes: Upgrade Helper
(https://backstage.github.io/upgrade-helper/?from=1.55.0&to=1.55.3)
for the template,
node_modules/@backstage/<package>/CHANGELOG.md per
package, and for minor releases the release notes at
https://backstage.io/docs/releases/v1.56.0/. One commit per
upgrade, way back via git revert (Day 14).
Failure patterns
| Symptom |
Cause |
Remedy |
Day |
yarn install:
got@patch:got@npm%3A11.8.2 … ENOENT |
Broken @yarnpkg/[email protected] |
resolutions to 4.9.1 |
0 |
401 Missing credentials /
Illegal token |
No or wrong token |
Use bs or load env.sh |
0, 11 |
/catalog 404 |
Until Day 8 the catalog is on / |
Use path / |
1 |
/ 404 after app.extensions in local |
List replaces the one from app-config.yaml |
Maintain the entry there |
9 |
| Yellow warning “relations … can’t be found” |
Owner group missing from the catalog |
Create the group (kranich/org) |
1, 4 |
is not of an allowed kind for that location |
catalog.rules |
Allow the kind, rule on the location |
2, 3, 4 |
"metadata.name" is not valid |
Space or similar in the name |
Follow the naming rule |
2 |
/spec must have required property 'owner' |
owner missing |
Add it |
2 |
| Red error card, old state remains |
Processing error |
status.items, log, revert |
2, 3 |
PlaceholderProcessor threw an error |
$text points nowhere |
Fix the path |
3 |
detected conflicting entityRef location:… |
Provider and manual registration |
Unregister the location |
3, 5 |
Detected conflicting entityRef group:… |
Entity in two files |
Delete one source |
4 |
| Owned shows 0 |
Guest is user:development/guest |
userEntityRef or login |
4 |
Only publish:github |
Gitea module missing in the scaffolder |
scaffolder-backend-module-gitea |
5 |
…/src/branch/catalog-info.yaml, 400 |
catalogInfoPath with / |
Without a leading / |
5 |
409 Conflict on publish |
Repo already exists |
Different name, START OVER |
5 |
does not support dry-run |
Action without supportsDryRun |
Expected |
6 |
Umlauts as für in the Template Editor |
btoa transfer in 1.55 |
The real run is correct |
6 |
Docker.ping() failed in the TechDocs tab |
runIn: docker without socket |
runIn: local + venv |
7 |
spawn mkdocs ENOENT |
Portal started without env.sh |
portal.sh restart |
7 |
{"updated":false} right after a push |
Check max. 1×/min per entity |
Open again later |
7 |
Search API 500 MissingIndexError |
Lunr empty after restart |
Wait approx. 30 s |
8 |
| New entity not in search |
Collator schedule (PT10M) |
search.collators.*.schedule |
8 |
INVALID_EXTENSION_CONFIG_KEY (console) |
Typo in the extension ID |
Check the ID in the Visualizer |
9 |
Lint: must be declared in dependencies |
Import without an entry |
yarn --cwd packages/app add … |
9 |
| Kubernetes tab “Backend (HTTP 404)” |
No kubernetes: block |
Configure the cluster |
10 |
Kubernetes 403 /api/v1/pods |
ServiceAccount without permissions |
ClusterRole + binding |
10 |
Test: No path for routeRef…catalog:entity |
EntityRefLink without route |
mountedRoutes in the test |
11 |
oidc/start 500,
requires session support |
auth.session.secret missing |
Set the secret |
12 |
user profile does not contain an email |
email_verified not in userinfo |
Your own auth module |
12 |
| Login fails despite a Forgejo account |
No matching user entity |
User in org.yaml |
12 |
does not allow 'service' credentials |
Lab token sent to permission/authorize |
Use a user token |
12 |
access is restricted to plugin(s) |
accessRestrictions |
Expected |
12 |
| No Choose, Unregister locked |
Policy: DENY |
Group plattform |
12 |
port is already allocated |
Another Postgres on 5432 |
Change the port in pg.env |
13 |
guest provider cannot be used outside… |
NODE_ENV ≠ development |
dangerouslyAllowOutsideDevelopment (lab) |
13 |
| APIs 500, readiness 200 |
Postgres gone |
Start the DB, it recovers by itself |
13 |
backend.baseUrl is set to a localhost URL |
Production with localhost |
A real baseUrl |
13 |
Warnings Postgres search engine…,
kubernetes…, Event subscribe…404 |
SQLite, no cluster |
Expected in the lab |
0 |
YAMLParseError: All mapping items must start at the same column |
Slipped indentation |
config:check, indentation |
14 |
portal.sh waits until timeout |
yarn start exited on a config error |
Ctrl+C, portal.sh logs 30 |
14 |
password missing in config:print |
Env variable empty or misspelled |
Check the variable |
14 |
Key has no effect ({ second: 20 }) |
Typo in the name |
config:check --strict |
14 |
401 Unauthorized on locations,
gitea-provider … refresh failed |
Bot token expired/wrong |
Renew the token |
14 |
Unable to read url … configure an integration |
Host doesn’t match (localhost ≠
127.0.0.1) |
URL or integrations.*.host |
14 |
No matching integration configuration for host |
repoUrl with a foreign host (API) |
Host from integrations |
14 |
Credentials for the gitea ${host} required. |
Integration without password |
Set the token |
14 |
Entity missing, no status.items |
Never processed successfully |
Unprocessed Pending |
14 |
| Misleading login message, console: CORS |
backend.cors.origin wrong |
Delete the override |
14 |
portal.sh ✔, but backend dead,
EADDRINUSE |
Port 7007 in use |
lsof, kill the process |
14 |
--strict:
additionalProperty=providers |
Gitea provider without schema |
False alarm |
14 |