My WordPress local setup broke again yesterday. For the third time this month.
I’m working on this ecommerce site for a jewelry store, and suddenly WooCommerce won’t load. MySQL keeps crashing. MAMP is throwing some error about port 8888 being occupied, but lsof -i :8888 shows nothing. Spent two hours on Stack Overflow before realizing my Postgres instance (from a completely different project) was somehow interfering.
This is stupid. We shouldn’t be dealing with this in 2025.
The Problem Everyone Ignores
WordPress developers have just accepted that local environments are garbage. We’ve normalized spending hours on environment setup instead of actual development.
Last month my friend Jake hired a new developer. Good portfolio, solid WordPress knowledge. First week on the job? Completely lost trying to get their local environment matching the staging server.
PHP 8.1 on their machine, PHP 7.4 on staging. Different MySQL versions. Some plugin needs mysqli, another needs pdo_mysql. Jake’s running XAMPP, the new developer installed WAMP (why?), staging uses Apache 2.4.52 but Jake’s XAMPP has 2.4.51.
By Friday, the new developer hadn’t written a single line of WordPress code. Just environment troubleshooting.
That’s a $1,200 week (at $30/hour) spent on literally nothing productive.
Why I Finally Switched to Docker
I avoided Docker for like three years. Seemed overly complicated for WordPress sites.
The breaking point was this custom theme project where everything worked perfectly on my MacBook. Deployed to staging, completely broken. Turns out I was running PHP 8.0.15 locally, staging had 8.0.12, and some random function in WooCommerce behaved differently between those versions.
Client called asking why their product pages weren’t loading. Had to tell them our “minor PHP version difference” was causing checkout failures.
That’s when I gave up on XAMPP and learned Docker properly. Not because Docker is amazing, but because “works on my machine” was costing me clients.
My Current WordPress Docker Setup
This configuration has worked for my last eight client projects. Not perfect, but it works :
version: ‘3.8’
services:
wordpress:
image: wordpress:6.3-fpm-alpine
ports: [“9000:9000”]
environment:
WORDPRESS_DB_HOST: mysql
WORDPRESS_DB_NAME: wordpress
WORDPRESS_DB_USER: wpuser
WORDPRESS_DB_PASSWORD: devpass123
volumes:
– ./wp-content:/var/www/html/wp-content
– ./php.ini:/usr/local/etc/php/php.ini
depends_on: [mysql]
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpass123
MYSQL_DATABASE: wordpress
MYSQL_USER: wpuser
MYSQL_PASSWORD: devpass123
volumes: [mysql_data:/var/lib/mysql]
command: –default-authentication-plugin=mysql_native_password
nginx:
image: nginx:alpine
ports: [“8080:80”]
volumes:
– ./wp-content:/var/www/html/wp-content:ro
depends_on: [wordpress]
volumes: mysql_data:
I know everyone says use MariaDB instead of MySQL but honestly I haven’t had problems with MySQL 8.0 and switching databases mid-project seems like asking for trouble.
The nginx configuration is probably not optimal – I basically copied it from some tutorial and modified it until WordPress loaded. But it works and I haven’t touched it in six months.
The Two Issues That Always Break
File Permissions Nightmare
WordPress needs to write files. Docker containers run as root by default. Your local filesystem runs as your user. They fight constantly.
Symptoms: WordPress can’t install plugins, upload media files fail, theme updates don’t work.
I still don’t fully understand Docker user mapping but this fixes it:
wordpress: user: “1000:1000” # Replace with your user ID
Get your user ID with id -u. Change that number. Should work
MySQL Connection Errors
MySQL 8.0 has some new authentication thing that WordPress doesn’t like. Error message is useless: “Error establishing database connection.”
I wasted an entire Saturday debugging this. The fix is adding one line to MySQL:
mysql:
command: –default-authentication-plugin=mysql_native_password
Why this isn’t the default, I have no idea. MySQL documentation is terrible about explaining this.
Real Results (Not Marketing Numbers)
Before Docker: New developers took 3-4 hours getting local WordPress running (when everything went right). When things went wrong, add another 2-3 hours.
After Docker: New developers run docker-compose up, wait 2 minutes, start working.
The time savings are obvious but the real benefit is consistency. Everyone runs identical WordPress environments. No more “it works on my computer” discussions.
Though I’ll be honest – Docker has its own problems. Sometimes containers just stop working for mysterious reasons. Had to rebuild my entire setup last month because MySQL data got corrupted somehow.
But Docker problems are at least predictable. XAMPP problems are random chaos.
When Docker Isn’t Worth It
Don’t containerize everything because some blog post told you to.
If you’re managing one WordPress site that rarely changes, XAMPP might be fine. If your current setup works for your team, keep using it.
I tried to convince a client to switch their simple business website to Docker. They update content twice per year and never modify code. Spent a week on Docker migration that provided zero business value.
Docker pays off when you’re juggling multiple WordPress projects with different PHP versions, plugins, or configurations.
Getting Started
Start simple. Don’t try to build the perfect Docker setup immediately.
- Get basic WordPress + MySQL containers running
- Test with one real project
- Add nginx after basic setup works
- Fix whatever breaks along the way
I see people trying to add Redis, SSL certificates, and mail servers on day one. That’s how you spend two weeks debugging container networking instead of building WordPress sites.
Keep it boring until you need complexity.
The Bottom Line
Your WordPress local development setup should be invisible. When environment problems take longer than building actual features, your workflow needs fixing.
Docker isn’t perfect but it eliminates the specific hell of PHP version conflicts, MySQL authentication issues, and “works locally” debugging sessions.
My team hasn’t had a major local environment problem in four months. New WordPress projects spin up in minutes instead of hours.
That’s worth learning Docker.
Is Docker overkill for simple WordPress sites? Probably. Does it solve real productivity problems for WordPress development teams? Absolutely.
Stop losing time to broken local environments. Stop missing deadlines because XAMPP decided to break randomly. Stop pretending environment inconsistency is normal.
Because it’s not normal. It’s just what we’ve all accepted as part of WordPress development.
And acceptance of broken workflows is expensive.
