Building an (ideal) Drupal development environment with Vagrant, Drupal VM and PhpStorm. Part 2

In part 2 of this becoming a «long read» blog post we’ll go through all steps needed to get a fully working Drupal VM machine ready for Drupal 8 development (let's make this interesting), and also try to resolve some common bottlenecks on the way.

Disclaimer. The following applies to MacOS and most Linux distros «out of the box». Dear Windows users, you will have to check the official docs for extra actions needed, but most of the things will be pretty identical in your environment.

The goal of this tutorial is to get the virtual machine up and running as quick as possible, but with a flexibility in mind, so instead of automating a few steps, we’ll do them manually.

Get Ansible

Ansible can be installed via «pip», the Python package manager. In my case it was as simple as:

sudo pip install ansible

If you don’t have pip, get it with:

sudo easy_install pip

For more information and details on how to install Ansible, check with

Get and configure the Drupal VM

Choose a location for your Drupal VM environment (nothing will be installed here), in my case it's ~/Dev/Vagrant.

git clone ~/Dev/Vagrant/drupal-vm

So the folder where the Drupal VM code and all configs will reside is ~/Dev/Vagrant/drupal-vm. Of course, you’re free to choose any location to your liking.

Open the folder we’ve just cloned and make a copy of example.config.yml, renaming it to config.yml. This is the main configuration file of the Drupal VM and in most cases we won’t touch anything else.

Create another folder where the codebases (sites) will be synced from VM to the host machine and vice versa. I have it like ~/Dev/Vagrant/www.

So once again:

~/Dev/Vagrant/drupal-vm - the configs folder and the folder from which we’re executing Vagrant management commands.

~/Dev/Vagrant/www - shared folder where the codebases will be located.

~/Dev/Vagrant/www/drupal8 - shared folder with the Drupal 8 installation we'll create later.

Now let’s edit the config.yml file and set up the common shared folder for all sites. For the simplicity I'm assuming that all sites will share a single folder, however this is not the only option.

  - local_path: ~/Dev/Vagrant/www
    destination: /var/www
    id: drupal
    type: nfs
    create: true

So what we’re saying here is «Please map the path on a local machine where I’ll have the codebases located with the path on the remote (guest) virtual machine».

Next, let’s create the virtual host for Drupal in the appropriate section of config.yml.

  - {servername: "", documentroot: "/var/www/drupal8"}

You should get the pattern here — create a domain (it can be absolutely anything, not necessarily a subdomain as in my case), and point it to the path on the VM.

Lastly, set a few variables to the sane defaults, go through each line in the file and adjust if needed.

install_site: false
build_makefile: false
php_memory_limit: "512M"

We’ll need a few very useful Vagrant plugins for a seamless experience, so run those commands from the Drupal VM folder:

vagrant plugin install vagrant-hostsupdater
vagrant plugin install vagrant-vbguest

Build the machine

Building a machine is as simple as running the command below from the Drupal VM folder:

vagrant up

If it fails or takes too long to finish, or you have to cancel the provisioning manually for some reason, just run:

vagrant provision

When the machine is up and there are no errors from the provisioning script, create the info.php with the following content:

<?php phpinfo(); ?>

And try to access it using the domain we’ve created for Drupal installation, in my case it was

If you can see the information about PHP version installed and loaded modules, all good to spin up Drupal.

Before going further, don’t forget to install Ansible roles required for this VM:

sudo ansible-galaxy install -r provisioning/requirements.yml --force

Install Drupal 8

First, we need a database.

As we’ve installed the Adminer tool with the ansible-galaxy install command in the previous part, we can go directly to and use the following credentials to login:

  • Username: root
  • Password: root

And create the database:

From the drupal-vm folder let’s login to the machine and install Drupal 8.

vagrant ssh
cd /var/www/drupal8

In general, choose whatever method you prefer. In order to get a codebase, you don't even need to login to the VM as you could upload files directly to ~/Dev/Vagrant/www folder on the host OS.

drush dl drupal-8.0.0-beta14
mv drupal-8.0.0-beta14/* .

On the next step, instead of using the drush site-install, I recommend to go through the normal installation procedure to be able to resolve any issues with a few mouse strokes.

On this point, you should be able to visit the domain and install Drupal as you usually do.

Tips and tricks

a) To access MySQL with external program, such as Sequel Pro or MySQL Workbench, use the following connection details (note the private key location):

b) When adding new site, run vagrant provision to make it live.

c) To turn the machine off, run vagrant halt

d) If you’re getting the «Maximum function nesting level of 'xxx' reached», login to the machine with vagrant ssh, then do

sudo nano /etc/php5/fpm/conf.d/20-xdebug.ini

and raise the number. But ONLY if you have the xdebug extension activated in config.yml.

e) If you need to install any software on the machine, DO NOT do it by running apt-get or pecl commands on the machine itself. Use the config.yml file instead and provision the machine.

f) If you spot your machine is slow, this is because of the synchronization issues between host and guest machines. Read this for details

g) Learn how to use awesome tools which come with Drupal VM - MailHog, Adminer, XHProf, XDebug, Pimp my Log, Apache Solr.

Useful links:

For any other questions or issues, please check with official documentation or shout in comments!