Developing WordPress locally has always been a challenge. Different team members use different operating systems. PHP versions vary. Database configurations differ. The result is the classic developer problem: “it works on my machine.” Docker solves this by packaging your entire development environment — PHP, MySQL, Redis, Apache or Nginx — into containers that run identically on any system.
This guide covers how to set up a Docker-based WordPress development environment for plugin and theme development.
Why Docker for WordPress?
Docker provides reproducible environments. Every developer on your team runs the same PHP version, the same database version, the same web server. No more “it works on my machine” debugging sessions. You can switch between PHP versions with a single configuration change. You can add Redis, Memcached, or Elasticsearch with a few lines of configuration.
Docker also isolates projects from each other. Each WordPress project has its own containers, its own database, its own dependencies. Your client site running WordPress 6.4 with PHP 8.1 doesn’t conflict with your plugin project running WordPress 6.5 with PHP 8.3.
The Docker Compose Stack
A basic WordPress Docker setup uses Docker Compose to define four services: a web server (Nginx or Apache), PHP-FPM, MySQL or MariaDB, and optionally Redis for object caching. The official WordPress Docker image handles PHP and WordPress configuration. Use the official MySQL or MariaDB image for the database, and the official Redis image for caching.
Mount your plugin or theme directory as a volume so changes are reflected immediately without rebuilding the container. Use environment variables in your docker-compose.yml for configuration values that differ between environments.
Configuration Files
The docker-compose.yml file defines your services, networks, and volumes. A separate Dockerfile for PHP allows you to install extensions like imagick or xdebug. An nginx.conf file configures the web server for WordPress permalinks. A php.ini file sets PHP configuration values like upload_max_filesize and memory_limit.
Keep these configuration files in version control alongside your project. New team members should be able to clone the repository, run docker-compose up, and have a working WordPress installation within minutes.
Adding Xdebug for Debugging
Xdebug integrates with Docker for step-through debugging of WordPress code. Add Xdebug to your PHP Dockerfile, configure it in php.ini, and set the IDE key and host IP in the configuration. VS Code’s PHP Debug extension connects to the Docker container automatically when you start debugging.
With Xdebug working in Docker, you can set breakpoints in your plugin code, inspect variables, step through function calls, and debug WordPress requests in real time — the same experience as debugging on a local installation, but with the consistency of a containerized environment.
Email Testing with MailHog
WordPress sends emails for password resets, new user registration, and plugin notifications. In development, these emails shouldn’t actually be delivered. MailHog is a fake SMTP server that captures outgoing emails and displays them in a web interface. Add MailHog as a service in your Docker Compose stack and configure WordPress to use it as the SMTP server.
Access the MailHog web interface at localhost:8025 to view captured emails, inspect their content, and debug email-related issues without risking accidental delivery to real recipients.
The Bottom Line
Docker takes the pain out of WordPress environment setup. It ensures consistency across your team, isolates projects from each other, and makes onboarding new developers a matter of minutes rather than hours. Start with a basic docker-compose.yml with WordPress, MySQL, and PHP. Add Redis, MailHog, and Xdebug as you need them. Once you’ve experienced Docker-based WordPress development, you’ll never go back to manual setup.