Instantly share code, notes, and snippets.

Embed
What would you like to do?
Docker For Mac Host Address Alias To Enable PHP XDebug (10.254.254.254 Trick)

Docker (Mac) De-facto Standard Host Address Alias

This launchd script will ensure that your Docker environment on your Mac will have 10.254.254.254 as an alias on your loopback device (127.0.0.1). The command being run is ifconfig lo0 alias 10.254.254.254.

Once your machine has a well known IP address, your PHP container will then be able to connect to it, specifically XDebug can connect to it at the configured xdebug.remote_host.

Installation Of IP Alias (This survives reboot)

Copy/Paste the following in terminal with sudo (must be root as the target directory is owned by root)...

sudo curl -o /Library/LaunchDaemons/com.ralphschindler.docker_10254_alias.plist https://gist.githubusercontent.com/ralphschindler/535dc5916ccbd06f53c1b0ee5a868c93/raw/com.ralphschindler.docker_10254_alias.plist

Or copy the above Plist file to /Library/LaunchDaemons/com.ralphschindler.docker_10254_alias.plist

Next and every successive reboot will ensure your lo0 will have the proper ip address.

Finally, make sure to configure your xdebug correctly. However you get your xdebug.remote_host into the container, ensure it has similar settings:

zend_extension=xdebug.so
xdebug.remote_host=10.254.254.254
xdebug.remote_enable=1
xdebug.remote_autostart=1

It is also useful to pass the following environment variable into your container:

PHP_IDE_CONFIG="serverName=localhost"

PHPStorm will use localhost as the server name when you setup the Preferences > PHP > Debugging profile.

Why?

Because docker.local is gone. This seems to be the easiest way to setup xdebug to connect back to your IDE running on your host. Similarly, this is a solution for any kind of situations where a container needs to connect back to the host container at a known ip address.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.ralphschindler.docker_10254_alias</string>
<key>ProgramArguments</key>
<array>
<string>ifconfig</string>
<string>lo0</string>
<string>alias</string>
<string>10.254.254.254</string>
</array>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>
@AlexanderAllen

This comment has been minimized.

Show comment
Hide comment
@AlexanderAllen

AlexanderAllen Sep 22, 2016

Ran manually, confirmed working. TYSM.

AlexanderAllen commented Sep 22, 2016

Ran manually, confirmed working. TYSM.

@DrNgo

This comment has been minimized.

Show comment
Hide comment
@DrNgo

DrNgo Sep 22, 2016

Ran this as well, confirmed working. Thanks so much for this solution!

DrNgo commented Sep 22, 2016

Ran this as well, confirmed working. Thanks so much for this solution!

@nabiyllin

This comment has been minimized.

Show comment
Hide comment
@nabiyllin

nabiyllin Sep 24, 2016

Thanks a lot for this solution!

nabiyllin commented Sep 24, 2016

Thanks a lot for this solution!

@ababushkin

This comment has been minimized.

Show comment
Hide comment
@ababushkin

ababushkin Oct 15, 2016

Can you please post your docker-compose configuration file for the PHP and nginx containers? I can't seem to get this to work still :(

Never mind, my container had the wrong configuration (reboot caused me to lose my local state).

Thanks this is working without issues 👍

ababushkin commented Oct 15, 2016

Can you please post your docker-compose configuration file for the PHP and nginx containers? I can't seem to get this to work still :(

Never mind, my container had the wrong configuration (reboot caused me to lose my local state).

Thanks this is working without issues 👍

@jkuma

This comment has been minimized.

Show comment
Hide comment
@jkuma

jkuma Jan 7, 2017

Working like a charm ! Many thanks sir 👍

jkuma commented Jan 7, 2017

Working like a charm ! Many thanks sir 👍

@lucasceballos

This comment has been minimized.

Show comment
Hide comment
@lucasceballos

lucasceballos Jan 9, 2017

Worked! Thanks

lucasceballos commented Jan 9, 2017

Worked! Thanks

@fjmiguel

This comment has been minimized.

Show comment
Hide comment
@fjmiguel

fjmiguel Jan 27, 2017

Thank you so much! Great solution!

fjmiguel commented Jan 27, 2017

Thank you so much! Great solution!

@ihr-it-projekt

This comment has been minimized.

Show comment
Hide comment
@ihr-it-projekt

ihr-it-projekt Feb 15, 2017

Thank you so much, IT WORKS.

ihr-it-projekt commented Feb 15, 2017

Thank you so much, IT WORKS.

@rakauchuk

This comment has been minimized.

Show comment
Hide comment
@rakauchuk

rakauchuk Apr 12, 2017

It works, thanks!

rakauchuk commented Apr 12, 2017

It works, thanks!

@starlocke

This comment has been minimized.

Show comment
Hide comment
@starlocke

starlocke May 17, 2017

Sanity checking:

  • less /Library/LaunchDaemons/com.ralphschindler.docker_10254_alias.plist

To run this straightaway (without a reboot) run the following:

starlocke commented May 17, 2017

Sanity checking:

  • less /Library/LaunchDaemons/com.ralphschindler.docker_10254_alias.plist

To run this straightaway (without a reboot) run the following:

@ralphschindler

This comment has been minimized.

Show comment
Hide comment
@ralphschindler

ralphschindler Jul 28, 2017

^ Good advice, and good blog post. Excellent @starlocke & @ashsmith. Thanks!

Owner

ralphschindler commented Jul 28, 2017

^ Good advice, and good blog post. Excellent @starlocke & @ashsmith. Thanks!

@J7mbo

This comment has been minimized.

Show comment
Hide comment
@J7mbo

J7mbo Sep 25, 2017

I've used this for a while, except that I found xdebug.remote_autostart=1 completely messes with Composer. Sometimes, Composer in the docker container just doesn't even work with it enabled and hangs.

As a result, I have to set the configuration to xdebug.remote_autostart=0 and pass the argument to my php script with -d instead:

php -dxdebug.remote_autostart=1 /path/to/script.php

J7mbo commented Sep 25, 2017

I've used this for a while, except that I found xdebug.remote_autostart=1 completely messes with Composer. Sometimes, Composer in the docker container just doesn't even work with it enabled and hangs.

As a result, I have to set the configuration to xdebug.remote_autostart=0 and pass the argument to my php script with -d instead:

php -dxdebug.remote_autostart=1 /path/to/script.php

@cristenicu

This comment has been minimized.

Show comment
Hide comment
@cristenicu

cristenicu Mar 5, 2018

There is a hostname available in each of your containers named the docker.for.mac.localhost. This hostname will resolve to your host OS. So you can skip the alias and use xdebug.remote_host=docker.for.mac.localhost
Check this article for more details.

cristenicu commented Mar 5, 2018

There is a hostname available in each of your containers named the docker.for.mac.localhost. This hostname will resolve to your host OS. So you can skip the alias and use xdebug.remote_host=docker.for.mac.localhost
Check this article for more details.

@ralphschindler

This comment has been minimized.

Show comment
Hide comment
@ralphschindler

ralphschindler Mar 9, 2018

@cristenicu yeah, for individuals/small teams that are entirely on mac, thats not a bad thing to bake into a project's container environment. At work, we still have the possibility that someone using linux or windows would want to use the project, in which case that host would not be available to them if it is baked into the container.

Owner

ralphschindler commented Mar 9, 2018

@cristenicu yeah, for individuals/small teams that are entirely on mac, thats not a bad thing to bake into a project's container environment. At work, we still have the possibility that someone using linux or windows would want to use the project, in which case that host would not be available to them if it is baked into the container.

@tomasfejfar

This comment has been minimized.

Show comment
Hide comment
@tomasfejfar

tomasfejfar Apr 13, 2018

For windows you need to add new Loopback adapter as per https://kb.vmware.com/s/article/1004779 and set an IP for it (if you want to keep using DHCP for your main adapter)

tomasfejfar commented Apr 13, 2018

For windows you need to add new Loopback adapter as per https://kb.vmware.com/s/article/1004779 and set an IP for it (if you want to keep using DHCP for your main adapter)

@botjaeger

This comment has been minimized.

Show comment
Hide comment
@botjaeger

botjaeger Oct 17, 2018

how about for ubuntu

botjaeger commented Oct 17, 2018

how about for ubuntu

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment