Docker and WordPress: How Containers Can Simplify Your Development Process

The “works on my machine” bug that finally pushed me to Docker for WordPress was a PHP extension. A plugin needed intl, it was present on my Mac and missing on a teammate’s, and we lost an afternoon to a white screen that only one of us could reproduce. That is the class of problem containers remove: not by magic, but by making the runtime a file in the repo instead of a property of someone’s laptop.

This article is the local development half of running WordPress in Docker — the parity, the workflow, and the WordPress-specific traps that generic Docker tutorials skip. The production deploy on shared hosting is a different problem with its own sharp edges, and it has its own guide at the end.

What Docker actually fixes in WordPress development

WordPress is unusually exposed to environment drift. It runs on a PHP version, a set of extensions, a MySQL version, and a web server, and a plugin can quietly depend on any of them. Containers pin all four in version-controlled config, so the stack is identical for everyone and reproducible in CI.

The concrete payoffs, in order of how much they matter day to day:

A development stack that is actually usable

The single-container demo everyone shows you is fine for a five-minute look and useless for real work:

docker run --name wp -p 80:80 -d wordpress:latest

It has no persistent database, no access to your theme and plugin code, and no way to run WP-CLI comfortably. Real development needs a multi-service stack with your code mounted in and the database persisted:

services:
  app:
    image: wordpress:php8.3-apache
    ports:
      - "8880:80"
    volumes:
      - ./wp-content:/var/www/html/wp-content
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
    depends_on:
      - db

  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
      MYSQL_ROOT_PASSWORD: root
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Two decisions in there matter more than they look. The PHP version is pinned in the image tag to match production — drift between local PHP 8.3 and a production 8.1 is exactly the bug Docker is supposed to prevent, so do not leave it floating on latest. And the database lives in the named volume db_data, which survives docker compose down; the code is a bind mount so your editor changes are live.

The WordPress-specific traps

These are the issues that are not in a generic Docker tutorial because they are WordPress problems that happen to surface inside Docker.

WordPress stores absolute URLs in the database. The siteurl and home options, and URLs baked into post content, are full http://localhost:8880 strings. Import a production database dump locally and every link, image, and redirect still points at production. Fix it with a serialization-safe search-replace, never a raw SQL UPDATE that corrupts serialized data:

docker compose exec app wp search-replace 'https://example.com' 'http://localhost:8880' --all-tables --skip-columns=guid

File ownership fights you. The Apache image runs as www-data (UID 33). Files it writes — uploads, generated CSS, plugin installs — end up owned by UID 33 on your host, and files you create as your host user may not be writable by the container. On Linux especially this shows up as upload failures. The clean fix is to align the container’s user with your host UID, or to keep writable directories (uploads) on a volume the container owns while your code stays a plain bind mount.

Run WP-CLI through the container. WP-CLI needs the same PHP and database the site uses, so run it inside the app container, not on your host:

docker compose exec app wp plugin list
docker compose exec app wp db export backup.sql

What not to mount

Bind mounts are how your code reaches the container, but mounting the wrong directories is the most common way to slow the stack down or break it outright.

Optional services worth adding

Once the core stack works, a few extra services make local development noticeably better. A mail catcher like Mailpit captures outgoing email so password resets and notifications land in a web UI instead of the void. Redis gives you a real object cache that matches production behavior. A dedicated queue worker container lets you exercise jobs the way they actually run. Each is a few lines in the same Compose file, version-controlled alongside the rest.

FAQ

Why does WordPress show “Error establishing a database connection” in Docker?

Almost always the database host. Inside Docker Compose, services reach each other by service name, so DB_HOST must be the database service name (db), not localhost. A secondary cause is the app container starting before MySQL is ready; depends_on plus a retry on connection handles that.

Why are my image URLs wrong after importing a production database?

WordPress stores absolute URLs in the database. Run a serialization-safe wp search-replace from the production domain to your local URL across all tables, skipping the guid column. Never do this with a raw SQL UPDATE, which corrupts serialized option data.

Should I mount vendor/ and wp/ as volumes?

No. Composer-managed directories belong in the image so versions stay consistent. Bind-mount only your own code (themes, plugins, mu-plugins). Mounting managed directories is a common source of “it works in CI but not locally” mismatches.

How do I run WP-CLI in a Dockerized WordPress site?

Run it inside the app container with docker compose exec app wp <command> so it uses the same PHP version and database connection as the site. A Makefile wrapper around that command saves a lot of typing.

Related articles

• WordPress Bedrock with Docker locally and bare PHP in production covers the deploy half: git-pull releases to shared hosting without Trellis or a VPS.
• Maximizing performance with Nginx and Apache covers the web-server layer you can benchmark cleanly once the stack is reproducible.