WPDock - A Simple WordPress Development Environment Using Docker
Tags: wordpress, docker, github
Published: 2021-01-26 13:23:04

Here at [WP Git Updater](https://wpgitupdater.dev) 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](https://github.com/docker-library/wordpress/issues/480) [problems](https://github.com/docker-library/wordpress/issues/30) 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](https://github.com/FiloSottile/mkcert).

Checkout the repository and install instructions over on [Github](https://github.com/wpgitupdater/wpdock). WPDock is a simple executable you just need to place in your path.

You can create a WPDock environment with the following command:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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).

```bash
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](https://12factor.net/dev-prod-parity) 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:

```bash
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](https://github.com/FiloSottile/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](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](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.