Skip to content

Docker and WordPress debug environment

We've previously posted about using Docker for WordPress Development, explaining how to use Docker and Docker compose to quickly and easily set up a local WordPress Software development environment.

This is great for being able to set up a local install of WordPress with an accompanying phpMyAdmin portal to help manage your local WordPress Database. This is all achieved by making use of the Official WordPress docker image.

The one draw back of this, is that it can be quite difficult to debug your PHP code, so if you have an error in your code you're left with some difficult work-arounds to debug it.

All is not lost though, in this post we'll discuss how we can build upon from what we learned by using Docker for WordPress Development by customizing the Official WordPress Image and incorporate Xdebug - Debugger and Profiler Tool for PHP to help with debugging.

Following the instructions below you'll be up and running with a WordPress development environment with debug capability in no time, to enable you to continue on your journey and work along to WordPress Web Application Development - Third Edition: Building robust web apps easily and efficiently

The book will help you learn how to;

  • Develop extendable plugins with the use of WordPress features in core modules
  • Develop pluggable modules to extend the core features of WordPress as independent modules
  • Manage permissions for a wide range of content types in web applications based on different user types
  • Follow WordPress coding standards to develop reusable and maintainable code

Custom Dockerfile

We created a custom Dockerfile to create a reusable Docker image which is available on the docker repository threenine/dockpressdebug.

The source code for the Dockerfile and extended docker-compose.yaml are available


Expanding upon the docker-compose.yaml we created in using Docker for WordPress Development we'll update the file to pull the new customised docker image.

In our particular case we have also update the volumes to map the entire html folder so we can develop more complex plugin functionality.


You will now be able to start and stop the container as normal.

Configure Xdebug

Edit the docker-compose.yaml and add the IP address of your host machine XDEBUG-CONFIG: remote_host={your ip} to the environment section under WordPress.

The customised docker image includes XDebug, whereas the standard WordPress image is a vanilla WordPress install.

Configure your IDE

You are free to use whichever IDE you choose to edit your PHP files.  We prefer Visual Studio Code which has become our unofficial default code editor.

We also make use of the PHP debug extension.

In order to enable debugger you will need to edit the launch.json , a copy of these edits is available from the Github repository

Latest posts by Gary Woodfine (see all)