WPDock - A Simple WordPress Development Environment Using Docker

Here at WP Git Updater we are announcing a new WordPress development environment using Docker!

WordPress already provides a docker image which can be used for development, but it has a few problems that are not dealt with in the usual docker way. We never really found a configurable solution to these problems, which always meant using the docker image requiring some repeated “must know” steps for everything the containers need to be built. Or reverting to using developer machines local php/apache/mysql or another dev environment tool.

We have used various other tools and they do not work well for us. Some just take over the host machine ports without telling you, others just do not provide all the features we need. WPDock is purposely designed to be a very thin layer over docker.

By design, the WordPress image is just WordPress. There is no https support, mail catching or database access. This means again polluting your dev machines MySql tool of choice with numerous connection profiles.

We wanted to find a way to run the WordPress Docker stack as it’s a perfect use case for docker in a team/collaboration environment. With Docker Compose we wanted a setup you can just "start" that includes some common tools used for WordPress local development.

We set out to achieve the following:

• A single command to start/stop the whole environment
• Easy access to the MySql database
• Mail catching out of the box
• No WordPress loopback or Rest Api health check errors
• Simple access to WP-CLI
• HTTPS/domain name support
• As little development machine pollution as possible
• Simple database sharing between team members

Enter WPDock

WPDock is a very simple bash script that gives you all of the above. All you need is docker for basic operation, and if you want https/tls support there is only 1 other dependency mkcert.

Checkout the repository and install instructions over on Github. WPDock is a simple executable you just need to place in your path.

You can create a WPDock environment with the following command:

wpdock init 

This will create a .env file in your current folder with the required environment variables for operation. It will also add the .env file and the .wpdock folder to a gitignore file and finally it will create a .htaccess file which prevents these dot files ever being accessible should you mistakenly upload them to a server.

Then to run the whole stack:

wpdock up or wpdock start

That’s it!

With this (and depending on what you have changed in the .env file. You will have access to:

• WordPress on localhost:8080
• PhpMyAdmin on localhost:8181
• Mailhog catching WordPress emails for review on localhost:8282
• MySql on localhost:33060

Your current directory is bound as the wp-content folder on the WordPress container and WordPress is already installed for you to start developing with.

What's more, the only development machine pollution is the ports being bound. WpDock will not use anything other than docker and those ports. This is perfect and gives you the flexibility to adjust the .env variables in another folder and run multiple instances at the same time!

This also follows WP Git Updaters recommended structure for WordPress source controlled setups. With this setup you can git init in the bound wp-content folder, ignore the uploads folder and your all set.

Need to access WP-CLI?

Of course we have made this simple too:

wpdock user list

Any commands not recognised by wpdock will pass through to the cli container.

Sharing Databases Between Team Members

You can of course use various mature tools to synchronise databases. But for simple usage wpdock provides dump and import commands:

wpdock dump # dump.sql will be in your current directory
wpdock import # will import the dump.sql file in your current directory

Stopping Environment

Stopping the environment can be done in a few ways:

wpdock stop # stops the containers
wpdock down # stops and removes the containers
wpdock destroy # stops and removes the containers + shared volumes

Other Commands

[service] can be one of: wordpress, cli, db, mailhag, phpmyadmin, and caddy (more on this later).

wpdock help # displays command help

wpdock file .env # displays the default env variables should you want to create or amend an existing .env file

wpdock exec [service] # eg: wpdock exec wordpress bash

wpdock run [service] … # eg: wpdock run cli bash

wpdock logs [service] # tails all container logs, or pass a service to view specific logs

wpdock compose … # proxy commands directly to docker-compose

wpdock … # is the same as wpdock run cli wp …

As you can see WPDock is a very thin layer over Docker Compose commands.

Real Domains with Valid Local TLS/HTTPS Certificates

Inline with the The Twelve Factor App recommendations on Dev/Prod parity. In 2021 there really isn’t an excuse not to use TLS even for local development.

What’s more if you plan on using any form of shopping cart plugins without TLS you're likely to run into some issues over plain http.

WPDock provides a simple option to enable custom domains with https for your development environments.

Let's take a look and how it works:

wpdock up --https

With the above command and the WORDPRESS_SITE_HOST .env variable setup you can develop locally with trusted TLS encryption for WordPress!

How does this work?

WpDock needs 1 additional tool to provide this feature: mkcert. Mkcert adds a locally trusted CA to your development machine, and allows you to generate TLS certificates against that CA.

This means no more untrusted certificate warnings.

First install Mkcert as detailed in their documentation. Run mkcert -install once to install the CA and let WpDock take over from there.

When you run wpdock up —https the following additional steps are performed.

• wpdock will generate a Caddyfile in the .wpdock folder.
• wpdock will generate certificate and key files from your WORDPRESS_SITE_HOST env variable in the .wpdock/certs folder.
• A new caddy web server container will be started, with the generated files mapped into the correct locations.

Caddy is a super simple to use web server which is perfect for what wpdock needs to provide TLS support. The generated Caddfyfile simply creates a reverse proxy from WORDPRESS_SITE_HOST to the wordpress container

The Caddy container does need to bind to ports 80 and 443 on your development machine to provide this mapping.

Now all you need to do is make sure WORDPRESS_SITE_HOST points to 127.0.0.1 via your /etc/hosts file.

Your website will be available over https/tls, automatically forwarding http requests, with a trusted certificate.

Additionally wpdock will update your database and replace the localhost:${PORT} urls with the new domain name.

When you stop your development environment, everything is cleaned up. Port 80 and 443 are free again to be used.

Head over to the Project to find out how to install and more on the commands: https://github.com/wpgitupdater/wpdock.

Feedback Welcome

We hope you enjoy using WPDock. For us it's a small but useful addition to our development workflow.

WPDock is open source and can be found at https://github.com/wpgitupdater/wpdock. Any improvements/suggestions are more than welcome.

At Wp Git Updater we develop locally using Apple machines, but we believe all of the commands will also work on Linux environments (please let us know if you have any issues).

For windows users we are more than happy to accept PR’s that provide support if it can be achieved.

Stay tuned, in the next few posts we are going to cover some of the features in more detail, and show you a setup automatically resolving your chosen tld to localhost using DNSMasq.

---