XDebug / WSL 2: Make xDebug work out-of-the-box.

ayalon commented 3 years ago

Hi

I wrote a blogpost about my WSL 2 setup under Windows 10. It is blazing fast and combined with mutagen.io sync it has a better performance than on OSX. (See blogpost here)

Almost everything works out-of-the-box except xDebug. I pinned down the issue, but I have no easy solution to it.

File: lando/plugins/lando-core/index.js

LANDO_HOST_IP: (process.platform === 'linux') ? ip.address() : 'host.docker.internal',

Because WSL 2 is a native linux kernel running under Windows, the above line detects 'linux' as the platform and therefore the ip.address() of WSL is taken. This will not work, because as compared to OSX, PHPStorm or any xDebugger will run on the Docker Host system. So the host ip should be 'host.docker.internal'

This means, this condition should be extend to:

if (platform === linux && platform !== wsl 2) ? ip.address() : 'host.docker.internal',

If this is correct; XDEBUG_CONFIG will be automatically correct: File: plugins/lando-services/services/php/builder.js

LANDO_WEBROOT: `/app/${options.webroot}`,
XDEBUG_CONFIG: `remote_enable=true remote_host=${options._app.env.LANDO_HOST_IP}`,

Unfortunatly I have no idea how to detect WSL 2 from javascript. Maybe someone has an idea how to fix that.

ianrogren commented 3 years ago

@ayalon thanks for this! Been banging my head for a while on why I kept getting timeouts with xdebug on Lando and WLS2. Setting the environment override to LANDO_HOST_IP: "host.docker.internal" fixed my issue!

marfillaster commented 3 years ago

Setting the env XDEBUG_CONFIG to remote_enable=true remote_host=host.docker.internal should work. If you're using VSCode Remote php-debug extension, you need to set .configurations[].hostname = 0.0.0.0 in launch.json.

GuyPaddock commented 3 years ago

(UPDATED on 2022-03-19) Here's what worked for me with IntelliJ/PHP Storm running outside WSL being able to debug a PHP app using the Pantheon recipe in Lando:

Installed WSL 2 with Ubuntu.
Installed Docker Desktop, with WSL 2 support turned on.
Instead of installing Lando in Windows, installed it in Docker using fake Docker CE package mentioned in https://github.com/lando/lando/issues/1723#issuecomment-890112132.

I enabled XDebug and logging XDebug logging (to confirm that it was in fact actually trying) via this in the .lando.yml file:

# ... several lines omitted ...
services:
  appserver:
    # ... several lines omitted ...
    xdebug: true
    overrides:
      environment:
        # Support debugging Drush with XDEBUG.
        PHP_IDE_CONFIG: "serverName=appserver"
    volumes:
      # We use file-based volume mounts to override PHP config instead of using
      # the 'config.php' override so that the recipe-provided PHP config is
      # still loaded first. Without this, our local environment is missing
      # Pantheon-specific settings and performance enhancements.
      # See https://github.com/lando/pantheon/issues/113
      #
      # The ${PWD} trick is required for a file mount to work properly, as it
      # appears that the source path must be an absolute path.
      # See https://stackoverflow.com/a/42260979/4342230
      #
      # The target filenames inside the container may look strange, but it's
      # because PHP configs are evaluated in alphabetical order. We want ours
      # evaluated after Lando's, which can be found at:
      # /usr/local/etc/php/conf.d/zzz-lando-my-custom.ini
      - ${PWD}/.lando/php.ini::/usr/local/etc/php/conf.d/zzz-my-dev-xdebug.ini
# ... several lines omitted ...

... and then placed the following in .lando/php.ini in my application directory (use an absolute path for the log unless you want to be confused about why the log only works for CLI!):

; All of the following is required in order for PhpStorm XDEBUG to work when it
; is running in Windows but Arkayo is running on Lando inside WSL2.
xdebug.idekey = 'www-data'
xdebug.mode = debug
xdebug.client_host = ${LANDO_HOST_IP}

To fix an issue with the IP address of Docker being used as the XDebug host, I put the following in ~/.lando/config.yml inside WSL:
```
appEnv:
  LANDO_HOST_IP: host.docker.internal
```
I had to configure IntelliJ to use the www-data IDE key. Here are my settings on the IntelliJ/PhpStorm side:

Running the Drupal PHP report, this is what it looked like when it was configured correctly inside Lando:

rabauss commented 3 years ago

Thanks, for the advice number 5 for wsl2:

To fix an issue with the IP address of Docker being used as the XDebug host, I put the following in ~/.lando/config.yml inside WSL:
appEnv:
 LANDO_HOST_IP: host.docker.internal

But I think we should add this step to the docs, because some wsl2 users are even running their IDE inside wsl2, so we wouldn't find a automatic solution, would we?

mrtronje commented 3 years ago

@rabauss thank this solution works. But we've to differentiate between:

Docker Desktop with WSL2 Backend <- your solution works as host.docker.internal is defined and works
Docker installation in WSL2 <- doesnt work as host.docker.interal is not defined (compare https://stackoverflow.com/questions/48546124/what-is-linux-equivalent-of-host-docker-internal)

I guess thats one of the reasons why we have the following line in the code

if (platform === linux ? ip.address() : 'host.docker.internal',

A possible solution would be to detect if we have a WSL system and then read the IP from the following command (should work in both situations):

awk '/nameserver/ { print $2 }' /etc/resolv.conf

rabauss commented 3 years ago

I guess I found a solution for the changing ip problem within wsl - here: https://github.com/docker/for-linux/issues/264#issuecomment-772844305

I added to my .lando.local.yml the following (because I'm currently in my team the only one with wsl and we have not tested yet with windows docker desktop neither mac + linux!):

services:
    appserver:
        overrides:
            extra_hosts:
                - "host.docker.internal:host-gateway"

And of course I had to manipulate the LANDO_HOST_IP via ~/.lando/config.yml

Adding the extra_hosts is only a solution for a wsl user, if you're also running the phpstorm inside the wsl - I'm not sure how to add the windows host instead, if you have phpstorm outside wsl running!

maxdev commented 3 years ago

@rabauss unfortunatelly, but this doesn't work if PHPStorm installed on Windows and Docker installed on WSL2 :(

Only this solution helps me for now, but it is not ideal https://github.com/lando/lando/issues/1723#issuecomment-821823611

rabauss commented 3 years ago

Yes, as I said my approach helps only for wsl users with phpstorm also inside wsl - for phpstorm in windows the linked solution of @maxdev would be the way.

But that's nothing lando can know automatically - so you always would need something for your .lando.local.yml or I would prefer a setting in ~/.lando/config.yml - if you have team members with different environment settings!

EDIT:

see the updated docs in my PR (https://github.com/lando/docs/pull/170): https://deploy-preview-170--docs-lando.netlify.app/guides/setup-lando-on-windows-with-wsl-2.html#configure-host-ip

@pirog can we add the extra_hosts with env variables LANDO_HOST_NAME_DEV/LANDO_HOST_GATEWAY_DEV and fallback for host/host-gateway always to the lamp recipes?

Or we should add that to the guide of @dustinleblanc 👍

GuyPaddock commented 2 years ago

BTW If you are using a custom PHP config per my instructions above and you are unable to use Solr, note: https://github.com/lando/pantheon/issues/113

I am working on finding a way to customize PHP settings without losing the defaults from the Pantheon recipe.

GuyPaddock commented 2 years ago

I've updated my earlier comment with a new approach that works for more recent versions of XDebug while not preventing recipe-supplied PHP config from loading.

This works for me when using:

PhpStorm/IntelliJ running on Windows
Docker for Windows
Lando running on Ubuntu inside WSL2, installed via dpkg and using my docker-ce fake package so that Docker does not get installed inside WSL2.

AlexanderAllen commented 2 years ago

https://github.com/lando/lando/issues/2540#issuecomment-712995359 is surprisingly working for me.

Using host.docker.internal is not enough. I am using it in my php.ini, but in addition:
I am running VSC inside WSL.
I am specifying "hostname": "0.0.0.0", per the comment above in the VSC launch.json.

Docker talks to host machine (host.docker.internal) -> host machine forwards connection to WSL -> VSC in WSL sees and accepts connection on XDebut port 9003.

rabauss commented 2 years ago

see the updated docs, too: https://docs.lando.dev/guides/setup-lando-on-windows-with-wsl-2.html#configure-host-ip

TheThor commented 2 years ago

Still can't get xdebug 3 to work. I have Lando inside WSL2 Ubuntu distro, PHPStorm in Windows. Followed the instructions in the docs, including the ones here.

So far, drupal phpinfo shows the following:

The LANDO_HOST_IP env doesn't get populated and, while building, this shows:

rabauss commented 2 years ago

so the instructions for ~/.bashrc doesn't seem to be applied - you should see the set variables with the following command in the bash where you run lando start:

echo $LANDO_HOST_NAME_DEV
echo $LANDO_HOST_GATEWAY_DEV

If you don't see them try running temporary 1 a) from https://docs.lando.dev/guides/setup-lando-on-windows-with-wsl-2.html#_1-add-this-lines-to-bashrc-inside-wsl2 and afterwards do a lando rebuild -y

TheThor commented 2 years ago

Didn't even cross my mind that If I run those two echos... but, before doing the steps in 1 a), I get the proper addresses so all is correct. $LANDO_HOST_NAME_DEV is set to host.wsl.internal and the other is the IP address. This was done on the WLS via the PHPStorm terminal, where I run the lando start

I did try to manually run the 1 a) and then rebuilding. I still got the same three of those warnings.

Is there any way to check (via logs or something) if the ~/.lando/config.yml is being looked at? The problem seems to be that appEnv part is being ignored completely. This is the echo:

quentint commented 1 year ago

I've written this guide, if that's of any help: https://gist.github.com/quentint/57f9144459598b66cf9d59c681361c03

rabauss commented 1 year ago

@quentint thanks for the more straight guide - maybe we should split my guide from https://docs.lando.dev/guides/setup-lando-on-windows-with-wsl-2.html in the official docs into your guide and another for the users with IDE inside WSL - but your steps after Restart WSL are the same for both IDE outside and inside wsl.

Unfortunately you also did not find a solution for the non static LANDO_HOST_GATEWAY_DEV 😭

rabauss commented 1 year ago

If someone has some problems with PHPStorm in Windows and Lando in the WSL: The communication through the Windows Firewall must be allowed for PHPStorm! I guess we should add that info to the guide ;-)

quentint commented 1 year ago

I recently used my own guide on a new setup and it failed 🙁 Things look a bit random, and the guide might miss an important step... If anyone has a clue, please tell me 😉

rockschtar commented 1 year ago

I recently used my own guide on a new setup and it failed 🙁 Things look a bit random, and the guide might miss an important step... If anyone has a clue, please tell me 😉

Check out this guide (https://gist.github.com/rockschtar/93a892a7065be425a4729e2690648150) and see if it works.

quentint commented 1 year ago

Works like a charm, thanks!

stale[bot] commented 1 year ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions and please check out this if you are wondering why we auto close issues.

gslexie-dwt commented 11 months ago

I had a lot of trouble getting any of these solutions to work. For whatever reason, my containers running in WSL just can't seem to talk to my Windows host at all. I can telnet from WSL to Windows but cannot telnet from a container to Windows.

In the end I found it easier following the directions to connect with PHPStorm by XDebug proxy here: https://www.jetbrains.com/help/phpstorm/multiuser-debugging-via-xdebug-proxies.html

Pretty much just run ./dbgpProxy -i0.0.0.0:9001 -s0.0.0.0:9003 inside WSL and then tell PHPStorm the IP address of your WSL distribution (the one assigned to eth0 interface).

quentint commented 11 months ago

This guide might help, too!

https://gist.github.com/quentint/265404e9fd9a6ada2893639006c0865b (see the Xdebug section).

lando / lando

XDebug / WSL 2: Make xDebug work out-of-the-box. #2540