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:
- Apache 2.2.x
- PHP 5.5.x (configurable)
- MySQL 5.5.x
- Drush latest release (configurable)
- Drupal 6.x, 7.x, or 8.x.x (configurable)
- XHProf, for profiling your code
- XDebug, for debugging your code
- MailHog, for catching and debugging email
- Vim 7.3, for editing and as an interface to Xdebug
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:
-
config.yml
: Contains variables like the VM domain name and IP address, PHP and MySQL configuration, etc. -
drupal.make
: Contains configuration for the Drupal core version, modules, and patches that will be downloaded on Drupal's initial installation (more about Drush make files).
If you want to switch from Drupal 8 (default) to Drupal 7 or 6 on the initial install, do the following:
- Update
projects[drupal][version]
andcore
inside thedrupal.make
file. - Update
drupal_major_version
insideconfig.yml
.
Quick Start Guide
1 - Install dependencies (VirtualBox, Vagrant, Ansible)
- Download and install VirtualBox.
- Download and install Vagrant.
- [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
- Download this project and put it wherever you want.
- Copy
example.config.yml
toconfig.yml
, and modify it to use settings you like. - Install Ansible Galaxy roles required for this VM:
$ sudo ansible-galaxy install -r requirements.txt
- Open Terminal, cd to this directory (containing the
Vagrantfile
and this README file). - 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.
-
Edit your hosts file, adding the line
192.168.88.88 drupaltest.dev
so you can connect to the VM. - Open your browser and access http://drupaltest.dev/.
4 - Start a debugging session.
- Edit
config.yml
, adding the linephp_xdebug_remote_enable: "true"
. - Run
vagrant provision
(if the VM is already running) orvagrant up --provision
(if not). - Log in to the VM with
vagrant ssh
. - Maximize your Terminal window.
- Start vim:
vim
. - Inside vim, start listening for Xdebug with
<F5>
or:python debugger.run()
. - 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 addingphp_xdebug_idekey: foo
toconfig.yml
.) - 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):
- Use the SSH connection type.
- Set the following options:
- MySQL Host:
127.0.0.1
- Username:
root
- Password:
root
(or whatever password you chose inconfig.yml
) - SSH Host:
192.168.88.88
(or whatever IP you chose inconfig.yml
) - SSH User:
vagrant
- SSH Key: (browse to your
~/.vagrant.d/
folder and chooseinsecure_private_key
)
- MySQL Host:
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:
-
xhprof directory:
/usr/share/php
-
XHProf URL:
http://local.xhprof.com/
(assuming you have this set inapache_vhosts
in config.yml)
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
- To shut down the virtual machine, enter
vagrant halt
in the Terminal in the same folder that has theVagrantfile
. To destroy it completely (if you want to save a little disk space, or want to rebuild it from scratch withvagrant up
again), type invagrant destroy
. - You can change the installed version of Drupal or drush, or any other configuration options, by editing the variables within
vars/main.yml
. - Find out more about local development with Vagrant + VirtualBox + Ansible in this presentation: Local Development Environments - Vagrant, VirtualBox and Ansible.
- Learn about how Ansible can accelerate your ability to innovate and manage your infrastructure by reading Ansible for DevOps.
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.