6/2/2018 - 9:20 PM

PHPStorm Remote Debugging a Docker Container

Run on Host

$ docker-machine upgrade <VM NAME>

Run on Environment PHP-Installed Container

$ pecl install xdebug-2.5.5 && docker-php-ext-enable xdebug

Put the Following Code to Your XDebug.ini File

Your ini file is located under /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini.

xdebug.remote_autostart=1 #Set this to 1 in order for xdebug to start when the container starts
xdebug.remote_connect_back=1 #Set this to 1 if you don't want to provide remote_host
\!h xdebug.idekey=<Unique IDE Key to be also set on PHPStorm config>
#xdebug.remote_host=<HOST LOCAL IP ADDRESS>

Extra Info

If you set xdebug.remote_connect_back=1 then you don’t have to provide xdebug.remote_host=<HOST LOCAL IP ADDRESS> but you have to enable Start Listening for PHP Debug Connections in PHPStorm.

PHPStorm Config

PHP Server

  1. Create a server from Languages & Frameworks > PHP > Servers.
  2. Name your server to whatever you want.
  3. Host IP address is your VM's IP address.
  4. Port is 80 if you are not listening from any other port in your web server in VM.
  5. Debugger is XDebug.
  6. Check Use path mappings.
  7. Under Absolute path on the server section write where your projetc is located in your docker container. (i.e. /var/www)

Debug Config

  1. Click Run > Edit Configurations....
  2. Add a PHP Remote Debug.
  3. Name it to whatever you want.
  4. Check Filter connection by IDE key.
  5. Select the server you have created before from the drowdown list.
  6. Write your IDE key. This is the same key you have written in your XDebug.ini file as xdebug.idekey. These two have to match.


  1. Click Run > Start Listening for PHP Debug Connections.
  2. Set a breakpoint in your PHP code.
  3. Click Run > Debug.
  4. Go to your browser and navigate to your web site.
  5. You will see that code is stopped at the breakpoint and variables are listed in Debug panel of PHPStorm.