Setup a Local WordPress Development Environment on Docker

Posted on Dec 17, 2019, 1:07 PM | 3 minute read

As I continue to explore Docker, this post will serve as my notes. I assume assume you already have the following technologies on your computer or know how to install them:

Docker
Git
Node & NPM
A terminal app
Helpful, but optional: VS Code w/ Docker extension

Installation

Clone WordPress:

$ git clone git@github.com:WordPress/wordpress-develop.git

Install dependencies:

$ cd wordpress-develop && npm i

Start Docker containers:

$ npm run env:start

Install WordPress:

$ npm run env:install

Build WordPress assets:

$ npm run build:dev

Where is everything?

Once you’re up and running, you can view the local instance of WordPress: http://localhost:8889/

Logging into WordPress is easy enough:
http://localhost:8889/wp-admin/
user: admin
pass: password

You can also open VS Code and inspect the file and directory structure. You should see something similar:

 ├── src
 │   ├── js
 │   ├── wp-admin
 │   ├── wp-content
 │   └── wp-includes
 ├── tests
 │   ├── e2e
 │   ├── phpunit
 │   └── qunit
 └── tools
     ├── local-env
     └── webpack
 ├── .editorconfig
 ├── .env
 ├── .gitignore
 ├── etc....

The /src directory is where WordPress is located. Here, you can work as you normally did using other local development applications like XAMPP, MAMP, or Local by Flywheel.

The /tests directory houses all unit tests used by @wordpress/scripts. You can run tests using NPM.

Finally the /tools and root directory are where the scripts for setting up Docker, along with other development related configs are located. You can ignore those.

Development

Watch for changes:

$ npm run watch

Run PHP unit tests:

$ npm run test:php

Run JavaScript unit tests:

$ npm run test:e2e

Use WP-CLI:

$ npm run env:cli

Note: Where the documentation mentions running wp, run npm run env:cli instead. For example, npm run env:cli scaffold plugin my-plugin --activate

Check out all the useful WP-CLI commands.

Other

View Docker log files:

$ npm run env:logs

Pull the latest versions of containers:

$ npm run env:pull

Stop the containers:

$ npm run env:stop

Reset the containers:

$ npm run env:reset && npm run env:start

Note: this will destroy the Docker containers and create new ones. Make sure you back up your data first!

Pruning dangling Docker stuffs:

$ docker system prune

Learn more about cleaning up dangling Docker containers, images, volumes, and networks.

Gutenberg Development

If you want to contribute to the development of Gutenberg, connecting it to your new local is very easy.

Clone Gutenberg in a new directory outside of /wordpress-develop

$ git clone git@github.com:WordPress/gutenberg.git && cd gutenberg

Install dependencies:

$ npm i && npm run build

Set the path to WordPress:

$ export WP_DEVELOP_DIR=../wordpress-develop

Connect Gutenberg and WordPress:

$ npm run env connect

If you open up the WordPress dashboard, you should now see the Gutenberg plugin, tests, and example blocks.

Simply activate Gutenberg and any other plugins that you need. Learn more about getting started, and read about the Git Workflow.

Staying Updated

Because both WordPress and Gutenberg are version controlled, you can simply use git pull to bring in the latest changes:

$ cd wordpress-develop && git pull && cd ../gutenberg && git pull

If you want pull in the latest Docker containers:

$ npm run env:pull

Greg Rickaby