Orchestrating Multi-Service Local Environments with Docker Compose

Unleashing the Power of Docker Compose for WordPress & Plugin Development

As WordPress plugin developers, we often juggle multiple services beyond just a web server and a database. Think about local Node.js environments for asset compilation, Redis for object caching, mail catchers, or even separate API services. Managing these disparate components manually can quickly become a tangled mess of different software versions, conflicting ports, and inconsistent setups across team members.

Enter Docker Compose: a powerful tool for defining and running multi-container Docker applications. With a single docker-compose.yml file, you can declare your entire local development stack, making it easy to spin up, tear down, and share complex environments.

What is Docker Compose?

At its core, Docker Compose uses a YAML file to configure your application’s services. Each service represents a containerized component (e.g., WordPress, MySQL, Node.js). Compose then allows you to manage the lifecycle of these services together, from building images to starting, stopping, and viewing logs.

Building Your WordPress Development Stack with docker-compose.yml

Let’s craft a basic, yet robust, docker-compose.yml file for a typical WordPress plugin development setup. This example will include WordPress itself, a MySQL database, and a Node.js container for build processes (like Webpack or Gulp).

version: '3.8'

services:
  wordpress:
    image: wordpress:latest
    container_name: my_wp_dev_site
    restart: always
    ports:
      - "8000:80" # Map host port 8000 to container port 80
    environment:
      WORDPRESS_DB_HOST: db:3306 # Service name 'db' is DNS resolvable within the network
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: password
      WORDPRESS_DB_NAME: wordpress
    volumes:
      # Mount your plugin source code from your local machine into the WordPress container
      - ./wp-content/plugins/my-awesome-plugin:/var/www/html/wp-content/plugins/my-awesome-plugin
      # Optional: Mount your theme code
      # - ./wp-content/themes/my-custom-theme:/var/www/html/wp-content/themes/my-custom-theme

  db:
    image: mysql:8.0
    container_name: my_wp_dev_db
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: root_password # Strong password in production!
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: password
    volumes:
      # Persist database data to a named volume to prevent data loss on container removal
      - db_data:/var/lib/mysql

  node_builder:
    image: node:lts-alpine # Lightweight Node.js image
    container_name: my_wp_dev_node_builder
    working_dir: /app
    volumes:
      # Mount your entire project directory into the Node.js container
      - .:/app
      # Use an anonymous volume for node_modules to avoid issues with host filesystem types
      - /app/node_modules
    # Example command: runs npm install and then starts a watch script
    command: bash -c "npm install && npm run watch"
    # Make sure this service starts after WordPress (though not strictly dependent here, good practice)
    depends_on:
      - wordpress

# Define the named volume for database persistence
volumes:
  db_data:

Key Concepts Explained:

• version: Specifies the Docker Compose file format version. Always use a recent stable version like 3.8.
• services: The core block where you define each containerized application.
  • image: The Docker image to use (e.g., wordpress:latest, mysql:8.0, node:lts-alpine).
  • container_name: A human-readable name for your container.
  • restart: always: Ensures the container restarts if it stops or Docker itself restarts.
  • ports: Maps ports from your host machine to the container. "8000:80" means accessing your WordPress site on http://localhost:8000.
  • environment: Sets environment variables within the container. Crucial for database connection details for WordPress or configuration for other services.
  • volumes: Defines how to persist data and mount your local code into containers.
    • Bind Mounts (e.g., ./wp-content/plugins/my-awesome-plugin:/var/www/html/...): Directly links a directory on your host machine to a directory inside the container. This is vital for plugin/theme development, as changes made on your host are immediately reflected in the running container.
    • Named Volumes (e.g., db_data:/var/lib/mysql): Docker manages these volumes. They are ideal for persistent data like databases, ensuring your data isn’t lost when containers are recreated.
    • Anonymous Volumes (e.g., /app/node_modules): Useful for dependencies like node_modules to prevent conflicts with host OS filesystem types or permissions. Docker creates and manages these automatically.
  • depends_on: Expresses dependency between services. While it doesn’t wait for a service to be "ready," it ensures containers are started in a specific order.
  • command: Overrides the default command run when the container starts (e.g., for Node.js build scripts).
• volumes (top-level): Defines named volumes used by your services.

Essential Docker Compose Commands

Once your docker-compose.yml file is ready, navigate to its directory in your terminal and use these commands:

• docker-compose up -d: Builds, creates, and starts your services in detached mode (in the background).
• docker-compose down: Stops and removes containers, networks, and named volumes defined in the Compose file.
• docker-compose stop: Stops running containers without removing them.
• docker-compose start: Starts previously stopped containers.
• docker-compose logs -f [service_name]: Follows the logs for a specific service (e.g., docker-compose logs -f wordpress).
• docker-compose exec [service_name] bash: Executes a command inside a running service’s container. Perfect for running wp-cli: docker-compose exec wordpress wp plugin list.
• docker-compose build: Builds or rebuilds services that have a build instruction in their definition (not used in our current example, but useful for custom Dockerfiles).

Best Practices for WordPress & Plugin Developers

1. Version Control Your docker-compose.yml: Treat your Compose file like code. Commit it to your project’s Git repository to ensure consistent environments for everyone.
2. Environment Variables for Secrets: For sensitive data (like strong database passwords for production, API keys), use .env files alongside your docker-compose.yml. Docker Compose automatically loads variables from a file named .env in the same directory. Remember to add .env to your .gitignore!
3. Isolate Projects: Give each project its own docker-compose.yml. This prevents port conflicts and keeps environments clean.
4. Leverage docker-compose.override.yml: For local-specific configurations that shouldn’t be shared (e.g., enabling XDebug, different ports), create a docker-compose.override.yml file. Compose automatically merges it with your main file. Add this to .gitignore too!
5. Consider PHP-FPM for Nginx: For more advanced setups or production parity, you might swap the official WordPress image for a separate Nginx service and a php-fpm image.
6. Caching Services: Easily add services like Redis or Memcached (as shown in the summary) for object caching. Configure your WordPress installation (e.g., via a plugin like "Redis Object Cache") to point to the service name (e.g., redis:6379).

Conclusion

Docker Compose transforms the often-cumbersome process of setting up local development environments into a streamlined, consistent, and reproducible workflow. By defining your entire multi-service stack in a single YAML file, WordPress users and plugin developers can eliminate "works on my machine" issues, onboard new team members faster, and focus more on writing great code rather than battling environment configurations. Embrace Docker Compose, and take full control of your local development landscape!