WordPress Docker Compose with Xdebug Environment

Easy WordPress development with Docker and Docker Compose.

With this project you can quickly run the following:

• WordPress and WP CLI
• phpMyAdmin
• MySQL
• Xdebug for remote debugging

Contents:

• Requirements
• Configuration
• Installation
• Usage
• Xdebug Setup
• Plugin Management
• License

Requirements

Make sure you have the latest versions of Docker and Docker Compose installed on your machine.

Clone this repository or copy the files from this repository into a new folder. In the docker-compose.yml file you may change the IP address (in case you run multiple containers) or the database from MySQL to MariaDB.

Make sure to add your user to the docker group when using Linux.

Configuration

Copy the example environment into .env

cp env.example .env

Edit the .env file to change the default IP address, MySQL root password and WordPress database name.

WordPress Version

You can easily change the WordPress version by editing the WP_VERSION variable in your .env file:

WP_VERSION=6.0

Available options include:

• Specific versions: 5.9, 6.0, 6.1.1, etc.
• Combined PHP versions: 5.9-php7.4, 6.0-php8.0, etc.
• latest (default) - for the latest stable version

After changing the version, rebuild the containers:

docker-compose down
docker-compose up -d --build

Installation

Open a terminal and cd to the folder in which docker-compose.yml is saved and run:

docker-compose up

This creates two new folders next to your docker-compose.yml file.

• wp-data – used to store and restore database dumps
• wp-app – the location of your WordPress application

The containers are now built and running. You should be able to access the WordPress installation with the configured IP in the browser address. By default it is http://127.0.0.1.

For convenience you may add a new entry into your hosts file.

Usage

Starting containers

You can start the containers with the up command in daemon mode (by adding -d as an argument) or by using the start command:

docker-compose start

Stopping containers

docker-compose stop

Removing containers

To stop and remove all the containers use thedown command:

docker-compose down

Use -v if you need to remove the database volume which is used to persist the database:

docker-compose down -v

Project from existing source

Copy the docker-compose.yml file into a new directory. In the directory you create two folders:

• wp-data – here you add the database dump
• wp-app – here you copy your existing WordPress code

You can now use the up command:

docker-compose up

This will create the containers and populate the database with the given dump. You may set your host entry and change it in the database, or you simply overwrite it in wp-config.php by adding:

define('WP_HOME','http://wp-app.local');
define('WP_SITEURL','http://wp-app.local');

Creating database dumps

./export.sh

Developing a Theme

Configure the volume to load the theme in the container in the docker-compose.yml:

volumes:
  - ./theme-name/trunk/:/var/www/html/wp-content/themes/theme-name

Developing a Plugin

Configure the volume to load the plugin in the container in the docker-compose.yml:

volumes:
  - ./plugin-name/trunk/:/var/www/html/wp-content/plugins/plugin-name

WP CLI

The docker compose configuration also provides a service for using the WordPress CLI.

Sample command to install WordPress:

docker-compose run --rm wpcli core install --url=http://localhost --title=test --admin_user=admin [email protected]

Or to list installed plugins:

docker-compose run --rm wpcli plugin list

For an easier usage you may consider adding an alias for the CLI:

alias wp="docker-compose run --rm wpcli"

This way you can use the CLI command above as follows:

wp plugin list

phpMyAdmin

You can also visit http://127.0.0.1:8080 to access phpMyAdmin after starting the containers.

The default username is root, and the password is the same as supplied in the .env file.

Xdebug Setup

This project includes Xdebug configuration for remote debugging with VS Code or other IDEs.

Configuration

The project includes the following Xdebug-related files:

• config/xdebug.ini - Configuration for Xdebug
• Dockerfile.wordpress - Builds WordPress image with Xdebug installed
• .vscode/launch.json - VS Code debug configuration

When running the containers, make sure to build them with:

docker-compose up -d --build

VS Code Integration

1. Install the PHP Debug extension
2. Open your project in VS Code
3. Set breakpoints in your PHP code
4. Press F5 or click "Start Debugging" button to start a debug session
5. Access your WordPress site to trigger the breakpoints

Troubleshooting

• Check that port 9003 is open and accessible
• Verify that paths in .vscode/launch.json correctly map to your project structure
• Check Xdebug logs in the WordPress container: docker-compose exec wp cat /var/log/xdebug.log

Plugin Management

Installing Plugins via Admin

Plugins installed through the WordPress admin panel are stored in:

• On host: ./wp-app/wp-content/plugins/
• In container: /var/www/html/wp-content/plugins/

Developing Custom Plugins

To develop custom plugins, you can map a local plugin directory to the container by uncommenting and updating the following line in docker-compose.yml:

#- ./plugin-name/trunk/:/var/www/html/wp-content/plugins/plugin-name

For multiple plugins, add additional volume mappings:

- ./plugin-a/trunk/:/var/www/html/wp-content/plugins/plugin-a
- ./plugin-b/trunk/:/var/www/html/wp-content/plugins/plugin-b

Using WP-CLI for Plugin Management

You can manage plugins via the included WP-CLI service:

# Install a plugin
docker-compose run --rm wpcli plugin install plugin-slug --activate

# List installed plugins
docker-compose run --rm wpcli plugin list

# Update all plugins
docker-compose run --rm wpcli plugin update --all

License

This project is based on WordPress Docker Compose by nezhar, and has been enhanced with Xdebug integration, customizable WordPress versions, and improved plugin management.