Alex blog All about IT!

Developing WordPress themes with Docker

Docker is very powerful DevOps tool when used correctly. For developers it can help to simplify setting up of environment or quickly switch between different environments in a few simple steps.

Developing WordPress themes with Docker

Step 1 – Install Docker

I am assuming here that the developers are using either Linux or macOS powered device for their environment. Simply because who in their right mind would use Windows for development unless you develop for Windows only.

Now, to start with Docker we will definitely need it installed on our computer. Let’s visit Docker Community Edition page and download and install it from there.

NOTE that Linux distributions such as Ubuntu or Centos might have Docker provided in repositories. However, those might be outdated, so my recommendation would be to get it from official website.

After the installation is done we can verify that we have it running:

$ docker version

The output should be something like below:

Client:
 Version:      18.03.1-ce
 API version:  1.37
 Go version:   go1.9.5
 Git commit:   9ee9f40
 Built:        Thu Apr 26 07:13:02 2018
 OS/Arch:      darwin/amd64
 Experimental: false
 Orchestrator: swarm

Server:
 Engine:
  Version:      18.03.1-ce
  API version:  1.37 (minimum version 1.12)
  Go version:   go1.9.5
  Git commit:   9ee9f40
  Built:        Thu Apr 26 07:22:38 2018
  OS/Arch:      linux/amd64
  Experimental: true

Which means are Docker installation is successful and we can begin getting wordpress running on our development machine.

Step 2 – Get WordPress container image and all dependencies from Docker Hub

The beauty of using Docker for development is that it allows us to get infrastructure up and running very easily by using public images of containers. In this article I will not go into details of what images are and how they relate to containers, otherwise this is going to be very long explanation which deserves its own post.

Now to get our WordPress ready to run on localhost all we need to do is pull its latest image from Docker Hub:

$ docker pull wordpress:latest

Running this command for the first time may take some time depending on your bandwidth speed. Repeating this command next time will only get changes between what we already have downloaded and latest version.

The output of above command should be similar to this:

latest: Pulling from library/wordpress
f2aa67a397c4: Already exists
4c3122805fd6: Already exists
98ce407ee18a: Already exists
8a56b8f1ca72: Already exists
3eb04e3939f2: Already exists
f5ecc66c0a5f: Already exists
30ebdb4a78e1: Already exists
9e9c0e2ba7f1: Already exists
da976026223e: Already exists
ce6d5c10d5f2: Pull complete
3b590479ffbe: Pull complete
c9c1886e0825: Pull complete
b4ec177bd8ba: Pull complete
82764b9d3ae8: Pull complete
25cebae8bec8: Pull complete
610c5839eb35: Pull complete
2f5a4b474ea5: Pull complete
e9a3a5708ca8: Pull complete
8a5a0d7dbd76: Pull complete
47c0fbaf8626: Pull complete
Digest: sha256:8aeabcc9fcf840474a8b61f58285d339a8358f7795a25f96b9ac5568522d19a6
Status: Downloaded newer image for wordpress:latest

And the last line means that we have latest up-to-date Docker image of WordPress.

This image already contains pre-configured Apache and PHP7. However it does not have any database. Which means we will need to get that somewhere. If you don’t use MySQL on your machine for anything else other that Docker development, then it can be done by pulling latest MySQL image from Docker as well. However on my laptop I have MySQL already pre-installed, so for now I will skip this part. I can add the steps for this at later stage. For now we just need to know that we should have MySQL schema named wordpress already created and there should be a user 'wordpress'@'%' and this user should have ALL permissions on this schema.

Step 3 – Docker-compose configuration

To run WordPress for development purposes we can use Docker-Compose tool that allows us to describe our infrastructure in simple YAML formatted document.

Let’s first create the directory where we will keep all projects files:

$ mkdir -p ~/Projects/wptheme
$ cd ~/Projects/wptheme

Now that we have create directory and changed active shell session to it, we can create new file:

$ nano docker-compose.yml

This will open an editor for a new file. Let’s first paste the entire content:

version: '3.3'

services:
  wordpress:
    image: wordpress:latest
    ports:
      - "8000:80"
    environment:
      WORDPRESS_DB_HOST: host.docker.internal:3306
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
    volumes:
      - .:/var/www/html/wp-content/themes/wptheme

Let’s review this file. First line simply tells docker-compose which syntax version it is going to be. services starts a list of services defined in our infrastructure. In this case we only have one named wordpress. Next lines all define this service, such as image to be used will be wordpress:latest, ports tells Docker to take port 80 on the inside of container and expose it to localhost on port 8000, which means we will be able to reach our WordPress in browser by entering http://localhost:8000/.

Two remaining parts of docker-compose.yml are essential for this configuration to work from the start. environment will define environment variables inside container and here we provide 3 variables for WordPress to connect to database:

  1. WORDPRESS_DB_HOST: host.docker.internal:3306 uses Docker magical host.docker.internal hostname that allows software inside container to connect to any port on localhost. Which is essential in my case as I already have MySQL installed. In case you use MySQL from image, it would need to be service name of MySQL container defined as dependency for wordpress. You can read more on this on Docker-Compose official documentation pages
  2. WORDPRESS_DB_USER: wordpress defines MySQL user (note it is the same one as we created above, if you created different used, this should be changed accordingly)
  3. WORDPRESS_DB_PASSWORD: wordpress defines password for MySQL user, which might need to be adjusted same as above

Last and perhaps most critical item for this setup is volumes. We define the only value there .:/var/www/html/wp-content/themes/wptheme, which translates as “mount current directory of localhost to container at /var/www/html/wp-content/themes/wptheme“. This will allow us editing files on localhost and be able to immediately use them in WordPress. In this example I used wp-content/themes/wptheme path, which means this project will be creating a new theme for WordPress.

Any good behaving WordPress theme should have at least two files. Let’s create them:

$ touch style.css
$ touch index.php

Now these files are completely empty and there is nothing in them, but it will allow us to see theme right away in WordPress.

Step 4 – Run WordPress!

Finally we are ready to start our first WordPress container. We can do this from our shell session:

$ docker-compose up -d

The above command tells Docker to start new environment which is described in docker-compose.yml file in current directory. The -d option tells Docker to run this container in background.

The output of above command should be similar to:

Creating network "wptheme_default" with the default driver
Creating wptheme_wordpress_1 ... done

Now we can verify it is running successfully:

$ docker ps

Which should print out following:

CONTAINER ID        IMAGE               COMMAND                  CREATED                  STATUS              PORTS                  NAMES
c7d837da5ae2        wordpress:latest    "docker-entrypoint.sā€¦"   Less than a second ago   Up About a minute   0.0.0.0:8000->80/tcp   wptheme_wordpress_1

If you see output similar to above. Excellent! You have WordPress running and ready for theme development.

Navigate to http://localhost:8000 in your browser and you should see WordPress initial setup page, which will populate database.

If you experience some errors, make sure you follow instructions to the dot. Otherwise feel free to ask in the comments and I will try my best to help you solve it.

Next time

Next article will be an addition to this on and there I will write a simple guide on how to create a custom WordPress theme from scratch. We will work on theme similar to the one I am using for this blog, which I also wrote from scratch specifically for my blog šŸ˜‰ Stay tuned!

1 comment

  • Alex on 12:09 #

    Hi Alex

    I followed this guid and all works well except CSS, any added css rules does not show in browser
    Im on Mac
    can you help with this issue

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: