コンテンツへスキップ

Blockstudioサイトのデプロイ

ブロックの場合、テーマフォルダーをサーバーにコピーするだけで十分です。Blockstudioがファイルシステムからブロックを検出し、キャッシュは変更された入力を自動で認識します。実際のサイトには、ほかにも考慮すべき要素があります。ファイルベースのページがデータベースに反映されるのは、同期したときだけです。静的な事前レンダリングは、置き換えられるまで昨日のHTMLを配信し続けます。手前にCDNがある場合は、キャッシュした内容を配信し続けます。

このガイドでは、ComposerでBlockstudioをバンドルするacmeというテーマのデプロイ方法を説明します。CIで実行する処理、ファイル配置後にサーバーで行う処理、ページ同期レポートの読み方、リリースに含めるwp bsコマンドを扱います。

リリースの全体像

  1. ビルド。 CIで本番用のComposer依存関係をインストールします。
  2. アップロード。 vendor/を含むテーマをサーバーに配置します。
  3. ページを同期。 wp bs pages syncでページ投稿をファイルに合わせ、レポートを出力します。
  4. オリジンのキャッシュを更新。 ページに変更があれば保存済みのHTMLを消去し、再度キャッシュします。
  5. CDNを消去。 最後に実行し、エッジのキャッシュを新しいオリジンから再取得させます。

ステップ3と4には、サーバー上のWP-CLIが必要です。以下のスクリプトでは、jqを使ってJSONも読み取ります。

ステップ 1:CIでComposerを使う

Blockstudioをテーマに含め、composer.lockをコミットして、CIでテストしたバージョンを正確にインストールできるようにします。

JSON
{
  "require": {
    "blockstudio/blockstudio": "^7.0"
  }
}
PHP
<?php
require_once __DIR__ . '/vendor/autoload.php';

CIでは開発用パッケージを除外してインストールします。

シェル
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

Blockstudioはオートローダーから起動し、実行時に必要な依存関係もパッケージ内にバンドルされ、名前空間化されています。vendor/ディレクトリから読み込まれると、組み込みのGitHubアップデーターは無効になるため、バージョンを変更する方法はComposerだけになります。

ステップ 2:書き込み可能にする対象を決める

Blockstudioは実行時に生成ファイルを書き込みます。デプロイでディレクトリを置き換えたりロックしたりする前に、書き込み先を確認してください。

  • デフォルトでは、実行時キャッシュはwp-content/blockstudio/cache/の下に保存されます。専用の書き込み可能なボリュームを使う場合は、cache.pathをその場所に指定してください。パスを変更するとキャッシュは空の状態から始まります。
  • コンパイル済みブロックアセットは、デフォルトで各ブロックの隣にある_distフォルダーへ書き込まれます。リリースディレクトリが読み取り専用、またはデプロイごとに置き換えられる場合は、assets.outputをcacheに設定すると、キャッシュディレクトリの下に保存されます。
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

デプロイ時にキャッシュを消去する必要はありません。各キャッシュエントリーは、ブロックファイル、設定、有効なテーマとプラグイン、WordPress、PHP、Blockstudioの各バージョンなど、入力値をキーにしています。そのため、これらを変更するリリースでは新しいキーが使われます。productionとstagingでは、Blockstudioは検証済みの監視スナップショットを20秒間信頼し、その後にファイルを再確認します。そのため、変更の検出に最大20秒かかることがあります。blockstudio/cache/watch_debounceフィルターでこの時間を変更できます。

ステップ 3:ページを同期する

ページ投稿を変更するには、明示的な同期が必要です。フロントエンド、管理画面、Ajax、REST、cron、通常のWP-CLIリクエストでは、ページソースの検出もページ投稿への書き込みも行いません。デプロイ時に次を実行する必要があります。

シェル
wp bs pages sync --format=json

テーマにaboutとcontactの2ページがあるサイトでは、初回実行時にページが作成されます。

JSON
{
    "discovered": 2,
    "created": 2,
    "updated": 0,
    "unchanged": 0,
    "removed": 0,
    "failed": 0,
    "fullReconciliation": true,
    "sourceId": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd",
    "sourceIdentity": {
        "commit": "",
        "dirtyHash": "",
        "inventoryHash": "aaec5b9dd13d74eea872117b6167caa7a5d5c1abad9572fba22f6ddf6340adfe",
        "engineFingerprint": "2c442442bb49f91e7187560e6db8f3475caa0b62b47708cab95b6ff13aba4469",
        "hash": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd"
    },
    "pages": {
        "about": {
            "status": "created",
            "postId": 545,
            "locked": false
        },
        "contact": {
            "status": "created",
            "postId": 546,
            "locked": false
        }
    },
    "errors": []
}

レポートの読み方:

  • created、updated、unchanged、removed、failedはページ数をカウントします。ソースのフィンガープリントが変わっていないページでは、投稿や投稿メタデータへの書き込みは発生せず、更新フックも実行されません。
  • 各実行ではページの完全な一覧を比較します。fullReconciliationは、その実行が完全な照合にあたるかどうかを示します。初回の実行時、--fullを指定した場合、または同期エンジン自体が変更された場合はtrue、以前の同期が成功した際の識別情報が存在する場合はfalseです。後続のツールはこれを使って、すべてを再構築するかどうかを判断できます。
  • sourceIdentityは、ページ一覧と同期エンジンの決定論的なフィンガープリントです。コマンドは実行の成功後にこれを保存します。

--format=jsonを指定しない場合、コマンドは概要行を1行と成功メッセージを出力します。ターミナルではないCIログでは、行はタブ区切りになります。

Text
discovered	created	updated	unchanged	removed	failed	source_id
2	0	1	1	0	0	7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.

この実行はabout/index.phpの編集後に行われ、1ページが更新され、1ページは変更されませんでした。

同期に失敗した場合

検出または照合でエラーが報告されると、コマンドはステータス1で終了し、CIのステップは失敗します。JSONレポートは引き続き出力されるため、ログに記録してください。不正なpage.jsonは次のようになります。

JSON
{
    "discovered": 0,
    ...
    "failed": 1,
    ...
    "pages": [],
    "errors": [
        {
            "code": "invalid_page_json",
            "message": "Invalid page.json file.",
            "context": {
                "path": ".../wp-content/themes/acme/pages/pricing/page.json"
            }
        }
    ]
}

ソースがなくなった管理対象ページは、エラーなしで実行が完了した後にのみ削除されるため、同期に失敗したリリースで稼働中のページが消えることはありません。削除されたページはデフォルトでゴミ箱に移動します。blockstudio/pages/orphan_actionフィルターは、trash、delete、またはkeepを返せます。

デプロイのたびに実行する

ページに変更がない場合も同期を実行してください。リリースディレクトリにデプロイしてシンボリックリンクを切り替える場合、変更のないページも、次回の同期で更新されるまで以前のリリースのテンプレートとレイアウトのパスを参照したままになります。この更新ではpost_contentも更新日も変更されません。

--authoritativeと--full

通常の同期では、キー付きブロック内で編集者が変更したコンテンツが保持されます。--authoritativeは代わりにファイルの管理対象コンテンツで置き換え、Page Syncのロックを解除する場合があります。ファイル側を優先する場合、たとえばステージングサイトをリセットするときや、ファイルに紐づくページをエディターで編集しないサイトで使用してください。編集者が作業中のサイトでは、すべてのデプロイで指定しないでください。

--fullは、保存済みの識別情報にかかわらず、実行を完全な照合として扱います。ページ比較は毎回すでに完了しているため、このフラグが変えるのはレポートのfullReconciliationであり、チェック対象のページではありません。後続のステップでこの値をもとに全体を再構築する場合に指定してください。

PHPで書かれたツールからは、Blockstudio\Pages::reconcile()を直接呼び出せます。同じレポートを返しますが、識別情報は保存しません。静的アーティファクトの有効化など、リリースの残りの処理が検証された後にBlockstudio\Pages::store_successful_source_identity()を呼び出してください。

ステップ4:静的キャッシュを更新する

サイトでデフォルトのsignatureモードの静的プリレンダリング]を使用している場合、WP-CLIから更新されたページ投稿は、保存済みのHTMLを自動的に消去しません。レポートを確認し、変更があれば消去してからウォームアップしてください。

シェル
#!/usr/bin/env bash
set -euo pipefail

cd /var/www/example.com
report=$(mktemp)

# 1. Reconcile file-backed pages and keep the report.
if ! wp bs pages sync --format=json > "$report"; then
  cat "$report"
  exit 1
fi
jq '{discovered, created, updated, unchanged, removed}' "$report"

# 2. Drop stored HTML when page content changed.
changed=$(jq '.created + .updated + .removed' "$report")
if [ "$changed" -gt 0 ]; then
  wp bs prerender purge
fi

# 3. Re-warm in bounded passes until a pass warms nothing.
for _ in $(seq 1 50); do
  warmed=$(wp bs prerender warm | jq '.warmed')
  [ "$warmed" -gt 0 ] || break
done

wp bs prerender status | jq '{files, queue}'

wp bs prerender warmを実行するたびに、古くなった公開URLがキューに追加され、そのうちwarm.concurrency件までがレンダリングされ、概要が出力されます。この実行では、キューにある6件のURLのうち4件が処理対象になりましたが、4件すべてのレンダリングに失敗しました。

JSON
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}

レンダリングに失敗したURLは古い状態のまま残り、次回の実行時に再びキューに追加されます。そのため、空のキューを待つのではなく、ウォームアップ対象がなかった最初の実行でループを停止します。残ったURLは、スケジュール済みウォーマーまたは次の匿名訪問時に処理されます。

graphモードでは、ページごとのURLウォーマーは無効になり、warmは何もキューに追加しません。グラフサイトでは、ステップ2と3を独自のビルドに置き換え、影響を受けるURLをレンダリングして結果を一括で有効化します。署名モードとグラフモードを参照してください。

ステップ5:CIワークフロー

以下のワークフローはGitHub Actionsの例です。基本的な流れはどのCIシステムでも同じです。ビルドし、アップロードし、サーバー上でスクリプトを実行して、CDNを消去します。

YAML
name: Deploy

on:
  push:
    branches: [main]

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.2"
          tools: composer:v2

      - name: Install production dependencies
        run: composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

      - name: Configure SSH
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan example.com >> ~/.ssh/known_hosts

      - name: Upload the theme
        run: |
          rsync -az --delete --exclude ".git" --exclude ".github" \
            ./ deploy@example.com:/var/www/example.com/wp-content/themes/acme/

      - name: Sync pages and refresh the static cache
        run: ssh deploy@example.com 'bash -s' < scripts/post-deploy.sh

      - name: Purge the CDN
        run: curl -fsS -X POST "${{ secrets.CDN_PURGE_URL }}"

cancel-in-progress: falseを指定したconcurrencyは、実行中のデプロイを同期の途中でキャンセルせず、後続のプッシュをキューに追加します。PHP 8.2はBlockstudioの最低要件です。最後のステップは、CDNの消去APIに置き換えてください。

メンテナンス用コマンド

これらは毎回のリリースでは使いませんが、デプロイ手順書には記載しておきましょう。

旧ロックの滞留分を解消する。 7.6.14より前のリリースでは、コンテンツが変更されるたびに.build.lockファイルが残されていました。アップグレード後は、WP-Cronが上限付きのバッチで削除します。状況を確認し、滞留分を一度に処理するには次のようにします。

シェル
wp bs cache status
wp bs cache cleanup
Text
0 legacy build lock(s) across 0 cache namespace(s).
Next cleanup batch in 0 second(s).

cleanupは、1時間以内に作成されたロック、または実行中のリクエストがまだ保持しているロックを次回の実行まで残します。サイトが稼働中にロックファイルを手動で削除しないでください。

実行時キャッシュを消去する。 wp bs cache clearは現在のサイトのキャッシュをすべて消去し、wp bs cache clear --scope=runtimeはすべての名前空間にまたがって1つのスコープを消去します。次のリクエストではキャッシュがない状態から再構築されるため、アクセスの少ない時間帯に、必要な場合のみ実行してください。入力を変更するとキーはすでに切り替わります。

Blockstudioを削除する。 Composerのインストールにはプラグイン無効化フックがないため、パッケージがなくなってもcronのイベントは解除されず、早期配信用のドロップインも削除されません。依存関係を削除する前に、次を実行してください。

シェル
wp bs teardown

このインストールが所有するcronイベントと静的プリレンダリングの状態を削除し、他のドロップインや設定ファイルには触れません。その後、再度有効にしたときにクリーンな状態で開始できます。

次のステップ