【Backstage】 TechDocsの基本設定

はじめに

こんにちは、ACS事業部の瀧澤です。
以前弊社ブログにてBackstageのTechDocsについて紹介しました。

techblog.ap-com.co.jp

今回は、Techdocsの基本的な設定についてまとめたいと思います。

Techdocsの設定はデフォルトのままでもローカル環境等での動作確認をする分には問題ありませんが、本番環境での利用には要件によってカスタマイズする必要が出てきます。本記事では、TechDocsの主要な設定項目である generator、builder、publisher を中心に、それぞれの選択肢や推奨設定を記載します。

TechDocsの処理の流れ

TechDocsは「docs-like-code」のアプローチを採用しており、Markdown で記述されたドキュメントをHTMLに変換して表示します。（変換後ファイルには厳密にはCSSや画像も含まれますが、本記事では便宜上HTMLと呼びます）

いつ・どこでHTMLを生成するかによって、大きく分けて以下2つの動作モデルがBackstage公式ドキュメントにて紹介されています。

ベーシック（デフォルト設定）

ユーザーがページを開いたタイミングでBackstage(Techdocsプラグイン)がリアルタイムで HTML を生成、サーバのローカルファイルシステムに配置した上でHTMLを返却します。その分初回アクセス時に時間がかかります。

推奨デプロイメント(本番環境向け)

CI/CD パイプラインで事前に HTML を生成し、ストレージに配置します。ページ表示時はすでに生成済みのファイルを取得するため高速です。

主要な設定項目

npx @backstage/create-app@latestでBackstageを新規作成した時点では、TechDocsの初期設定は以下のようになっています。

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

それぞれの設定項目について、詳しく見ていきましょう。

1. generator: mkdocsの実行環境を選択する

generator.runInは、ドキュメント生成ツールである mkdocsをどこで実行するかを指定します。

選択肢

docker: Docker イメージを指定し（例：dockerImage: 'spotify/techdocs'）、そのコンテナ内で mkdocs を実行します。
- メリット
  - 環境の一貫性が保たれる
  - ホストマシンに Python や mkdocs をインストールする必要がない
- デメリット
  - Docker in Docker の構成になる可能性がある
local: Backstage を動作させているマシン上で直接mkdocsを実行します。
- メリット
  - シンプルな構成で管理しやすい
- デメリット
  - mkdocs と Python のインストールが必要

推奨設定

本番環境ではBackstageをKubernetes等コンテナ環境でデプロイすることが多いかと思います。その際DinD構成にならないよう、localが推奨されています。BackstageアプリのDockerfileにてPythonおよびmkdocsのpip installが必要になります。

以下のような内容をDockerfileに追加して利用します。

RUN apt-get update && \
    apt-get install -y python3 python3-pip python3-venv && \
    rm -rf /var/lib/apt/lists/*

ENV VIRTUAL_ENV=/opt/venv
RUN python3 -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

RUN pip3 install mkdocs-techdocs-core

2. builder: HTML生成のタイミングを決める

generatorと似ていて紛らわしいですが、builder はMarkdownファイルからHTMLを生成するタイミングを制御します。

選択肢

local: ユーザーが TechDocs の画面を開いたタイミングで、リアルタイムに HTML を生成します。
- メリット
  - CI/CD パイプラインの構築が不要
- デメリット
  - 初回アクセス時にページの表示が遅くなる
  - Backstage サーバーに負荷がかかる
external: 事前に CI/CD パイプライン等で Markdown ファイルから HTML を生成しておき、ページを開いた時には生成済みの HTML をストレージから取得します。
- メリット
  - 応答速度向上
  - Backstage サーバーの負荷軽減
- デメリット
  - CI/CD パイプラインの構築が必要

推奨設定

パフォーマンス最適化のため external の使用が推奨されています。特に、ドキュメント数が多い場合や、ユーザーアクセスが頻繁な環境では採用した方が良いでしょう。※mkdocsの動作として、ページ（ファイル）ごとにHTML生成が実行されるのではなく、BackstageのEntity単位（リポジトリdocs配下のファイル全部）で生成が走るため、１ページ分見たいだけなのにファイル数の多いリポジトリだと表示に時間がかかってしまう、ということが起こりえます

externalで事前にbuildを実行するため、コードリポジトリでドキュメント(docs配下ファイル)が更新されたタイミングで自動的にHTMLを生成するパイプラインを組む必要があります。

以下はAzureのStorage AccountにHTMLを保存する場合のGitHub Actionsワークフロー例です

name: Generate and Publish TechDocs

on:
  push:
    branches:
      - main
    # ドキュメント関連のファイルが変更されたときにのみワークフローをトリガー
    paths:
      - "docs/**"
      - "mkdocs.yml"
  workflow_dispatch:

jobs:
  publish-techdocs:
    runs-on: ubuntu-latest

    env:
      ENTITY_NAMESPACE: default
      ENTITY_KIND: Component
      ENTITY_NAME: my-component

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install techdocs-core dependencies
        run: pip install mkdocs-techdocs-core==1.*

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install @techdocs/cli
        run: npm install -g @techdocs/cli

      - name: Generate TechDocs
        run: |
          techdocs-cli generate \
            --no-docker \
            --source-dir . \
            --verbose

      - name: Publish TechDocs to Azure Blob Storage
        run: |
          techdocs-cli publish \
            --publisher-type azureBlobStorage \
            --azureAccountName "${{ vars.AZURE_ACCOUNT_NAME }}" \
            --azureAccountKey "${{ secrets.AZURE_ACCOUNT_KEY }}" \
            --storage-name "${{ vars.AZURE_STORAGE_NAME }}" \
            --entity "${{ env.ENTITY_NAMESPACE }}/${{ env.ENTITY_KIND }}/${{ env.ENTITY_NAME }}" \
            --directory ./site

Backstageに登録したいリポジトリそれぞれについてワークフロー追加が必要となるため、それなりに労力がかかることになります。
開発チームの負担を減らすためにも、上記のようなyamlをプラットフォームチームで用意しておき、BackstageのTemplate機能を使って各チームに簡単に配布できるような仕組みを構築するのが良いかもしれません。

ハイブリッド方式

開発チームの状況によっては、一律でexternalの設定を適用できない場合もあるかと思います。コードの変更が必要にはなりますが、Backstage Entityのメタデータをもとに条件分けしてCI/CDパイプラインで事前に生成するもの・ユーザーアクセス時にその場で生成するもの、と振り分けることも可能です（詳細設定は以下）

https://backstage.io/docs/features/techdocs/how-to-guides/#how-to-implement-a-hybrid-build-strategy

3. publisher: 生成したHTMLの保存先を選択する

publisher.type は、生成された HTML ファイルをどこに保存するかを指定します。

選択肢

local: techdocs-backendのstaticディレクトリに保存されます
- メリット
  - 外部ストレージの用意が不要で手軽
- デメリット
  - スケーラビリティに制限がある
googleGcs/awsS3/azureBlobStorage: 各種クラウドストレージに保存します
- メリット
  - スケーラビリティ確保できる
  - バックアップと冗長性が確保される
- デメリット
  - クラウドサービスの設定とコストが必要
  - 認証情報の管理が必要

推奨設定

当然ですがクラウドストレージに配置することが推奨されています

以下のように、対象のクラウドストレージと認証情報をapp-config.yamlに記載することになります

(Azure Blob Storageの例)

techdocs:
  publisher:
    type: 'azureBlobStorage'
    azureBlobStorage:
      containerName: ${TECHDOCS_AZURE_BLOB_CONTAINER_NAME}
      credentials:
        accountName: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME}
        accountKey: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY}

まとめ

generator・builder・publisher の3つの設定は独立しており、全てを一度に推奨設定へ切り替える必要はありません。例えば、まず builder だけを external に変更し、publisher は引き続き local のままにするといった段階的な移行も可能です。チームの状況や優先度に応じて、変更する設定を絞ることができます。

まずは local 設定で TechDocs を動作させ、運用を通じて要件が明確になった段階で、external builder やクラウドストレージへの移行を検討することをお勧めします。

APC 技術ブログ

株式会社エーピーコミュニケーションズの技術ブログです。

【Backstage】 TechDocsの基本設定

はじめに

TechDocsの処理の流れ

ベーシック（デフォルト設定）

推奨デプロイメント(本番環境向け)

主要な設定項目

1. generator: mkdocsの実行環境を選択する

選択肢

推奨設定

2. builder: HTML生成のタイミングを決める

選択肢

推奨設定

ハイブリッド方式

3. publisher: 生成したHTMLの保存先を選択する

選択肢

推奨設定

まとめ

参考資料