How can I use XDebug with a PHP upstream behind an nginx reverse proxy?

Question

I have a PHP server running through PHP-FPM which is served with fastcgi through nginx on port 7000. This application has been dockerized and is running as a running container, e.g. my_api.

The my_api docker container can be connected to directly via port 7000 (for sanity checking) as well as through another container which acts as an nginx reverse proxy that uses upstreams to expose the my_api application (and others) on ports 80 and 443 (port 80 redirects to SSL) through proxy_pass directives under the appropriate locations.

If I start an XDebug session using dbgp on port 9000 directly against a file served from http://localhost:7000 I can see the debugging session established correctly and I can debug.

However, if I attempt to start the XDebug session against the URL served by the nginx reverse proxy, e.g. https://localhost/my-api, the debug session does not appear to start or at least it doesn't create the connection properly (no breakpoints are hit in my IDE, etc.).

How can I establish an XDebug session for requests made through the nginx reverse proxy?

For purposes of this question, below is a (relevant) sample of my docker-compose.yml configuration and xdebug.ini:

docker-compose.yml:

version: "2"

services:
  api:
    build: <path_to_dockerfile>
    ports:
       - 7000:7000
       #- 9000:9000   # may be uncommented for direct debugging access
  nginx_proxy:
    build: <path_to_dockerfile>
    links:
      ...
      - api:api
    ports:
      - 80:80
      - 443:443

xdebug.ini

zend_extension=xdebug.so
xdebug.remote_enable=true
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_autostart=0

---

NB: I've tried a couple of different configurations to try and get this working, including launching a Docker container running a dbgpproxy but nothing seems to allow me to debug requests which pass through the reverse proxy. It is very possible though that the configuration I was using for these attempts was just wrong.

I have a few theories on what my problems may be, among them the suspicion that it is the reverse proxy's IP address that is being communicated to XDebug via the remote_connect_back configuration property.

Any help or insight into how to properly configure XDebug to work with requests that are made to a server via nginx proxy passes to an upstream server would be greatly appreciated!

I can provide further details if it would be helpful!

Answer 1

Here's how I got PHP Storm to connect to a dockerized php-fpm / nginx application:

Inject the remote host IP into the container. In your host, set the variable:

XDEBUG_HOST=$(ipconfig getifaddr en0)

I'm not too familiar with docker-compose. I'm using a Kubernetes manifest, but I'm sure there's a way to inject environment variables.

in xdebug.ini:

xdebug.remote_host=${XDEBUG_HOST}

Now you should be able to set up your xdebug client to listen on xdebug.remote_port for debug connections. You'll also have to set up a debug server in PHP Storm or whatever IDE you're using that points to http://127.0.0.1:8080 (or whatever port you're port-forwarding the nginx container to).

Here's what my setup looks like. I'm using PHP Storm but I'm sure you can adapt this to other xdebug clients.

xdebug.ini:

zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_port=10000
xdebug.remote_autostart=1
xdebug.idekey=www-data
xdebug.remote_host=${XDEBUG_HOST}

Reference: https://shippingdocker.com/xdebug/

Answer 2

Being on windows I needed to disable also the option remote_connect_back (on linux it was not needed though)

xdebug.remote_connect_back = 0
xdebug.remote_host = host.docker.internal

Answer 3

Although it is quite late to answer but I have been trying very hard to implement this idea of xdebug i.e. xdebug a website behind an NGINX reverse proxy. However, I've concluded that there's no way it can be achieved without exposing the website's port, in your case 7000. I've tried it on IntelliJ PHPStorm.

Reason:

xdebug tries to upload a file _intellij_phpdebug_validator.php to the web container using Path Mapping in order to validate the URL. e.g. it tries to upload the file at var/www/web, however, it doesn't find this folder on the proxy container since this is the only container accessible using that particular URL http://web.local/web. And when it tries to access this file through URL http://localhost/web/_intellij_phpdebug_validator.php, the internal proxy pass call tries to access the file /var/www/web/_intellij_phpdebug_validator.php and when it doesn't find that file, it returns the error 404 not found.

In othercase, when I use xdebug by exposing my port 8110 and when I access the URL http://web.local:8110, it finds the correct Path Mapping i.e. /var/www/web and xdebug starts working alright.

NGINX Proxy container Error Log entry (trying to find the file at /etc/nginx/html i.e. the nginx proxy's path whereas it was trying initially to upload the file on /var/www/web as per configuration)

2021/10/27 10:50:37 [error] 34#34: *25 open() "/etc/nginx/html/_intellij_phpdebug_validator.php" failed (2: No such file or directory), client: 172.23.0.1, server: proxy, request: "GET /_intellij_phpdebug_validator.php HTTP/1.1", host: "127.0.0.11"

Website container Error Log entry (trying to find the file at /var/www/web i.e. the website's path whereas it was never uploaded here, thus giving error 404)

172.23.0.2 - - [27/Oct/2021:10:51:01 +0000] "GET /web/_intellij_phpdebug_validator.php HTTP/1.0" 404 16 "-" "Java/11.0.6" "172.23.0.1"