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