Skip to main content

Composing Docker Local Development: Xdebug (OSX)

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

by Nick Schuch /

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

Posted by Nick Schuch
Sys Ops Lead

Dated

Comments

Comment by Mads H. Danquah

Dated

As of docker for mac 17.06 and forward docker.for.mac.localhost resolves to the IP of the host - so, just use that instead :)

Pagination

Add new comment

Restricted HTML

  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd> <h2> <h3> <h4> <h5> <h6>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.
Not sure where to start? Try typing "hello" or "help" if you get stuck.