Composing Docker Local Development: Xdebug (OSX)

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.

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

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

Posted by nick.schuch
Sys Ops Lead

Dated 15 September 2017