Skip to content
Hands-on IT IT Drills

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