WordPress Bootstrap

This guide explains how to bootstrap a WordPress instance with WooCommerce and EMS plugins for local development.

Overview

The WordPress stack runs alongside the Registration Portal backend services and provides:

WooCommerce — Order management and payment processing
Event Info Plugin — Event information display and management
Event Payment Plugin — Integration between WooCommerce and Admin Service

Prerequisites

Docker and Docker Compose installed
GitHub Personal Access Token with repo scope (for private plugin repositories)
Backend services running (MySQL, Admin Service)

Quick Start

cd src/main/docker

# 1. Create environment file
cp .env.wordpress.example .env.wordpress

# 2. Edit .env.wordpress with your GITHUB_TOKEN

# 3. Start full stack with WordPress
docker compose --env-file .env.wordpress -f dev.yml -f wordpress.yml up -d

# 4. Run bootstrap (first time only)
docker compose --env-file .env.wordpress -f dev.yml -f wordpress.yml \
    --profile setup run --rm wordpress-setup

After bootstrap completes:

WordPress: http://localhost:8080
WordPress Admin: http://localhost:8080/wp-admin/
Default credentials: admin / admin123

Configuration

Environment Variables

Create .env.wordpress from the example template:

# WordPress Site
WP_PORT=8080
WP_URL=http://localhost:8080
WP_TITLE=EMS Development
WP_ADMIN_USER=admin
WP_ADMIN_PASS=admin123
[email protected]

# GitHub Token (required for private plugin repos)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Plugin Versions
EIP_PLUGIN_VERSION=1.0.0
EPA_PLUGIN_VERSION=2.0.3

# Event Payment Plugin Configuration
EPA_ADMIN_API_URL=http://admin-service:12504/api
EPA_ADMIN_API_KEY=your-admin-api-key
EPA_CALLBACK_API_URL=http://wordpress:80/wp-json/epa/v1
EPA_CALLBACK_API_KEY=your-callback-api-key
EPA_ENABLE_LOGGING=true

GitHub Token

Create a Personal Access Token at https://github.com/settings/tokens with the repo scope to access private plugin repositories.

Never commit .env.wordpress to version control. It is already in .gitignore.

What the Bootstrap Does

The bootstrap script (wordpress/setup-wp.sh) performs these steps:

Wait for WordPress — Ensures wp-config.php exists
Install WordPress Core — Sets up site with admin credentials
Configure WordPress — Timezone, date format, permalinks
Install WooCommerce — From WordPress plugin repository
Configure WooCommerce — Currency (ZAR), skip onboarding wizard
Create WooCommerce Pages — Shop, Cart, Checkout, My Account
Create Legal Pages — Privacy Policy, Terms & Conditions, Transaction Currency, Cancellation Policy
Enable Bank Transfer — Direct bank transfer with test account (1234567890 @ Test Bank Ltd)
Install Event Info Plugin — From GitHub release
Install Event Payment Plugin — From GitHub release
Configure Payment Plugin — API URLs and keys
Cleanup — Remove default posts and comments

The script is idempotent — safe to run multiple times.

Pages Created

Page	Purpose
Shop	WooCommerce product listing
Cart	Shopping cart
Checkout	Payment checkout
My Account	Customer account management
Privacy Policy	Data handling policy (placeholder)
Terms and Conditions	Legal terms (placeholder)
Transaction Currency	ZAR-only notice
Cancellation Policy	Refund terms (placeholder)

Page

Purpose

Shop

WooCommerce product listing

Cart

Shopping cart

Checkout

Payment checkout

My Account

Customer account management

Data handling policy (placeholder)

Terms and Conditions

Legal terms (placeholder)

Transaction Currency

ZAR-only notice

Cancellation Policy

Refund terms (placeholder)

Test Bank Account

For development, the Direct Bank Transfer payment method is configured with:

Account Name: EMS Test Account
Account Number: 1234567890
Bank Name: Test Bank Ltd
Sort Code: 123456

Daily Usage

Starting the Stack

cd src/main/docker

# With WordPress
docker compose --env-file .env.wordpress -f dev.yml -f wordpress.yml up -d

# Without WordPress (original setup)
docker compose -f dev.yml up -d

Stopping the Stack

docker compose -f dev.yml -f wordpress.yml down

Full Reset

To delete all data and start fresh:

docker compose -f dev.yml -f wordpress.yml down -v

Then run the bootstrap again.

WP-CLI Commands

Use the wpcli service for ad-hoc WordPress administration:

cd src/main/docker

# List installed plugins
docker compose -f dev.yml -f wordpress.yml --profile tools run --rm wpcli plugin list

# Check plugin option
docker compose -f dev.yml -f wordpress.yml --profile tools run --rm wpcli option get epa_admin_api_url

# Update plugin option
docker compose -f dev.yml -f wordpress.yml --profile tools run --rm wpcli option update epa_admin_api_url "http://new-url"

# List WooCommerce orders
docker compose -f dev.yml -f wordpress.yml --profile tools run --rm wpcli wc shop_order list --user=1

Service URLs

Service	External URL	Docker Internal URL
WordPress	http://localhost:8080	http://wordpress:80
Admin Service	http://localhost:12504	http://admin-service:12504
Registration Portal	http://localhost:12505	http://registration-gateway:12505
MySQL	localhost:3306	mysql:3306

Service

External URL

Docker Internal URL

WordPress

http://localhost:8080

http://wordpress:80

Admin Service

http://localhost:12504

http://admin-service:12504

Registration Portal

http://localhost:12505

http://registration-gateway:12505

MySQL

localhost:3306

mysql:3306

Plugin Configuration

Event Payment Plugin Options

The Event Payment Plugin stores configuration in WordPress options. Configure these via WooCommerce > Event API Settings in the WordPress admin.

Option Description

Option	Description
`epa_admin_api_url`	Admin Service API base URL (e.g., `http://admin-service:12504/api`)
`epa_admin_api_key`	API key for Admin Service authentication
`epa_callback_api_url`	Callback URL displayed in settings — Admin Service posts orders here
`epa_callback_api_key`	API key generated by the plugin — Admin Service must include this in requests
`epa_admin_api_connect_timeout`	Connection timeout in seconds (default: 5)
`epa_admin_api_timeout`	Request timeout in seconds (default: 30)
`epa_enable_logging`	Enable debug logging (true/false)

epa_admin_api_url

Admin Service API base URL (e.g., http://admin-service:12504/api)

epa_admin_api_key

API key for Admin Service authentication

epa_callback_api_url

Callback URL displayed in settings — Admin Service posts orders here

epa_callback_api_key

API key generated by the plugin — Admin Service must include this in requests

epa_admin_api_connect_timeout

Connection timeout in seconds (default: 5)

epa_admin_api_timeout

Request timeout in seconds (default: 30)

epa_enable_logging

Enable debug logging (true/false)

The Callback API Key is either: - Set via EPA_CALLBACK_API_KEY environment variable during bootstrap, or - Auto-generated by the bootstrap script (a deterministic key based on WP_URL)

The generated key is displayed in the bootstrap output and in the WordPress admin settings (WooCommerce > Event API Settings). Copy this value to the Admin Service configuration.

API Integration Flow

┌─────────────────┐                      ┌─────────────────┐
│  Admin Service  │  ── (1) Create ───►  │   WordPress     │
│                 │      Order           │   WooCommerce   │
│                 │  ◄── (2) Payment ──  │                 │
│                 │      Status Update   │                 │
└─────────────────┘                      └─────────────────┘

Admin Service → WordPress: POST /wp-json/payment-api/v1/order/event/create/ with callback API key
WordPress → Admin Service: Notifies of payment status changes via Admin API URL with admin API key

Viewing/Updating Options

# View all EPA options
docker compose -f dev.yml -f wordpress.yml --profile tools run --rm wpcli \
    option list --search="epa_*"

# Update API URL
docker compose -f dev.yml -f wordpress.yml --profile tools run --rm wpcli \
    option update epa_admin_api_url "http://admin-service:12504/api"

Troubleshooting

Bootstrap Fails: GITHUB_TOKEN Required

Ensure GITHUB_TOKEN is set in .env.wordpress with a valid Personal Access Token.

WordPress Not Responding

Check if containers are running:

docker compose -f dev.yml -f wordpress.yml ps

Check WordPress logs:

docker logs ems-wordpress

Database Connection Issues

WordPress shares the MySQL instance with Admin Service. Ensure MySQL is healthy:

docker compose -f dev.yml -f wordpress.yml ps mysql

Plugin Installation Fails

Verify the GitHub token has repo scope and the release version exists:

# Check if release exists (requires gh CLI)
gh release view 2.0.3 --repo christhonie/event-payment-plugin-woocommerce

Architecture

The WordPress stack shares infrastructure with the existing backend:

┌─────────────────────────────────────────────────────────────────┐
│                    Docker Network: registration-portal-mysql    │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   MySQL     │  │   Admin     │  │   Registration          │  │
│  │   :3306     │  │   Service   │  │   Gateway               │  │
│  │             │  │   :12504    │  │   :12505                │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────────────────-─┘  │
│         │                │                                      │
│         │                │         ┌─────────────────────────┐  │
│         │                │         │   WordPress             │  │
│         └────────────────┼─────────│   :8080                 │  │
│                          │         │   - WooCommerce         │  │
│                          └─────────│   - Event Info Plugin   │  │
│                          API calls │   - Event Payment Plugin│  │
│                                    └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

WordPress uses the same MySQL instance (creates its own wordpress database) and communicates with Admin Service over the Docker network.