LAMP環境で動くアプリケーションを移行する際、だいたいは

  1. 移行先でWebアプリを作成する
  2. 移行元から移行先へとデータ(画像や添付ファイル)をコピーする
  3. DBをエクスポート→インポートする

の流れで別サーバへと移行が可能です。BookStackも同じような理屈で移行が行えるかを確かめたところ、罠がいくつかありました。

環境

共通環境

  • Apache 2.4
  • MySQL8系

移行元

  • Ubuntu 20.04
  • PHP 8.1

移行先

  • Ubuntu 24.04
  • PHP 8.3

さっくりといかない手順

  1. 【移行先】BookStackを構築します。
  2. オプション【移行元】アカウントのセキュリティ設定を一度解除します。
  3. 【移行元】→【移行先】画像や添付データ一式を転送します。
  4. 【移行元】→【移行先】MySQLのダンプを行い、DBを転送します。
  5. 【移行先】DBをインポートします。
  6. 【移行先】DBマイグレーションを行います。
  7. オプション【移行先】URLの変更処理を行います。
  8. 【移行先】設定の反映を行います。
  9. 【移行先】移行先で確認を行います。

【移行先】BookStackを構築します。

自サイトで恐縮ですが、手順はこちらをそのまま用いています。

オプション【移行元】管理アカウントの二要素認証を解除。

これが一番ハマったポイントでした。

マイアカウント ＞ アクセス＆セキュリティ ＞ 多要素認証

で、二要素認証をオンにしていると、移行先でログインができませんでした。

なので、移行時の一時的な措置として解除を行います。

【移行元】→【移行先】データの転送

BookStackのルートディレクトリ配下の

/public/uploads/を一式、移行先へと転送して、同じディレクトリ構造に上書きします。SCPやtarで固める塔、任意の方法で転送します。

このとき、アクセス権をWebサービス実行ユーザにしてください。（Ubuntuのデフォルトはwww-data）

【移行元】→【移行先】DBのデータ移行

mysqldump -h localhost -u bookstackuser -p --no-tablespaces --single-transaction bookstack > bookstack_backup.$(date +%Y%m%d).sql

-h DBサーバ名、-u bookstackのDBにアクセスできるユーザー DB名という形です。DBユーザに設定されているパスワードを入力してダンプを取ります。

こうしてできたDBは、任意の（安全で確実な）方法で移行先に転送します。

【移行先】DBのリストア

  • ディレクトリ移動
cd /hoge && pwd

ダンプしたDBファイルが転送されているディレクトリに移動します。

  • DBインポート
mysql -h localhost -u bookstackuser -p bookstack < bookstack_backup.$(date +%Y%m%d).sql

【移行先】DBのマイグレーション

これもハマったポイントでした。

  • BookStackルートディレクトリに移動
/path/to/BookStack/root/directory && pwd

/var/www/html/BookStackなど、移行先の、BookStackがインストールされているディレクトリに移動します。

  • DBマイグレーション
sudo -u www-data php artisan migrate --force

このマイグレーションを行わないと、リストアしたDBを参照してくれませんでした。

オプション【移行先】URL変更処理

サーバのURLを変える場合はここにも罠があります。BookStackの設定ファイル、.envに

# Application URL
# This must be the root URL that you want to host BookStack on.
# All URLs in BookStack will be generated using this value
# to ensure URLs generated are consistent and secure.
# If you change this in the future you may need to run a command
# to update stored URLs in the database. Command example:
# php artisan bookstack:update-url https://old.example.com https://new.example.com

という但し書きがありますので、この処理を行います。

  • BookStackルートディレクトリに移動
/path/to/BookStack/root/directory && pwd
  • URLアップデート
sudo -u www-data php artisan bookstack:update-url https://old.example.com https://new.example.com

二回ほど確認されますので、両方とも「yes」で答えます。

DB上書き反映

  • BookStackルートディレクトリに移動
/path/to/BookStack/root/directory && pwd
  • キャッシュクリア
sudo -u www-data php artisan cache:clear
  • Webサービス(apache)再起動
sudo systemctl restart apache2.service
  • Webサービス(apache)再起動確認
systemctl status apache2.service

active(running)を確認します。

サーバ移行確認

  1. ブラウザで移行先のURLにアクセスします。
  2. ログインできることを確認します。
  3. 前のデータ(画像や添付含む)が閲覧できることを確認します。
  4. 記事の作成等が行えることを確認します。
  5. 多要素認証をしている場合は、再設定します。