11月13日にこのブログをLaravelで作り直して公開しました。その日のうちに、デプロイのやり方を2回変えています。
公開のときはメンテナンスモードを入れて切り替え、サイトは37分ほど止まりました。途中でCSSが効かなくなり、その修正もこの時間に入っています(原因はこちらの記事に書きました)。1時間後、問い合わせフォームの小さな修正を出したときも、メンテナンスモードで11分ほど止まりました。コマンドを1つずつ確認しながら進めたので、時間の多くは確認待ちです。
どちらのときも、メンテナンス画面を出している間はずっと緊張していました。小さな修正のたびにこれでは困るので、その日の午後に、マイグレーションのないデプロイは止めずに切り替えられる形にしました。手順はClaude Codeと相談しながら決めました。
環境はお名前.com レンタルサーバーRS(SSHあり、sudoなし、nodeなし)、PHP 8.4、Laravel 13、Filament 5です。
共有ディレクトリに分けるまで
最初はリリースごとに storage を持たせていて、デプロイのたびにサムネイル画像を新しいリリースへコピーしていました。
この形だと、管理画面から上げた画像は、そのとき公開中のリリースの中にしか保存されません。次のデプロイでコピーを忘れれば、画像は消えます。.env もリリースごとにコピーしていたので、どれが最新か分からなくなりそうでした。
そこで .env と storage を共有ディレクトリに移し、各リリースからリンクすることにしました。正直、切り替える前は、画像が消えないか、リンクを張り間違えてサイトが表示されなくならないかが不安でした。結果としてはどちらも起きず、12時36分に切り替えが終わりました。
できあがった構成はこうです。
~/production/
├── feelgood.site -> feelgood.site-v2-20261113-3 # 公開中のリリースを指すリンク
├── feelgood.site-v2-20261113-2/ # 1つ前のリリース(ロールバック用)
├── feelgood.site-v2-20261113-3/ # 公開中のリリース
│ ├── .env -> ~/production/feelgood-shared/.env
│ └── storage -> ~/production/feelgood-shared/storage
├── feelgood-shared/ # 全リリース共通
│ ├── .env
│ └── storage/
└── feelgood-tools/
└── composer.phar
~/public_html/feelgood.site/ # ドキュメントルート
├── index.php -> ~/production/feelgood.site/public/index.php
├── build -> ~/production/feelgood.site/public/build
├── css, js, fonts, images ...(同じくリンク)
├── storage -> ~/production/feelgood.site/storage/app/public
└── .htaccess # 実ファイル
コードはリリースごとのディレクトリに毎回まっさらな状態で展開し、ドキュメントルートからは ~/production/feelgood.site というリンクを通して参照します。このリンクの向き先を変えれば、公開中のリリースが切り替わります。
ドキュメントルートの storage もこのリンクを通ります。リリースの storage は共有ディレクトリへのリンクなので、最後は共有の storage/app/public にたどり着きます。
デプロイの手順
1. 新しいリリースを準備する
サーバーにnodeがないので、Viteのビルド結果(public/build)はローカルでビルドしてコミットしています。storage を除いたアーカイブを作って送ります。
git archive --format=tar.gz -o release.tgz HEAD ':(exclude)storage'
scp release.tgz server:~/
サーバー側で展開し、共有ディレクトリへのリンクを張ってから依存パッケージを入れます。
cd ~/production
mkdir feelgood.site-v2-20261113-3
tar -xzf ~/release.tgz -C feelgood.site-v2-20261113-3
cd feelgood.site-v2-20261113-3
ln -s ~/production/feelgood-shared/.env .env
ln -s ~/production/feelgood-shared/storage storage
php ~/production/feelgood-tools/composer.phar install --no-dev -o --no-interaction
--no-scripts は付けません。post-autoload-dump で動く filament:upgrade が、Filamentの css・js・fonts を public に作るからです。これらはgitに入れていません。
リンクを composer install より先に張るのは、storage がないと post-autoload-dump の package:discover が「Please provide a valid cache path.」で止まるからです。ローカルで storage を外して試すと、filament:upgrade も同じ理由で失敗しました。.env はこの時点では要りませんが、続けて使う migrate:status のために一緒に張っています。
ここでマイグレーションが残っていないかを見て、どちらの手順で切り替えるかを決めます。
php artisan migrate:status
2. キャッシュを作ってからリンクを切り替える
マイグレーションがなければ、メンテナンスモードは使いません。公開中のリリースのビルド済みファイルを新しいリリースにコピーし、キャッシュを先に作ってから、リンクを切り替えます。
cp -n "$(readlink -f ~/production/feelgood.site)"/public/build/assets/* \
~/production/feelgood.site-v2-20261113-3/public/build/assets/
cd ~/production/feelgood.site-v2-20261113-3 && php artisan optimize
ln -s ~/production/feelgood.site-v2-20261113-3 ~/production/feelgood.site.new
mv -T ~/production/feelgood.site.new ~/production/feelgood.site
最初の cp -n は念のための備えです。切り替えた直後に古いリリースのHTMLが返ると、そのHTMLは古いハッシュ名のCSSやJSを読みにいきます。ところが build のリンクはもう新しいリリースを指しているので、古いファイルがなければ404になります。ファイル名にハッシュが入っているので、コピーしても新しいファイルとはぶつかりません。
cp -n で既にあるファイルを飛ばしたときの終了コードは、環境によって違います。このサーバーのcpはcoreutils 8.22で、0を返す版です。手元のmacOSのcpでは1が返りました。set -e のスクリプトや && でつなぐ場合は気をつけてください。
キャッシュは optimize だけで作っています。最初は optimize:clear も実行していました。ただ、このサイトはキャッシュをDBに置いていて、DBはどのリリースからも共通です。そのため optimize:clear に含まれる cache:clear を新しいリリースで実行しても、公開中のサイトのキャッシュまで消えてしまいます。問い合わせフォームの連続送信の制限も、このキャッシュに入っています。デプロイのたびに制限がリセットされるのは困るので、外しました。
optimize にはFilamentの最適化も含まれていて、新しいリリースには設定やルートのキャッシュがまだないので、これで足ります。
3. 2分待ってからスモークテスト
PHPは、シンボリックリンクをたどった結果をrealpathキャッシュに持っています。切り替えてしばらくは、古いリリースを使い続けるプロセスが残るかもしれません。realpath_cache_ttl はCLIで確認すると120秒でした。Web側の値は設定ファイルを見ても分からなかったので、PHPの既定値と同じ120秒を目安に、2分待ってから主要なURLを確認するスモークテストを流します。
この形で最初にデプロイしたのは、同じ日の13時44分です。リンクを切り替えた直後にトップページを3回読んで3回とも200、2分後のスモークテストも93項目すべて通りました。メンテナンス画面を一度も出さずに終わったので、本当に切り替わったのか半信半疑でした。やってみると、思っていたよりずっと簡単でした。
リンクの切り替えに mv -T を使う理由
リンクの付け替えには ln -sfn もよく使われます。ただ ln は版によって置き換え方が違うので、一度で置き換わる mv -T にそろえました。
mv -T は rename(2) で既存のリンクを一度に置き換えるので、リンクがない瞬間がありません。-T を付け忘れると、feelgood.site が指しているディレクトリの中に移動してしまいます。リンクは切り替わらないので、ここは気をつけてください。
メンテナンスモードも共有される
storage を共有したので、メンテナンスモードの目印のファイル(storage/framework/down)も共有されます。古いリリースで down しても、サイト全体が503になります。古いリリースを止めておこう、と考えて down しないように注意しています。
マイグレーションがある場合
マイグレーションがあるときだけ、この順番で進めます。
php artisan down --with-secret- 新しいリリースのディレクトリで
php artisan migrate --force - ビルド済みファイルのコピー → キャッシュ作成 →
mv -Tでリンク切り替え → 2分待つ - 迂回用URLでスモークテスト
php artisan up→ もう一度スモークテスト
migrate は必ず新しいリリースで実行します。新しいマイグレーションのファイルはそちらにしかないので、まだ古いリリースを指している ~/production/feelgood.site で実行すると「Nothing to migrate」で終わってしまいます。DBは共通なので、どちらで実行しても書き込み先は同じです。
マイグレーションは、1つ前のリリースでも動く形(カラムの追加、nullableなど)で書くようにしています。こうしておけば、ロールバックはDBに触らず、リンクを戻すだけで済みます。
ロールバックと後片付け
ロールバックも、1つ前のリリースに向けて同じ手順で mv -T をします。
PREV=~/production/feelgood.site-v2-20261113-2
cp -n "$(readlink -f ~/production/feelgood.site)"/public/build/assets/* $PREV/public/build/assets/
cd $PREV && php artisan optimize
ln -s $PREV ~/production/feelgood.site.new
mv -T ~/production/feelgood.site.new ~/production/feelgood.site
1つ前のリリースにもキャッシュは残っていますが、作り直してから切り替えます。設定のキャッシュは、そのリリースをデプロイしたときの .env から作られています。その後に共有の .env を変えていたら、戻したリリースが古い設定のまま動いてしまうからです。
そのあとは、デプロイのときと同じく2分待ってスモークテストを流します。
リリースは新しい2つだけを残し、古いものは消しています。共有ディレクトリとツールのディレクトリは削除の対象から外しています。
止めずに出せるようになって
翌日も、wwwからのリダイレクトとRSSフィードを、サイトを止めずに出しました。メンテナンス画面のことを考えなくてよくなったので、小さな修正でも気軽にデプロイできそうだと感じています。