Composing Docker Local Development: Xdebug (OSX)

by nick.schuch /

Share this post on social media

In this post, we will show the pain points of running Xdebug in a Docker local development environment and how we overcame them.

Xdebug is essential when it comes to local development.

Normally the hardest part about configuring Xdebug is setting the IP address which it should send its debugging data to (eg. PHPStorm).

Configuring this with Vagrant was very simple since we were able to use the following setting for it to "Just Work":

xdebug.remote_connect_back = 1

Remote Connect Back is awesome, it allows for Xdebug to send its debugger information back to the IP address making the web request, where PHPStorm is running.

However, running Xdebug with "Docker for Mac" (D4M) is hard. D4M runs over multiple networks:

  • OSX host
  • Linux VM

This means that the IP address Xdebug ends up sending data to is the IP address of the Linux VM.

A diagram showing where xdebug traffic stops

Existing solutions in the Docker community usually end up with the developer running additional configuration that they have to manage:

eg. https://forums.docker.com/t/ip-address-for-xdebug/10460/21

To solve this we wrote a tool called "D4M TCP Forwarder", which receives requests being sent to a port on the D4M host and forwards them to the OSX users host IP.

https://github.com/nickschuch/d4m-tcp-forwarder

Diagram showing Xdebug traffic being forwarded

To add this to your project you simply add this service to your Docker Compose file:

xdebug:
  image: nickschuch/d4m-tcp-forwarder
  network_mode: host

The solution results in:

  • No configuration for a developer
  • Reusable solution for the community

Tagged

Docker