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

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

事前準備¶

Docker Desktop または Docker Engine（Compose v2 が利用可能な状態）
git でこのリポジトリを取得済み
環境変数は Doppler（dev_wp）で管理（ローカル .env は非推奨）

# Doppler を利用した環境変数の確認
doppler secrets --project b2b-ecommerce --config dev_wp

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

起動手順¶

WordPress 用ディレクトリへ移動します。

cd apps/wordpress-local

コンテナを起動します（Doppler 経由を推奨）。

doppler run --project b2b-ecommerce --config dev_wp -- docker compose up -d

データベースのヘルスチェック完了後、WordPress が http://localhost:8181 で応答します。

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

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

doppler run --project b2b-ecommerce --config dev_wp -- docker compose run --rm wp-cli bootstrap

bootstrap.sh は以下を自動的に行います： - 管理者アカウント作成: WP_ADMIN_USER / WP_ADMIN_PASSWORD を使用。 - 設定値の同期: RITSUBI_VENDURE_API_URL などの環境変数を検出し、WordPress のオプション（データベース）に自動保存します。 - プラグイン有効化: WPGraphQL, ACF, Ritsubi EC Plugin などの必須プラグインを有効化。 - 地域設定: 日本語化、タイムゾーン (Asia/Tokyo) の設定。

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

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

反映ファイル: apps/wordpress-local/php/uploads.ini
マウント設定: apps/wordpress-local/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-local/php/uploads.ini
cd apps/wordpress-local
docker compose up -d --force-recreate wordpress

反映確認:

cd apps/wordpress-local
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-local/plugins/ themes/ uploads/: ローカルで編集したプラグイン・テーマ・メディア資産

wp-cli の利用¶

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

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

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

cd apps/wordpress-local
DOPPLER_CONFIG=dev_wp pnpm with-env docker compose run --rm wp-cli bootstrap

管理者アカウントが WP_ADMIN_* の値で作成されます。
サイトURL・タイムゾーン・日付/時刻フォーマット・パーマリンク・コメント設定が自動適用されます。
日本語言語パックの導入と有効化が行われます。
WPGraphQL プラグインが自動的にインストール・有効化されます。
初期状態の不要プラグイン（Hello Dolly / Akismet）は削除されます。

任意コマンドの実行¶

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

cd apps/wordpress-local
DOPPLER_CONFIG=dev_wp pnpm with-env docker compose run --rm wp-cli plugin list

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

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

cd apps/wordpress-local
DOPPLER_CONFIG=dev_wp pnpm with-env docker compose run --rm wp-cli plugins-setup

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

E2E テスト（Playwright）¶

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

cd apps/wordpress-local
DOPPLER_CONFIG=dev_wp pnpm with-env pnpm exec playwright test -c apps/wordpress-local/playwright.config.ts

VS Code タスク連携¶

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

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

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

導入と設定の流れ:

プラグイン導入（wp-cli 経由で実行可能）

DOPPLER_CONFIG=dev_wp pnpm with-env docker compose run --rm wp-cli plugin install advanced-custom-fields --activate
DOPPLER_CONFIG=dev_wp pnpm with-env docker compose run --rm wp-cli plugin install https://github.com/wp-graphql/wpgraphql-acf/releases/download/v2.4.1/wpgraphql-acf.zip --activate

投稿タイプの登録
functions.php などで register_post_type / register_taxonomy を使い、announcement・campaign と必要なタクソノミー（顧客ステータス、メニューコード等）を登録
REST API への露出 (show_in_rest => true) と WPGraphQL 用設定 (show_in_graphql => true) を有効化。特に announcement 投稿タイプは GraphQL から announcements クエリで取得するため、graphql_single_name = Announcement / graphql_plural_name = Announcements を必ず設定する
ACF でフィールドグループ定義
投稿タイプごとの推奨フィールド例
- お知らせ (notice): 「表示対象ステータス」「概要テキスト」「関連リンク」等。固定表示は WordPress 標準の Sticky Post（この投稿を先頭に固定表示）を利用し、開始／終了日時は任意オプションにする
- キャンペーン (campaign): 「開催期間」「対象ステータス／メニュー」「対象商品」「達成条件」「特典内容」等
GraphQL 公開設定を「Show」にしてヘッドレス側から取得可能にする
入力ルールの文書化
顧客ステータス一覧やメニューコード一覧などは /docs/ に手順書を整備し、誤入力防止とトレーサビリティを確保
初期データ投入
管理画面でコンテンツを登録するか、wp post create / wp post meta update を用いて CLI で投入
Next.js Storefront はサーバーサイドで WORDPRESS_GRAPHQL_ENDPOINT（例: http://localhost:8181/graphql）を参照し、クライアントからは /api/wordpress/graphql Route Handler 経由でアクセスするため、値は .env.local にのみ設定しフロントへは公開しない

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

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

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

コード資産の管理
apps/wordpress-local/themes/・plugins/ 配下で Git 管理が必要なテーマ／プラグインのみリポジトリに含める。
ベンダー配布プラグインは本番環境側でインストールし、バージョン情報は別途運用リストで管理する。
設定・データの同期
ローカルで作成したページ／投稿／設定は wp-cli によるエクスポートで管理。
- 例: DOPPLER_CONFIG=dev_wp pnpm with-env docker compose run --rm wp-cli db export backups/local-YYYYMMDD.sql
マネージド環境への反映は以下いずれかを採用する。
- wp-cli db import + wp search-replace による手動同期
- WP Migrate またはマネージド環境の標準ミグレーション機能（ex. Kinsta Migrate, WP Engine Migrate）
URL 置換と動作確認
本番 URL に合わせて wp option update home / siteurl を更新。
ヘッドレス連携先 (Next.js 等) のドメインを WPGraphQL / REST API の CORS 設定に登録。
バックアップ・ロールバック手順
本番環境はマネージド側の自動バックアップに加え、移行直前の DB/Uploads を wp-cli でスナップショット取得。
Migrate 実行後に GraphQL エンドポイント (/graphql) と REST API (/wp-json/) のテストを実施し、問題があればスナップショットからリストアする。
権限・セキュリティ運用
管理ユーザーはマネージド環境側の SSO や Two-Factor Auth を活用し、ローカルのデフォルト資格情報は移行後すぐに無効化する。
プラグインアップデートはマネージド環境のステージングで事前検証し、wp plugin update --dry-run で互換性を確認してから本番適用する。

停止と再開¶

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

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

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

GraphQL エンドポイント: http://localhost:8181/graphql
REST API: http://localhost:8181/wp-json/
認証方式は本番設計に合わせ、JWT や Application Passwords の利用を検討してください。
CORS 設定はフロントエンドのドメインが確定した段階で調整します。

統合ドキュメント¶

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

WordPress CMS統合ガイド: アーキテクチャ、実装パターン、設定方法
WordPress GraphQL API リファレンス: クエリ例、エラーハンドリング
WordPressコンテンツ管理ガイド: コンテンツ作成・編集手順

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

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

推奨設定¶

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

環境変数設定¶

Next.js Storefrontの .env.local に以下を設定:

WORDPRESS_GRAPHQL_ENDPOINT=https://your-wordpress-site.com/graphql

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

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

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

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

ファイル構成¶

apps/wordpress-local/
├── docker-compose.yml
├── .env.example
├── plugins/
├── themes/
├── uploads/
└── scripts/
    ├── bootstrap.sh
    └── wp-cli-entrypoint.sh

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