Spin up a quick installation of ProcessWire with Docker Compose

So I landed onto ProcessWire’s home page the other day and quickly got excited about the possibilities of managing and publishing data and content in unique ways. I wanted to try it out for myself. For ProcessWire, Docker Compose would be my go-to install.

For much of the past year I have been building and playing in test sites built with Docker Compose. I like the cleanliness of each individual container and how neatly it comes together.

If you’re not using Docker Compose, you’re just using a computer

I also like the separation of concerns: Each container runs a single service and they are connected with their own network and IP addresses. Most of all, I like being able to erase the whole thing and wipe it out without any residual code floating around on my laptop. This last bit was especially helpful since I had to fire up and kill off a full operating system of PHP and Apache server more than a dozen times in one afternoon.

A lot of very necessary stuff is beyond the scope of this post so I hope it just inspires you to keep digging.
I have a few Docker Compose recipes for WordPress, Elixir/Phoenix, NodeJS, Apache, Drupal, Joomla, Ruby on Rails, Jekyll, and a few more. Each one creates its own standalone, self-contained system. GitHub and Docker Hub are loaded with different examples for spinning up your own.

If it doesn’t work? Just wipe it out and start over. It’s like the best way to cheat at checkers when I’m losing: tip the board over.

However if you really want to advance and get a deep understanding, then learn the details about how Docker creates networks and binds the containers together. For bonus points, figure out how you can deploy your local development network of containers to a live site and use version control for ongoing live updates, even with a team scattered across multiple sites with their own laptops.

If WordPress is the gateway drug of web development then once WordPress developers jump into the deep end, things get complex fast. We are spoiled with the famous WordPress five minute install, which lately has been more like three and a half seconds. This doesn’t just happen the same way most anywhere else.

ProcessWire with Docker Compose: All the Pieces

So let’s get under the hood and figure out how to set up ProcessWire using Docker Compose.

To install ProcessWire, we need a few things:

  • A Unix or Windows-based web server running Apache (and others, see next section)
  • PHP version 5.3.8 or newer with PDO database support (PHP 5.5+ preferable)
  • MySQL or MariaDB, 5.0.15 or greater (5.5+ preferable)
  • Apache must have mod_rewrite enabled (when applicable)
  • Apache must support .htaccess files (when applicable)
  • PHP’s bundled GD 2 library (ImageMagick also supported)

Fair enough. My game plan is to put PHP and Apache in one container and MySQL in another container. They will be on the same local network so that they can talk to each other.

The end user – as seen in my laptop’s browser – will only have access to the container running ProcessWire and not any other part of the PHP/Apache container, nor any of the MySQL container at all.

The MySQL container only allows requests from the PHP/Apache container and locks everything else out. This is a great security practice: You can’t hack through a door when there is no door.

ProcessWire also requires additional PHP extensions to work. Other Dockerfile examples show how it’s done. In fact, this particular Dockerfile works like a charm. However, I want to make two separate containers rather than stuff PHP and MySQL into just one.

The Docker Compose file

My Docker Compose file describes two services: db, the MySQL database, and web, the PHP/Apache server where ProcessWire will reside. Because both db and web are listed under services in the docker-compose.yml file, Docker knows to automatically create a private network, assign them their own IP addresses and expose ports to the public. In this case we are exposing Port 80, which means that once we’re up and running, you’ll just enter localhost into your browser.

The Docker Compose file also exposes a volume (i.e. directories and their files) for me to use when I eventually build my ProcessWire site. I designate a folder on my laptop which is linked in real time to another folder inside the PHP/Apache box – and I choose the folder where ProcessWire gets installed. Then I can use my favorite text editor to mess around with all the files as long as I want.

The Dockerfile file

This section held me up for hours and led me to fire up and kill off whole Linux systems in their containers over again until I got it right. This is why Docker and Docker Compose are important: If you make a mistake, erase something you shouldn’t or forget to add something you should, then just erase it and start over. No need to worry about some library or orphaned code files hidden somewhere that may keep causing conflicts.

In my Dockerfile, I had trouble getting the PHP extensions to load. Finally they installed correctly, however they weren’t showing up in my container. What gives?

The culprit was the php.ini file. In my case, I needed php.ini to tell PHP that it should load those extensions which Dockerfile just finished installing. Are you running PHP and don’t have a php.ini file? Maybe you should get one. Who knew?

I opted instead for a related file called local.ini. It can also be whatever.ini and should live in a subdirectory called conf.d. This avoids future problems when PHP updates are released. It is probably unnecessary in a local development setting, however let’s do it just to learn how.

By the way, how did I know that the PHP extensions were not loading correctly? I jumped into the actual container and looked around. On my laptop, the container is called processwire_web_1. With this knowledge, I used this command to get to the Linux command line:

docker exec -it processwire_web_1 /bin/bash

Back outside on my laptop’ command line, I added local.ini in my directory next to docker-compose.yml and my trusty Dockerfile and tried again. No luck. It turns out that Docker Compose does not do things like create directories very well. This is due to the way it creates a Docker Image, however that is beyond the scope of this post. Honestly, a lot of very necessary stuff is beyond the scope of this post so I hope it just inspires you to keep digging.

Finally, I borrowed an idea from suzel and created a bash script which would write its own local.ini file in the correct, newly created conf.d directory. Success!

Follow the instructions on setting up the database once you’re in the ProcessWire installer. Good luck! This is a work in progress and I will probably revisit it with future updates. Especially when I find a good use for running ProcessWire on a production site.

David Kissinger consults with companies, trade associations, non-profits and entrepreneurs on government affairs, public relations, marketing, IT strategy, web development and content.

Leave a Reply