Local Development

Prerequisites

Docker and Docker Compose — the entire environment runs in containers
Node.js (LTS) — for theme asset compilation (Laravel Mix)
Composer — for building the deploy artifact (not needed for day-to-day dev)

First-Time Setup

# Clone the repo
git clone [email protected]:joeyyax/womens-healthcare-associates.git
cd womens-healthcare-associates

# Copy environment template
cp .env.example .env
# Edit .env with your credentials (database, Redis, Mapbox token, etc.)

# Run setup (generates Caddyfile, updates /etc/hosts)
npm run setup

# Install WordPress core + Composer plugins
composer install

# Start Docker containers
npm run start

# Install theme dependencies and start watching
cd src/wp-content/themes/wha2025
npm install
npm run dev

The npm run setup script reads .env and adds local domains to /etc/hosts.

Docker Services

Service	Container	Image	Purpose
db	wha-mysql	mysql	Database (data persists in `.dev/db/`)
wordpress	wha-wordpress	wordpress (php-fpm)	PHP-FPM process
nginx	wha-nginx	nginx	Static files + PHP proxy
caddy	wha-caddy	caddy	Local HTTPS
redis	wha-redis	redis	Object cache (data persists in `.dev/redis/`)
wpcli	wha-wpcli	wordpress-cli	WP-CLI commands
dozzle	wha-dozzle	amir20/dozzle	Log viewer at localhost:8888

The WordPress container uses a custom entrypoint (tools/entrypoint-local.sh) that skips the upstream WordPress image's extraction step — because WP core is Composer-managed and bind-mounted from the host. On startup, it runs four entrypoint scripts in order:

01-cleanup-plugins.sh — Removes plugins listed in WORDPRESS_BLOCK_PLUGINS env var
02-cleanup-themes.sh — Removes default WP themes, keeps only the active theme
03-composer-install.sh — Runs composer install if vendor/ is missing or stale, then ensures the 000yax-loader.php bootstrap file exists
04-setup-cache.sh — Creates the FastCGI cache directory with proper permissions

Available Commands

All commands run from the project root:

Docker Management

Command	What it does
`npm run start`	Start all containers (`docker compose up -d`)
`npm run stop`	Stop containers
`npm run restart`	Restart containers
`npm run clean`	Stop + remove volumes (full reset — destroys local DB)
`npm run logs`	Follow all container logs
`npm run logs:wordpress`	Follow WordPress container logs
`npm run logs:nginx`	Follow Nginx container logs
`npm run shell`	Bash into WordPress container
`npm run wp -- <cmd>`	Run WP-CLI (e.g., `npm run wp -- plugin list`)
`npm run ps`	Show container status
`npm run stats`	Show container resource usage

Theme Development

Run from src/wp-content/themes/wha2025/:

Command	What it does
`npm run dev`	Watch mode — recompiles CSS/JS on changes
`npm run production`	Production build with cache-busting version hashes

Testing

Command	What it does
`npm test`	Run Playwright tests
`npm run test:ui`	Playwright test UI
`npm run test:headed`	Run tests in headed browser

Build

Command	What it does
`npm run build`	Build deploy artifact into `dist/`

Theme Development Workflow

Start Docker: npm run start
Start theme watcher: cd src/wp-content/themes/wha2025 && npm run dev
Edit CSS in assets/css/, JS in assets/js/, PHP in components/ or template files
Laravel Mix auto-recompiles CSS and JS on save
For PHP template changes, flush caches: docker compose exec redis redis-cli FLUSHALL && npm run wp -- cache flush

The theme watcher (npm run dev) handles CSS and JS changes automatically. PHP changes are picked up immediately by PHP-FPM, but Redis object cache may serve stale data for component output — flush when you see stale content.

Database

Local development uses the MySQL container. Data persists in .dev/db/ across container restarts. A full reset (npm run clean) destroys this directory.

For production data access, import a database dump from Amazon RDS (the production MySQL host on Heroku).

Accessing wp-admin

WordPress admin is at /wp/wp-admin/. Nginx redirects bare /wp-admin automatically.

Local Development

On this page