Last updated 14 April 2015. Created on 1 August 2013.
Edited by therobyouknow, kae76, waako, wusel. Log in to edit this page.

Why would you want this?

A Vagrant configured Virtual Machine setup for your Drupal work provides:

  • Match your real go-live production environment (as opposed to a MAMP setup or putting a LAMP stack directly on your machine means your site is dependent on that environment)
  • Repeatability and consistency: can re-run your scripts to setup the VM if you need to, you can share your setup with others

More detail on these at end of doc - see "Background"

Don't get put off by the length of instructions!

A bit long aren't they?! TL;DR and all that!

NOTE: Most of the stuff is a one-off setup. Hang in there! Keep going! After that it's much less and it will pay off - see "Why would you want this?" Contact me if you need advice - post a comment - help me write a better guide :)

Revision History

revision history is here


credits (so far): on twitter @kaelle76 (d.o. kae76) where I saw on their timeline passed on from @rupertjabelman @a_c_m - credit to them as well. Also @blowski for some suggestions about overcoming permissions conflicts between the VM and its host, using samba. I will do my best to credit everyone involved, I believe that this guide has also been repositioned in the Guide -thanks to those who did that. Also Mitchell Hashimoto for Vagrant and Will try keep this up to date...

Checklist overview

The structure of this guide is 2 parts ~ 1: a quick checklist overview for quick reference, followed by detail on each of the steps

1. prerequisites: Oracle VirtualBox ( - 4.2.12 works well), Vagrant installed ( - working version 1.2.2 works). *Why older versions?* - answer because some later versions may be unstable or have regression introduced to them. Platform tested on: Mac OS
2. get .zipped "manifest" from .zip file from wheezy64. set mysql root password (create any databases you need here, note settings leave everything else alone)
3. unzip the zip file to place on your host machine where you want it, we call this your vagrant host folder
4. in Vagrantfile of the unzipped folder: config.vm.synced_folder "./", "/var/www", id: "vagrant-root", :extra => "dmode=777,fmode=666"
5. in terminal / command line window cd to the folder containing the unzipped vagrant files
6. run Vagrant: vagrant up
7. be patient while things are setup and downloaded - could take 30mins first time around if downloading the box file
8. when finished open another terminal window, ssh into the VM
9. in the VM, enabled the root user
10. in the VM, as root user, if not created databases (in 2) or want to add more later do this now
11. Download drupal to a folder in the web server root (/var/www/)
12. Kick off the Drupal install
12b NOTE: Apache directive AllowOverride All needed

Optional - if you want debugging with Komodo IDE 8:

1-12 In Detail:

1. Pre-requisites

  • Tested on Mac OS X 10.8.4 - would it expect it to work on other versions and platforms (Linux, Windows -with adjustments)
  • Oracle Virtual Box 4.2.12 (regression was introduced in 4.2.14 that stopped Vagrant working)
  • Vagrant 1.2 or greater
  • Configurator from

2. Create your Vagrant and Manifest file:

// Reason: I tried Precise and got fatal errors so sticking with Wheezy for now, haven't tried the others yet

Databases in the Configurator:

  • must do this:
  • set the MySQL Root Password

// Reason: "MySQL will only be installed when a password is entered here."
// I just use 'root' as the password

  • Create Database

// You'll need this before running the Drupal install

I suggest two options:

  • Option 1: Create databases users and passwords in PuPHPet - see the section in the Configurator on
  • Option 2: Leave as is and create them in the VM (see steps later)

// Note down the IP address of the machine ( you will need this for ssh later )

  • Then click "Create My Manifest" button at the bottom

// Leave everything else alone and click 'create manifest' button to download the generated .zip file with your Vagrant config

// Note just for info:
php5-mysql is automatically installed, not an option for wheezy64 - I observed that makes it mandatory.

3. unzipped the zip file to place on your host machine

Where you want it - e.g. for me I put mine here: /Users/robdaviswork/work/projects/vagrant/wheezy64
this is your vagrant host folder

4. In the Vagrant file in your vagrant host folder

Important adjustment:
config.vm.synced_folder "./", "/var/www", id: "vagrant-root"

config.vm.synced_folder "./", "/var/www", id: "vagrant-root", :extra => "dmode=777,fmode=666"


Reason (and notes):
- drupal install fails with permissions issues - the installer was not able write to files without this adjustment
- background: around the internet there are some folks also having issues around this so it looks like a fairly common issue (may be a bug with vagrant, virtual box, or just that we need a better way to configure sharing between host and guest than this)
- even with this fix, chmod is ignored on the guest vm but the files are fully writeable on the guest so the install of drupal passes
- ultimately, it would be my preference to not use this approach but rather instead use samba (credit: @blowski) so will be looking to work out how to configure samba in vagrant (one of the key things I need to learn is how to automate in vagrant the appending of config statements onto existing files)

5. have a terminal window ready on your host, cd to your host vagrant folder

6. then issue command: vagrant up

7. be patient while things are setup and downloaded - could take 30mins first time around if downloading the box file

8. when vagrant finished (successfully)...

To log into the VM:

ssh vagrant@ip
password: vagrant

where ip address is the one shown in the configurator page
example for:

ssh vagrant@
password: vagrant

9.Unlock (enabling) the root account:

You'll probably want to be the root user at some point

vagrant@lucid32:~$ sudo passwd -u root
passwd: password expiry information changed.

Then change the root password:

vagrant@lucid32:~$ sudo passwd root
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully

(thought: would like to include this in the vagrant automation)

10. Adding more databases in the VM

This can be done in the standard Linux/MySQL way, at the command line for example.
If you are creating many VMs using Vagrant (including from manifests from you may want to consider adding creation of these from Vagrant to save manual effort, after all, that is what Vagrant is for. And for example will do the work for you by generating the necessary stuff in the vagrant files.

Anyway, here's a standard way to create databases at the command line

Note: (I think) you'll need to have enabled the root user and know the password to do this - see previous steps

mysqladmin -u root -p create drupal
(enter password)

mysql -u root -p
(enter password)


GRANT ALL PRIVILEGES ON drupal.* TO drupaldbuser@localhost IDENTIFIED BY 'fuffy';

For your particular case, in the example above, replace:
- drupaldbuser with the name that you would like for the MySQL database user that Drupal will use to access the database
- fuffy with the password you want for this user
- drupal with the name of the database you want drupal to use


my setup for a drupal8 setup:

(logged in as root)

mysqladmin -u root -p create drupal8

password: root

mysql -u root -p

then when asked for password, enter:


then when in mysql > prompt, enter:

GRANT ALL PRIVILEGES ON drupal8.* TO drupal8@localhost IDENTIFIED BY 'drupal8';

Note all of the above for when you run the drupal installer


11. Getting Drupal on the system

Multiple site development

It's a good point to touch upon approaches to multi-site development. For Drupal (and other technologies) there are several approaches:

  • separate VMs for each site
    • benefits: if your sites have various complex backends, e.g. interfacing with other technologies. By defining separate VMs means that only the necessary goes into the Vagrant scripts and config of the VM
    • disadvantage: resource heavy, more configs to manage, but it can be done with suitable way of working, use of git etc.
  • separate folders (in website root) and databases on one VM
    • benefits: compartmentalise each website on the VM, share the same general config of the VM - savings in time for setup
    • disadvantage: sites coupled to the general config of the VM, any thing exotic or special required for a site might need reconfig of the VM (risk of breaking the other sites)
  • (for Drupal) use the sites folder and manage multiple sites there
    • benefits: as with separate folders savings because sites share same config
    • disadvantages: even further coupling - with the common drupal install (for example couldn't mix and match different versions of drupal). But again, can be managed, with git (and using .gitignore) to only versioncontrol the specifics of each site
some options for setting up Drupal:
  • download drupal7 .zip file from
  • drush (section to be written for this guide - I use drush a lot, and would need to do a write up here, regarding install)
  • drupal8: git clone
For getting Drupal 8 on the system
  • log into the guest vm (as root - see step)
  • git is already installed on this guest vm (as it was either already part of wheezy64 or the vagrant files installed it)
  • cd to the web server root path - i.e.:-
    cd /var/www
  • get drupal8
    git clone drupal8

    (the drupal 8 bit at the end is optional - if left off you will get this stuff in a folder just called drupal. I prefer to name the folder with the version so I know what I am working on, not essential though, just a way of working)

    (credit/reference: )

12. Run the Drupal install

- e.g. kick it off via the web:

12b NOTE:

Apache directive AllowOverride All needed to ensure clean-urls work for Drupal (and perhaps indeed other frameworks) - full exact details as to what to do here: ttps://

Looking for support? Visit the forums, or join #drupal-support in IRC.


kae76’s picture

I'm glad the PuPHPet link was so well received!
As of yet I've not played with it - was glad to be pointed to it by the #drupal-uk crowd much appreciated!

I'm hoping to have a play at the weekend, because I'm a fuss-pot I'm going to copy paste this into a repo & apply some markdown... (I need me some mark down) hope you don't mind, will share back with you obv.

Cheers o/

therobyouknow’s picture

That would be great, kae76, thank you, will make it more readable. It's plain text with minimal formatting so not as friendly as it should be - and that is certainly the intention to make it readable. So, thank you! Please also feel free to follow up on any errors. I went through the steps twice, successful both times, but open to knowing about any gotchas.

By the way, you will need to edit your Apache directive to Allow Override All as I found that Clean-URLs were broken with this "out-of-the-box" - exact instructions as to what to do are here - I've written up:

I'm going to update the doc too, in a moment.

therobyouknow’s picture

Thanks for the formatting - I like the style. Most appreciated!

As promised, soon, I should be looking at writing instructions for syncing one's work done Drupal on this VM to a production server (for setups that include shared hosting, full server or whatever), using drush (sql-sync) etc and sync and setting up ssh keys. So that we have a nice end-to-end complete workflow setup.

Luukyb’s picture

synced_folder used to accept :extra, this is now mount_options. The parameter should be an array as well. So :
config.vm.synced_folder "./", "/var/www", id: "vagrant-root", :extra => "dmode=777,fmode=666"
Becomes :
config.vm.synced_folder "./", "/var/www", id: "vagrant-root", :mount_options => ["dmode=777","fmode=666"]

alex.designworks’s picture

Good news!

All mentioned above and other goodies in one place.

This is a Vagrant configuration to provision LAMP stack with tools required for Dupal development.

Provisions full stack virtual machine and installs Drupal 7 and Drupal 8 using only 1 command - vagrant up.

What's in the box?

  • Ubuntu Precise x64
  • git, vim, curl
  • Apache 2
  • PHP 5.4
  • MySQL
  • Composer
  • XDebug
  • APC
  • Memcache
  • Mail catcher
  • Drupal 7
  • Drupal 8

Software Engineer | Integrated Experts |