WordPress local development with Docker

Version 2.0.0 - WordPress 7.0

About This Project

ideasonpurpose/wordpress on DockerHub.

This project provides local development environments for fast iteration of existing WordPress websites. This includes pre-configured Docker-based MySQL and PHP servers, our Docker-Build toolchain, Xdebug, ImageMagick and a number of helper scripts.

The project builds on the official WordPress docker image, currently v7.0

Getting Started & Tooling

Project scaffolding and tooling updates are provided by @ideasonpurpose/build-tools-wordpress:

# new project
npx @ideasonpurpose/build-tools-wordpress init

# existing project (run from project root)
npx @ideasonpurpose/build-tools-wordpress refresh

docker-wordpress-dev is now focused exclusively on the tuned WordPress runtime image. The only Docker-based utility kept in generated projects is pull (remote content sync for DB/plugins/uploads via SSH).

See the build-tools package for bootstrap/start commands, .env setup and boilerplate files (docker-compose.yml, webpack config, etc).

Databases

All *.sql files from the top-level _db directory will be in alphabetical order. Later files will overwrite earlier ones.

Workflow & Commands

Basic development commands

• npm run start
  Spins up a database and php server, then serves all content through the devServer proxy at http://localhost:8080. Files in the project directory will be watched for changes and trigger reloads when saved. Type control-c to stop the local server. Change the default port with --port=8080

• npm version [major|minor|patch] Increments the version then uses version-everything to update project files before calling npm run build which generates a production build and compresses all theme files into a versioned, ready-to-deploy zip archive.

Additional Commands and helpers

• bootstrap
  A helper script for starting projects. This will install npm and composer dependencies, reload the MySQL database, activate the development theme and sort the package.json file.
• build - Generate a production-ready build in a zip archive. Ready-to-deploy.
• composer
  Runs composer install from Docker.
  • composer:install - Installs packages from the composer.lock file
  • composer:require - Add new packages and update composer.json
  • composer:update - Updates composer dependencies to their newest allowable version and rewrites the composer.lock file. Opens a mysql shell to the development WordPress database
• db:admin - Starts a phpMyAdmin server at localhost:8002
• db:dump - Writes a compressed, timestamped database snapshot into the _db directory
• db:pull - Alias for pull:db
• db:reload - Drops then reloads the database from the most recent dumpfile in _db, then attempts to activate the development theme
• db:shell - Opens a shell to the development WordPress database
• dev - Alias for start
• mariadb, mysql - Aliases for db:admin
• mariadb-dump, db:dump, mysql:dump, mysqldump - Aliases for db:dump
• mariadb:reload, mysql:reload - Aliases for db:reload
• phpmyadmin - Alias for db:admin
• pull
  Syncs data from a remote server to the local development environment. The bare command will run these sub-commands:
  • pull:db - Syncs down the most recent mySQL dumpfile, backs up the current dev DB then reloads the DB
  • pull:plugins - Syncs down wp-content/plugins from the remote
  • pull:uploads <$YEAR> - Syncs down the current year's wp-content/uploads/$YEAR from the remote. Sync specific years with the optional year argument.
  • pull:uploads-all - Syncs down the entire wp-content/uploads directory from the remote
• logs:wordpress - Stream the WordPress debug.log
• wp-cli - Runs wp-cli commands. The default command re-activates the development theme.

Permissions Repair on macOS

On macOS hosts, modifying permissions inside a mounted Docker volume will add extended attributes to the shared files on the host instead of modifying their actual mode or ownership. To see these values in the terminal, run ls -la@ or xattr -l <file>. Extended attribute values are prefixed with com.docker.grpcfuse regardless of whether Docker is using gRPC FUSE or VirtioFS (they're both FUSE).

Pulling Data from Remote Servers

The npm run pull command brings together several sub-commands to sync remote data to the local development environment. Each command can also be called individually. Connection info must be configured in a .env file. Values are documented in the .env.sample file.

Private SSH keys are passed to the image as Docker Secrets, point $SSH_KEY_PATH to a local private key in .env.

Pulling uploads, plugins and database dumps is currently supported on WP Engine and Kinsta*.

Connections must be configured on a per-machine basis using a .env file in the project root. For new projects, rename the .env.example to .env and update the settings.

The important properties are:

• SSH_KEY_PATH
  Local path to your private key. If you uploaded a id_rsa_wpengine.pub key to your WP Engine account, point this to the pair's matching private key: ~/.ssh/id_rsa_wpengine

• SSH_LOGIN
  This is simply the SSH connection string from WP Engine backend, something like iop001@iop001.ssh.wpengine.net where the elements are ${SSH_USER}@${SSH_HOST}. Each item can also be entered individually, individual entries take precedence over components extracted from SSH_CONNECT_STRING.

• SSH_USER
  The user account which connects to the server.

• SSH_HOST
  The server address to connect to.

• SSH_WP_CONTENT_DIR
  (default: sites/${SSH_USER}/wp-content) The path to the wordpress wp-content folder. Most likely matches the WP_CONTENT_DIR WordPress constant. Does not include a trailing slash. Can relative to the SSH user home folder or an absolute path.

Both $SSH_LOGIN and $SSH_HOST can be extracted from $SSH_LOGIN. Specifying either will override the value in $SSH_LOGIN.

Syncing Databases from Kinsta

Unlike WP Engine, Kinsta does not store regular database snapshots in a site's wp-content directory, but they do allow cron. Set up a basic crontab task to regularly backup the database so pull scripts will work correctly. Here's an example which backs up hourly at 37 minutes after the hour:

# dump db hourly for dev mirrors
37      *       *       *       *       mysqldump --default-character-set=utf8mb4 -udb_user -pdb_password db_name > ~/public/wp-content/mysql.sql

Neither Kinsta's nor WP Engine's servers will not fulfil requests for *.sql files, and the db_user. db_password and db_name values are stored already stored in plaintext in wp-config.php so this isn't a security risk.

Debugging

WP_DEBUG is enabled by default, and can be toggled by setting the WORDPRESS_DEBUG variable in the .env config file.

Updating WordPress

The base image provides a specific version of WordPress, but once running that version can be upgraded using the wp-admin dashboard, just like any other site.

wp-cli can also be used to update to pre-release version of WordPress. An example command looks like this:

npm run wp-cli wp core update --version=7.0-RC4

Versions can be rolled back by removing the docker *_wp volume.

Bumping Image Versions

The npm run bump script will query the WordPress releases API and DockerHub, then update the docker image and readme to the latest WordPress image.

To update to a pre-release image, enter a valid DockerHub tag into the wp-version.json file.

Plugin Development

Projects often rely on plugins which are developed in parallel. A number of placeholder IOP_DEV_PLUGIN_# environment variables are provided which can be used to directly mount plugins into the WordPress environment. These enable better version control and dependency management since the nested and .gitignored wp-content/plugins directory often conflicts with a parent theme.

To add a development plugin to the WordPress environment, point the plugin's local relative path to an absolute path inside the container. Here's how we would make an example-plugin project being developed in a sibling directory available to the current WordPress development environment:

   IOP_DEV_PLUGIN_1="../example-plugin:/var/www/html/wp-content/plugins/example-plugin"
   IOP_DEV_PLUGIN_2=
   IOP_DEV_PLUGIN_3=

Accessing running containers

To open a shell on any running Docker container, run docker ps to retrieve container IDs or Names, then run docker exec -it <name or ID> bash. Some containers may use sh instead of bash. To open a shell on the running WordPress instance, run docker-compose exec wordpress bash.

Other composer commands

The Composer image can also run other, more specific commands directly from docker-compose:

docker-compose run --rm  composer update
docker-compose run --rm  composer require monolog/monolog

# Open a shell in the composer image

docker-compose run --rm  composer bash

Serving on Alternate Ports

All services which provide a server can have their default ports customized with the --port= flag. This allows for multiple projects to be run simultaneously on the same computer.

# site one
npm run start --port=8080

# site two
npm run start --port=8081

Default ports

• webpack devserver: 8080
• phpMyAdmin: 8002
• WebGrind: 9004

phpinfo()

A PHP Info page is available at localhost:8080/info.php.

Debugging & Profiling

To profile a request with XDebug and WebGrind, add ?XDEBUG_PROFILE=1 to any request. A cachegrind.out.nn file will be created in webpack/xdebug. Running npm run webgrind will launch a webgrind server for viewing those files. The default address is http://localhost:9004, or change ports with npm run webgrind --port=9123.

Reading Call Graphs

Every profiled run can also be viewed as a call graph. These graphs are documented in the gprof2dot project:

+------------------------------+
|        function name         |
| total time % ( self time % ) |
|         total calls          |
+------------------------------+

where:

• total time % is the percentage of the running time spent in this function and all its children;
• self time % is the percentage of the running time spent in this function alone;
• total calls is the total number of times this function was called (including recursive calls).

wp-cli

The default command replaces the wp prefix, so alternate commands would look like this:

• npm run wp-cli transient delete --all
• npm run wp-cli user list

wp-cli Command Reference

Local Development

To iterate on this project locally, build the image using the same name as the Docker Hub remote. Docker will use the local copy. Specify dev if you're using using versions.

docker build . --tag ideasonpurpose/wordpress:dev

Shell Scripts

All shell scripts in bin have been checked with ShellCheck and formatted with shfmt with command: npm run shfmt

Docker maintenance

While not specific to this project, here are a few useful docker commands for keeping Docker running.

• docker-compose down tears down the containers
• docker system prune Clean up unused containers and images
• docker system prune -a Clean everything, will need to download stuff again
• docker ps List running containers
• docker exec -it <container> bash Open a shell on a running container

Additional Notes

The docker-entrypoint.sh script in the base WordPress docker image checks for a WordPress installation by checking for index.php and wp-includes/version.php.

 

Brought to you by IOP

	This project is actively developed and used in production at Ideas On Purpose.