Building a WordPress development environment with Docker Compose, as easy as magic!

Hello! 🚀 Aspiring web developers or WordPress users! Are you still struggling with building your own LAMP (Linux, Apache, MySQL, PHP) or LEMP (Linux, Nginx, MySQL, PHP) stack to install WordPress? 🛠️ Say goodbye to complex dependency issues, version conflicts, and the pain of setting up a new environment every time!

Today I’m going to show you in detail how to magically, easily, and quickly build a WordPress development environment using Docker Compose that will take all of those headaches away in one fell swoop. By the end of this post, you’ll be able to easily build and manage a fully self-contained WordPress development environment with just a few lines of code ✨.

—.

💡 Why build a WordPress environment with Docker Compose?

WordPress is a complex application that requires a web server (Apache or Nginx), PHP, and a database (MySQL or MariaDB) to work together. Using Docker Compose, you get a ton of benefits, including

• ⚡️ Easy setup: No complicated manual installation process, you can define all services with a single configuration file (.yml) and run them at once.
• 🌐 Consistent environments: Your local dev, staging, and production environments stay the same, avoiding issues like “It works on my machine, but…” issues, such as.
• 🧱 Isolation and independence: Each service (WordPress, database) runs in an independent container, so they don’t affect each other.
• ♻️ Easy reproducibility: When you share your project with others or work on a new machine, you can instantly reproduce the same environment with just a docker-compose.yml file.
• 🔄 Fast start/stop: Quickly spin up your development environment when you need it, and cleanly shut it down with a single command when you don’t.

—.

📝 What to bring

Before we get started, make sure you have the necessary tools installed.

• Docker Desktop (Windows / macOS) or Docker Engine (Linux):
  • Download and install the version for your operating system from the Docker official website.
  • Download Docker Desktop
• Text editor: Your favorite text editor, such as VS Code, Sublime Text, Atom, etc.
• Terminal or Command Prompt: Basic command literacy.

—.

🧠 Understand core concepts

Before we start building our WordPress environment, let’s briefly review the core concepts of Docker and Docker Compose.

• **🐳 Docker: A platform for packaging applications and their dependencies into self-contained units called containers. Containers are lighter and faster than virtual machines, and run equally well in any environment.

  • Image: A blueprint (template) for creating a container. Examples include WordPress images, MySQL images, etc.
  • Container: The actual running instance created from the image.

• **🏗️ Docker Compose: A tool for defining and running multiple containers bundled together into a single application. It makes it easy to manage complex multi-container applications (e.g. WordPress + database). Define your services in the docker-compose.yml file.

• Components of WordPress:

  • Web server (PHP-FPM + Nginx / Apache): interprets PHP code and serves web pages. It is provided as a Docker image.
  • Database (MySQL / MariaDB): Stores all of WordPress’ posts, settings, user information, and more. Comes as a Docker image.

—.

📄 Analyze docker-compose.yml file: The blueprint of WordPress

Now let’s write the docker-compose.yml file that will define our WordPress environment. This file is like a “blueprint” that specifies all the components of our WordPress application.

version: '3.8' # Version the Docker Compose file format

services: # Define the services that make up the application.

  wordpress: # WordPress website service
    image: wordpress:latest # Use the latest version of WordPress image.
                            # You can also specify a specific version, such as wordpress:apache or wordpress:fpm-alpine.
    ports:
      - "80:80" # Connect port 80 on the host to port 80 on the container.
                # You should be able to reach http://localhost in a web browser.
    environment: # Environment variables for WordPress to access the database.
      WORDPRESS_DB_HOST: db:3306 # Specify the name (db) and port (3306) of the database service.
                                 # Within the Docker Compose network, it is accessible by the service name.
      WORDPRESS_DB_USER: wordpress # Database username for WordPress to use.
      WORDPRESS_DB_PASSWORD: supersecretpassword # Database password for WordPress to use
      WORDPRESS_DB_NAME: wordpress_db # WordPress database name
    volumes: # Volume settings for data persistence
      - ./wordpress:/var/www/html # Mount the ./wordpress directory on the host to /var/www/html in the container.
                                  # This is where WordPress core, themes, plugins, upload files, etc. are stored.
                                  # data is retained even if the container is deleted.
    depends_on: # Specifies that the 'db' service must be started before this service is started.
      - db

  db: # The MySQL database service to store WordPress data in.
    image: mysql:5.7 # Use the MySQL 5.7 version image (mariadb:latest is also a good choice)
    environment: # MySQL database configuration environment variables
      MYSQL_ROOT_PASSWORD: supersecretpassword # password for the root user
      MYSQL_DATABASE: wordpress_db # The name of the database to be used by WordPress (must be the same as your WordPress service)
      MYSQL_USER: wordpress # Database username to be used by WordPress (must be the same as your WordPress service)
      MYSQL_PASSWORD: supersecretpassword # Database password to be used by WordPress (must be the same as your WordPress service)
    volumes: # Volume settings for data persistence
      - ./db:/var/lib/mysql # Mount the ./db directory on your host to /var/lib/mysql in the container.
                            # Database files are stored here so that data is retained even if the container is deleted.

  phpmyadmin: # (optional) PhpMyAdmin service for database management
    image: phpmyadmin/phpmyadmin # Use the latest version image of PhpMyAdmin.
    ports:
      - "8080:80" # Connect port 8080 on the host to port 80 on the container.
                  # Connect to http://localhost:8080 in a web browser to manage the database.
    environment: # PhpMyAdmin settings environment variables
      PMA_HOST: db # Database host to which PhpMyAdmin will connect (database service name)
      MYSQL_ROOT_PASSWORD: supersecretpassword # Password of the root user (must be the same as the root password of the db service)
    depends_on:
      - DB # Specifies that the 'DB' service must be started before this service is started.

# volumes: # (optional) If you are using named volumes, define them here.
# wordpress_data:
# db_data:

• version: '3.8': Defines the grammar version of the Docker Compose file. It is recommended to use the latest version.
• services: Define the individual containers (services) we will run under this section.
  • wordpress: This is the service for the WordPress website itself.
    • **image``: Specifies the Docker image and tag to use (wordpress:latest` is the most recent stable version).
    • ports: Connect the ports on the host machine to the ports inside the container. This is in the form of hostport:containerport.
    • environment: Sets the environment variables to use inside the container. Define here the information WordPress needs to connect to the database (WORDPRESS_DB_HOST, WORDPRESS_DB_USER, WORDPRESS_DB_PASSWORD, WORDPRESS_DB_NAME). The WORDPRESS_DB_HOST uses the name and port of the db service.
    • volumes: Mounts a specific directory on the host machine (./wordpress) to a directory inside the container (/var/www/html) for data persistence. This way, if the container is deleted or recreated, the data in WordPress, such as themes, plugins, uploaded files, etc. will remain intact.
    • depends_on: Specifies that this service depends on the db service. The db service must be started before the wordpress service can function properly.
  • db: The service for WordPress’ database.
    • image: Uses a MySQL 5.7 image. You can also use mariadb:latest.
    • environment: Defines the environment variables required for initial setup of the MySQL database. The values MYSQL_ROOT_PASSWORD, MYSQL_DATABASE, MYSQL_USER, and MYSQL_PASSWORD must match the environment variables in your WordPress service.
    • volumes: Mount the host’s ./db directory to /var/lib/mysql in the container to ensure persistence of database files.
  • phpmyadmin (optional): A web-based MySQL database management tool. It is very useful for viewing and modifying database contents directly during development. Set PMA_HOST to point to the name of the db service.

—.

🚀 Hands-on! Running a WordPress Container

Now let’s build and run a WordPress environment based on the docker-compose.yml file.

1. Create a project directory: 1. Open a terminal and create a directory for your WordPress project.

mkdir my-wordpress-app
cd my-wordpress-app

2. Create a docker-compose.yml file: 2. Save the contents of docker-compose.yml that we analyzed earlier under the name docker-compose.yml inside the my-wordpress-app directory.

# For example, if you are using VS Code:
code docker-compose.yml

file, copy and paste the YAML content described above.

3. Run the Docker Compose service: **3. Run the following command in the directory where the docker-compose.yml file is located.

docker compose up -d

• docker compose up: Builds and runs all services defined in the docker-compose.yml file.
• -d: Enters detached mode, running the containers in the background so that the terminal is still available.

The first time you run it, it may take some time to download the necessary Docker images. Once the images have finished downloading and the containers have started successfully, you should see a message in the terminal similar to this

[+] Running 3/3
 ✔ Container my-wordpress-app-db-1 Started
 ✔ Container my-wordpress-app-wordpress-1 Started
 ✔ Container my-wordpress-app-phpmyadmin-1 Started

4. Complete the WordPress installation: 4. Open a web browser and go to http://localhost. 🎉 â

The WordPress initial setup screen will appear. Enter your language choice, site title, username, password, etc. as you would normally install WordPress and complete the installation.

5. Connect to PhpMyAdmin (optional): 5. If you want to manage the database yourself, connect to http://localhost:8080 in your web browser.
   • Server: db (or you can enter the name of your container, like my-wordpress-app-db-1)
   • Username: root
   • Password: supersecretpassword (the MYSQL_ROOT_PASSWORD you set in docker-compose.yml)

After entering the above information and logging in, you will be able to visually manage your database.

6. Stop the service: ! When you are done developing or no longer need your WordPress environment, you can stop all services and delete the container by running the following command in the directory where your docker-compose.yml file is located.

docker compose down

This command will delete the container and the underlying network, but the data stored in the ./wordpress and ./db volumes will remain intact.

7. Restart the service: 7. The next time you start development again, simply run the docker compose up -d command again. Since the image is local, it will start much faster. Your data will be preserved by the volumes, so your WordPress site should reappear exactly as you had it set up before.

—]

🛠️ Troubleshooting tips

• Port conflicts (Error: port is already allocated, etc.): * Try changing the host port in the ports setting.
  • Try changing the host port (the leading 80 in 80:80) to another unused port (such as 8000:80) in the ports setting.
• Container startup failed:
  • Check the logs for a specific service using the docker compose logs [service_name] command, for example, docker compose logs wordpress or docker compose logs db to determine the error message.
• Database connection error:.
  • Make sure that the WORDPRESS_DB_HOST of the wordpress service is correctly set to db:3306.
  • Double check that the environment variables (username, password, database name) for the wordpress and db services match exactly. Make sure there are no typos and that they are case sensitive.
• Permissions issues:.
  • When mounting a volume, sometimes permissions issues in the host directory prevent the container from accessing files. In a Linux environment, try using sudo or checking the directory permissions.

—.

🌱 Going further

Managing environment variables with an .env file:* **Manage environment variables with an .env file Instead of putting sensitive information (like passwords) directly into the docker-compose.yml file, you can create an .env file to manage it. Create an .env file in your my-wordpress-app directory and write the following contents

```
MYSQL_ROOT_PASSWORD=your_secure_root_password
WORDPRESS_DB_USER=wordpress_user
WORDPRESS_DB_PASSWORD=your_secure_password
WORDPRESS_DB_NAME=my_wordpress_db
```
And in the `docker-compose.yml` file, we refer to it as `$VARIABLE_NAME`.

```yaml
# ...
environment:
  WORDPRESS_DB_HOST: db:3306
  wordpress_db_user: ${wordpress_db_user}
  wordpress_db_password: ${wordpress_db_password}
  wordpress_db_name: ${wordpress_db_name}
# ...
```
This ensures that no sensitive information is exposed in the `.yml` file, and makes it easy to apply different variables for different development/production environments. It is recommended that the `.env` file be appended to `.gitignore` to keep it out of version control.

• Applying custom themes/plugins: Applying custom themes/plugins to the ./wordpress volume You can put files directly into wp-content/themes or wp-content/plugins inside a directory mounted in the ./wordpress volume (/var/www/html), which will be automatically recognized and activated by the WordPress admin page.

• Enforcing SSL/HTTPS: * **Enforce SSL/HTTPS In a real service environment, SSL (HTTPS) must be enforced. A common way to do this is to add an Nginx proxy container, issue a certificate with Let’s Encrypt or similar, and place it in front of the WordPress container. (This can be covered in more depth in the next step).

—.

🎉 Conclusion

You are now fully familiar with how to build a WordPress development environment using Docker Compose! Container-based development radically simplifies the setup of your WordPress environment, facilitates collaboration between team members, and ultimately greatly improves development efficiency.

We hope this guide has been a great help in your WordPress development journey. Now, don’t get bogged down in complicated installations and focus on WordPress development itself! 👨‍💻👩‍💻 If you have any questions, feel free to ask in the comments! Happy coding! ✨