Sérgio Lopes Sakabatō, the reversed blog!

PHP Development with Vangrant, xDebug and NetBeans IDE20 Oct 2016

Being a slow adopter of some things tech (still no Docker or any other container thingy), I’ve started moving my development stack to virtual machines using Vagrant. Yes, I know everyone is using it now (I’ve actually started a year and a half ago), but I’m now creating my own local machines tailored to the tools I use instead of just pooling the latest packaged distro from Atlas/HashiCorp. So, if you want to build your own development boxes here are a few rough steps.

I’m using Debian as my development/deployment distro, so my box will have the latest Debian 8, 64bit, with Apache Webserver, Oracle Java JRE/JDK, xDebug, MySQL and PHP 7. You can change the installed software to anything you like, this is based on what I’m using at work.

Software/tools being used and setup:

  • VirtualBox
  • Vagrant
  • Debian 8.6 64 bit
  • Composer
  • xDebug
  • NetBeans IDE 8.2, with PHP module
  • Yii2 Framework

The outline of the process is:

  • Install support software (VirtualBox + Vagrant) on the host/work machine
  • Create a virtual machine and install Debian in the standard way
  • Add and configure the WEB stack on the virtual machine
  • Remove all non essential features and settings, package the machine using vagrant
  • Setup the project and the vagrant base file
  • Setup NetBeans IDE (optional) so it can work with xDebug on the VM

Create the virtual machine/server

On VirtualBox create a new virtual machine with the following settings:

  • name: Debian-vagrant-base
  • type: Linux
  • version: Debian (64-bit)

  • RAM Size: 1024MB
  • New VMDK disk with 20GB, dynamically allocated space

Change the machine settings to boot from a CD-ROM first, pointing device should be PS/2 Mouse, add the Debian ISO and start the virtual machine to install Debian. The only change you need is that the first user should be named “vagrant”, password “vagrant”. You can use whatever password you need on root, your development box has no company secrets right?

Boot the machine and login as root (all following commands assume you’re running as root).

Server software

Update and upgrade your new virtual server, add install VirtualBox Guest Additions. You’ll need linux-headers-amd64, build-essential and linux-kbuild package for you’re kernel version. Add the Guest Additions CD to the virtual machine (Devices > Insert Guest Additions CD Image …), mount the CD and run the VBoxLinuxAdditions.run script as root and when done reboot.

PHP 7 is not officially in Debian 8.6 yet, but you can install it by using DotDeb, https://www.dotdeb.org/instructions/. Include all the modules you usually need, setup apache, mysql and any other software as you require.


Edit /etc/php/7.9/apache2/conf.d/20-xdebug.ini and add:


In the standard LAMP install, xdebug is already setup to listen to requests on local machines, and when using your IDE to debug a project all requests are local. In this setup we’re running our project on a remote server (even if it is just a virtual machine) and we need to tell xdebug to accept requests from external machines (our host). VirtualBox will, most of the time, route your network traffic through address (check with the netstat -rn command).

If you’re using NetBeans IDE you need to map your local project paths to the remote paths (on the virtual server) so that it can show you breakpoints and step-by-step execution. To do this, in your project’s advanced run configuration add a new path mapping.

Project Properties > Run Configuration > Advanced
Debug URL: default
Path Mapping: /vagrant -> /<full path to project root>

Vagrant user

When installing Debian you should have created one user besides the default root one. This user should be named vagrant as this is the account that Vagrant expects to find. Debian doesn’t ship with sudo by default so you’ll need to install it.

After installing sudo, add the vagrant user to the sudoers list and make sure it can run commands without being asked for a password (this is required by Vagrant).

visudo -f /etc/sudoers.d/vagrant


We now need to add an SSH key in order for the Vagrant commands to be executed in the guest (virtual server) machine. This key is insecure, everyone uses the same key.

mkdir -p /home/vagrant/.ssh
chmod 0700 /home/vagrant/.ssh
wget –no-check-certificate \
      https://raw.github.com/mitchellh/vagrant/master/keys/vagrant.pub \
      -O /home/vagrant/.ssh/authorized_keys
chmod 0600 /home/vagrant/.ssh/authorized_keys
chown -R vagrant /home/vagrant/.ssh

Edit /etc/ssh/sshd_config and uncomment the AuthorizedKeysFile setting.

AuthorizedKeysFile %h/.ssh/authorized_keys

Restart the ssh service.

VM Settings

I usually change a few settings on the virtual machine to make it simpler/performant. These are:

  • Disabling the Floppy and CD-ROM drives from the Motherboard settings screen
  • Make sure Pointing device is PS/2 Mouse
  • Disable all network adapters except for the Adapter 1
  • Disable USB Ports and sound

Packaging the virtual machine

In order to reuse this virtual machine we need to package it into a format that Vagrant understands. Before powering off the machine, we’ll “zero out” de virtual HDD.

dd if=/dev/zero of=/EMPTY bs=1M
rm -f /EMPTY

On the host system, create a folder to hold your Vagrant boxes, package the new virtual machine, and add it to the list of known boxes.

mkdir ~/.vagrant-boxes
cd ~/.vagrant-boxes

vagrant package –base Debian-vagrant-base –output debian-webbase
vagrant box add debian-base debian-base


And we’re done! On your Vagrantfile use the name of the local box and and any bootstrap you need. You can add the boxes to a remove server, shared hosting, etc., so the same box is available to all developers of your team.