Setting up a WordPress Dev Environment with Docker and Nimble

In my last post, I released the environment I use to set up local WordPress installs on my machine using Docker. In this post, I'm going to show you how to set up a dev environment all your own or for a team with this simple project and get you started on customizing it. Once you've set it up once, creating future projects only takes about a minute, so hang in there!

Install Docker

The first step is to install Docker. If you're on a Mac, Ubuntu or Windows 10 Professional, follow one of these links:

If you're on Windows 10 Home, an earlier version of Windows or an unsupported version of Mac, try Docker Toolbox -- though your mileage may vary.

Add ~/bin to your PATH

Windows

  1. Start the System Control Panel applet (Start - Settings - Control Panel - System).
  2. Select the Advanced tab.
  3. Click the Environment Variables button.
  4. Under User Variables, select Path, then click Edit.
  5. Add %USERPROFILE%\bin as an entry if it doesn't exist.

Other

Add to your .bash_profile:

  1. Open terminal or bash.
  2. echo "export PATH=$PATH:~/bin" >> ~/.bash_profile
  3. source ~/.bash_profile

Pull the Nimble Environment

Go to your preferred location for all of your projects, and pull the Nimble repository. I prefer a spot like ~\docker on Mac or ~\Documents\docker on Windows, but it's entirely up to you!

Create a new project

Before creating a new project, open a Bash command line or alternative like Git Bash (Windows), Terminal (Mac), Bash on Ubuntu WSL (Windows) or a regular old command line (Ubuntu). Run the following command to make nimble as easy as can be:

./nimble.sh localize

Now, you can just type nimble from this location. Please note, all commands must currently be run in this directory. Keeping a command line specifically for this directory helps.

Switch the Nimble Environment to your own repo

First thing's first, delete the existing Git repository by deleting ./.git from the root folder. You can (and should!) keep the .gitignore file. Then create a Git repository either using your GUI of choice, or git init. Once created, you should set up a branch to your own repo if you plan on syncing on the web. Eventually, I'll come up with a way you can update the actual Nimble Environment, but I'd like some community feedback before I delve too far into it.

You can start up the docker containers with no projects via nimble up. For more commands, check out the Git repo

Actually create a new project

Creating a project is easy, and even interactive. Just run the command nimble create myproject, replacing myproject with whatever alphanumeric project name you would like. Nimble will ask you a few questions, notably:

  • Do you want this project kept in Git?

    If so, you can this repo with other users, they can run nimble init myproject, and pull the new project you are creating

  • Do you want to clone a repo?

    If this is an existing project, you can pull its repo into the sites/myproject/www folder.

  • Do you want to add this project to your hosts?

    No more editing hosts files!

  • Do you want to generate certificates for this site?

    Automatic (untrusted) SSL capabilities

  • Do you want to install WordPress?

    It will ask you the basic questions for installing WordPress

Once installed, your project will be available at yourproject.local, with PHPMyAdmin at phpmyadmin.yourproject.local and Webgrind at webgrind.yourproject.local (to be used with nimble up profile).

Customizing your projects

Now that the framework has been laid for a basic project, here's a quick yet complicated briefer on the templates that make this possible. Each WP project is built from a template located at ./_templates/docker-wp-template.yml. This template is compiled to a respective docker-compose template responsible for the project's configuration at ./_projects/project.yml. Additionally, each project has multiple parts -- database, server, files, phpmyadmin, etc -- which extend services located at ./_templates/docker-common-template.yml.

Now, this complicated web of files needs an infographic, which I have not prepared just yet, but the flow is like this:

./_templates/docker-wp-template.yml -> creates -> ./_projects/myproject.yml -> extends -> ./_templates/docker-common-template.yml

If you want to make a change across the board, like change the version of MariaDB that is used across all of your WP projects to 10.0.30, you can go to ./_templates/docker-common-template.yml, find the wp_db service, and change image: to mariadb:10.0.30.

If you want to make this same change only for myproject, you can go to ./_projects/myproject.yml, find service myproject_db and add image: mariadb:10.0.30.

And if you want to make the same change only to new projects that are created, you can go to ./_templates/docker-wp-template.yml find PROJECT_db and add image: mariadb:10.0.30.

Now, if you run nimble up, it will whichever of the above containers you just modified and in a matter of moments, you'll be running that version of MariaDB. Of course keep in mind that if the DB data from your version is not compatible with the new version, you could end up with a corrupt database, but you hopefully have a dev database with a single source of truth for your data that you can pull from at any time.

I hope you can see how powerful it is to be able to completely change how your environments are built at any time and share those environments when collaborating. Be sure to leave some notes in the comments if you've tried it out, hated it, experienced bugs, or if it completely changed your life!