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.
If you want to find out more about Vagrant, check out its documentation pages.
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.
Installation instructions for Vagrant and VirtualBox are beyond the scope of this tutorial. However, both are fairly easy to setup check out the Vagrant “Getting Started” page for details.
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.
19 thoughts on “Getting Started With Drupal Vagrant”
First, thanks much for this tutorial. Following it, I was able to get the two sites in the Drupal project up and running. I’m a total newbie to Vagrant. What I want to do is clone an existing repo, import the db, and work on my client sites on this Vagrant box.
I’m guessing the steps to setting up a local instance of an existing site are similar to the steps outlined in “Adding New Sites”, and then I could use PHP MyAdmin to set up the db, but do you have any other tips or hints for using Git and/or Drush to set up existing sites in Vagrant?
Thanks for the kind words.
In regards to cloning a site, you are correct. Follow the steps in the “Adding New Sites” section. Vagrant will setup the apache vhosts and set a document root folder. All you have to do is copy your existing into site into the right /public folder and setup the settings.php to point to the database. Also, use phpMyAdmin to create a database table.
If your site is stored in GIT, then clone a copy of it into the /public folder like you would normally do.
Hope this helps.
Wow. That is really excellent. Thanks again.
I’m having some permissions issues. I set up an SSH key with GitHub on my Vagrant box. It won’t let me clone into a new directory. I *think* it has to do with the fact that www-data is owner as per the Vagrantfile. I am going to try and file an issue with the Drupal Vagrant project about this, and hopefully there’s a miracle cure. If not, then I’ve got server-y peeps I can ask.
I filed an issue here: http://drupal.org/node/1914530
Instead of cloning a git repo within the virtual machine. Clone the repository from the host operating system (main operating system that run virtual box).
I thought of that and just wasn’t sure if there was a different recommended practice. But that does make the most sense. Thanks yet again. I will cross-post this in the issue so that others can find the documentation.
I’m a little confused as to setting up a multisite, the root will be /vagrant/public/drupal/docroot then the Drupal 7 files. I have 2 sites i.e http://www.local.example.com and http://www.local.example2.com and every thing is setup correctly the Drupal end as I’ve been using MAMP but I want to switch to Vagrant. The folder structure has to be this way as its a repository. Any advice would be appreciated.
Hi Ivan, it’s Ivan 🙂 (I don’t get to say that very often) Thanks for this great and very useful write-up!
Can you say more about how you would connect to the virtual host with GUI programs like Transmit (Panic SFTP app) or Sequel Pro (SQL app)?
I’ve read a bunch of tutorials that sort of vaguely mention things like this but nothing I try seems to work. Some said just connecting to servername=vagrant should work, but it doesn’t seem to. I also tried connecting to localhost and 188.8.131.52, and tried all three of those options with and without port 2222 specified.
I can login just fine using vagrant ssh on the command line, but I’m not sure how to tell these programs to do something equivalent. Any experience in that? I used phpMyAdmin for years but have recently become acquainted with Sequel Pro and kind of dread the idea of having to go back…
I have used Sequel Pro to connect to MySQL
To test that everything is working, try to SSH manually “ssh vagrant@localhost -p 2222” and use vagrant as the password.
Go to the SSH connection.
MySQL host: 127.0.0.1
SSH Host: localhost
SSH User: vagrant
SSH Port: 2222
How to connect to Transmit
Go to “Connect to SFTP Server”
User Name: vagrant
Hope this helps.
Ivan, thanks for this Drupal-specific tutorial on using Vagrant for server building automation. I particularly found useful the information about vagrant ssh (which I didn’t know existed – handy, save me having to use another ssh tool for some situations) and also the www-data user steps – permissions can be problematic so this is a useful tip. Your article will be added to my pinboard.in book marks! I see that you have some other articles that might be of use to me too – such as your EntittyForms one. Thank you. Myself, I have written Vagrant setup steps for those who have a Windows machine and who want to run a LAMP stack in a Virtual box: http://stackoverflow.com/questions/14608875/getting-a-lamp-stack-running-on-a-vagrant-vm-under-windows-7-host-full-instru
Dont worry got there in the end – updated the drupal_apps.rb file.
That’s good to hear.
I would like to add this resource to this excellent article. To find different vagrant boxes available (if you don’t want to spin up your own) visit this resource: http://www.vagrantbox.es
Multiple OS boxes and preconfigured setups.
Thanks for the link.
Does this allow developers to share each other’s work even though each works in their respective virtual box? For example, if I created a page in my local can other developers get to my page in their local environment?
No, Vagrant does not work like that. It’s used to share server configuration using a virtual environment.
If you want to share Drupal specific configuration, then look at using Features. (https://drupal.org/project/features)
Good Article, there is a vagrant drupal stack that allows for the creation, downloading, installation, etc to be fired on a vagrant up/provision etc.
Try it out and see what you think
Thanks for the tip.
Under the “Adding New Sites” section, the “d7-dev.vbox.local” vhost wasn’t getting created for me initially. After running “vagrant provision” the vhost gets created though.