WordPress Docker Development Environment

This is a Docker based local development environment for WordPress.

What's Inside

This project is based on docker-compose. By default, the following containers are started: PHP-FPM, MariaDB, Elasticsearch, nginx, and Memcached. The /wordpress directory is the web root which is mapped to the nginx container.

You can directly edit PHP, nginx, and configuration files from within the repo as they are mapped to the correct locations in containers.

A custom phpfpm image is used for this environment that adds a few extra things to the PHP-FPM image.

Requirements

• Docker
• docker-compose

Setup

1. git clone https://github.com/Clark-Nikdel-Powell/wp-local-docker.git <my-project-name>
2. cd <my-project-name>
3. Clone the project repo into the app directory.
4. Edit docker-composer.yml under the phpfpm and nginx images to add the project plugin and theme volumes. If you centralize your local plugins, you can add those as additional volumes.
5. Run docker-compose up.
6. Run setup to download WordPress and create a wp-config.php file.
   1. On Linux / Unix / OSX, run sh bin/setup.sh.
   2. On Windows, run ./bin/setup.
7. Edit your hosts file to add a local domain.
   1. In Terminal, enter sudo nano /etc/hosts. Enter your computer password.
   2. Add a local hosts entry for the new dev site, e.g. 127.0.0.1 docker.test.
   3. Hit ⌃+O to write the file changes, then ↩ to confirm the filename.
   4. Hit ⌃+X to exit the editor.
8. Navigate to your local domain in a browser to finish WordPress setup.

Default MySQL connection information (from within PHP-FPM container):

Database: wordpress
Username: wordpress
Password: password
Host: mysql

Docker Compose Overrides File

Adding a docker-compose.override.yml file alongside the docker-compose.yml file, with contents similar to the following, allows you to change the domain associated with the cluster while retaining the ability to pull in changes from the repo.

version: '3'
services:
  phpfpm:
    extra_hosts:
      - "dashboard.dev:172.18.0.1"
  elasticsearch:
    environment:
      ES_JAVA_OPTS: "-Xms2g -Xmx2g"

WP-CLI

Add this alias to ~/.bash_profile to run the WP-CLI command.

alias dcwp='docker-compose exec --user www-data phpfpm wp'

Instead of running a command like wp plugin install you instead run dcwp plugin install from anywhere inside the <my-project-name> directory, and it runs the command inside of the php container.

There is also a script in the /bin directory that will allow you to execute WP CLI from the project directory directly: ./bin/wp plugin install.

SSH Access

You can access the WordPress/PHP container with docker-compose exec. Here's an alias to add to your ~/.bash_profile:

alias dcbash='docker-compose exec --user root phpfpm bash'

This alias lets you run dcbash to SSH into the PHP/WordPress container.

Alternatively, there is a script in the /bin directory that allows you to SSH in to the environment from the project directory directly: ./bin/ssh.

MailCatcher

MailCatcher runs a local SMTP server which catches any message sent to it, and displays it in it's built-in web interface. All emails sent by WordPress will be intercepted by MailCatcher. To view emails in the MailCatcher web interface, navigate to http://localhost:1080 in your web browser of choice.

Credits

This project is our own flavor of an environment created by John Bloch.

Troubleshooting

MySQL won't start

We downgraded from mysql:latest to mysql:5 because MySQL 8 has some authentication setup that no one supports yet. If you run into that, you'll need to clear out the contents of the /data directory in order to start from scratch. It may also be helpful to remove the images and containers you're not using.