PapayaSoft - Phuket web development

Debugging a Web-app in a Vagrant-provisioned VirtualBox VM Using Netbeans

| Comments

Our team has begun to use Vagrant to provision controlled virtual machine environments for all our development. It’s a cool concept, but I was left without the ability to use my Netbeans debugger. It took a little fiddling around to get it right, but I didn’t think about blogging about it until:

  1. Jake McGraw wisely suggested it on Twitter.
  2. I realized that I had re-provisioned my virtual machine (VM) and was maddeningly unable to reproduce what I had done.

So, as much as I hope this will be a help to others, getting it down someplace is as much an act of self-interest as it is altruism.

In the end, the XDebug remote debugging docs really did say it all, but it took some time to wrap my head around it all.


Just dropping the results here for quick reference. At a later date, I hope to fill out with a discussion of what I think is going on and why it works.

IP of my Host (as it appears to Guest):

Port-forwarding: 4003 on Host mapped to 80 on Guest

In XDebug config on Guest:

xdebug.remote_enable  = 1
xdebug.remote_host    =
xdebug.remote_port    = 9000
xdebug.remote_handler = dbgp
xdebug.remote_mode    = req

In Netbeans (on Host):

Under Tools > Options > PHP > Debugging:

Debugger Port: 9000
Session ID: netbeans-xdebug

Under Project Properties > Run Configuration:

Run as: Local Web Site (running on local web server)
Project URL: http://localhost:4003/ Index file: public/index.php

Note that the “Index file” value it wants is an actual file path relative to project root, *not* a URL *relative to vhost doc-root. If Netbeans can’t find the file, it will continually prompt you, making you want to toss the whole thing off a high building. Well, YMMV.

Under Project Properties > Run Configuration > Advanced

Debug URL: Do Not Open Web Browser
Path Mapping:
Server Path: /vagrant/ (path to project in Guest)
Project Path: /path/to/project/in/host/

Then to debug:

In Netbeans (on Host):

  1. Debug > Debug Project <my-project>
  2. Set a breakpoint

To trigger debugging for an HTTP request (from Host)


To trigger debugging for an HTTP request (from Guest)


To trigger debugging for a command-line operation (from Guest):

$ export XDEBUG_CONFIG="idekey=netbeans-xdebug"
$ my-command-line-operation

Aaaah, got my debugger back.