Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: TechDocs

Ziel: Markdown-Doku aus dem Repo der sendungs-api ohne Docker im Portal bauen, erweitern, aktualisieren und lokal vorab prüfen. · Dauer: ca. 75 min · Voraussetzung: Tag 6

Briefing

  • Docs-like-Code: Die Doku liegt als Markdown neben dem Code im selben Repo, wird per Pull Request geändert und vom Portal zur Komponente angezeigt.
  • TechDocs = MkDocs (Python) + Plugin techdocs-core. Die Annotation backstage.io/techdocs-ref: dir:. sagt: mkdocs.yml liegt neben der catalog-info.yaml.
  • Ab Werk baut Backstage im Docker-Container (runIn: docker). Im Lab bauen wir lokal mit einem Python-venv (runIn: local).
  • Vorausgesetzt (Ende Tag 6): Portal läuft, sendungs-api ist im Katalog, ihr Repo enthält mkdocs.yml und docs/index.md.
 Forgejo kranich/sendungs-api          Backend (techdocs)                 Frontend
 ┌──────────────────────┐  1 prepare   ┌─────────────────────────────┐   ┌──────────┐
 │ catalog-info.yaml    │ ───────────► │ 2 generate: mkdocs build    │   │ TechDocs │
 │ mkdocs.yml           │   (Git-Stand)│   (venv, runIn: local)      │──►│ Tab und  │
 │ docs/*.md            │              │ 3 publish: local (Dateien)  │   │ /docs    │
 └──────────────────────┘              └─────────────────────────────┘   └──────────┘

Drill 1: Docs-like-Code im Repo

Erst ansehen, was schon da ist – Annotation per API, Dateien per Forgejo-API:

source ~/backstage-lab/setup/env.sh
mkdir -p ~/backstage-lab/tag07
bs catalog/entities/by-name/component/default/sendungs-api \
  | jq -r '.metadata.annotations["backstage.io/techdocs-ref"]'
curl -sf -u "$ADMIN" "$FORGEJO/api/v1/repos/kranich/sendungs-api/raw/mkdocs.yml"

Erwartet:

dir:.
site_name: Sendungs-API
nav:
  - Überblick: index.md
plugins:
  - techdocs-core

dir:. ist relativ zur Location der Entity: Backstage holt das Repo auf dem Stand von main und baut ab dessen Wurzel. nav legt Reihenfolge und Titel der Seiten fest.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Das Fehlerbild mit runIn: docker

Die app-config.yaml aus create-app enthält:

grep -A5 '^techdocs:' ~/backstage-lab/portal/app-config.yaml

Erwartet:

techdocs:
  builder: 'local' # Alternatives - 'external'
  generator:
    runIn: 'docker' # Alternatives - 'local'
  publisher:
    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for …
  1. Öffne Catalog → sendungs-api.
  2. Klicke auf den Tab TechDocs.

Erwartet: eine rote Meldung wie in der Abbildung. Über Show Build Logs siehst du das Protokoll des Build-Versuchs.

Der TechDocs-Tab scheitert, weil der Generator Docker sucht

Dasselbe ohne Browser: Der Endpunkt techdocs/sync startet den Build und streamt das Log als Server-Sent Events (-N schaltet die Pufferung von curl ab):

bs techdocs/sync/default/component/sendungs-api -N \
  | grep -oE 'Step [0-9] of 3: [A-Za-z]+ docs|requires Docker[^;]*' | uniq

Erwartet:

Step 1 of 3: Preparing docs
Step 2 of 3: Generating docs
requires Docker. Docker does not appear to be available. Docker.ping() failed with

Warum? Der Generator spricht über die Docker-API mit dem Socket /var/run/docker.sock. Colima legt seinen Socket woanders ab, also scheitert schon der ping – im Testlauf mit connect ENOENT /var/run/docker.sock.

Achtung: Mit Docker Desktop ist der Socket erreichbar. Dann zieht Backstage beim ersten Öffnen des Tabs das Image spotify/techdocs:v1.2.8 (techdocs.generator.pullImage ist ab Werk true) und baut darin. Das funktioniert, kostet aber Plattenplatz und braucht Zugriff auf Docker Hub. Wir stellen gleich auf runIn: local um.

Fortschritt speichern? Kostenlos registrieren

Drill 3: MkDocs im Python-venv

mkdocs-techdocs-core bringt MkDocs, das Theme Material und alle Markdown-Erweiterungen mit, die TechDocs erwartet. Ein venv hält das vom System-Python fern (ca. 150 MB):

python3 -m venv ~/backstage-lab/venv
~/backstage-lab/venv/bin/pip install -q mkdocs-techdocs-core
~/backstage-lab/venv/bin/pip show mkdocs-techdocs-core | grep '^Version'
~/backstage-lab/venv/bin/mkdocs --version | cut -d' ' -f1-3

Erwartet (Testlauf vom 13.10.2026 mit Python 3.14.8):

Version: 1.7.1
mkdocs, version 1.6.1

Tipp: Für reproduzierbare Builds pinnst du die Version (pip install mkdocs-techdocs-core==1.7.1) – genau so, wie es später die CI tun soll.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Backend auf runIn: local umstellen

Mit runIn: local ruft das Backend schlicht mkdocs build auf – es sucht das Programm im PATH seines eigenen Prozesses. portal.sh lädt bei jedem Start env.sh, also gehört das venv dorthin (nicht nur in deine aktuelle Shell):

cat >> ~/backstage-lab/setup/env.sh <<'EOF'
# Tag 7: mkdocs aus dem Python-venv finden (TechDocs mit runIn: local)
export PATH="$LAB/venv/bin:$PATH"
EOF
source ~/backstage-lab/setup/env.sh
command -v mkdocs

Erwartet:

/Users/<du>/backstage-lab/venv/bin/mkdocs

Jetzt die Konfiguration. app-config.local.yaml hat seit Tag 2 einen Top-Level-Block catalog:; techdocs: ist ein neuer Top-Level-Schlüssel und darf als eigener Block ans Ende. Er überschreibt die Werte aus app-config.yaml:

cd ~/backstage-lab/portal
cat >> app-config.local.yaml <<'EOF'
# Tag 7: TechDocs ohne Docker – mkdocs läuft lokal (PATH aus env.sh)
techdocs:
  builder: local
  generator:
    runIn: local
  publisher:
    type: local
EOF
grep -c '^techdocs:' app-config.local.yaml
yarn backstage-cli config:print --lax | grep -A5 '^techdocs:'

Erwartet:

1
techdocs:
  builder: local
  generator:
    runIn: local
  publisher:
    type: local

Steht bei grep -c eine 2, hast du den Block doppelt angehängt – YAML nimmt dann stillschweigend nur einen. config:print zeigt die zusammengeführte Konfiguration aus allen app-config*.yaml. Neustart:

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

Erwartet:

✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)

Achtung: Startest du das Portal einmal ohne env.sh (z. B. direkt mit yarn start in einer neuen Shell), findet das Backend kein mkdocs und meldet beim nächsten Build spawn mkdocs ENOENT.

Fortschritt speichern? Kostenlos registrieren

Drill 5: TechDocs-Tab und Docs-Seite

Erst per API bauen und dabei zusehen:

bs techdocs/sync/default/component/sendungs-api -N | grep -oE \
  'Step [0-9] of 3: [A-Za-z]+ docs|Documentation built[^"]*|\{"updated":[a-z]+\}'

Erwartet (die Zeit variiert):

Step 1 of 3: Preparing docs
Step 2 of 3: Generating docs
Documentation built in 0.25 seconds
Step 3 of 3: Publishing docs
{"updated":true}

Die drei Schritte heißen im Code prepare (Repo-Stand holen), generate (mkdocs build) und publish (Ergebnis ablegen). Der lokale Publisher schreibt nach portal/node_modules/@backstage/plugin-techdocs-backend/static/docs/ – bei einem frischen yarn install ist das weg und wird neu gebaut.

  1. Öffne Catalog → sendungs-api → Tab TechDocs.

Erwartet: die gerenderte docs/index.md mit Suchfeld darüber, wie in der Abbildung.

Der TechDocs-Tab der sendungs-api mit der gerenderten Startseite
  1. Klicke in der Sidebar auf Docs.

Erwartet: die Tabelle All mit allen Entities, die eine techdocs-ref haben – heute nur sendungs-api, Owner team-sendung. Die Spalte Actions kopiert den Link oder setzt einen Stern. Wie die Seite mit zwei Einträgen aussieht, zeigt die Challenge.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Doku erweitern

Eine zweite Seite mit Code, Admonition und Tabelle. Klonen, Dateien schreiben, lokal mit demselben mkdocs prüfen, pushen:

cd ~/backstage-lab/tag07
GIT=http://lab-admin:[email protected]:3300
git clone -q $GIT/kranich/sendungs-api.git && cd sendungs-api
cat > mkdocs.yml <<'EOF'
site_name: Sendungs-API
nav:
  - Überblick: index.md
  - Betrieb: betrieb.md
plugins:
  - techdocs-core
EOF
cat > docs/betrieb.md <<'EOF'
# Betrieb

## Start

```bash
npm install
PORT=8080 npm start
```

!!! note "Bereitschaft"
    Störungen meldest du im Kanal `#team-sendung`. Außerhalb der Geschäftszeiten
    ist die Rufbereitschaft von Team Sendung zuständig.

## Kennzahlen

| Kennzahl        | Zielwert  |
|-----------------|-----------|
| Verfügbarkeit   | 99,9 %    |
| Antwortzeit p95 | < 200 ms  |

!!! warning
    Die API ist zustandslos – Sendungsdaten liegen im Zustelldienst.
EOF
mkdocs build -q -d "$(mktemp -d)" 2>&1 | grep -iE 'error|warning:' || echo "Build ok"
git add -A && git commit -qm "Doku: Seite Betrieb" && git push -q origin main
git log --oneline -1

Erwartet:

Build ok
1a41822 Doku: Seite Betrieb

Der lokale Build druckt zusätzlich einen roten Kasten „Warning from the Material for MkDocs team” zu MkDocs 2.0 – ein Hinweis der Theme-Autoren, kein Fehler. !!! note und !!! warning sind Admonitions; techdocs-core aktiviert die Erweiterung dafür automatisch.

Mermaid-Diagramme gehen nicht ohne Zusatz: techdocs-core richtet keinen Mermaid-Fence ein, ein ```mermaid-Block erscheint als Quelltext. Dafür bräuchte es ein Frontend-Addon – das lassen wir weg.

  1. Warte gut eine Minute (warum, zeigt Drill 7) und öffne den Tab TechDocs der sendungs-api.
  2. Klicke auf Refresh, sobald die grüne Meldung erscheint, dann im Menü (Symbol mit drei Strichen) auf Betrieb.

Erwartet: die neue Seite mit Codeblock und blauer Note-Box wie in der Abbildung.

Die neue Seite Betrieb mit Codeblock und Admonition

Fortschritt speichern? Kostenlos registrieren

Drill 7: Rebuild nach git push

Backstage baut nicht bei jedem Push, sondern beim Lesen: Öffnet jemand den Tab, zeigt das Frontend sofort die gespeicherte Version und fragt im Hintergrund techdocs/sync. Das Backend vergleicht den Git-Stand mit dem etag des letzten Builds und baut nur bei Abweichung. Noch eine Änderung:

cd ~/backstage-lab/tag07/sendungs-api
cat >> docs/index.md <<'EOF'

Wie du den Dienst startest und wen du bei Störungen erreichst, steht unter
[Betrieb](betrieb.md).
EOF
git commit -qam "Doku: Verweis auf Betrieb" && git push -q origin main
git rev-parse HEAD
bs techdocs/metadata/techdocs/default/component/sendungs-api | jq -r .etag

Erwartet (Hashes weichen ab):

b46b539e9b072f5b1c13c6453f0818a8c248fe4e
1a41822ebd1f82c792f45ba3ca0326398e7009a1

Der gespeicherte Stand ist noch der alte Commit.

  1. Öffne den Tab TechDocs der sendungs-api.

Erwartet: Erst „A newer version of this documentation is being prepared …“, nach wenigen Sekunden die grüne Meldung mit Refresh wie in der Abbildung. Ein Klick lädt die neue Version, ohne die Seite neu zu laden.

Nach dem Push meldet TechDocs eine neue Version

Jetzt zweimal direkt hintereinander synchronisieren:

for i in 1 2; do
  bs techdocs/sync/default/component/sendungs-api -N | grep -o '{"updated[^}]*}'
done

Erwartet:

{"updated":false}
{"updated":false}

Warum false? Der erste Aufruf findet den Stand schon gebaut (etag gleich Commit), der zweite prüft gar nicht erst: Nach jeder Prüfung schaut das Backend pro Entity höchstens einmal pro Minute wieder nach. Ein Push direkt nach einem Tab-Besuch erscheint deshalb erst beim übernächsten Öffnen. Das ist ein Speicher im Backend-Prozess, kein Konfig-Schlüssel – techdocs.cache.ttl ist etwas anderes: ein optionaler Cache für die ausgelieferten Dateien (siehe Enterprise-Notiz).

Fortschritt speichern? Kostenlos registrieren

Drill 8: Vorschau mit der TechDocs-CLI

Autorinnen und Autoren wollen vor dem Push sehen, was TechDocs daraus macht. Die CLI macht genau den Generate-Schritt des Backends – mit --no-docker über das mkdocs im PATH:

cd ~/backstage-lab/tag07/sendungs-api
npx -y @techdocs/[email protected] generate --no-docker
ls site
echo "site/" >> .gitignore

Erwartet (gekürzt, ohne den Material-Hinweiskasten; der erste npx-Aufruf lädt die CLI und dauert gut eine Minute):

info: Using source dir /Users/<du>/backstage-lab/tag07/sendungs-api
info: Will output generated files in /Users/<du>/backstage-lab/tag07/sendungs-api/site
info: Generating documentation...
info: Successfully generated docs from /Users/<du>/…/sendungs-api into …/site using …
info: Computed generated site content hash: e79f746b6d10c328e25673579faaa2b053a8f52…
info: Done!
404.html  assets  betrieb  index.html  search  sitemap.xml  sitemap.xml.gz
techdocs_metadata.json

Das ist exakt das Verzeichnis, das ein Publisher hochlädt. techdocs-cli serve startet zusätzlich eine Vorschau mit Backstage-Rahmen, belegt dafür aber Port 3000 – also nur bei gestopptem Portal (nicht live getestet). Für den schnellen Blick reicht mkdocs serve im venv.

Im Recommended Setup baut nicht das Portal, sondern die CI bei jedem Merge. Das Backend liest dann nur noch aus einem Objektspeicher (gekürzt, kann je nach Version abweichen; nicht live getestet):

techdocs:
  builder: external
  publisher:
    type: awsS3
    awsS3:
      bucketName: kranich-techdocs
      region: eu-central-1

Der zugehörige CI-Job nach dem generate:

npx @techdocs/[email protected] publish --publisher-type awsS3 \
  --storage-name kranich-techdocs --entity default/component/sendungs-api \
  --directory ./site

Mit builder: external ruft das Backend nie mkdocs auf; techdocs/sync meldet sofort {"updated":false}. Für Google Cloud Storage heißt der Typ googleGcs.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Die Datei liegt auch unter ~/backstage-lab/code/tag07/kontrollpunkt.sh.

#!/usr/bin/env bash
# kontrollpunkt.sh – Tag 7: TechDocs (✔/✘). Exit-Code = Anzahl Fehler.
source ~/backstage-lab/setup/env.sh
fail=0
t() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"
  else echo "✘ $1"; fail=$((fail+1)); fi; }
DOCS=techdocs/static/docs/default/component/sendungs-api
t "mkdocs aus dem venv im PATH" "command -v mkdocs | grep -q '/venv/bin/mkdocs'"
t "mkdocs-techdocs-core installiert" "pip show mkdocs-techdocs-core"
t "Generator läuft lokal (runIn: local)" \
  "grep -A2 '^  generator:' '$PORTAL/app-config.local.yaml' | grep -q 'runIn: local'"
t "Annotation techdocs-ref an sendungs-api" \
  "bs catalog/entities/by-name/component/default/sendungs-api \
     | jq -e '.metadata.annotations[\"backstage.io/techdocs-ref\"] == \"dir:.\"'"
t "Metadaten: Site Sendungs-API gebaut" \
  "bs techdocs/metadata/techdocs/default/component/sendungs-api \
     | jq -e '.site_name == \"Sendungs-API\"'"
t "Startseite index.html ausgeliefert" "bs $DOCS/index.html"
t "Seite Betrieb mit Admonition" \
  "bs $DOCS/betrieb/index.html | grep -q 'admonition note'"
exit "$fail"

Erwartet:

✔ mkdocs aus dem venv im PATH
✔ mkdocs-techdocs-core installiert
✔ Generator läuft lokal (runIn: local)
✔ Annotation techdocs-ref an sendungs-api
✔ Metadaten: Site Sendungs-API gebaut
✔ Startseite index.html ausgeliefert
✔ Seite Betrieb mit Admonition

techdocs/metadata/techdocs/… liefert die techdocs_metadata.json des letzten Builds (Site-Name, Dateiliste, etag), techdocs/static/docs/… die gebauten Seiten selbst.

Challenge

Gib tracking-web eine eigene Doku: Annotation, mkdocs.yml und eine Startseite mit einer !!! tip-Box. Beweise per API, dass sie gebaut wurde, und sieh nach, ob die Docs-Seite jetzt zwei Einträge zeigt.

Hinweis: Die Dateien liegen in ~/backstage-lab/code/tag07/challenge/tracking-web; die Annotation ergänzt du in der vorhandenen catalog-info.yaml, ohne den Rest zu ändern (z. B. mit yq, Homebrew-Paket yq).

Lösung

source ~/backstage-lab/setup/env.sh
cd ~/backstage-lab/tag07
git clone -q http://lab-admin:[email protected]:3300/kranich/tracking-web.git
cd tracking-web
yq -i '.metadata.annotations["backstage.io/techdocs-ref"] = "dir:."' catalog-info.yaml
cp -R ~/backstage-lab/code/tag07/challenge/tracking-web/. .
git add -A && git commit -qm "TechDocs für tracking-web" && git push -q origin main
sleep 70   # Gitea-Provider (1/min) liest die neue catalog-info.yaml
bs catalog/entities/by-name/component/default/tracking-web \
  | jq -r '.metadata.annotations["backstage.io/techdocs-ref"]'
bs techdocs/sync/default/component/tracking-web -N | grep -o '{"updated[^}]*}'
bs techdocs/metadata/techdocs/default/component/tracking-web | jq -r .site_name

Erwartet:

dir:.
{"updated":true}
Tracking-Web

yq -i fügt nur metadata.annotations hinzu und lässt system, consumesApis und dependsOn aus Tag 2 stehen. Unter Docs stehen jetzt beide Komponenten wie in der Abbildung.

Die Docs-Seite mit sendungs-api und tracking-web

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Recommended Setup: CI baut (techdocs-cli generate, gepinnte mkdocs-techdocs-core-Version im eigenen Image) und veröffentlicht (publish) nach S3, GCS oder Azure Blob; das Portal läuft mit builder: external und braucht weder Python noch Docker noch Schreibzugriff auf die Repos.
  • runIn: docker im Kubernetes-Pod heißt Docker-in-Docker bzw. Socket-Mount – in regulierten Umgebungen meist tabu. Deshalb dort entweder CI-Build oder ein Backend-Image mit fest installiertem venv und runIn: local.
  • MkDocs-Konfiguration kann Code ausführen: Das Backend entfernt unbekannte mkdocs.yml-Schlüssel und Plugins (Allowlist). Freischaltungen über techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins/…Keys nur nach Review.
  • Bei vielen Lesern techdocs.cache.ttl setzen (braucht einen backend.cache wie Redis/Memcache), damit nicht jeder Seitenaufruf den Objektspeicher trifft.
  • Zugriff: Mit aktivierten Permissions (Tag 12) prüft TechDocs, ob der Leser die Entity sehen darf; ein öffentlicher Bucket umgeht das – Bucket privat halten.