On February 23rd Eric and Alex gave a presentation at their local WordPress user group, MSPWP, on using Docker to mount local copies of WordPress sites for development. They demonstrated editing a site from Visual Studio Code. Finally, they covered getting started with debugging using XDebug in VS Code. Only a week and a half before they gave their presentation they first began experimenting with Docker, and quickly recognized it as the future for their local development sandboxes of client (and personal) websites. It was recognizing its potential so immediately that led them to want to share their finding with others.

The remainder of this post is a reproduction of the tutorial document that they made available after the presentation to the user group (and this post is, for all intents and purposes, their own place to archive it for anyone to find in the future, and they hope for those who find it that it is useful to you).

Install Docker

To install Docker go to the Docker download page.

An Example docker-compose.yml

The first part of our presentation showed how to create a WordPress install using the standard WordPress image. Here is the contents of the docker-compose.yml we used:

version: '2'

services:
  db:
    image: mysql:5.7
    ports:
      - "3999:3306"
    volumes:
      - db_data:/var/lib/mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: wordpress
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress

  wordpress:
    depends_on:
      - db
    image: wordpress:latest
    ports:
      - "8999:80"
    volumes:
      - ./html:/var/www/html
    restart: always
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_PASSWORD: wordpress

    volumes:
      db_data:

We created a new folder, mspwp, put this docker-compose.yml in that folder, and created a folder named html in that folder. For the purposes of trying this out yourself, do the same.

Run your Docker WordPress Site

In a Terminal at the folder that contains your docker-compose.yml:

Start the Docker container:

docker-compose up -d

Hint: You can omit the -d if you want to see the log stream for the Docker in your Terminal output (but not be returned to a command prompt).

The first time you run the container it will take longer to start as it downloads and sets up the images specified in your YAML.

At this point you should be able to point your browser at localhost:8999 and see the WordPress set up screen. You can run through the setup as usual, and now you have a WordPress site running on your Mac.

To see all the containers Docker is running type the following in Terminal:

docker ps

A Note on the Files for this WordPress Install

After running the container once notice that the files for this WordPress installation are all in the html folder. You can edit any of them there and the changes will be reflected the next time you reload a page of the WordPress site.

To demonstrate this, add a new PHP file named info.php to your html folder that runs:

<?php
echo "Hello MSPWP!";
phpinfo();

Save the file, then point your browser to localhost:8999/info.php. That file should load, and show you details on the PHP installation in your Docker.

Stopping your Docker

Take down the container by running the following in a Terminal at the folder you created above:

docker-compose down

Or simply quit the Docker app from the menubar; in this case when you relaunch Docker the containers (in this case, your WordPress site and its database) will automatically be ready to use. But to continue with this tutorial, for now leave it running.

Install Visual Studio Code

To install Visual Studio Code go to the Visual Studio Code download page.

Installing Extensions

Visual Studio Code has a number of extensions. To access these go to the Extensions area by clicking the square item at the bottom of items in the lefthand sidebar of the window. You can install whatever extensions you’d like, but for the purposes of this tutorial make sure to install PHP Debug.

Opening a folder in Visual Studio Code

Going back to the top item in the lefthand sidebar (Explorer) a Welcome screen should still be shown. In it select the Open folder… option, and select your mspwp folder.

Editing Local Files

Open up info.php from the files list in the folder you opened in Visual Studio Code. Edit the echo line to say something else. Save the file and reload your browser window (or if it is pointed elsewhere, point it to localhost:8999/info.php).

Try your hand at navigating in Visual Studio Code and editing some more by making a change to the header.php file of the active theme (probably twentyseventeen) and loading localhost:8999.

Set up XDebug

To set up XDebug in your container we need to modify docker-compose.yml. First take down your container.

Change the image line for wordpress to use the eceleste/docker-wordpress-xdebug image. Also add XDEBUG-CONFIG: remote_host={your ip} to the environment section under wordpress. This new image includes XDebug, whereas the standard WordPress image is just the vanilla WordPress install with minimum other software.

Note, to find your Mac’s IP Address run the following in Terminal:

ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}'

You can now restart your container.

Using XDebug to Debug PHP in Visual Studio Code

Go to the Debug area by choosing the debug item from the lefthand sidebar (thrd item down). Click on the green Run button, the first time you do this it should give you a menu to choose what kind of debugging to do, select PHP. This will create and open your launch.json file, which defines how the debugger should work. It is stored in the .vscode folder in your workspace (the folder you opened). The contents of this file should be:

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

To test debugging, add a breakpoint in your header.php (click in the gutter by the line number to set a breakpoint at that line). Then run the debugger using the green Run button in the Debug area. With the debugger running you’ll have a debug control bar towards the top of the Visual Studio Code window.

Just reload the page in your browser and the debugger should come forward when your breakpoint gets hit. Look at the variables in the Variables section of this view. You can find and inspect all the usual WordPress variables, including WP_Post.

You can also manipulate the page as it loads using the Debug Console (should be towards the bottom of the Visual Studio Code window). For example, you can modify the post title by typing the following into the console and hitting return: php $post->post_title = "Hello MSPWP"

The debugger can also be invoked for PHP notices, warnings, and exceptions. It will also let you follow all the way through your theme or plugin files, to parent theme and even core files, should you wish.

Copying a Live Site to your Container

To copy a live WordPress website to your container you need to both copy the wp-content files, and copy the database. We do not copy core files, as those might as well be the cleaner versions from the Docker image that was used.

Copy the wp-content files with the following while in your mspwp folder:

rsync -a example.com/wp-content html/

If WordPress is installed in a subdirectory, be sure to include that in the path to copy from.

Assuming that you’re using something other than wp_ as the table prefix, remember to update wp-config.php with the proper prefix for your site.

To copy the database, in an SSH connection to the live server, first dump the database contents (check in the live wp-config.php for the proper username and password):

mysqldump -u username -p password > backup.sql

Copy backup.sql to your Mac. Then you may want to drop the current contents of the database in your container, so in a Terminal on your Mac:

echo "drop database wordpress; create database wordpress;" | docker exec -i mspwp_db_1 mysql -u wordpress -pwordpress

Then import your backup file:

docker exec -i mspwp_db_1 mysql -u wordpress -pwordpress wordpress < backup.sql

Yes, this will generate a warning about the idiocy of including the password on the command line, but in this case we don’t really care. To make a fresh backup of the database in your container, just grab it from MySQL:

docker exec -i mspwp_db_1 mysqldump -u wordpress -pwordpress wordpress > backup.sql

Further Reading

• Composing a WordPress Development Environment with Docker
• Docker Documentation
• XDebug Documentation

About the Presenters

Eric and Alex Celeste do WordPress site management and development as Tenseg LLC. We have clients both locally and across the nation who work in a number of fields. We can be reached at dev@tenseg.net.