WordPress Local Development with Docker

A clean, developer-friendly setup for running WordPress locally with Docker Compose. It bundles MySQL 8.4 LTS, phpMyAdmin, Mailpit, WP-CLI and custom PHP/MySQL tuning — ideal for plugin/theme development, marketing tests or client prototypes.

Updated for June 2026: WordPress on PHP 8.3, MySQL 8.4 LTS, Mailpit (the maintained MailHog replacement) and Docker Compose v2.

---

🚀 Quick Start

1. Clone this repository or copy it to a new folder
2. Make sure you have Docker Desktop installed (it ships Compose v2)
3. Create your local env file from the template and adjust if needed:

   cp .env.example .env

4. Launch the project:

   docker compose up -d

5. Open in your browser:
   • WordPress: http://localhost:8000
   • phpMyAdmin: http://localhost:8080
   • Mailpit: http://localhost:8025

Note the command is docker compose (Compose v2 plugin). The legacy docker-compose v1 is end-of-life.

---

⚙️ Configuration (.env)

All key variables live in .env (copied from .env.example). The .env file is git-ignored so your local credentials/ports never get committed.

COMPOSE_PROJECT_NAME=mywp           # Prefix for containers, network and volumes

# WordPress Database
WORDPRESS_DB_NAME=wordpress
WORDPRESS_DB_USER=wordpress
WORDPRESS_DB_PASSWORD=wordpress
MYSQL_ROOT_PASSWORD=root

# Port mapping
PROJECT_PORT=8000          # WordPress
PMA_PORT=8080              # phpMyAdmin
MAILPIT_HTTP_PORT=8025     # Mailpit UI
MAILPIT_SMTP_PORT=1025     # Mailpit SMTP

Change these if you run several projects at once.

---

🧠 Running Multiple Projects Without Conflict

1. Use a unique COMPOSE_PROJECT_NAME in each .env
2. Change the host ports (8000, 8080, 8025) to avoid clashes
3. Or use dynamic naming based on the folder:

   COMPOSE_PROJECT_NAME=$(basename "$PWD") docker compose up -d

---

📧 Email Testing (Mailpit)

All WordPress email is automatically captured by Mailpit — no SMTP plugin needed.

The WordPress image is extended (see Dockerfile) with msmtp, and PHP's sendmail_path relays every mail() call to the Mailpit SMTP server (mailpit:1025, configured in php-config/msmtprc). Open the inbox at http://localhost:8025.

Mailpit is a drop-in, actively maintained replacement for the now-abandoned MailHog (same ports, faster, with full-text search and TLS support).

---

🛠️ WP-CLI

A wpcli service is included (it does not run as a daemon). Run commands on demand:

docker compose run --rm wpcli wp core version
docker compose run --rm wpcli wp plugin install woocommerce --activate
docker compose run --rm wpcli wp user list
docker compose run --rm wpcli wp search-replace 'http://old.test' 'http://localhost:8000'

---

⚙️ Custom MySQL Configuration

Tune MySQL via mysql-config/wp.cnf (mounted into the container):

[mysqld]
max_allowed_packet = 64M
innodb_buffer_pool_size = 256M
innodb_redo_log_capacity = 134217728  # 128M
sql_mode = ""

This helps with importing large databases, avoiding strict-mode errors and stable plugin performance (WooCommerce, Elementor, etc.).

MySQL 8.4 uses caching_sha2_password by default. The deprecated mysql_native_password plugin (and the removed default_authentication_plugin option) is no longer used — modern WordPress and phpMyAdmin work with it out of the box.

---

🐛 PHP & Debugging

php-config/php.ini raises upload/memory limits and enables error display for local development. WordPress debugging is on by default:

• WP_DEBUG enabled
• WP_DEBUG_LOG → writes to wordpress/wp-content/debug.log
• WP_DEBUG_DISPLAY off (errors go to the log, not the page)
• SCRIPT_DEBUG on, WP_ENVIRONMENT_TYPE=local

---

📦 File Structure

project-root/
│
├── docker-compose.yml        # Main Docker configuration
├── Dockerfile                # WordPress image + msmtp (mail → Mailpit)
├── .env.example              # Template for local variables (copy to .env)
├── .env                      # Your local variables (git-ignored)
├── wordpress/                # WordPress source files (git-ignored)
├── php-config/php.ini        # Custom PHP settings
├── php-config/msmtprc        # msmtp config (routes mail to Mailpit)
└── mysql-config/wp.cnf       # MySQL tuning for WordPress

Database data is stored in a named Docker volume (db-data), not a bind-mounted folder.

---

🧪 Useful URLs

• WordPress: http://localhost:8000
• phpMyAdmin: http://localhost:8080
• Mailpit (email testing): http://localhost:8025

---

🧼 Cleanup

Stop and remove containers:

docker compose down

Remove containers and the database volume (full reset):

docker compose down -v

---

📬 Tips

• Use Mailpit to intercept all outgoing email locally instead of a real SMTP server
• Inspect PHP settings with docker compose run --rm wpcli wp eval 'phpinfo();'
• Tail WordPress debug output: tail -f wordpress/wp-content/debug.log

---

Happy coding! 🚀