Tutorial

Docker + WordPress Setup

Docker is a software container platform that whisks away all of the complexities of setting up a local development environment into a neatly packaged application.

I used it for the first time recently to test a simple WordPress theme and was highly impressed — it truly is contained; no “running around” to various places installing databases, obscure supporting packages and so forth. My one grievance is there seems to be many different ways to do the same thing which overcomplicates learning how to use it.

That said, the rest of this post is a tutorial on how I setup a local development environment (on a Mac) with Docker for developing a WordPress theme. I’ll walk through how to install WordPress (including a MySQL database, all via Docker), and setup your “wp-content” folder so you can work with the actual theme files.

If you want to jump to the end result, I’ve put the files on GitHub for reference as well.

1 Install Docker

Download and install the Docker Community Edition for Mac like you would any other application. This version of Docker includes Docker Compose which we’ll need for our WordPress setup.

2 Start Docker

Once Docker is installed, start the application. There will be a prompt for your system password, enter it and after it runs through a few more steps automatically you’ll see Docker running in the toolbar menu in the upper right of your screen. It’s a whale ship carrying cargo, clever little icon.

3 Create New Directory

Now it’s time to setup the directory where we’ll build our WordPress theme. All you do is create a new folder and name it whatever you want. I named mine docker-wordpress-theme-setup to match the GitHub repository and put it in Users/davidyeiser/dev. So the full path is: Users/davidyeiser/dev/docker-wordpress-theme-setup. We’ll need this later.

4 docker-compose.yml

For the rest of the tutorial, I’m assuming you are familiar with Terminal and have a favorite code editor. Though I’ll write out the Terminal commands explicitly just in case because tutorials that assume common knowledge on crucial steps are highly frustrating.

Open your code editor, create a blank file named docker-compose.yml and save it in the directory you created in step 3. This file is what Docker will use to setup WordPress and the MySQL database.

Open Terminal. When you start Terminal the blank screen will likely be in your home directory. Just in case type the command below and hit ‘return’:

cd ~

The cd command means “change directory” and the tilde is a shortcut to the home directory. So now you’re located in your home directory. Next we need to navigate to the directory we created in step 3. For me, I type:

cd dev/docker-wordpress-theme-setup

Once there, type ls and you should see your docker-compose.yml file.

Now let’s add some instructions to create our WordPress setup. In your code editor, paste the following in your docker-compose.yml file and save it.

version: '3'

services:
   db:
     image: mysql:5.7
     volumes:
       - db_data:/var/lib/mysql
     restart: always
     environment:
       MYSQL_ROOT_PASSWORD: somewordpress
       MYSQL_DATABASE: wordpress
       MYSQL_USER: wordpress
       MYSQL_PASSWORD: wordpress

   wordpress:
     depends_on:
       - db
     image: wordpress:latest
     ports:
       - "8000:80"
     restart: always
     environment:
       WORDPRESS_DB_HOST: db:3306
       WORDPRESS_DB_USER: wordpress
       WORDPRESS_DB_PASSWORD: wordpress
     working_dir: /var/www/html
     volumes:
       - /Users/davidyeiser/dev/docker-wordpress-theme-setup/wp-content:/var/www/html/wp-content
       - /Users/davidyeiser/dev/docker-wordpress-theme-setup/uploads.ini:/usr/local/etc/php/conf.d/uploads.ini
volumes:
    db_data:

The only thing you must change is the path to your WordPress ”wp-content” folder towards the end under wordpress: volumes:. (A special thanks to this Stack Overflow answer for helping me figure this part out.)

There are two parts to this setting. The left is the path to your local folder from the computer’s file system, where the themes and plugins will be located. Here you need to type out the full path to the directory you created prior PLUS the normal WordPress wp-content directory path.

As you can see, mine is: /Users/davidyeiser/dev/docker-wordpress-theme-setup/wp-content. Note the forward slash at the beginning and the lack of one on the end. The themes and plugins directories will be created automatically when we run the Docker command to setup everything.

Make these changes then save the file.

5 Run Docker Compose

Now we’re ready to run the Docker command that will build our local environment. In Terminal, make sure you are still in the directory we created in step 3 (again you can check for the docker-compose.yml file by typing the ls command) and run the following command (when I say “run” I mean type and hit enter, just in case that’s not obvious):

docker-compose up -d

The command will begin running scripts and you should see various “Downloading” and “Waiting” messages appear in Terminal. This will take a little while to run.

6 Install WordPress

Once the script has finished running (you’ll know because the messages will stop scrolling on the screen and the terminal will be ready for you to type in it again) go to this URL in your browser:

http://localhost:8000/

The standard WordPress installation screen should appear. Complete the installation like you normally would and then login to WordPress. As you can see you have a regular WordPress installation. Go to ‘Appearance > Themes’ and you’ll see the default WordPress themes. We’re almost finished.

7 Create the WordPress Theme

If you go back to the directory you created in step 3 — this time open it in Finder — you’ll now see along with the docker-compose.yml file a wp-content directory and in there a themes directory and in there the default WordPress themes. This is just like having a normal WordPress install. Create a new folder and give it the name of your theme and then create an index.php and style.css file in the theme folder.

style.css

/*
Theme Name: My Theme
Author: David Yeiser
Author URI: http://davidyeiser.com/
Description: Sample theme for Docker setup.
Version: 0.1
*/

index.php

<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
  <meta charset="<?php bloginfo( 'charset' ); ?>">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <?php wp_head(); ?>
</head>

<body <?php body_class(); ?>>

<div class="wrap">
  <div id="primary" class="content-area">
    <main id="main" class="site-main" role="main">

      <?php
      if (have_posts()) :
        /* Start the Loop */
        while (have_posts()) : the_post();
      ?>
        <div>
          <a href="<?php the_permalink(); ?>"><h3><?php the_title(); ?></h3></a>
        </div>
      <?php
        endwhile;
        /* End the Loop */
      else :
        // Nothing
      endif;
      ?>

    </main><!-- #main -->
  </div><!-- #primary -->
</div><!-- .wrap -->

<?php get_footer(); ?>
<?php wp_footer(); ?>

</body>
</html>

Save these files then refresh the themes page in your browser. You should now see your theme among the others. Activate your theme then go to http://localhost:8000/ and you should see the “Hello World!” post linked — that’s our theme!

From there you can develop the theme as you normally would. There are certainly more advanced techniques from here, like installing plugins. I’ve included three links at the end of this post for further reference if you’d like to learn more. And as mentioned in the beginning all the code from this tutorial is on GitHub: docker-wordpress-theme-setup.

Restarting

As long as Docker is running you’ll be able to access the WordPress install at http://localhost:8000/. If it’s ever not working restarting Docker usually fixes the problem. Just click the icon in the upper right and click the “Restart” button at the top of the dropdown menu.

More Resources

This tutorial was condensed from my setup experience and following other tutorials. Specifically these three:

If you have any trouble following this tutorial feel free to file an issue on GitHub.

Update

When you initiate a new Docker setup the default file upload limit is 2 MB which is not ideal for a local development environment. To increase this you can add your own uploads.ini file and link to it in the docker-compose.yml file. I’ve added the command to link it in the docker-compose.yml code above and the code for the uploads.ini file is below. The uploads.ini file goes in the same place as the docker-compose.yml file.

file_uploads = On
memory_limit = 64M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 600