Remotely debugging PHP on App Service on Linux

I previously wrote about the possibility of remote debugging PHP apps in Microsoft Azure using ngrok. This solution wasn’t much secure and required the use of 3rd party software. During build, Microsoft announced support for SSH directly into the App Service on Linux instance and thanks to that, we no longer need ngrok or similar software and can do with just Azure CLI and VS Code. In this article, we are going to look at the setup.

The only thing you need is to have Azure CLI installed on your machine and an SSH client. My setup is fairly simple, I have the Ubuntu Bash on Windows installed, where I have both Azure CLI and SSH client. You could alternatively install SSH client to Windows directly along with Azure CLI.

Since this functionality is still in preview at the time of writing, you need to install the webapp extension into the CLI first.

You also need to be using App Service on Linux with a proper container. The default PHP runtime containers don’t contain Xdebug, however the GitHub and Docker Hub has got you covered, so simply use the custom Docker image (don’t forget to enable persistent storage mount).

Next, you need to open the tunnel to the Kudu instance which is then going to proxy the communication to the web instance. Just FYI, the tunnel seems to be simple websocket (wss://) connection (see the TunnelExtension.zip if you want to learn how it works behind the scenes on server and Tunnel.py on the client, alternatively TunnelProxy.ts in VS Code used for Node.js remote debugging). To open the tunnel, simply execute following command:

The port is optional but it allows you to specify the local port used for the tunnel. Once you execute it, the tunnel is going to be open until you end the process.

Then you should try connecting to the instance by SSH like so (the port in this case is the one that you either chose or  was generated for you after executing the command above):

The password for the connection is Docker! (in case you are using custom image, follow these instructions to setup SSH). Once you successfully connect, feel free to terminate the session, since in order to be able to remotely debug PHP, we need to configure SSH port forwarding.

Port forwarding basically allows you to forward a port from the remote instance to your own through SSH tunnel. To create the port forward, use the following command:

The remote_port is the port on the remote machine which is going to be forwarded to your local machine and local_port is the port which the remote port will be forwarded to on your machine. You should usually set them the same unless the remote_port is blocked or used already on your machine.

Once this has worked successfully, you need to also configure Xdebug. In php.ini, make set the following (for full Xdebug configuration, see my previous article):

And that’s it, now you have a secure tunnel set up for PHP debugging.

Author: Jan Hajek

I am Honza, hi.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.