【Docker】社内LAN環境にBookStackを構築し、DB接続事故を解決した記録

【Docker】社内LAN環境にBookStackを構築し、DB接続事故を解決した記録

概要

社内LAN環境において、ログイン不要かつ堅牢に運用できるドキュメント管理ツールとして BookStack を Docker（docker-compose）上に構築しました。

初回起動時の DB 接続事故（SQLSTATE[HY000]）とその解決アプローチ、および画像アップロード時の権限管理についてまとめています。

1. システム構成と環境

  • ホスト環境: 社内LAN内 Linux サーバー（192.168.1.223）

  • 構成: Docker / docker-compose

  • サービス:

  • BookStack (Web / APP) — ポート: 6875

  • MariaDB (Database) — DB名: bookstackapp, User: bookstack

  • 永続化パス: /opt/bookstack

2. 構築手順（docker-compose.yml）

ベースとなる docker-compose.yml の定義です。

version: '3'

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=http://192.168.1.223:6875
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=bookstack_pass_1234
      - DB_DATABASE=bookstackapp
    volumes:
      - /opt/bookstack/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
      - MYSQL_ROOT_PASSWORD=root_pass_1234
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=bookstack_pass_1234
    volumes:
      - /opt/bookstack/db_data:/config
    restart: unless-stopped

3. トラブルシューティング

① DB起動遅延による .env の自動不整合事故 (SQLSTATE[HY000])

発生した現象

docker compose up -d 実行後、BookStack にアクセスすると SQLSTATE[HY000] [2002] または Access denied エラーが発生。

原因

LinuxServer.io 製 BookStack コンテナの初回起動時、依存している MariaDB の初期化（テーブル生成等）が完了していないと、BookStack 内部の自動スクリプトが DB 接続失敗を検知します。 その際、コンテナのフォールバック仕様により内部で DB_HOST=localhost として .env ファイル（/opt/bookstack/config/www/.env）を誤生成し、そのまま固定化されてしまうことが原因でした。

解決手順

コンテナを破棄せず、生成された .env 内の DB_HOST を正しいサービス名（bookstack_db）に修復し、Laravel の設定キャッシュをクリアします。

# 1. .env 内の DB_HOST を強制修正
sudo sed -i 's/DB_HOST=.*/DB_HOST=bookstack_db/' /opt/bookstack/config/www/.env

# 2. 修正値の確認
grep DB_HOST /opt/bookstack/config/www/.env

# 3. Laravelのキャッシュクリアと再起動
sudo docker exec -it bookstack php /app/www/artisan config:clear
sudo docker compose restart bookstack

予防策: 初回構築時は docker compose up -d bookstack_db で DB のみを先に立ち上げ、30秒ほど待ってから bookstack コンテナを起動すると事故を防げます。

② 画像アップロードと権限管理

BookStack は「棚 ＞ ブック ＞ 章 ＞ ページ」の階層構造を持ち、画像は「ページ編集画面」へのドラッグ＆ドロップや Ctrl + V で挿入します。

画像アップロード時に権限エラーが出る場合は、永続化ディレクトリの所有権・権限を修正することで解決します。

sudo chown -R 1000:1000 /opt/bookstack/config
sudo chmod -R 775 /opt/bookstack/config/www/uploads

4. 初期設定と運用

  1. アクセス: ブラウザで [http://192.168.1.223:6875](http://192.168.1.223:6875) を開く。
  2. 初期ログイン:
  • メールアドレス: admin@admin.com
  • パスワード: password
  1. 推奨設定:
  • 管理者パスワードの初期値からの変更。
  • プロフィール編集から言語設定を Japanese に変更。

まとめ

  • 初回起動時の DB コンテナ準備待ちによる .env の誤生成（localhost 化）に注意する。
  • 接続エラーが出た場合は .env の修正と php artisan config:clear で即時復旧可能。
  • /opt/bookstack 以下の権限設定を適切に行うことで、画像のドラッグ＆ドロップ貼り付け機能がスムーズに利用可能。
← 一覧へ戻る