PlatformEngr® Backstage course

Module 08 · Golden paths and docs · 30 min · You are: Platform and product

Docs next to the code with TechDocs

In this module

  • You learn: How TechDocs builds Markdown with MkDocs (here in Docker), stores the site and shows it on the entity page.
  • You do: Open the docs of checkout and cart, change a page as team-checkout, and rebuild it.
  • You end with: Both services have a TechDocs tab with their docs. You know where the build runs and what the annotation does.

Docs in a wiki drift away from the code. Docs in the repo, built by the portal and shown next to the owner and the API, get updated in the same pull request as the code. The annotation backstage.io/techdocs-ref: dir:. is the only link between the entity and its docs.

Open this module in the interactive course to track progress.

Concepts

techdocs-ref
The annotation that says where mkdocs.yml is, relative to catalog-info.yaml. dir:. means the same folder.
Builder and generator
The backend fetches the repo and runs MkDocs. runIn: docker uses the spotify/techdocs image; runIn: local needs MkDocs installed.
Publisher
Where built sites are stored: on the local disk here, a bucket (S3, GCS, Azure) in production.

Files to know

Open them in your editor or on GitHub; the bullets say what to look at.

Steps

1. Open the docs

The first build takes about half a minute: the backend fetches the repo and runs MkDocs in Docker.

Open checkout in the catalog, then the TechDocs tab. Expect the Overview page and a Runbook in the navigation.

The image that built them. Expect spotify/techdocs with tag v1.2.8:

docker images spotify/techdocs

2. The template's docs

Every service from the template has docs from its first commit.

Open cart → TechDocs. It says Owned by Team Checkout: the skeleton rendered values.ownerTitle.

3. As team-checkout: update the runbook

Docs change in the repo, like code.

Add to ~/work/checkout/docs/runbook.md at the end


## Who to call

Team Checkout, in the #team-checkout channel.

cd ~/work/checkout && git commit -qam "docs: who to call" && git push -q

Ask TechDocs to rebuild now instead of on the next visit. It streams the build log and ends when the site is updated:

curl -s -H "Authorization: Bearer $PORTAL_API_TOKEN" -N localhost:7007/api/techdocs/sync/default/component/checkout

Reload Runbook: Who to call is there.

Simplified for the course

The portal builds docs on request. The recommended setup builds them in each repo's CI with techdocs-cli and publishes to a bucket; the portal only reads. See TechDocs architecture.

Break it on purpose: Docs in the docs folder

team-checkout reads that the docs live in docs/ and "fixes" the annotation to match.

You practise: reading a TechDocs build error and mapping it back to the annotation.

1. Break it

Change in ~/work/checkout/catalog-info.yaml

-     backstage.io/techdocs-ref: dir:.
+     backstage.io/techdocs-ref: dir:./docs

cd ~/work/checkout && git commit -qam "docs: point at docs folder" && git push -q

curl -s -H "Authorization: Bearer $PORTAL_API_TOKEN" -X POST -H 'Content-Type: application/json' localhost:7007/api/catalog/refresh -d '{"entityRef":"component:default/checkout"}'

Wait half a minute, then rebuild:

curl -s -H "Authorization: Bearer $PORTAL_API_TOKEN" -N localhost:7007/api/techdocs/sync/default/component/checkout

2. What you see

Expected: the docs rebuild. You get: Config value 'docs_dir': The path '/input/docs' isn't an existing directory. and Failed to generate docs ... Docker container returned a non-zero exit code (1).

3. Fix it yourself

Work out which folder MkDocs ran in and why it looked for /input/docs. Fix it as team-checkout.

Hint 1

/input is the folder the annotation points at, mounted into the container. What is in it now?

Hint 2

The annotation points at the folder with mkdocs.yml, not the folder with the Markdown.

The fix

Change in ~/work/checkout/catalog-info.yaml

-     backstage.io/techdocs-ref: dir:./docs
+     backstage.io/techdocs-ref: dir:.

cd ~/work/checkout && git commit -qam "docs: techdocs-ref is the mkdocs.yml folder" && git push -q

curl -s -H "Authorization: Bearer $PORTAL_API_TOKEN" -X POST -H 'Content-Type: application/json' localhost:7007/api/catalog/refresh -d '{"entityRef":"component:default/checkout"}'

curl -s -H "Authorization: Bearer $PORTAL_API_TOKEN" -N localhost:7007/api/techdocs/sync/default/component/checkout
After you fixed it: the five questions
What failed?
The annotation pointed at the Markdown folder, so MkDocs ran without the right mkdocs.yml and found no docs folder inside it.
How was it detected?
In the build log, on the TechDocs tab or the sync stream.
Who responds?
team-checkout: they own the annotation and the docs.
How is it corrected?
Point techdocs-ref at the folder that holds mkdocs.yml.
How is it prevented?
Build docs in the repo's CI with techdocs-cli generate, so a broken build fails the pull request.

Quiz

  1. What does backstage.io/techdocs-ref: dir:. point at?
    • The folder with mkdocs.yml, relative to catalog-info.yaml
    • The folder with the Markdown pages
    • The URL of a published site
  2. Why does the portal need Docker for docs on your laptop?
    • TechDocs only renders in a browser inside Docker
    • With runIn: docker the generator runs MkDocs in the spotify/techdocs image
    • Docker stores the built sites
  3. What is the recommended production setup?
    • Build in the portal on every visit
    • Copy HTML into the portal repo
    • Build in each repo's CI and publish to a bucket; the portal only reads
Answers
  1. The folder with mkdocs.yml, relative to catalog-info.yaml MkDocs then reads docs_dir (default docs) from there.
  2. With runIn: docker the generator runs MkDocs in the spotify/techdocs image runIn: local would need MkDocs and its plugins installed instead.
  3. Build in each repo's CI and publish to a bucket; the portal only reads Builds fail where the change is made, and the portal stays light.

Field note

Docs get read when they are one click from the thing you are looking at. The TechDocs tab beats every wiki I have migrated away from, as long as the build is not the portal's problem.

Report a problem with this module