Posted inホームラボ

設定の勘頼みはやめよう：BookStackでプロフェッショナルなHomeLab Wikiを構築する

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

深夜2時15分の現実

夜も更けた頃。メインのProxmoxノードがカーネルパニックを起こし、ローカルDNSもダウンした。私はターミナルを凝視しながら、リカバリブリッジをVLAN 10と20のどちらに割り当てたか思い出そうとしている。14ヶ月間更新されていない、ノートPC内の乱雑な notes.txt ファイルをあさりながら、ドキュメント作成を怠った過去の自分を呪う。

HomeLabを1週間以上運用したことがある人なら、このもどかしさがわかるはずだ。私たちは複雑なシステムを構築するが、ドキュメント作成は後回しにしがちだ。長年システムを壊し続けてきた経験から、私は確信した。一元管理され、検索可能なWikiは贅沢品ではない。安定したラボのバックボーンなのだ。それがなければ、HomeLabを運営しているとは言えない。いつか崩壊する「砂上の楼閣」を管理しているに過ぎないのだ。

ドキュメント戦略の選択

ラボの構成を記録するために、ほぼすべての方法を試してきた。ここでは、危機的な状況において、一般的な戦略が実際にどのように機能するかを見ていく。

フラットファイルによるアプローチ (Markdown & Git)

多くのエンジニアは、MarkdownファイルをGitリポジトリで管理することを好む。ポータビリティに優れ、バージョン管理もできるため、コードには最適だ。しかし、VS Codeを使わない家族と簡単なガイドを共有したい場合には不向きだ。また、ネットワークがオフラインのときに、ターミナルで50以上のネストされたディレクトリを検索するのは、頭痛の種でしかない。

クラウドによるアプローチ (Notion/Confluence)

Notionは見た目が美しく、Confluenceは企業の標準だ。しかし、大きな欠陥がある。プライバシーと可用性だ。内部IPスキームやSSHキーをサードパーティのサーバーに置きたくはない。さらに重要なのは、インターネットがダウンしたとき、ゲートウェイを修理するために最もドキュメントが必要な瞬間に、それらが消えてしまうことだ。

BookStackという解決策

BookStackは絶妙なバランスを保っている。**本棚（Shelves） > 本（Books） > 章（Chapters） > ページ（Pages）** という、シンプルな図書館のメタファーを採用している。セルフホスト型で軽量、転送速度も速く、必要な情報を確実に見つけ出せる検索エンジンを備えている。MarkdownとWYSIWYGエディタの両方をサポートしているため、「開発者モード」でないときでも扱いやすい。

なぜBookStackが機能するのか

強み

  • 論理的な階層構造: 本棚/本システムにより、「無限フォルダ」問題を防げる。私はスイッチ構成には「Networking」の本棚、ハードウェア仕様には「Servers」の本棚を使用している。
  • バックアップの容易さ: システム全体はMySQLデータベースと画像フォルダだけで構成されている。5行のスクリプトでバックアップを自動化できる。
  • Draw.ioのネイティブ統合: ネットワーク図をページに直接埋め込むことができる。ラックの配線や複雑なDockerネットワークを記録するのに不可欠だ。
  • きめ細かな権限設定: 家族にはPlexのガイドへの「読み取り専用」アクセスを許可しつつ、ルートパスワードを記載した本は管理者アカウントのみに制限するといった運用が可能だ。

トレードオフ

  • 固定された構造: BookStackは独自の階層構造を強制する。完全にフラットな構造や、ネットワーク状の構造（Zettelkastenなど）を好む場合、窮屈に感じるかもしれない。
  • データベースへの依存: フラットファイルとは異なり、データベースが破損し、バックアップがない場合、ドキュメントは失われる。

推奨されるデプロイ方法

BookStackはDocker内で実行することを強くお勧めする。これにより、PHPの依存関係をホストOSから分離でき、ハードウェアの移行も容易になる。ここでは、BookStackアプリとMariaDBデータベースの2つのコンテナを使用した docker-compose 設定を使用する。

ステップ1：ディレクトリ構造の作成

まず、Wikiデータ用の専用スペースを作成する。私は通常 /opt/bookstack でホストしている。

mkdir -p ~/homelab/bookstack/config
mkdir -p ~/homelab/bookstack/db_data
cd ~/homelab/bookstack

ステップ2：Docker Composeの設定

docker-compose.yml ファイルを作成する。HomeLabユーザー向けに一貫したアップデートと優れたドキュメントを提供している linuxserver.io のイメージを使用する。

version: "3.8" 
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Tokyo
      - APP_URL=http://192.168.1.50:6875 # サーバーの固定IPを使用してください
      - DB_HOST=bookstack_db
      - DB_USER=bookstack
      - DB_PASS=UseAStrongPasswordHere # 強力なパスワードに変更してください
      - DB_DATABASE=bookstackapp
    volumes:
      - ./config:/config
    ports:
      - 6875:80
    restart: unless-stopped
    depends_on:
      - bookstack_db

  bookstack_db:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Tokyo
      - MYSQL_ROOT_PASSWORD=YourRootPassword # ルートパスワードを設定してください
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=UseAStrongPasswordHere # 強力なパスワードに変更してください
    volumes:
      - ./db_data:/config
    restart: unless-stopped

技術的な注意: APP_URL が使用するIPまたはDNS名と正確に一致していることを確認してください。これが正しくないと、BookStackはCSSやJavaScriptの読み込みに失敗し、テキストだけの壊れたページが表示されることになります。

ステップ3：起動

1つのコマンドでスタックを起動します。

docker compose up -d

データベースが初期化されるまで30秒ほど待ちます。docker logs -f bookstack を実行して進捗を確認できます。

ステップ4：初期セキュリティ

http://your-server-ip:6875 でインターフェースにアクセスします。デフォルトのログイン情報は、ユーザー名 [email protected]、パスワード password です。これらはすぐに変更してください。HomeLabにおいて、Wikiはデジタルライフ全体の設計図を含んでいます。パスワードマネージャーと同じように保護してください。

危機に備えた整理術

単にテキストを流し込むのではなく、BookStackの構造を利用して機能的なマップを作成しましょう。多くのラボでうまく機能する3層構造の例を紹介します。

  1. 本棚：インフラストラクチャ
    • 本：ネットワーク（VLAN ID、24ポートスイッチの割り当て、ファイアウォールルール）
    • 本：仮想化（ノードIP、共有ストレージのマウントポイント）
  2. 本棚：サービス
    • 本：メディア（Plexライブラリ、Docker Composeのスニペット）
    • 本：自動化（Home Assistantエンティティ、Zigbeeチャネルマップ）
  3. 本棚：メンテナンス
    • 本：ディザスタリカバリ（バックアップから復元するための、文字通り「ステップ1、ステップ2」の手順）

最後のステップ：バックアップの自動化

バックアップの自動化がないWikiは負債と同じです。Dockerを使用しているため、データベースをダンプし、設定フォルダを圧縮するのは簡単です。私は以下のスクリプトをcronジョブで毎晩午前3時に実行しています。

#!/bin/bash
# BookStack バックアップスクリプト
BACKUP_DIR="/mnt/nas/backups/bookstack"
DATE=$(date +%Y-%m-%d)

# データベースをエクスポート
docker exec bookstack_db /usr/bin/mariadb-dump -u bookstack -pUseAStrongPasswordHere bookstackapp > $BACKUP_DIR/db_$DATE.sql

# 設定ファイルと画像を圧縮
tar -czf $BACKUP_DIR/files_$DATE.tar.gz ~/homelab/bookstack/config

# 14日以上前のバックアップを削除
find $BACKUP_DIR -type f -mtime +14 -delete

設定には20分もかかりませんが、これにより将来の再構築の手間を何時間も省くことができます。次にラボがダウンしたとき、もう勘に頼る必要はありません。BookStackを開き、半年前に書いたガイドを見つけ、数分で問題を解決できるはずです。これこそが、ホビイストからプロの管理者へとステップアップする方法なのです。

Share:
Tags: