To run WordPress locally you need to recreate the same technical stack it runs on in production: a web server, a database server, and PHP. There are several ways to do this. Many tutorials suggest MAMP or XAMPP, which bundle these together into a simple installer. These tools work, but they are showing their age and Docker has become the more modern and flexible approach.
This article walks through setting up a local WordPress environment using Docker, including fixes for two problems you are likely to encounter along the way.
Docker, Docker Desktop, and Docker Compose
When you first visit the Docker website it is not immediately obvious which products you need, particularly if you have seen tutorials that mention Docker Compose but cannot find it listed anywhere prominent.
For Mac and Windows, the starting point is Docker Desktop. This is a single installer that includes everything you need:
- Docker Engine — the core runtime that runs containers
- Docker CLI — the command-line interface for managing containers
- Docker Compose — the tool for defining and running multi-container applications using a configuration file
Download and install Docker Desktop from docker.com, choosing the version for your operating system. Once installed, Docker Compose is available immediately.
Setting up WordPress with Docker Compose
The official starting point recommended by WordPress is their November 2022 guide: Setting up your local development environment for WordPress. It covers several approaches including MAMP, XAMPP, and Vagrant before focusing on Docker as the recommended method.
Following the guide involves three steps:
- Create a local project directory
- Create a
docker-compose.ymlfile and paste in the provided configuration - Run
docker compose upin the terminal from that directory
Fix: MariaDB version error on startup
When following the WordPress guide, you may encounter the following error in the terminal when Docker Compose tries to start the database:
db | [ERROR] [Entrypoint]: mariadbd failed while attempting to check config
db | command was: mariadbd --verbose --help
db | Can't initialize timers
db exited with code 1This is a known issue that many developers encounter when using mariadb:latest in the Docker Compose configuration. The latest version of MariaDB can be incompatible with the WordPress Docker setup.
The fix is to specify a particular version of MariaDB instead of using latest. In your docker-compose.yml file, find the database service and change the image line to specify a version. MariaDB 10.6 is a stable and widely compatible choice:
db:
image: mariadb:10.6Once you make this change, stop any running containers and run docker compose up again. The database, WordPress, and PHP should all install successfully this time.
Fix: the chown command on macOS
The next step in the WordPress guide asks you to run the following command in the terminal to set the correct file ownership on the WordPress directory:
sudo chown -R {your-username}:{your-username} wordpressThe chown command sets the owner and group of a file or directory. The format is:
chown username:groupname directoryIf you are not sure what your username is, type whoami in the terminal:
% whoami
your-usernameThe problem on macOS is that the guide assumes your primary group name is the same as your username, which is common on Linux but not on macOS. When you try running the command with username:username you are likely to see this error:
chown: your-username: illegal group nameTo find out what groups your user belongs to, run:
groups your-usernameOn macOS this will typically return something like:
staff everyone localaccounts adminThe primary group on macOS is staff, not your username. Use that instead:
sudo chown -R your-username:staff wordpressAlternatively you can omit the group name entirely, which will leave the group unchanged:
sudo chown -R your-username: wordpressEither approach should work. Once this command runs without errors, open localhost:8080 in your browser and you should see the WordPress installation page.