Docker WordPress Dev Environment

Remote Debugging with Xdebug and VS Code

In order to set breakpoints and step through the PHP code used in WordPress core, themes and plugins, The Xdebug PHP extension needs to be installed, configured and built into an image.

IP address for the xdebug.remote_host setting is needed to configure the extension.

Windows 10 Professional running Docker Version 17.03.0-ce-win1, open a command prompt and enter ipconfig. The address is listed under DockerNAT. For example:


Ethernet adapter vEthernet (DockerNAT):

   IPv4 Address. . . . . . . . . . . :

OS X El Capitan running Docker Version 17.03.0-ce-mac2, create an alias of IP to your existing subnet mask.

sudo ifconfig en0 alias

If you want to remove the alias, use sudo ifconfig en0 -alias

Using git, clone the official docker WordPress image package. To avoid conflicts with the existing wordpress volume, create a build directory to clone the package into.

mkdir build

cd build

git clone

Edit the build/wordpress/php5.6/apache/Dockerfile appending to the docker-php-ext-install instruction. For example, at the end of the line, add an escape character \ to escape a newline.

docker-php-ext-install gd mysqli opcache \

Add the following code which includes the newline escape at the end of each line, except for the last. This is so the docker-php-ext-install instruction can span multiple lines to install and configure Xdebug.

docker-php-ext-install gd mysqli opcache \
&& pecl install xdebug \
&& echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_enable=1\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_autostart=1\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_connect_back=0\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_host=\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_port=9001\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.idekey=REMOTE\n" >> /usr/local/etc/php/conf.d/xdebug.ini
  • For OS X, use xdebug.remote_host= in the Dockerfile.

Dockerfile reference:


Navigate to the folder where the updated Dockerfile is and tag the image build wpxdebug followed by a dot.

cd wordpress/php5.6/apache

docker build -t wpxdebug .

Once the build has completed, the output should contain a success message with the image ID, for example:

Successfully built 446ca7686815

Verify that the wpxdebug build exists.

docker images wpxdebug
  • Squash newly built layers into a single new layer using the –squash option. For example docker build --squash -t wpxdebug . Remove the unused layers after the build with docker image prune

Update the wp service in the docker compose file by replacing image: wordpress with image: wpxdebug. Additionally, create a custom php.ini file for overwriting various setting and add a volume for it. Everything else remains the same as before.

version: "2"
    image: mariadb
      - mysql:/var/lib/mysql
      - "8001:3306"
      - MYSQL_ROOT_PASSWORD=secret
    image: phpmyadmin/phpmyadmin:latest
      - "8002:80"
      - db:mysql
      - MYSQL_ROOT_PASSWORD=secret
      - VIRTUAL_PORT=8002
    image: wpxdebug
      - ./php/php.ini:/usr/local/etc/php/php.ini
      - ./wordpress:/var/www/html
      - "8003:80"
      - db:mysql
      - VIRTUAL_PORT=8003
memory_limit = 128M
post_max_size = 32M
upload_max_filesize = 16M
max_execution_time = 300

VS Code has great support for PHP, add an adapter for Xdebug such as vscode-php-debug and we’re good to go. Open the local volume folder named wordpress which should be in the same folder as the docker compose wp.yml file.

After installing vscode-php-debug, the projects launch.json file needs to be updated to include the properties to map the files on the server to the local machine. Add the serverSourceRoot and localSourceRoot settings to the wordpress/.vscode/launch.json file. For example,

    "version": "0.2.0",
    "configurations": [
            "name": "Listen for Xbebug",
            "type": "php",
            "request": "launch",
            "port": 9001,
            "serverSourceRoot": "/var/www/html",
            "localSourceRoot": "${workspaceRoot}"
        }, {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9001

Set some breakpoints and reload in the browser.

Published by

Jim Frenette

Web Developer - views here are my own except those taken from people more clever than me.

Loading Disqus Comments ...
Loading Facebook Comments ...