コンテンツにスキップ

WordPress CMS ローカル開発環境セットアップ手順

このドキュメントは Headless CMS 用の WordPress をローカルで動作させるための手順をまとめたものです。apps/wordpress-cms/ ディレクトリに配置した Docker Compose 構成を利用します。

事前準備

  • Docker Desktop または Docker Engine（Compose v2 が利用可能な状態）
  • git でこのリポジトリを取得済み
  • 環境変数は AWS Secrets Manager（dev_wp）で管理（ローカル .env は非推奨）
# Secrets Manager + just を使うための推奨設定
export RITSUBI_AWS_PROFILE=ritsubi
export SECRETS_PREFIX=/b2b-ecommerce
aws sso login --profile "$RITSUBI_AWS_PROFILE"

WORDPRESS_UID / WORDPRESS_GID は、docker-compose.yml 内でデフォルト値 1000 が設定されています。一般的な Linux 開発環境では設定不要ですが、異なる場合は環境変数で上書き可能です。

起動手順

  1. WordPress 用ディレクトリへ移動します。
cd apps/wordpress-cms
  1. コンテナを起動します（just 経由で AWS Secrets Manager を適用）。
just wp-up
  1. データベースのヘルスチェック完了後、WordPress が http://localhost:8181 で応答します。

初期セットアップの自動化 (Bootstrap)

環境変数を注入した状態で bootstrap スクリプトを実行すると、管理者アカウントの作成や API 連携設定が自動的に完了します。

just wp-bootstrap

bootstrap.sh は以下を自動的に行います：

  • 管理者アカウント作成: WP_ADMIN_USER / WP_ADMIN_PASSWORD を使用。
  • 設定値の同期: RITSUBI_VENDURE_API_URL などの環境変数を検出し、WordPress のオプション（データベース）に自動保存します。
  • 監視設定の同期: SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE, SENTRY_SEND_DEFAULT_PII が存在する場合、WordPress の runtime 監視設定として option へ同期します。 WORDPRESS_BROWSER_SENTRY_* が存在する場合は browser runtime 用 override として同様に同期します。
  • Storefront 即時反映 webhook: CMS_REVALIDATE_SECRET（*_shared 正本） と任意の STOREFRONT_REVALIDATE_URL がコンテナへ注入されると、 ritsubi-ec-plugin の menu / post / option 保存 hook が Storefront /api/revalidate/cms を非同期で叩き、フッター・ヘッダー・ お知らせ等を即時反映させます（参照: wordpress-cms-integration.md）。 ローカルで STOREFRONT_REVALIDATE_URL を明示しない場合、STOREFRONT_URL +/api/revalidate/cms にフォールバックします。
  • プラグイン有効化: WPGraphQL, ACF, Ritsubi EC Plugin などの必須プラグインを有効化。
  • 地域設定: 日本語化、タイムゾーン (Asia/Tokyo) の設定。
  • ローカル用シード投入: お知らせ・キャンペーン投稿、campaign 連動メインバナー、画像を投入。
  • bootstrap verify: plugin / ACF schema / seed / option / menu が揃ったかを機械確認。
  • drift audit: just wp-drift-audit で、WordPress が期待する CMS 状態との差分を JSON 監査。

just wp-* レシピでは、WP_ADMIN_* のローカル環境変数は無視され、dev_wp（または指定 config）の AWS Secrets Manager の値のみを利用します。

[!IMPORTANT] 本番/ステージングは 管理画面の UI 操作のみ で運用します。
seed-data.sh によるキャンペーン/画像投入は ローカル限定 です。

[!TIP] 「環境変数からDBへの同期」ルール 設定値（API URL等）は、DB (wp_options) を Source of Truth とします。これはマネージド環境との運用を統一するためです。ローカル開発では bootstrap スクリプトが環境変数から DB へ値を流し込むことで、初期設定の手間を省いています。

アップロード上限の調整（デフォルト256MB）

  • 反映ファイル: apps/wordpress-cms/php/uploads.ini
  • マウント設定: apps/wordpress-cms/docker-compose.yml の wordpress サービスで ./php/uploads.ini:/usr/local/etc/php/conf.d/uploads.ini を指定済み

現在のデフォルト値:

upload_max_filesize = 256M
post_max_size      = 256M
memory_limit       = 512M
max_execution_time = 180

値を変更したい場合:

# 例: 512MB に拡張する場合
sed -i 's/256M/512M/' apps/wordpress-cms/php/uploads.ini
cd apps/wordpress-cms
docker compose up -d --force-recreate wordpress

反映確認:

cd apps/wordpress-cms
docker compose exec wordpress php -r 'echo ini_get("upload_max_filesize"),"\n",ini_get("post_max_size"),"\n",ini_get("memory_limit");'

永続化対象:

  • wordpress-data ボリューム: WordPress コアとアップロードファイル
  • db-data ボリューム: MariaDB データベース
  • apps/wordpress-cms/plugins/ themes/ uploads/: ローカルで編集したプラグイン・テーマ・メディア資産

wp-cli の利用

Docker Compose には wp-cli サービスを含めています。WordPress の自動セットアップやプラグイン導入を CLI から行うことができます。

初期セットアップの自動化

環境変数を準備した上で以下を実行します（Secrets Manager + just 推奨）。

cd apps/wordpress-cms
just wp-bootstrap
  • 管理者アカウントが WP_ADMIN_* の値で作成されます。
  • サイトURL・タイムゾーン・日付/時刻フォーマット・パーマリンク・コメント設定が自動適用されます。
  • 日本語言語パックの導入と有効化が行われます。
  • WPGraphQL プラグインが自動的にインストール・有効化されます。
  • 初期状態の不要プラグイン（Hello Dolly / Akismet）は削除されます。
  • wp-auth-check と wp-bootstrap-verify により、管理者資格情報と local 検証前提が揃っていることまで確認されます。
  • さらに bootstrap 後の drift を明示確認したい場合は just wp-drift-audit を実行してください。

任意コマンドの実行

wp コマンドはそのまま渡せます。例: プラグイン一覧を表示。

cd apps/wordpress-cms
just wp-cli 'plugin list'

必須プラグインのセットアップ

ローカル開発に必要なプラグインをインストール・有効化します。

cd apps/wordpress-cms
just wp-cli 'plugins-setup'

引数を指定せずに実行すると wp shell が起動します。

E2E テスト（Playwright）

WordPress のプラグイン動作確認は Playwright で実行します。ローカルの WordPress が起動していることが前提です。

cd apps/wordpress-cms
just wp-test

WordPress Drift Audit

WordPress 側の drift は、MariaDB のテーブル/カラム差分ではなく、コードベースが期待する CMS 状態との差分として扱います。

just wp-drift-audit

staging / production では just wp-drift-audit-vps <env> を使います。こちらは SSH で wp-cli を叩くのではなく、WORDPRESS_ENDPOINT と CMS_API_TOKEN を使って live WordPress の /wp-json/ritsubi/v1/drift-audit を read-only で呼び出します。

監査対象:

  • 必須 plugin
  • 必須 post type / taxonomy / menu location
  • apps/wordpress-cms/plugins/ritsubi-ec-plugin/acf-json/ と live ACF 定義
  • home / siteurl / ritsubi_ec_storefront_url などの同期対象 option
  • fixed route page
  • local profile では seed campaign / product_detail / attachment / main banner seed

just wp-bootstrap-verify は bootstrap-local profile の薄い wrapper です。継続運用の正規コマンドは just wp-drift-audit とします。

VS Code タスク連携

ルートの .vscode/tasks.json に「CMS: WordPress Up」「CMS: WordPress Down」を追加済みです。VS Code からタスクを実行すると just wp-up / just wp-down が発火し、ブラウザで http://localhost:8181 を開くだけで管理画面にアクセスできます。

構造とデータの同期方針

本プロジェクトでは、WordPress の「構造（スキーマ）」「データ（コンテンツ）」「インフラ（R2）」を分離して管理します。

0. インフラの管理（R2 バケット・API トークン）

WordPress 用の R2 バケットおよび Cloudflare API トークンの正本は infra-ritsubi リポジトリで管理されています。

  • 管理場所: infra-ritsubi/live/prod/cloudflare/r2.tf
  • デプロイ: Terraform Cloud (prod-cloudflare ワークスペース) 経由で適用されます。
  • 注意: バケットの作成や物理的な設定変更は infra-ritsubi 側で行い、ritsubi-local 側ではそれらを参照（AWS Secrets Manager 経由）するのみに留めます。

1. 構造の同期（スキーマ・設定）

カスタム投稿タイプ、ACF フィールド定義、タクソノミーなどの構造は、「ACF Local JSON」 を利用してコードベース（Git）で管理します。

  • 管理場所: apps/wordpress-cms/plugins/ritsubi-ec-plugin/acf-json/
  • 同期の流れ:
  • ローカルの管理画面でフィールド等を変更すると、JSON ファイルが自動更新される。
  • JSON ファイルをコミット・プッシュする。
  • 各環境（Staging/Production）へのデプロイ時、WordPress が自動的に JSON を読み込み DB 構造を同期する。
  • 手動同期コマンド:
# Local JSON 読込とは別に、DB へ明示 import したい場合だけ使う
just wp-acf-sync

2. データの同期（コンテンツ・投稿内容）

お知らせ、キャンペーン、ページなどの実際の投稿データは、各環境で独立して運用することを基本としますが、必要に応じて環境間で同期可能です。

  • ローカル初期化（シードデータ）:
just wp-bootstrap

※ 内部で seed-data.sh が走り、開発に必要なプレースホルダーを投入します。

  • 環境間（Local → Remote）のコンテンツ同期 (Push):
# dry-run
just wp-graphql-push

# 実際に反映
just wp-graphql-push apply=true
  • 環境間（Remote → Local）のコンテンツ同期 (Pull): Staging や Production の最新データをローカルに取り込んで開発したい場合に使用します。
# dry-run
just wp-graphql-pull

# 実際に反映
just wp-graphql-pull apply=true

※ AWS Secrets Manager の WORDPRESS_ENDPOINT をソースとして自動設定します。

  • DB 全体の同期（大規模移行時）: メディアライブラリを含む完全な同期が必要な場合は、WP-CLI を使用します。
# エクスポート
just wp-cli 'db export backups/dump.sql'
# インポート
just wp-cli 'db import backups/dump.sql'
# URL置換
just wp-cli 'search-replace <old_url> <new_url>'

コンテンツモデリング方針（お知らせ・キャンペーン）

ヘッドレス側で利用する「お知らせ」「キャンペーン」などの CMS コンテンツは、WordPress の標準機能で投稿タイプを登録し、 Advanced Custom Fields (ACF) でメタデータを管理します。必要に応じて WPGraphQL for ACF を併用し、GraphQL スキーマにフィールドを公開します。 WPGraphQL は初期セットアップ済みです。

導入と設定の流れ:

  1. プラグイン導入（wp-cli 経由で実行可能）
# ACF Pro が配布済みの場合
just wp-cli 'plugin activate advanced-custom-fields-pro'
just wp-cli 'plugin install https://github.com/wp-graphql/wpgraphql-acf/releases/download/v2.4.1/wpgraphql-acf.zip --activate'
  1. 投稿タイプの登録
  2. functions.php などで register_post_type / register_taxonomy を使い、announcement・campaign と必要なタクソノミー（顧客ステータス、メニューコード等）を登録
  3. REST API への露出 (show_in_rest => true) と WPGraphQL 用設定 (show_in_graphql => true) を有効化。特に announcement 投稿タイプは GraphQL から announcements クエリで取得するため、graphql_single_name = Announcement / graphql_plural_name = Announcements を必ず設定する
  4. ACF でフィールドグループ定義
  5. 投稿タイプごとの推奨フィールド例
    • お知らせ (notice): 「表示対象ステータス」「概要テキスト」「関連リンク」等。固定表示は WordPress 標準の Sticky Post（この投稿を先頭に固定表示）を利用し、開始／終了日時は任意オプションにする
    • キャンペーン (campaign): 「開催期間」「対象ステータス／メニュー」「対象商品」「達成条件」「特典内容」等
  6. GraphQL 公開設定を「Show」にしてヘッドレス側から取得可能にする
  7. 入力ルールの文書化
  8. 顧客ステータス一覧やメニューコード一覧などは /docs/ に手順書を整備し、誤入力防止とトレーサビリティを確保
  9. 初期データ投入
  10. 管理画面でコンテンツを登録するか、wp post create / wp post meta update を用いて CLI で投入
  11. Storefront は WordPress を直接参照せず、Vendure shop-api 経由で CMS データを取得する。Storefront 側で必要なのは VENDURE_BASE_URL / VITE_PUBLIC_VENDURE_BASE_URL で、WordPress 側の endpoint は Vendure プラグイン設定で管理する

マネージド環境でも同じプラグインが利用できるか（ライセンス・プラン制限）を事前確認し、CPT UI/ACF の設定は JSON エクスポート等で同期する方針とします。

マネージド環境への移行方針

本番は WordPress マネージドホスティング（例: WP Engine, Kinsta, ConoHa WING Managed WordPress 等）を想定します。以下の運用フローでローカル → マネージドの差分反映を行います。

  1. コード資産の管理
  2. apps/wordpress-cms/themes/・plugins/ 配下で Git 管理が必要なテーマ／プラグインのみリポジトリに含める。

  3. ベンダー配布プラグインは本番環境側でインストールし、バージョン情報は別途運用リストで管理する。

  4. 設定・データの同期

  5. ローカルで作成したページ／投稿／設定は wp-cli によるエクスポートで管理。
    • 例: just wp-cli 'db export backups/local-YYYYMMDD.sql'

  6. マネージド環境への反映は以下いずれかを採用する。

    • wp-cli db import + wp search-replace による手動同期
    • WP Migrate またはマネージド環境の標準ミグレーション機能（ex. Kinsta Migrate, WP Engine Migrate）

  7. URL 置換と動作確認

  8. 本番 URL に合わせて wp option update home / siteurl を更新。

  9. ヘッドレス連携先 (Storefront 等) のドメインを WPGraphQL / REST API の CORS 設定に登録。

  10. バックアップ・ロールバック手順

  11. 本番環境はマネージド側の自動バックアップに加え、移行直前の DB/Uploads を wp-cli でスナップショット取得。

  12. Migrate 実行後に GraphQL エンドポイント (/graphql) と REST API (/wp-json/) のテストを実施し、問題があればスナップショットからリストアする。

  13. 権限・セキュリティ運用

  14. 管理ユーザーはマネージド環境側の SSO や Two-Factor Auth を活用し、ローカルのデフォルト資格情報は移行後すぐに無効化する。
  15. プラグインアップデートはマネージド環境のステージングで事前検証し、wp plugin update --dry-run で互換性を確認してから本番適用する。

停止と再開

  • 停止: docker compose down
  • 再開: docker compose up -d

ボリュームを削除したい場合は docker compose down -v を使用します（データが全て削除されるので注意してください）。

フロントエンド連携のポイント

本プロジェクトでは、Storefront は WordPress へ直接アクセスせず、Vendure の CmsIntegrationPlugin をプロキシとして経由します。

  • WordPress 端点: http://localhost:8181 (Internal Base URL)
  • Vendure プロキシ設定: Vendure サーバーで WORDPRESS_ENDPOINT に上記 base URL を指定します（内部で /graphql を付与）。
  • Storefront 取得: Storefront は VENDURE_BASE_URL / VITE_PUBLIC_VENDURE_BASE_URL を使い、Vendure の Shop API から正規化されたデータを取得します。
  • 認証: WordPress 側の API 制限がある場合は、Vendure 側で JWT や Application Passwords を保持・付与します。

統合ドキュメント

WordPress CMS統合の詳細については、以下のドキュメントを参照してください：

マネージド環境でのGraphQLエンドポイント設定

マネージドWordPress環境では、パーマリンク設定によってGraphQLエンドポイントのURLが変わります。

推奨設定

  • パーマリンク設定: 数字ベースまたはカスタム構造（/%post_id% や /post/%post_id%）
  • 理由: 一意性が保証され、日本語が混入しないため
  • 設定方法: WordPress管理画面 → 設定 → パーマリンク設定
  • GraphQLエンドポイント: /graphql
  • パーマリンク設定が「プレーン」の場合、index.php?graphql 形式になることがあります
  • パーマリンク設定を変更することで、/graphql でアクセス可能になります

環境変数設定

Storefront の環境変数として以下を設定（Secrets Manager 推奨）:

WORDPRESS_ENDPOINT=https://your-wordpress-site.com

フィーチャー済みお知らせバナーの実装

isFeatured が true のお知らせは、サイトトップに黄色のバナーで固定表示されます。

  • ACFフィールド: announcementMeta.isFeatured (boolean)
  • 表示位置: ヘッダーの直下、画面の一番上
  • スタイル: 黄色の警告色バナー（bg-amber-50）
  • 機能:
  • 複数のお知らせを同時表示
  • 各お知らせごとに個別に閉じるボタン
  • クリックでお知らせ詳細ページに遷移

実装詳細: apps/storefront/src/components/layout/featured-announcement-banner.tsx

ファイル構成

apps/wordpress-cms/
├── docker-compose.yml
├── .env.example
├── plugins/
├── themes/
├── uploads/
└── scripts/
    ├── bootstrap.sh
    └── wp-cli-entrypoint.sh
  • plugins/ themes/ は Git 管理したい独自コードを配置する領域です。
  • scripts/bootstrap.sh は初期セットアップと必須プラグイン有効化を自動化します。
  • 追加の自動化が必要な場合は scripts/ 配下にシェルスクリプトを追加し、wp-cli サービスから呼び出してください。

VPS へのデプロイ

ローカルで構築した構成は WebArena Indigo VPS へ、Ansible を用いてデプロイ可能です。 just wp-cli-vps を使用することで、ローカルと同様の wp-cli 操作を VPS 上の環境に対しても実行できます。

詳細は WordPress VPS デプロイメントガイド を参照してください。