Tag 7: TechDocs
Ziel: Markdown-Doku aus dem Repo der
sendungs-apiohne 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 Annotationbackstage.io/techdocs-ref: dir:.sagt:mkdocs.ymlliegt neben dercatalog-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-apiist im Katalog, ihr Repo enthältmkdocs.ymlunddocs/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.yamlErwartet:
techdocs:
builder: 'local' # Alternatives - 'external'
generator:
runIn: 'docker' # Alternatives - 'local'
publisher:
type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for …
- Öffne Catalog →
sendungs-api. - Klicke auf den Tab TechDocs.
Erwartet: eine rote Meldung wie in der Abbildung. Über Show Build Logs siehst du das Protokoll des Build-Versuchs.
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[^;]*' | uniqErwartet:
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.pullImageist ab Werktrue) und baut darin. Das funktioniert, kostet aber Plattenplatz und braucht Zugriff auf Docker Hub. Wir stellen gleich aufrunIn: localum.
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-3Erwartet (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 mkdocsErwartet:
/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 restartErwartet:
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
Achtung: Startest du das Portal einmal ohne
env.sh(z. B. direkt mityarn startin einer neuen Shell), findet das Backend keinmkdocsund meldet beim nächsten Buildspawn 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.
- Öffne Catalog →
sendungs-api→ Tab TechDocs.
Erwartet: die gerenderte docs/index.md mit Suchfeld
darüber, wie in der Abbildung.
- 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
EOFcat > 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.
EOFmkdocs 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 -1Erwartet:
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.
- Warte gut eine Minute (warum, zeigt Drill 7) und öffne den Tab
TechDocs der
sendungs-api. - 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.
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 .etagErwartet (Hashes weichen ab):
b46b539e9b072f5b1c13c6453f0818a8c248fe4e
1a41822ebd1f82c792f45ba3ca0326398e7009a1
Der gespeicherte Stand ist noch der alte Commit.
- Ö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.
Jetzt zweimal direkt hintereinander synchronisieren:
for i in 1 2; do
bs techdocs/sync/default/component/sendungs-api -N | grep -o '{"updated[^}]*}'
doneErwartet:
{"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/" >> .gitignoreErwartet (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-1Der 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 ./siteMit 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_nameErwartet:
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.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Recommended Setup: CI baut
(
techdocs-cli generate, gepinntemkdocs-techdocs-core-Version im eigenen Image) und veröffentlicht (publish) nach S3, GCS oder Azure Blob; das Portal läuft mitbuilder: externalund braucht weder Python noch Docker noch Schreibzugriff auf die Repos. runIn: dockerim 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 undrunIn: local.- MkDocs-Konfiguration kann Code ausführen: Das Backend entfernt
unbekannte
mkdocs.yml-Schlüssel und Plugins (Allowlist). Freischaltungen übertechdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins/…Keysnur nach Review. - Bei vielen Lesern
techdocs.cache.ttlsetzen (braucht einenbackend.cachewie 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.