Developing WordPress sites locally used to mean installing XAMPP, MAMP, or manually configuring PHP and MySQL. Those methods still work, but they often lead to environment mismatches between your local machine and production server. Enter Docker: the containerization platform that guarantees consistency across every stage of development. In this tutorial, I’ll show you how to set up a WordPress development environment with Docker in just five straightforward steps. By the end, you’ll have a fully isolated, reproducible WordPress stack running on your machine—perfect for theme development, plugin testing, or client work.

Why a WordPress Development Environment with Docker Beats Traditional Local Stacks

Before we dive into the steps, let’s understand why a WordPress development environment with Docker is superior to XAMPP, MAMP, or native LAMP setups. Docker containers encapsulate the exact PHP version, web server, and database your production site uses. This means no more “it works on my machine” surprises when you deploy. Plus, Docker starts in seconds, uses fewer resources than virtual machines, and lets you run multiple isolated WordPress sites side by side without conflicts.

What You Need Before Starting

  • Docker Desktop installed (free from Docker’s official site).
  • Node.js (optional, for asset compilation).
  • A terminal (Command Prompt, PowerShell, or Bash).
  • Basic familiarity with the command line.

Ready? Let’s begin.

Step 1: Create Your Project Folder and Docker Compose File

Open your terminal and create a new directory for your WordPress project:

mkdir my-wordpress-docker
cd my-wordpress-docker

Now create a file named docker-compose.yml using your favorite code editor. This file will define the services: WordPress (with PHP) and MySQL (or MariaDB). Paste the following configuration:

version: '3.8'

services:
  db:
    image: mysql:8.0
    container_name: wp_db
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wp_user
      MYSQL_PASSWORD: wp_password
      MYSQL_ROOT_PASSWORD: root_password
    ports:
      - "3306:3306"
    volumes:
      - db_data:/var/lib/mysql

  wordpress:
    depends_on:
      - db
    image: wordpress:latest
    container_name: wp_site
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_USER: wp_user
      WORDPRESS_DB_PASSWORD: wp_password
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - ./wp-content:/var/www/html/wp-content
      - ./uploads.ini:/usr/local/etc/php/conf.d/uploads.ini

volumes:
  db_data:

This configuration uses MySQL 8.0 and the official WordPress image, maps port 8080 on your machine to port 80 inside the container, and persists your wp-content folder on your host system (so your themes and plugins survive container restarts).

Step 2: Start the Containers

In your terminal, navigate to the folder containing it docker-compose.yml and run:

docker-compose up -d

The -d flag runs containers in detached mode (in the background). Docker will pull the required images (MySQL and WordPress) if you don’t have them locally. Once finished, verify both containers are running:

docker ps

You should see wp_site it wp_db with the status “Up.”

Step 3: Access WordPress and Complete Installation

Open your browser and go there. You’ll see the standard WordPress installation wizard. Select your language, then fill in:

  • Site Title: My Docker WordPress
  • Username: admin (or any secure name)
  • Password: choose a strong one
  • Your Email: your@email.com

Click Install WordPress. After a few seconds, you’ll be logged into your fresh WordPress site. Congratulations – you’ve begun to set up a WordPress development environment with Docker successfully.

Step 4: Customize PHP Settings (Upload Limits, Timeouts)

By default, WordPress inside Docker has a 2MB upload limit and short execution times. To increase these, create a file named so uploads.ini in the same folder as docker-compose.yml with the following content:

upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 256M
max_execution_time = 300

Then restart the containers:

docker-compose down
docker-compose up -d

Your WordPress environment now accepts larger uploads – essential for theme files or media-heavy sites.

Step 5: Add wp-cli and phpMyAdmin (Optional but Powerful)

To supercharge your workflow, add two more services to your

  wpcli:
    image: wordpress:cli
    container_name: wp_cli
    depends_on:
      - wordpress
      - db
    volumes:
      - ./wp-content:/var/www/html/wp-content
    working_dir: /var/www/html
    entrypoint: wp

  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    container_name: wp_phpmyadmin
    depends_on:
      - db
    environment:
      PMA_HOST: db
      PMA_PORT: 3306
    ports:
      - "8081:80"

After saving, run docker-compose up -d again. You can now:

  • Manage your database at http://localhost:8081 (login: wp_user / wp_password).
  • Run WP-CLI commands like this.

For more advanced Docker WordPress setups, refer to the external resource: Official WordPress Docker Image Documentation.

Managing Your Environment Day-to-Day

  • Stop containers: docker-compose stop
  • Start again: docker-compose start
  • View logs: docker-compose logs -f
  • Destroy everything (including the database): docker-compose down -v

Because your wp-content folder is mounted from your host machine, you can edit theme files with your local IDE (e.g., VS Code) and see changes instantly.

Common Issues and Fixes

Problem Solution
Port 8080 already in use Change "8080:80" to another port, e.g.
MySQL connection refused Wait 30 seconds after docker-compose up – MySQL needs time to initialize.
Permission denied on Linux Run sudo chown -R $USER:$USER ./wp-content to fix folder ownership.

Next Steps: Going Production-Ready

Once you’ve mastered the local setup, consider using Docker for staging and production. Many managed hosts now support Docker Compose natively. For a hands-on comparison, read our internal guide on migrating from local Docker to a production VPS for WordPress.

Conclusion

Learning how to set up a WordPress development environment with Docker is a game-changer for your workflow. You gain consistency, speed, and isolation—all without cluttering your host system with PHP versions or databases. In five steps, you’ve created a reusable, shareable WordPress stack that works on Windows, macOS, or Linux.

Now go ahead and build your next WordPress site inside containers. Your future self (and your team) will thank you. If you need personalized assistance or have questions about customizing your Docker setup, feel free to contact our team here.