How to Use Docker for Local WordPress Development: Complete Step-by-Step Guide

Learn how to build a local WordPress development environment with Docker and Docker Compose. This step-by-step guide helps you streamline setup, improve workflows, and mirror production with ease.

Docker is a powerful platform that uses containerization to create lightweight, isolated environments for running applications. For WordPress development, Docker offers consistent setups across different machines, isolation from host OS conflicts, and a closer mirroring of production environments. This tutorial will guide you, step by step, through building and deploying a local WordPress site using Docker and Docker Compose.

Table of Contents

• Prerequisites: Getting Docker Ready
• Docker Compose: Orchestrating Your WordPress Environment
• Step-by-Step: Crafting Your docker-compose.yml
• Configuring the Database and WordPress Services
• Launching and Managing Your Containers
• The Local Development Workflow: Code, WP-CLI, Databases
• [Optional] Bridging the Gap: Docker Concepts for Production
• Common Pitfalls & Troubleshooting Tips
• Conclusion

Prerequisites: Getting Docker Ready

Before you begin, make sure you have:

• Docker Desktop installed (for Mac/Windows) or Docker Engine + Docker Compose (for Linux). Refer to the official Docker installation guides for your platform.
• Basic familiarity with WordPress and command line operations.

Docker Compose: Orchestrating Your WordPress Environment

Docker Compose enables you to define and run multi-container Docker applications. In our case, we will create a docker-compose.yml file that describes the services required for a WordPress site: the WordPress application itself and a MySQL or MariaDB database.

Step-by-Step: Crafting Your docker-compose.yml

Create a file named docker-compose.yml in your project directory and add the following content. This example uses MySQL 8.0 as the database service.

version: '3.8'

services:
  db:
    image: mysql:8.0
    container_name: wp_db
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpressuser
      MYSQL_PASSWORD: wordpresspassword
    volumes:
      - db_data:/var/lib/mysql

  wordpress:
    image: wordpress:latest
    container_name: wp_site
    depends_on:
      - db
    restart: always
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_USER: wordpressuser
      WORDPRESS_DB_PASSWORD: wordpresspassword
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - ./wp-content:/var/www/html/wp-content

volumes:
  db_data:

Configuring the Database and WordPress Services

This docker-compose.yml configuration defines:

• Database Service: Uses the official MySQL 8.0 image. Environment variables set the root and application database credentials. A named volume (db_data) persists your database files.
• WordPress Service: Uses the official WordPress image. It maps container port 80 to host port 8080 for browser access. The depends_on directive ensures the database starts before WordPress. Local directory ./wp-content is mounted into the container for live theme and plugin development.
• Volumes: A named volume (db_data) is defined to retain your database data between container restarts.

Launching and Managing Your Containers

With your docker-compose.yml file in place, use the following commands to manage your environment:

• Start Containers: docker-compose up -d (Runs containers in detached mode)
• Stop and Remove Containers: docker-compose down
• List Running Containers: docker-compose ps
• View Container Logs: docker-compose logs -f wordpress (Replace wordpress with the service name if needed)
• Execute Commands in a Container: docker-compose exec wordpress bash (Launches an interactive shell inside the WordPress container)

Once up and running, access your site at http://localhost:8080.

The Local Development Workflow: Code, WP-CLI, Databases

Docker Compose not only isolates your environment but also streamlines development workflows. Here’s how:

• Editing Code: With your ./wp-content folder mounted, you can edit theme or plugin files locally using your preferred editor. Changes will reflect immediately in the container.
• WP-CLI Integration: Run WP-CLI commands inside the container:
  
  Example: docker-compose exec wordpress wp plugin install jetpack --activate
• Database Management: The MySQL service maintains persistence with named volumes. For tasks like importing or exporting the database, use WP-CLI or a dedicated tool such as phpMyAdmin (which you can optionally add as a service).

[Optional] Bridging the Gap: Docker Concepts for Production

While this guide focuses on local development, it’s useful to understand how containerization can extend to production:

• Custom Dockerfiles: In production, you might create a custom Dockerfile to bake in specific PHP extensions, themes, and plugins, optimizing image size and performance.
• Volume Mounts vs. Image Builds: In local development, volume mounts allow rapid iteration, whereas in production, code is copied into the image during the build process.
• Container Orchestration: Consider tools like Kubernetes or Docker Swarm, or Docker-friendly hosting platforms, for managing scaling, rolling updates, and secret management.

Example: A Simple Production Dockerfile

FROM wordpress:latest

# Copy your theme/plugin files into the image
COPY wp-content /var/www/html/wp-content

# Set non-root user and optimize the image
USER www-data

# Expose port 80
EXPOSE 80

CMD ["apache2-foreground"]

This Dockerfile demonstrates a basic approach to building a production-ready WordPress image.

Common Pitfalls & Troubleshooting Tips

• Port Conflicts: Ensure the host port mapped in docker-compose.yml (e.g., 8080) is not in use by another service.
• Volume Permissions: File permission issues can arise when mounting local directories; adjust permissions as necessary.
• Environment Variables: Verify that environment variables (e.g., database credentials) are correctly set in both the docker-compose.yml file and within the containers.
• Container Logs: Use docker-compose logs to diagnose issues if containers fail to start.

Conclusion

Docker transforms local WordPress development by providing consistent environments, isolation from host systems, and streamlined workflows. By following this guide and using the provided configurations, you can set up a robust local development environment, run WP-CLI commands effortlessly within containers, and even begin to explore containerized deployment for production.

Embrace Docker to reduce setup hassles, align your local environment with production, and enhance your overall development efficiency. Happy containerizing!