WP BOX Installation. WordPress with Docker Compose and Makefile

In this section:

Prerequisites

WP BOX is a bundle, that installs server software on a linux-based operating system via Docker and on top of that server software it installs WordPress with Composer and other necessary tools for development and production. Installation might vary depending on your host machine.

Installing WSL2 (Windows Only )

To install on Windows machine, you will need to install a WSL2 first.
Microsoft have an extensive guide explaining how to install that: https://learn.microsoft.com/en-us/windows/wsl/install

In short you will need to run this command in Windows PowerShell, but if you need additional details, follow the link above.

wsl --install -d Debian

WP BOX is tested on Debian and should work well on distros like Ubuntu. However you might need to implement some modifications to the installer scripts.

Installing Docker, Make and Git

Once you have installed a WSL2, or if you running on MacOS or GNU/Linux system. You will need to get Docker, Make and Git using command line interface of that system.

On Debian you would need that command:

sudo apt-get install docker docker-compose git make

On MacOS you would need to install brew first (from .pkg or via CLI) and then install packages using brew:

sudo brew install docker docker-compose git make

On Windows you can install Docker and Git on your main OS, instead of Linux in a subsystem. Probably downloading them as an installer, would be the best option.

Cloning the project

Before cloning the project into your local machine, consider that on Windows webserver software performs a lot faster on Linux filesystems, thus it is important to clone the project into the directory inside WSL2. For MacOS and when using Linux as main OS you don’t need any special preparations, but on MacOS you might need to allow Docker to access the selected directory, if its on Desktop or in user directory.

On any OS, you should set correct permissions to the directory, so that it belongs to your current user, but it should not be root user. I generally use the same directory as it would be on a production webserver – located in /var/www/your.domain

sudo mkdir -p /var/www/your.domain
sudo chown -R <USER>:<GROUP> /var/www/your.domain

Once you created the directory, enter it and clone the project with your current user:

cd /var/www/your.domain
git init .
git remote add -t \* -f origin <repository-url>
git checkout master

Make sure to add your user to the docker group:

sudo usermod -u $(id -u) -a -G docker $(whoami)
newgrp docker

Finally, copy the environment variables file from example and modify it with your own tokens and keys for all functionality to work, but the site should start with defaults.

cp .env.example .env

Building and starting Docker

By default base images are downloaded from Docker Hub, but in project .env you can specify your own custom registry for base images, in case you don’t want to be dependent on Docker Hub. Dockerfiles have conditional logic that will download base images from your registry if they are specified.

From this point, you should be able to use make commands listed in ./Makefile.
To build docker images and start containers you can run all-in-one command:

make install-all

This command fetches packages and builds Docker images, starts the webserver, links volumes to directories, start caching service, database service and everything except the website data itself.

Please note, that installer connects to various package suppliers, which might be unavailable for whatever reason. In this case you may try one of the following:

use proxy during download
replace suppliers with your own sources
request Docker images via email – sam.tyurenkov@wp-box.org

Installing WordPress

Now you will need to install WordPress, it is also available with make command:

make post-install

This commands seeds WordPress database and some initial data, like first user with admin rights, activates the theme and so on.

That’s it, try to open website in your browser.
(Note: if you used a domain name in .env instead of localhost, you will need to add it to hosts file of your host machine for DNS resolving to your local machine)