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.
Getting Started
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.
Build Environment
Go to Vagrant project page on drupal.org and download the zip or tar file and extract it somewhere onto your filesystem (Example: ~/Documents/vagrant/vagrant-7.x/).
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.
Steps
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 public directory.
$ 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", ".")
With:
config.vm.share_folder("public", "/vagrant/public", "./public", :owner => "www-data", :group => "www-data")
4. Finally, add the line below to your host file.
33.33.33.10 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 vagrant up.
$ 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 /vagrant/public.
phpMyAdmin
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, drupal.vbox.local and 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 d7-dev.vbox.local alias.
Steps
1. Add 33.33.33.10 d7-dev.vbox.local to your hosts file.
2. Open the Vagrantfile file and add d7-dev.vbox.local to the :localhost_aliases array.
: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 vagrant up.
$ 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 d7-dev.vbox.local folder.
5. Once you have downloaded a copy of Drupal, go to http://d7-dev.vbox.local and install the site.
Vagrant Commands
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
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
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
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
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
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.
Hi Ivan,
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 again!
Johanna
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 33.33.33.10, 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.
Sequel Pro
Go to the SSH connection.
MySQL host: 127.0.0.1
Username: myadmin
Password: myadmin
SSH Host: localhost
SSH User: vagrant
SSH Password:vagrant
SSH Port: 2222
How to connect to Transmit
Go to “Connect to SFTP Server”
Server: localhost
User Name: vagrant
Password: vagrant
port: 2222
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.
Thanks
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)
Hey Man,
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.
https://github.com/cyberswat/drupal-lamp
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.