View on GitHub

Drupal-dev-vm

Drupal Development VM (for Drupal 6, 7, 8, etc.) using Vagrant + VirtualBox + Ansible + Xdebug + Vim

Download this project as a .zip file Download this project as a tar.gz file

Drupal Development VM

For Drupal 6, 7, 8, etc.

This project aims to make spinning up a simple local Drupal test/development environment incredibly quick and easy, and to introduce new developers to the wonderful world of Drupal development on local virtual machines (instead of crufty old MAMP/WAMP-based development).

It will install the following on an Ubuntu 12.04 linux VM:

It should take 5-10 minutes to build or rebuild the VM from scratch on a decent broadband connection.

Customizing the VM

There are a couple places where you can customize the VM for your needs:

If you want to switch from Drupal 8 (default) to Drupal 7 or 6 on the initial install, do the following:

  1. Update projects[drupal][version] and core inside the drupal.make file.
  2. Update drupal_major_version inside config.yml.

Quick Start Guide

1 - Install dependencies (VirtualBox, Vagrant, Ansible)

  1. Download and install VirtualBox.
  2. Download and install Vagrant.
  3. [Mac/Linux only] Install Ansible.

Note for Windows users: Ansible will be installed inside the VM, and everything will be configured internally (unlike on Mac/Linux hosts). See JJG-Ansible-Windows for more information.

2 - Build the Virtual Machine

  1. Download this project and put it wherever you want.
  2. Copy example.config.yml to config.yml, and modify it to use settings you like.
  3. Install Ansible Galaxy roles required for this VM: $ sudo ansible-galaxy install -r requirements.txt
  4. Open Terminal, cd to this directory (containing the Vagrantfile and this README file).
  5. Type in vagrant up, and let Vagrant do its magic.

Note: If there are any errors during the course of running vagrant up, and it drops you back to your command prompt, just run vagrant provision to continue building the VM from where you left off. If there are still errors after doing this a few times, post an issue to this project's issue queue on GitHub with the error.

3 - Configure your host machine to access the VM.

  1. Edit your hosts file, adding the line 192.168.88.88 drupaltest.dev so you can connect to the VM.
  2. Open your browser and access http://drupaltest.dev/.

4 - Start a debugging session.

  1. Edit config.yml, adding the line php_xdebug_remote_enable: "true".
  2. Run vagrant provision (if the VM is already running) or vagrant up --provision (if not).
  3. Log in to the VM with vagrant ssh.
  4. Maximize your Terminal window.
  5. Start vim: vim.
  6. Inside vim, start listening for Xdebug with <F5> or :python debugger.run().
  7. In your web browser, open http://drupaltest.dev/?XDEBUG_SESSION_START=sublime.xdebug. (The key sublime.xdebug is the default setting. You can override it by adding php_xdebug_idekey: foo to config.yml.)
  8. Go back to your Terminal window and start debugging!

Syncing folders

You can share folders between your host computer and the VM in a variety of ways; the two most commonly-used methods are using an NFS share, or using Vagrant's rsync method to synchronize a folder from your host into the guest VM. The example.config.yml file contains an example rsync share that would sync the folder ~/Sites/drupal on your host into a /drupal folder on the VM.

If you want to use NFS for the share instead, you could simply change the share to:

vagrant_synced_folders:
  - local_path: ~/Sites/drupal
    destination: /drupal
    id: drupal
    type: nfs

You can add as many synced folders as you'd like, and you can configure any type of share supported by Vagrant; just add another item to the list of vagrant_synced_folders.

Connecting to MySQL

By default, this VM is set up so you can manage mysql databases on your own. The default root MySQL user credentials are root for username+password, but you could change the password via config.yml. I use the MySQL GUI Sequel Pro (Mac-only) to connect and manage databases, then Drush to sync databases (sometimes I'll just do a dump and import, but Drush is usually quicker, and is easier to do over and over again when you need it).

Connect using Sequel Pro (or a similar client):

  1. Use the SSH connection type.
  2. Set the following options:
    • MySQL Host: 127.0.0.1
    • Username: root
    • Password: root (or whatever password you chose in config.yml)
    • SSH Host: 192.168.88.88 (or whatever IP you chose in config.yml)
    • SSH User: vagrant
    • SSH Key: (browse to your ~/.vagrant.d/ folder and choose insecure_private_key)

You should be able to connect as the root user and add, manage, and remove databases and users.

You can also install and use PHPMyAdmin (a simple web-based MySQL GUI) by adding the geerlingguy.phpmyadmin role to provisioning/playbook.yml, and installing the role with $ ansible-galaxy install geerlingguy.phpmyadmin.

Using XHProf to Profile Code

The easiest way to use XHProf to profile your PHP code on a Drupal site is to install the Devel module, then in Devel's configuration, check the 'Enable profiling of all page views and drush requests' checkbox. In the settings that appear below, set the following values:

Catching/Debugging Email with MailHog

By default, the VM is configured to redirect PHP's emails to MailHog (instead of sending them to the outside world). You can access the MailHog UI at http://drupaltest.dev:8025/ (where drupaltest.dev is the domain you've configured for the VM).

You can override the default behavior of redirecting email to MailHog by editing or removing the php_sendmail_path inside config.yml.

Notes

About the Author

Jeff Geerling, owner of Midwestern Mac, LLC, created this project in 2014 so he could accelerate his Drupal core and contrib development workflow. This project, and others like it, are also featured as examples in Jeff's book, Ansible for DevOps.