Quickstart with Docker in PhpStorm

So, you’ve decided to try something new today and started a project from scratch. Your first step will be to set up a development environment: at the bare minimum, you’d want to run a web server and a PHP interpreter (preferably – with the debugging engine installed).

With Docker, you can start developing, running, and debugging your code in a matter of minutes!

Probably the easiest way to integrate Docker with PhpStorm is to use the PhpStorm Docker registry. It provides a selection of preconfigured Docker images curated by the PhpStorm team, which cover the most common PHP development needs.

Before you proceed, make sure that you have Docker installed on your machine: see how to do it on Windows and on macOS.

Defining the environment

To get started, we create a new project in PhpStorm. Next, we create a new file named docker-compose.yml , which will describe the configuration of the services comprising our app. In our case, it will be a single webserver service:

As you can see, we use the preconfigured Docker image comprising the Apache web server and PHP 7.1 with Xdebug.

Note that we use the host.docker.internal  value to refer to the remote host. In Docker for Windows and Docker for Mac, it automatically resolves to the internal address of the host, letting you easily connect to it from the container.

An important note for Linux users: host.docker.internal  on Linux is currently not supported. You’ll have to use your local machine’s hostname instead (to find out what your machine’s hostname is, simply execute hostname  in Terminal).

The corresponding environment configuration section for Linux will read as follows:

See here for more details and possible workarounds.

Our environment is fully described:


We can now start using it by creating a dedicated run/debug configuration.

Creating a run/debug configuration

Right-click docker-compose.yml  and select Create… from the context menu:


In the dialog that opens, provide the name of the configuration and apply your changes:


You can now start the configuration from the toolbar:


PhpStorm will automatically download the required image and start the web server:


That’s it: we’ve got everything ready for running and debugging our code!

Running and debugging code

Let’s ensure that everything works as expected. To do this, we’ll create the most simple Hello world PHP file and try to debug it following the PhpStorm Zero-Configuration Debugging approach.

Since we already have Xdebug installed and configured, this will only require that you:

  • Have a debugging extension installed and enabled for your browser:chrome_debug_extension
  • Set a breakpoint in your code:
  • Enable listening to incoming debug connections in PhpStorm:enable_listening_debug_connections

Now, simply open the page in the browser, and the debugging session will be started automatically:


We encourage you to further explore the PhpStorm Docker registry: while we’ve looked at a very simple case, you can use the described technique to provide your environment with, for example, a database, or an sftp server.
Using these Docker images will save you a lot of effort and let you start coding in a matter of a minute, or even less!

If you’d like to learn more about Docker and how to use it in PhpStorm, make sure to check out the excellent tutorial series by Pascal Landau, and PhpStorm documentation, of course.

Your JetBrains PhpStorm Team
The Drive to Develop

This entry was posted in Cool Feature, Newsletter, Tutorial and tagged , , , . Bookmark the permalink.
  • me

    This is a fantastic write-up. Thanks! For newbies, be aware that these steps will only work if you’ve already installed Docker on your local machine.

  • http://laurinkeithdavis.com/ Keith Davis

    I’m just barely above a novice with Docker, but I’ve yet to get it work well with PhpStorm. I’m on Windows and I’m getting a 403 Forbidden when loading the page.

  • Апостол Маринов

    Any additional tips on the debugging part? Its not working for me.

    • http://blog.riff.org/ FGM

      I had the problem too (macOS High Sierra). Turned out that in that configuration (Ethernet + Wi-Fi) docker.host.internal did not resolve to the correct IP: it found one of the addresses, but PhpStorm was listening on the other one. So I went to the Network Panel, found the IP associated with my Wi-Fi (192.168.19.something), and used that instead of host.docker.internal (which resolved to After restarting the docker-compose configuration, Bingo!

      • Апостол Маринов

        Ugh I dont know, when I run the “Web Server Debug Validation Dialog” everything checks out, but it still doesnt work.

        • http://blog.riff.org/ FGM

          That was my situation too. So I wrote down all the IPs on my mac (host), launched a docker exec -it /bin/bash to enter the container, installed ping and netcat (apt update && apt install iputils-ping telnet), and tried port 9000 on all the addresses. Turned out the IP for docker.host.internal didn’t answer but another one did. Changed the docker-compose.yml to that address, rebuild/redeployed the container, and it worked. You could try that.

          • Апостол Маринов

            I made it work eventually by using a custom container and adding a script I found that maps the correct IP to host.docker.internal and by setting “zend_extension=xdebug.so”, initially I read somewhere you have to specify the full path to the extension but it didnt work that way. Anyway the project Im working on uses dependency injection and the debugger doesnt work with it ;(

    • Dmitry Tronin

      Getting any errors? Please try setting IDE up according to https://confluence.jetbrains.com/display/PhpStorm/Docker+Support+in+PhpStorm#DockerSupportinPhpStorm-DebuggingthePHPwebapplicationrunningintheDockercontainer

      If that doesn’t help – please contact us directly via Help > Submit New Request

  • Tom M.

    Hi, I’m missing the option ‘create docker-compose.yml’ in my context menu.

    • Eugene Morozov

      You can the option to the New menu manually at Settings/Preferences | Editor | File & Code Templates | Files.

  • Eugen Neuber

    running the docker PHP container does work undel Linux too — but debugging does not. Is there any tutorial for Linux users?

    • Dmitry Tronin

      Debugging in Linux shouldn’t be different from the one described above. We have a series of debugging guides at https://www.jetbrains.com/phpstorm/documentation/debugger/ – feel free to start with those

      • Eugen Neuber

        Thanks! I have xdebug up and running with PHP’s internal server “php -S localhost:8080” (xdebug validation says ok). When I switch to docker server (xdebug validation says also ok) but there are no incoming connections (docker ip is, there seems to exist a brigde …

        • Eugene Morozov

          As I suggested in the support ticket, please try using the host’s hostname instead of host.docker.internal.
          Probably we’ll need to add this information to the post.