Docker For Mac Host Address Alias To Enable PHP XDebug (10.254.254.254 Trick)

README.md

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.

com.ralphschindler.docker_10254_alias.plist

<?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>

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 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.

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)

how about for ubuntu

Sanity checking:

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

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

• sudo launchctl load /Library/LaunchDaemons/com.ralphschindler.docker_10254_alias.plist

  • Partial credits to: https://www.ashsmith.io/docker/get-xdebug-working-with-docker-for-mac/

... and ifconfig lo0 inet | grep 10.254.254.254 to see directly if it worked.

I suggest simply using a script like this without any kind of networing configuration on your mac

https://github.com/bsramin/dch-project-sample/blob/master/container/php/xdebug-starter.sh

docker known the host ip via this special DNS name host.docker.internal

https://docs.docker.com/docker-for-mac/networking/#use-cases-and-workarounds