guoyu07 / docker-compose-wordpress

An example use of the chriszarate/wordpress image for plugin or theme development using Docker Compose.

WordPress plugin or theme development with Docker Compose

This is an example repo for how one might wire up Docker Compose with the chriszarate/wordpress image for plugin or theme development. In addition to WP-CLI, PHPUnit, Xdebug, and the WordPress unit testing suite, the docker-compose.yml file adds MariaDB and nginx-proxy to create a complete development environment that starts quickly.

Set up

1. Clone or fork this repo.

2. Put your plugin or theme code in the root of this folder and adjust the services/wordpress/volumes section of docker-compose.yml so that it syncs to the appropriate directory.

   If you would like your plugin or theme activated when the container starts, edit the WORDPRESS_ACTIVATE_PLUGINS or WORDPRESS_ACTIVATE_THEME environment variables.

3. Add project.test (or your chosen hostname) to /etc/hosts, e.g.:

   127.0.0.1 localhost project.test
   

   If you choose a different hostname, edit .env as well.

Start environment

docker-compose up -d

The first time you run this, it will take a few minutes to pull in the required images. On subsequent runs, it should take less than 30 seconds before you can connect to WordPress in your browser. (Most of this time is waiting for MariaDB to be ready to accept connections.)

The -d flag backgrounds the process and log output. To view logs for a specific container, use docker-compose logs [container], e.g.:

docker-compose logs wordpress

Please refer to the Docker Compose documentation for more information about starting, stopping, and interacting with your environment.

Log in to /wp-admin/ with wordpress / wordpress.

Update environment

To pull in the latest images (including chriszarate/wordpress), make sure your clone/fork of this repo is up to date, then run the following commands. Note that this will destroy your current environment, including the database, and reset it to its initial state.

docker-compose down
docker-compose pull
docker-compose up -d

WP-CLI

You will probably want to [create a shell alias][3] for this:

docker-compose exec --user www-data wordpress wp [command]

Running tests (PHPUnit)

The tests in this example repo were generated with WP-CLI:

docker-compose exec --user www-data wordpress wp scaffold plugin-tests my-plugin

This is not required, however, and you can bring your own test scaffold. The important thing is that you provide a script to install your test dependencies, and that these dependencies are staged in /tmp.

The testing environment is provided by a separate Docker Compose file (docker-compose.phpunit.yml) to ensure isolation. To use it, you must first start it, then manually run your test installation script. These commands work for this example repo, but may not work for you if you use a different test scaffold (note that, in this environment, your code is mapped to /app):

docker-compose -f docker-compose.yml -f docker-compose.phpunit.yml up -d
docker-compose -f docker-compose.phpunit.yml run --rm wordpress_phpunit /app/bin/install-wp-tests.sh wordpress_test root '' mysql_phpunit latest true

Now you are ready to run PHPUnit. Repeat this command as necessary:

docker-compose -f docker-compose.phpunit.yml run --rm wordpress_phpunit phpunit

Xdebug

Xdebug is installed but needs the IP of your local machine to connect to your local debugging client. Edit .env and populate the DOCKER_LOCAL_IP environment variable with your machine's (local network) IP address. The default idekey is xdebug.

You can enable profiling by appending instructions to XDEBUG_CONFIG in docker-compose.yml, e.g.:

XDEBUG_CONFIG: "remote_host=${DOCKER_LOCAL_IP} idekey=xdebug profiler_enable=1 profiler_output_name=%R.%t.out"

This will output cachegrind files (named after the request URI and timestamp) to /tmp inside the WordPress container.

Seed MariaDB database

The mariadb image supports initializing the database with content by mounting a volume to the database container at /docker-entrypoint-initdb.d. See the MariaDB Docker docs for more information.

Seed wp-content

You can seed wp-content with files (e.g., an uploads folder) by mounting a volume to the wordpress container at /tmp/wordpress/init-wp-content. Everything in that folder will be copied to your installation's wp-content folder.