コンテンツにスキップ

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

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

事前準備

  • Docker Desktop または Docker Engine（Compose v2 が利用可能な状態）
  • git でこのリポジトリを取得済み
  • apps/wordpress-local/.env.example をベースにした .env の作成
cp apps/wordpress-local/.env.example apps/wordpress-local/.env

必要に応じて .env 内のパスワードや管理者アカウント情報（WP_ADMIN_*）を編集してください。 WORDPRESS_UID / WORDPRESS_GID はホストユーザーの id -u / id -g に合わせておくと、WordPress コンテナがファイルを書き込む際の権限エラーを防げます。

id -u  # 例: 1000
id -g  # 例: 1000

権限エラーが出た場合は、以下で wp-content 配下を再度調整してください。

docker compose run --rm --user root --entrypoint bash wp-cli -lc "chown -R $WORDPRESS_UID:$WORDPRESS_GID /var/www/html/wp-content"

起動手順

  1. WordPress 用ディレクトリへ移動します。
cd apps/wordpress-local
  1. コンテナを起動します。
docker compose up -d
  1. データベースのヘルスチェック完了後、WordPress が http://localhost:8181 で応答します。初回はインストール画面が表示されます。
  2. 初回セットアップ時は WordPress コンテナの起動後に権限を整えます。
docker compose run --rm --user root --entrypoint bash wp-cli -lc "chown -R www-data:www-data wp-content"

plugins/ や themes/ をホスト側で管理するための権限調整です（初回のみ実行）。

アップロード上限の調整（デフォルト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 から行うことができます。

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

.env を準備した上で以下を実行します。

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

任意コマンドの実行

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

cd apps/wordpress-local
docker compose run --rm wp-cli plugin list

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

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 は初期セットアップ済みです。

導入と設定の流れ:

  1. プラグイン導入（wp-cli 経由で実行可能）
docker compose run --rm wp-cli plugin install advanced-custom-fields --activate
docker compose run --rm 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. 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 等）を想定します。以下の運用フローでローカル → マネージドの差分反映を行います。

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

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

  4. 設定・データの同期

  5. ローカルで作成したページ／投稿／設定は wp-cli によるエクスポートで管理。
    • 例: docker compose run --rm 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. ヘッドレス連携先 (Next.js 等) のドメインを 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 を使用します（データが全て削除されるので注意してください）。

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

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

統合ドキュメント

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

マネージド環境での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 サービスから呼び出してください。