Are you still spending 30 minutes or more setting up the environment for every WordPress client project? With a template that combines Docker Compose and WP-CLI, you can spin up a development environment for a new project in just 5 minutes. This article explains a battle-tested docker-compose.yml template and initial-setup script used in real production work.
Why Docker — Breaking Up with MAMP/XAMPP
Many creators still use MAMP or XAMPP as their local development environment, but when running multiple client projects in parallel, there are several limitations: switching PHP versions is cumbersome, managing per-project databases is messy, and environment differences between team members easily arise.
With Docker, you can create an isolated container for each project and pin the PHP/MySQL/Nginx versions to match the project's production environment. Because you can codify the environment in a single docker-compose.yml, the same environment is reproduced even when handed to a team member. The biggest benefit is freedom from the "secret-sauce environment" problem.
A docker-compose.yml Template
Let's go over the design points of a practical docker-compose.yml. It consists of three services: the wp service (WordPress itself), the db service (MySQL 8.0), and the phpmyadmin service (for database management).
The wp service uses the official WordPress image and shares the theme and plugin directories with the host machine via volume mounts. This way, editing theme files in your host editor is reflected in the container in real time. Set WordPress's database connection details via environment variables, and set WP_DEBUG to true to make errors easier to catch during development.
The key is to change the port number per project. Assigning, say, 8080 to project A and 8081 to project B lets you run multiple projects simultaneously. To avoid confusion, list the port numbers in a README.md or turn them into variables in a .env file.
Automating Initial Setup with WP-CLI
Once the Docker container is running, automate the initial setup with WP-CLI. Prepare a setup.sh script that runs the following steps in one batch.
- Installing WordPress core: Use wp core install to set the admin account, site title, and URL. Since this is a development environment, a simple password is fine.
- Japanese localization: Switch to the Japanese locale with wp language core install ja && wp site switch-language ja. Also set the time zone with wp option update timezone_string Asia/Tokyo.
- Permalink settings: Change to post-name-based URLs with wp rewrite structure /%postname%/. This is almost mandatory for client projects.
- Removing unnecessary plugins: Remove pre-installed unnecessary plugins with wp plugin delete akismet hello.
- Activating the theme: Activate the theme under development with wp theme activate mytheme. Since theme files are shared via Docker volume mounts, changes are reflected immediately.
If you make this script a Makefile target, the initial setup completes with a single make setup command. When a new member joins the project, you only need to write "run make setup" in the README.
Practical Tips: Tricks You Can Use in the Field
Here are some tips to make your development environment even more convenient.
For testing email delivery, incorporate MailHog as an additional service. Add a mailhog service to docker-compose.yml and point WordPress's SMTP settings to MailHog, and you can check test emails from form submissions right in your browser. This eliminates the risk of accidentally sending to the production mail server.
Make use of database snapshots too. Export a SQL dump with wp db export and include it in your project repository, and you can revert to a specific state anytime with make db-import. Preparing a snapshot that includes test posts, pages, and menu structure also lets you build a demo environment instantly.
Customizing PHP settings via uploads.ini is also important. The default file upload limit is 2MB, but client projects often handle high-resolution images, so raise upload_max_filesize to around 64MB. Adjust post_max_size similarly. Apply this file inside the container via a volume mount in docker-compose.yml as well.
Operating and Extending the Template
Manage this template as a Git repository and clone it for each new project. Separating project-specific settings into a .env file lets you customize without polluting the template itself. It's handy to turn the project name, port number, PHP version, and WordPress version into variables in .env.
To take it further, you can also build a setup that integrates with GitHub Actions to automatically run docker compose up and tests when a PR is created. However, for client projects, excessive automation can outweigh its maintenance cost, so judge based on your team's size and the project's duration.
A Docker × WP-CLI environment template generates cumulative returns with every project once you've built it. Even if the initial setup takes half a day, used across 10 projects that's an investment of just 2–3 minutes per project. Try it on your next project.