Solved: Remote XDebug from Dockerized PHP app via SSH Tunnel on Ubuntu and WSL

expose:
  - "9000"

1. Remove the ports: section from docker-compose.yml and define expose
   
2. On the remote machine enable GatewayPorts clientspecified in /etc/ssh/sshd_config (then restart the sshd service).
3. This allows you to create an SSH port forward tunnel which listens on all network interfaces (0.0.0.0 or *) which is required in order for the Docker container's virtual network interface to reach your client machine via the tunnel. By default, the GatewayPorts setting limits remote port forwardings to bind to the localhost interface only which Docker can't "see".

Change SSH connection string to explicitly specify that I wanted to listen on the global interface *:

ssh -R *:9000:localhost:9000 [email protected]

Or with Putty/Kitty

After doing all this, I was finally able to connect to Xdebug running inside a Docker container on the remote server from my local machine. 🎉

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch built-in server and debug",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-S",
                "localhost:8000",
                "-t",
                "."
            ],
            "port": 9000,
            "serverReadyAction": {
                "action": "openExternally"
            }
        },
        {
            "name": "Debug current script in console",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "externalConsole": false,
            "port": 9000
        },
        {
            "name": "Listen for Xdebug 9000",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/html/": "${workspaceRoot}/",
            },
        }
    ]
}

xdebug-php.ini

zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20230831/xdebug.so

xdebug.mode=debug
xdebug.client_port=9000
;xdebug.client_host=dockerhost
xdebug.client_host=xdebug://gateway
xdebug.idekey=PHPSTORM
xdebug.start_with_request = yes

---

Optionally, if you want to explicitly force Xdebug to connect only to the host machine (meaning you only want to use Xdebug via the SSH tunnel), either:

Add the following section to your service in docker-compose.yml:

     extra_hosts:
       - host.docker.internal:host-gateway

Then set xdebug.client_host=host.docker.internal and xdebug.discover_client_host=Off

or

• Set xdebug.client_host=xdebug://gateway

---

P.S. A useful command while debugging this was nc -vz 127.0.0.1 9000 which allowed me to check if my SSH port forward was working on the host machine, at least.

Original credits to WackGet

---

How to xdebug docker PHP app in WSL (behind VPN it should work too)

1. create .wslconfig in %UserProfile%
2. restart computer! (wsl --shutdown is not enough!)

[wsl2]
networkingMode=mirrored
debugConsole=true

[experimental]
hostAddressLoopback=true

configure xdebug.ini in your docker container

[xdebug]
xdebug.mode=off
xdebug.start_with_request=trigger
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/dev/stderr
xdebug.log_level=0
xdebug.remote_connect_back=off

create .env in your app directory where you have docker-compose.yml and configure debug host ip.

DEBUG_HOST=10.150.85.91

Update docker-compose.yml and add .env loading + extra_hosts

web:
    image: php/php:8
    working_dir: /var/www/html
    env_file: .env
    extra_hosts:
        host.docker.internal: ${DEBUG_HOST}

How to detect correct ips? Open PHPStorm debug settings and get it from here

Restart your web app container

• docker compose up -d web
• docker compose exec -u root web bash
• apt install iputils-ping
• ping host.docker.internal
• if it is pinging, your setup is fine

Install xdebug helper

https://microsoftedge.microsoft.com/addons/detail/xdebug-helper/ggnngifabofaddiejjeagbaebkejomen

or add get param to url to start debug ?XDEBUG_SESSION_START=PHPSTORM

---

PHPStorm xdebug setup

Docker compose server - WSL

CLI Interpreters

PHPStorm CLI debug WSL configuration