DEV Community

Cover image for Docker environment for WordPress development
Sarah Siqueira
Sarah Siqueira

Posted on • Updated on

Docker environment for WordPress development

A little while ago, I wrote about the reasons why I changed from XAMPP to Docker, back then I shortly describe my actual Docker WordPress environment. Now, I am writing about this Docker environment in more detail.

Is a Docker WordPress Environment focused on the development of WordPress plugins and themes, supports WP-CLI, phpMyAdmin, Xdebug and WordPress Coding Standards - WPCS.

Is meant to be used for development purposes only. It's not meant to be used in production.



Folders Structure

Image description

  • .vscode

  • db

  • docker: also install Xdebug and set Xdebug.ini.

  • plugins

  • themes

  • wp-core

  • .gitignore

  • composer.json

  • license

  • readme


Docker containers used on docker-compose. yml:

  • WordPress: Uses the official WordPress latest docker image.
  • WP-CLI: The wpcli container was added to only run one-off commands. Don’t need it to run as a service, only as a cli tool, for that run docker-compose run --rm wpcli command
  • db: The MYSQL official image.
  • phpMyAdmin: Intended to handle the administration of MySQL.

Basic usage

Clone (or download) the repository git clone available on GitHub.
Then, go to the /docker folder and set up your chosen variables on the .env file.

Set variables

The variables used for WordPress installation are the following ones, you can use the same or change them, it's up to you.

Enter fullscreen mode Exit fullscreen mode

WARNING: DO NOT store your variables on a .env file, a better approach would be to add the .env file to a .gitignore and store the variables as encrypted secrets.

Starting Docker

After setting your variables, run docker-compose up -d to start the Docker.

When Docker finishes their work (can take a few minutes at the first time, depending on your connection and machine), you will see the WordPress default installation screen in your browser.

Finish WordPress installation.

Image description

In your terminal, cd the root project folder again to start working on your plugins and/or themes.

For using wp-cli, use docker-compose run --rm wpcli command as it was added to only run one-off commands.

🚀 You already can start to work on your themes and plugins, but there are more tools available for use, keep reading.

More Tools

Debugging in WordPress

The wp-core is synchronized through the docker-composer.yml just in case you need to check and/or debug something. After running docker-compose up -d, you will be able to change the WordPress debug mode by changing the following lines on the wp-config.php file inside the wp-core folder.

By default, the wp-config.php generated by Docker will look something like this:

define( 'WP_DEBUG', !!getenv_docker('WORDPRESS_DEBUG', '') );
Enter fullscreen mode Exit fullscreen mode

Replace it with the following:

define( 'WP_DEBUG', true);

define( 'WP_DEBUG_LOG' , true );

define ( 'WP_DEBUG_DISPLAY', true );
Enter fullscreen mode Exit fullscreen mode

More info about debugging in WordPress you can find here.

Xdebug for VSCode

Xdebug will be installed by the docker file as you can see in

RUN pecl install xdebug
RUN docker-php-ext-enable xdebug
Enter fullscreen mode Exit fullscreen mode

Xdebug is enabled and configured to work on VSCode using the extension PHP Debug, install it. The settings are already configured according to the extension documentation, in the launch.json file on the .vscode folder, including the pathMappings for remote host debugging.

"pathMappings": {
"/var/www/html": "${workspaceRoot}/wp-core",
                "/var/www/html/wp-content/plugins": "${workspaceRoot}/plugins",
                "/var/www/html/wp-content/themes": "${workspaceRoot}/themes"
Enter fullscreen mode Exit fullscreen mode

Set WordPress Coding Standards

There are several ways to config WordPress Coding Standards, but in this environment, we will manage it through Composer. To use WordPress Coding Standards we also need to install PHP Code Sniffer.
If you inspect the composer.json on the root folder of the project, you will see the lines:

"require-dev": {
    "squizlabs/php_codesniffer": "^3.7",
    "wp-coding-standards/wpcs": "^2.3",
Enter fullscreen mode Exit fullscreen mode

They are responsible to install PHP Code Sniffer and WordPress Coding Standards when you run:

composer install

After that, Composer will download the necessaire dependencies to the vendor folder. To check if it works, run:

./vendor/bin/phpcs -i

On the first time, the expected output will be:

The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, and Zend

To use WPCS, we have "to tell" the PHP Code Sniffer about the WordPress Coding Standards. For that, run the command:

./vendor/bin/phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs

To confirm if it works, run ./vendor/bin/phpcs -i again, and the expected output this time should be:

The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, WordPress, WordPress-Core, WordPress-Docs, and WordPress-Extra

This way, WordPress Coding Standards are available for all plugins and themes you work with inside this Docker environment.

Using wpcs

For VS Code "to understand the standards", we need some extension, my chosen one was the phpcs. Install it. The settings are already configured according to the phpcs extension documentation, in the settings.json on the .vscode folder in this repository.

If you installed everything correctly because the "phpcs.lintOnSave": true, line on settings.json, when you hit save any PHP file, it will be linted correctly and the warnings/errors will be displayed on the problems tab of your IDE aka VS Code.

Image description

We can also run the following commands on the terminal to check a single file:

./vendor/bin/phpcbf --standard="WordPress" /file-name.php

To display a report on the terminal:

./vendor/bin/phpcs --standard="WordPress" /file-name.php

We can also run the commands to check all the files at once in the project but may experience performance issues depending on your project size, may be even necessaire to adjust our php.ini directives like the max_execution_time. For that reason, use the following commands carefully:

(A workaround for this performance issue is to define the standards using a .phpcs.xml, I will write about that in the future.)

./vendor/bin/phpcbf --standard="WordPress" .

To display a report on the terminal:

./vendor/bin/phpcs --standard="WordPress" .

🤝 Contributing

It's work in progress. Feel free to comment below, contribute informing about issues or even pull requests for improvements, and if you liked, please star my repository so I can know it's being useful for others devs.

Top comments (2)

dasnow profile image

Hi Sarah,

Thank you for good guide. I would like to add one thing. In my case WordPress Health said that REST API is not working. As I've found the reason was that it try to connect not from outside, but from inside.
In file docker-compose.yml you have port mapping settings for WordPress section:

      - ${WORDPRESS_PORT}:80
Enter fullscreen mode Exit fullscreen mode

If we have in .env file

Enter fullscreen mode Exit fullscreen mode

so REST is sending requests to 8000 port, and can't reach WP.
The solution: before running docker-compose up -d commandset in .env

Enter fullscreen mode Exit fullscreen mode
sarahcssiqueira profile image
Sarah Siqueira

Thanks for notice and reporting it @dasnow, I updated this post and the repository as well: