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

credits (so far): on twitter @kaelle76 (d.o. kae76) where I saw puphpet.com 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 puphpet.com. 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 (virtualbox.org - 4.2.12 works well), Vagrant installed (vagrantup.com - 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 puphpet.com 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:
https://www.drupal.org/node/2183375

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 puphpet.com

2. Create your Vagrant and Manifest file:

• Go to puphpet.com
• choose Debian Wheezy 7.0rc1 x64

// 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 puphpet.com
• 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:
PHP
php5-mysql is automatically installed, not an option for wheezy64 - I observed that puphpet.com 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"

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

credit: http://serverfault.com/questions/398414/vagrant-set-default-share-permis...

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 puphpet.com configurator page
example for: 192.168.56.101

ssh vagrant@192.168.56.101
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 puphpet.com) 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 puphpet.com 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)

Example:

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

e.g.

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:

root

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

(credit: https://drupal.org/node/22675)

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 drupal.org
• 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 http://git.drupal.org/project/drupal.git 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: http://drupalladder.org/lesson/027b5839-7a74-af04-6905-fee2d01c7ef4 )

12. Run the Drupal install

- e.g. kick it off via the web: http://192.168.56.101/drupal8/

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://drupal.org/node/735500#comment-7712261