Vagrant allows developers to build, manage and share virtual development environments. Vagrant uses VirtualBox for its virtual machines and you can use Puppet or Chef as a provisioning tool. The goal of Vagrant is to offer developers the ability to build and work in a consistent virtualized environment without wasting time setting up a local version of Apache, PHP and MySQL.
In this tutorial, we’ll look at how to setup and run a Vagrant environment using the Vagrant Drupal project. Even though, the Vagrant project is hosted on drupal.org it is not a module. It is a combination of Chef cookbooks and a Vagrantfile.
Before you begin, make sure you have installed Vagrant. Installation is very easy just go to the download page and download the latest version. Vagrant uses VirtualBox for its virtual machines. If you haven’t already, download and install VirtualBox.
Go to Vagrant project page on drupal.org and download the zip or tar file and extract it somewhere onto your filesystem (Example:
As stated earlier, what you download from the Vagrant project on drupal.org is not a module, it’s a “Vagrant” project. All the vagrant commands in this tutorial will need to be run from within the vagrant project that you just downloaded and extracted.
1. First, we have to download a Vagrant box. Run the following command from your terminal.
$ vagrant box add base http://files.vagrantup.com/lucid32.box
2. Go to the Vagrant project that you just downloaded and create a
$ cd [vagrant project] $ mkdir public
If you don’t create a
public directory, you will get the following error:
There was a problem with the configuration of Vagrant. The error message(s) are printed below: vm: * Shared folder host path for 'public' doesn't exist: ./public
3. We have to make one change to the Vagrantfile which gives user
www-data access to the Vagrant shared folder. I couldn’t install Drupal without giving the user (
www-data) access to the
public directory (Issue #1364008).
The Vagrantfile is used to configure Vagrant on a per-project bases. The file can be located in the root directory of any Vagrant project.
Open up the Vagrantfile and replace:
config.vm.share_folder("v-root", "/vagrant", ".")
config.vm.share_folder("public", "/vagrant/public", "./public", :owner => "www-data", :group => "www-data")
4. Finally, add the line below to your host file.
22.214.171.124 drupal.vbox.local dev-site.vbox.local
5. Now it’s time to boot up our virtual machine. Using Terminal go to the Vagrant project and run
$ cd [vagrant project] $ vagrant up
The build process will take between 2 to 5 minutes.
Default Test Site
Vagrant creates a default site at
drupal.vbox.local. We’ll use this site to test that everything is working. Go directly to http://drupal.vbox.local/install.php and install the default Drupal site. If you go to http://drupal.vbox.local before you install the site, you will get database errors. The Drupal code for the
drupal.vbox.local site can be found in the
public folder. VirtualBox allows you to share folders between host and guest OS. Within the virtual machine, the
public folder is
You can access phpMyAdmin by going to http://drupal.vbox.local/phpmyadmin/. Login with
myadmin for the username and
myadmin for the password.
Configure Default Development Site
The Vagrantfile defines two websites,
dev-site.vbox.local. As stated earlier the
drupal.vbox.local site has already been setup. However, the
dev-site.vbox.local site has not been fully setup. The only configuration that has been created is the Apache vhost, and that’s it. To setup the
dev-site.vbox.local site, all we need to do is place a copy of Drupal into
./public/dev-site.vbox.local/www and create a database using phpMyAdmin.
You may need to restart Apache, once you have created the
dev-site.vbox.local/www folder. All we need to do is SSH into the virtual machine and restart Apache.
1. SSH into the virtual machine by running the
vagrant ssh command.
$ cd [vagrant project] $ vagrant ssh
2. Restart Apache by running the
$ sudo service apache2 restart command.
Adding New Sites
Right now we have two sites setup, a default Drupal and development site. Both of these sites were already defined in the Vagrantfile. As developers, we tend to work with a lot more than two websites at any one time. Let’s now setup another site using the
126.96.36.199 d7-dev.vbox.local to your hosts file.
2. Open the Vagrantfile file and add
d7-dev.vbox.local to the
:localhost_aliases => ["drupal.vbox.local", "dev-site.vbox.local", "d7-dev.vbox.local"]
3. Restart the virtual machine so that the
d7-dev.vbox.local site will get created. First, we must shutdown the virtual machine using
vagrant halt and then boot it back up with
$ cd [vagrant project] $ vagrant halt $ vagrant up
4. SSH into the virtual machine (
vagrant ssh) and download a copy of Drupal into
/vagrant/public/d7-dev.vbox.local/www. You will have to create a
5. Once you have downloaded a copy of Drupal, go to http://d7-dev.vbox.local and install the site.
In this tutorial, we have used a few Vagrant commands. In this section, we’ll go through some of the common commands you’ll need to know.
vagrant up: This is the main command that boots or builds a virtual machine.
$ cd [vagrant project] $ vagrant up [default] Importing base box 'base'... ...
vagrant halt: This command will shutdown the virtual machine and when you boot it back up you won’t lose any data.
$ cd [vagrant project] $ vagrant halt [default] Attempting graceful shutdown of VM...
vagrant ssh: This command will simply login you into the virtual machine via SSH.
$ cd [vagrant project] $ vagrant ssh Linux lucid32 2.6.32-38-generic #83-Ubuntu SMP Wed Jan 4 11:13:04 UTC 2012 i686 GNU/Linux Ubuntu 10.04.4 LTS Welcome to Ubuntu! * Documentation: https://help.ubuntu.com/ New release 'precise' available. Run 'do-release-upgrade' to upgrade to it. Welcome to your Vagrant-built virtual machine. Last login: Fri Sep 14 07:26:29 2012 from 10.0.2.2 vagrant@lucid32:~$
vagrant destroy: This command will delete the virtual machine and any file and database stored within the virtual machine. Only use this command if you’re certain you want to start from scratch.
$ cd [vagrant project] $ vagrant destroy Are you sure you want to destroy the 'default' VM? [Y/N]
vagrant status: This command will give you the current state of a virtual machine. Use this command if you want to know if a virtual machine is running or shutdown.
$ cd [vagrant project] $ vagrant status Current VM states: default poweroff The VM is powered off. To restart the VM, simply run `vagrant up`
If a virtual machine is running, then you should see the message below:
Current VM states: default running The VM is running. To stop this VM, you can run `vagrant halt` to shut it down forcefully, or you can run `vagrant suspend` to simply suspend the virtual machine. In either case, to restart it again, simply run `vagrant up`.
If you have any questions, please leave a comment.