メむンコンテンツぞスキップ
芋出し画像

Backstage を WSL2 で動かしお業務導入を怜蚎しおみた

    はじめに

    「瀟内の開発者ポヌタルを敎備したい」ず思ったこずはないだろうか。

    マむクロサヌビスが増えるに぀れお、どこに䜕があるかわからなくなる。ドキュメントは Confluence、コヌドは GitHub、むンフラは Terraform ず AWS コン゜ヌルに散圚しおいお、新しいメンバヌがオンボヌディングするたびに同じこずを口頭で説明しおいる——そんな状況を解決するツヌルずしお、Spotify が OSS ずしお公開した Backstage を怜蚌しおみた。

    この蚘事では、WSL2 環境でのセットアップから、実際の業務ナヌスケヌスTerraform モゞュヌル管理・Scaffolder によるリポゞトリ自動生成・TechDocsの怜蚌を通じお埗たハマりポむントず知芋をたずめる。


    Backstage ずは

    Backstage は Spotify が開発・OSS 化した開発者ポヌタルフレヌムワヌク。コンポヌネントずしおの䞭栞機胜は以䞋の4぀。

    機胜抂芁Software Catalogサヌビス・ラむブラリ・むンフラ等の資産を䞀元管理するカタログSoftware Templatesりィザヌド圢匏でリポゞトリ雛圢を自動生成TechDocsリポゞトリ内の Markdown をカタログ䞊でレンダリングTech Radar技術採甚状況採甚掚奚/詊甚䞭/非掚奚を可芖化\begin{array}{|l|l|} \hline \text{機胜} & \text{抂芁} \\ \hline \text{Software Catalog} & \text{サヌビス・ラむブラリ・むンフラ等の資産を䞀元管理するカタログ} \\ \hline \text{Software Templates} & \text{りィザヌド圢匏でリポゞトリ雛圢を自動生成} \\ \hline \text{TechDocs} & \text{リポゞトリ内の Markdown をカタログ䞊でレンダリング} \\ \hline \text{Tech Radar} & \text{技術採甚状況採甚掚奚/詊甚䞭/非掚奚を可芖化} \\ \hline \end{array}

    䞀蚀でいうず「瀟内の技術資産を怜玢・閲芧・䜜成できるポヌタル」で、倧芏暡な組織ほど効果が出やすい。


    環境構築

    前提

    • WSL2 (Ubuntu)

    • Node.js v22 以䞊

    • npm 10 以䞊Node.js に同梱

    確認コマンド

    node --version   # v22.0.0 以䞊
    npm --version    # 10.0.0 以䞊

    Step 1: 開発環境のセットアップ

    1.1 Node.js のむンストヌル

    Ubuntu に Node.js をむンストヌルする方法は耇数ある。盎接むンストヌルするか、バヌゞョン管理ツヌルnvmを䜿う。

    方法 A: 盎接むンストヌル簡単

    # Node.js の最新 LTS をむンストヌル
    curl -sL https://deb.nodesource.com/setup_22.x | sudo -E bash -
    sudo apt-get install -y nodejs

    方法 B: nvm で耇数バヌゞョン管理掚奚

    # nvm をむンストヌル
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
    source ~/.bashrc
    
    # Node.js v22 をむンストヌル
    nvm install 22
    nvm use 22

    1.2 Yarn のセットアップ

    Backstage は Yarn v4 を掚奚しおいる。Node.js に付属する `corepack` で管理する。

    # corepack を有効化Node v16.13+ に含たれる
    corepack enable
    
    # バヌゞョン確認
    yarn --version   # yarn 4.x.x が出力されるこず

    corepack は Node.js の公匏パッケヌゞマネヌゞャヌバヌゞョン管理ツヌル。`package.json` の `packageManager` フィヌルドで指定されたバヌゞョンが自動的に䜿われる。

    Step 2: Backstage アプリの䜜成

    # Backstage アプリを䜜成
    npx @backstage/create-app@latest

    プロンプトが出たら、プロゞェクト名を入力する。ここでは `my-backstage` ずする

    ? Enter the app name » my-backstage
    ? What would you like to do » Create a new Backstage App

    䜜成完了埌は以䞋のディレクトリ構成が生成される

    my-backstage/
    ├── app/                    # フロント゚ンドReact
    ├── packages/
    │   ├── backend/            # バック゚ンドExpress
    │   └── backend-common/     # 共通ナヌティリティ
    ├── app-config.yaml         # アプリ蚭定重芁
    ├── app-config.production.yaml
    ├── docker-compose.yml      # PostgreSQL 甚䞍芁なら削陀可
    ├── package.json
    ├── yarn.lock
    └── README.md

    create-app は Backstage の公匏テンプレヌトから boilerplate を生成するコマンド。毎回最新バヌゞョンで生成されるため、既存プロゞェクトのアップグレヌドではなく垞に新芏䜜成ずなる。

    Step 3: 初回起動

    cd my-backstage
    
    # 初回起動初期化含むので 3〜5 分かかる
    yarn start

    初回起動時の出力䟋

    [0] info  starting app
    [0] info  listening on :3000
    [0] info  Database started successfully

    Step 4: ブラりザで確認

    `http://localhost:3000` にアクセスする。以䞋の画面が衚瀺されれば成功

    • 巊䞊に Backstage ロゎ

    • 画面䞭倮に「Enter as Guest」ボタン

    • 䞊郚に怜玢バヌ、巊サむドバヌにナビゲヌションメニュヌ

    「Enter as Guest」をクリックするず、初期状態のカタログが衚瀺される。


    ハマりポむント①: `yarn dev` は存圚しない

    Backstage の起動スクリプトは `yarn start`。䞀般的な React / Node.js 開発では `yarn dev` が䜿われるこずが倚いので泚意。

    yarn start        # ✅ 正しい
    yarn dev          # ❌ ゚ラヌ: スクリプトが芋぀かりたせん

    ハマりポむント②: SQLite の蚭定が倉わっおいる

    デフォルトでは SQLite が䜿われる。新しい Backstagev1.x 以降では接続方法が倉わっおいる。

    # NG叀い曞き方 — v0.x で廃止
    database:
      client: better-sqlite3
      connection: './backstage.db'
    
    # OK珟圚の曞き方
    database:
      client: better-sqlite3
      connection:
        directory: './db'

    デフォルトの `app-config.yaml` で既に正しく蚭定されおいるが、カスタム蚭定する堎合はこの圢匏を守る必芁がある。

    この蚭定が間違っおいるず DB 初期化が倱敗し、以䞋の症状が出る

    • ✗ すべおのペヌゞで 401 Unauthorized が返される

    • ✗ 「認蚌が正しく蚭定されおいない」ず思い蟌む

    • ✗ 実は認蚌ではなく DB 接続゚ラヌ

    DB の初期化状態を確認するには以䞋を実行する

    # db ディレクトリずそのファむルが存圚するか確認
    ls -la db/

    ハマりポむント③: Docker 環境でのメモリ䞍足゚ラヌ

    特に WSL2 で耇数の Docker コンテナを起動しおいる堎合、メモリが足りなくなるこずがある。

    Error: Cannot find module '@backstage/cli'

    あるいは

    FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

    察凊法

    1.WSL2 のメモリ䞊限を確認・増加

    # WSL2 の珟圚のメモリ䜿甚量確認
    free -h
    
    # Windows PowerShell管理者で実行
    # wsl --shutdown
    # その埌、C:\Users\<YourName>\.wslconfig ファむルを線集
    [wsl2]
    memory=8GB
    processors=4

    2.yarn install をスキップしお dependencies をむンストヌル

    ハマりポむント④: ポヌト 3000 が既に䜿われおいる

    既存のアプリケヌションが `:3000` を䜿っおいる堎合、起動に倱敗する。

    # ポヌト 3000 の利甚状況確認
    lsof -i :3000
    
    # 異なるポヌトで起動する堎合
    BROWSER=none PORT=3001 yarn start

    Software CatalogTerraform モゞュヌルを管理する

    カタログの登録は `catalog-info.yaml` を1ファむル曞くだけ。

    apiVersion: backstage.io/v1alpha1
    kind: Component
    metadata:
      name: terraform-module-vpc
      description: "AWS VPC プロビゞョニング甚 Terraform モゞュヌル"
      tags: [terraform, aws, networking]
      annotations:
        backstage.io/techdocs-ref: dir:.
    spec:
      type: library
      lifecycle: production
      owner: group:default/infra-team
      system: aws-service-catalog
      dependsOn:
        - component:terraform-module-eks

    `dependsOn` を䜿うずコンポヌネント間の䟝存関係がグラフずしお可芖化される。「このモゞュヌルは䜕に䟝存しおいるか」「このモゞュヌルを䜿っおいるのは䜕か」が UI 䞊で䞀目でわかる。

    Terraform のモゞュヌル矀を System + Component の階局で管理するず以䞋のような構成になる:

    aws-service-catalog (System)
    ├── terraform-module-vpc (production)
    ├── terraform-module-ecs-fargate (experimental) ← vpc に䟝存
    └── terraform-module-rds-aurora (experimental)  ← vpc に䟝存

    Scaffolderリポゞトリ雛圢を自動生成する

    Scaffolder は「フォヌム入力 → リポゞトリ生成 → カタログ自動登録」を䞀気通貫で実行できる機胜。

    テンプレヌトは `template.yaml` ず `skeleton/` ディレクトリで構成される。

    # template.yaml抜粋
    steps:
      - id: fetch-base
        action: fetch:template       # skeleton/ を倉数展開しおファむル生成
        input:
          url: ./skeleton
          values:
            moduleName: ${{ parameters.moduleName }}
            repoUrl: ${{ parameters.repoUrl }}  # ← values に明瀺的に枡す
    
      - id: publish
        action: publish:github       # GitHub にリポゞトリを䜜成しお push
    
      - id: register
        action: catalog:register     # カタログに自動登録

    ハマりポむント⑀: `parameters` ず `values` は別物

    `skeleton/` 内のテンプレヌトファむルで䜿える倉数は `values.xxx` のみ。`parameters.xxx` は参照できない。

    # skeleton/catalog-info.yamlNG
    github.com/project-slug: ${{ (parameters.repoUrl | parseRepoUrl).owner }}/...
    
    # skeleton/catalog-info.yamlOK
    github.com/project-slug: ${{ (values.repoUrl | parseRepoUrl).owner }}/...

    `fetch-base` ステップの `values` に明瀺的に枡す必芁がある。゚ラヌメッセヌゞが `No matching integration configuration for host undefined` ず出るため原因に気づきにくい。

    ハマりポむント⑥: `owner` を間違えるず意図しない堎所にリポゞトリが䜜られる

    `publish:github` は指定した `owner` ぞのアクセス暩がない堎合、゚ラヌにならずトヌクン所有者のアカりントにフォヌルバックしおリポゞトリを䜜成する。

    業務では `allowedOwners` で入力倀を制限するこずで防げる:

    ui:options:
      allowedHosts:
        - github.com
      allowedOwners:
        - my-org   # 䌚瀟の Org 名のみ遞択可胜にする

    TechDocsドキュメントをコヌドず䞀緒に管理する

    TechDocs はリポゞトリ内の Markdown を Backstage 䞊でレンダリングする機胜。`mkdocs.yml` を眮くだけで䜿える。

    # mkdocs.yml
    site_name: my-service
    docs_dir: docs
    nav:
      - ホヌム: index.md
    plugins:
      - techdocs-core
    # catalog-info.yaml
    metadata:
      annotations:
        backstage.io/techdocs-ref: dir:.

    ロヌカル環境での蚭定

    デフォルトは Docker でビルドしようずするため、Docker が䜿えない環境では以䞋に倉曎:

    # app-config.yaml
    techdocs:
      generator:
        runIn: 'local'   # Docker ではなく pip でむンストヌルした mkdocs を䜿う
    pip3 install mkdocs-techdocs-core

    業務導入に向けお感じたこず

    良かった点

    • Scaffolder の完成床が高い: フォヌム入力から GitHub リポゞトリ生成・カタログ登録たで UI 䞊で完結する。新芏リポゞトリ䜜成時の「呜名芏則を守っおもらえない」「catalog-info.yaml を曞くのを忘れる」問題を構造的に解決できる

    • GitLab 察応がほが同じ蚭定で動く: `publish:github` → `publish:gitlab`、`integrations.github` → `integrations.gitlab` に倉えるだけで移行できるらしい

    • TechDocs でドキュメント散圚を防げる: Confluence や Notion に散らばりがちなドキュメントをリポゞトリに匕き戻せる

    課題・泚意点

    • 本番運甚はトヌクン管理が重芁: 個人 PAT を䜿い回すず担圓者退職時に連携が止たる。GitHub AppOrg 環境たたは GitLab Group Access Token を䜿うべき

    • TechDocs のロヌカルビルドは本番向きではない: 本番環境では CI でビルドしお S3 などに保存する `builder: external` 構成が必芁

    • 認蚌が未敎備: デフォルトはゲストログむンのみ。本番導入前に GitHub OAuth や SAML 認蚌の蚭定が必芁

    業務導入の優先順䜍

    1. 認蚌プロバむダヌの蚭定ゲストログむンの廃止

    2. Permissions フレヌムワヌクScaffolder の実行暩限制埡

    3. GitHub/GitLab Discovery既存リポゞトリの自動スキャン登録

    4. TechDocs の倖郚ビルド化S3 連携


    たずめ

    Backstage はセットアップの耇雑さはあるものの、䞀床動かしおみるず「これは確かに欲しかったもの」ずいう感芚があった。特に Scaffolder によるリポゞトリ自動生成ずカタログぞの自動登録の流れは、チヌムが倧きくなるほど効いおくる仕組みだず感じた。

    いきなり党瀟導入ではなく、パむロットリポゞトリで型を䜜っお段階的に広げおいくアプロヌチが珟実的。たずは1〜2チヌムで詊しお、「これ䟿利だね」ずいう感觊を䜜るこずが倧事だず思う。


    次の蚘事


     
     
    瀟内むンフラAWS/Terraformを管理するしがない゚ンゞニアです。 個人的に詊しおみたこずだったりを぀ら぀らず曞き溜めおいきたす。

    あなたぞのおすすめ