search

ideasonpurpose / docker-wordpress-dev

Docker-based local development environment for WordPress projects
8 stars 7 forks source link

readme

WordPress local development with Docker

Version 1.6.7 - WordPress 6.6.2

Docker Pulls Push to DockerHub

About This Project

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 v6.6.2

Getting Started

To update an existing project or start a new one, run the following commands in your working directory.

macOS, Linux & Windows PowerShell
docker run --rm -it -v ${PWD}:/usr/src/site ideasonpurpose/wordpress:6.6.2 init

Followed by:

npm run bootstrap

NOTE: If ~/.composer doesn't exist, mounting the Docker volume will create the directory with root ownership, likely causing the Composer task to fail. Either create this directory before running npm run bootstrap or reset it's ownership with sudo chown -R $UID:$GID .composer and then run bootstrap again. See #21

Windows Command Prompt
docker run --rm -it -v %cd%:/usr/src/site ideasonpurpose/wordpress:6.6.2 init

Setup and Prerequisites

Docker and npm (node.js) should be installed. The development server runs from Docker images and all workflow commands are called from npm scripts.

New Projects

In an empty directory, running init will prompt for the new project's name and description, then build out a complete environment with a basic theme skeleton.

Existing Projects

Recently updated project can run npm run project:refresh to update tooling to the latest release.

Older projects should run init manually to update. Projects should be in a clean Git working tree so any undesirable changes can be easily reverted.

These files will be updated:

Before calling npm run start, copy a database snapshot into the top-level _db directory, add any required plugins to Plugins and mirror media files to Uploads.

Plugins and Uploads folders should not be committed to Git, but should be mirrored from production sites so the local environment works as expected.

After configuring your SSH key path in .env, the database, plugins and uploads be can be synced down from a remote server with the npm run pull command. The .env.sample file documents the required credentials.

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

Additional Commands and helpers

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:

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 https://wordpress.org/wordpress-6.5-RC3.zip

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

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:

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.

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

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