Internal Developer Platforms – Part 13: Working with Backstage TechDocs

Table of Contents:

Tags:

In the last blog post, we showed how to publish the API of a simple Spring REST Application and provide an API documentation in a OpenAPI/Swagger way. In this blog post, we will extend the example and show how to integrate Backstage Techdocs.

If you’re looking to streamline your documentation process within your organization, integrating TechDocs into Spotify’s Backstage can be a game-changer. TechDocs provides a unified, seamless documentation experience directly within your Backstage instance. This blog post will provide information about the entire setup process, from prerequisites to deployment and show an example.

Prerequisites

  1. Backstage Application: A running instance of Backstage.
  2. Node.js and Yarn: Installed on your machine.

First, you have to check, if Techdocs is already installed. If you have created your Backstage app with npx @backstage/create-app, TechDocs may already be present.

Otherwise, you need to perform the following steps (detailed instructions can be found in the Backstage documentation at https://backstage.io/docs/features/techdocs/getting-started):

  • Adding the Techdocs frontend plugin
  • Adding the Techdocs backend plugin

Bear in mind, that if you deploy Techdocs on your local computer, you need Docker installed – otherwise it will not work by default. If you run Techdocs in a containerized environment, you can run the Techdocs Docker logic outside the Backstage container. You also have to figure out, where to store your documentation. The best way would be to use some kind of object storage (AWS S3, Google Cloud Storage and so on) outside the Backstage deployment and have some CI/CD pipeline to publish documentation.

Once again, the exact configuration is described in the Backstage documentation. We will use a local installation here, and use the following snippet in the app-config.yaml

techdocs:
  builder: 'local' # Alternatives - 'external'
  generator:
    runIn: 'docker' # Alternatives - 'local'
  publisher:
    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.

Writing the backstage entities for Techdocs

Once, Techdocs is configured you can begin with designing your entities for Techdocs. In the last blog post, we were already setting up a directory structure. That will be our starting point:

Directory structure of a Spotify Backstage TechDocs project. It shows the following files and folders:

all-apis.yaml
all-components.yaml
all.yaml
apis/
employees-api.yaml
components/
employees-component.yaml
docs/
architecture.md
employees.md
index.md
sample.md
structure.md
mkdocs.yaml
The structure contains documentation files and API definitions, organized in YAML and Markdown files.

Now let’s take a look in the mkdocs.yaml:

site_name: backstage-sample-app

nav:
  - Overview: index.md
  - Quick Start: sample.md
  - Business Logic:
      - Employees: employees.md
  - System Architecture : architecture.md
  - Code Structure: structure.md

plugins:
  - techdocs-core

The site_name property defines the name of the documentation with Techdocs. We then define the navigation consisting of five different menu items. The plugins property configures how Backstage will render the documentation. In our simple scenario, techdocs-core is sufficient, but there might be use cases where you want to diagrams or other visual elements, where you need additional plugins.

Now let’s show a simple markdown file:

# Structure

"Wenn ich Hunger in der Jacke habe, dann kenne ich mich nicht vor Wut! Von Natur bin ich aber friedlich!"

"Es ist mir hier zu laut, ich kann nicht richtig kauen!“

"Hat dir eigentlich schon mal einer mit einem Vorschlaghammer einen Scheitel gezogen?"

"Wenn du denkst, du hast ’nen Dummen vor dir, bist du an der richtigen Adresse!"

"Gegen meine Kelle hilft nicht mal ein Waffenschein"

"Ganz ruhig, sonst drücken wir das Köpfchen in deinen Hals."

"Ohne Heu kann das beste Pferd nicht furzen."

"Mamor, Stein und Eisen bricht, aber mein kleines Fäustchen nicht!"

Once we are finished, with our documentation. We can upload it either manually to Backstage or in case we configured a object storage, we can upload the files to the object storage location. If we want to do it manually, just navigate to Create… on the left nagivation area, click on “REGISTER EXISTING COMPONENT” and upload the configuration files as described before. In our case, the all.yaml files had an annotation referencing to the Techdocs configuration.

annotations:
    backstage.io/techdocs-ref: dir:.

Now we can navigate to Docs and choose our application:

Screenshot of a web page titled "backstage-sample-app" within Spotify Backstage. The page displays documentation with a pink header. Below the header, there is a search bar. The left sidebar includes navigation links: Overview, Quick Start, Business Logic, System Architecture, and Code Structure. The main content area shows a section titled "Structure" with a list of German phrases or sentences, such as "Wenn ich Hunger in der Jacke habe, dann kenne ich mich nicht vor Wut! Von Natur bin ich aber friedlich!" and others. The system is labeled "system: backstage-sample-app" and the owner is "user: guido.soeldner".

Autor

Dr. Guido Söldner

Geschäftsführer

Guido Söldner ist Geschäftsführer und Principal Consultant bei Söldner Consult. Sein Themenfeld umfasst Cloud Infrastruktur, Automatisierung und DevOps, Kubernetes, Machine Learning und Enterprise Programmierung mit Spring.