Introduction to Vagrant

Virtualization allows multiple operating systems to simultaneously share processor resources in a safe and efficient manner. One tool we can use to create a virtual environment is Vagrant. By the end of this video, you will be able to describe the advantages, and disadvantages for creating a local development environment with Vagrant, and you should be able to answer the following questions:

• Do you want to proceed with Vagrant?
• Does it sound like it will solve your problems? [yes | no]
• Do you have the necessary hardware to proceed with the lessons? Or should you stick with WAMP/MAMP?

Note: Another common tool for creating development environments today is Docker, which is becoming very popular with Drupal (and other) developers. Take a look at our Drupal Development with Docker series to learn more.

Additional resources

Vagrant

Note: This video is outdated. The following command:

$ vagrant init precise32 http://files.vagrantup.com/precise32.box

...now has download problems if you try it. Try this instead:

$ vagrant init hashicorp/precise64

(The written instructions below contain this update.)

Before we jump into the automation of creating a new developer environment, we need to get the building blocks we'll be working with. You will need to download and install both Vagrant and VirtualBox.

Lesson Outcomes

By the end of this lesson, you will be able to install Vagrant and VirtualBox on a host platform of OSX, or Windows; and create and destroy a Vagrant instance.

Lesson Summary

1. Install VirtualBox
2. Install Vagrant
3. Create a new directory for your configuration scripts. e.g. Websites, or Work-environments. This folder will not contain the VirtualBox binary files, just the Vagrant configuration scripts.
4. From the command line, run the following commands:
   • $ vagrant init hashicorp/precise64
   • $ vagrant up
   • $ vagrant ssh
     Note: this command will not work for Windows. You will need to use PuTTY to log into your machine. This is covered in the bonus lesson.
5. To return to your host machine, run the command:
   • $ exit
6. To destroy the VM and remove the binary disk image:
   • $ vagrant destroy
     This command must be run from the directory which contains the Vagrantfile for the box you wish to destroy. It will not remove any of your configuration files. To recreate the machine, use the commands in step 4.

Troubleshooting and Gotchas

• The lessons were recorded using Vagrant 1.4.3, and VirtualBox 4.3.6.
• There are some gotchas to be aware of: Linux and Windows may need a reboot because of the kernel drivers being added.
• Sometimes upgrades don't work, and re-installing is your best bet. If you have automatic software updates turned on, and Vagrant stops working for you without an obvious reason, try removing everything and re-install using the instructions in this lesson. Removing Vagrant and VirtualBox are covered in one of the extra lessons.

Additional resources

VirtualBox Downloads
Vagrant Downloads

Note: another common tool for creating development environments today is Docker, which is becoming very popular with Drupal (and other) developers. Take a look at our Drupal Development with Docker series to learn more.

In this lesson you will learn how to install a Web server on your virtual machine. Ultimately we will use a provisioning script to automate this task, but this lesson shows you the virtual machine is just like any other server you might have worked with in the past. Any time you want to add new software, you can always come back to this lesson if you (for some reason) don't want to create a recipe and re-provision your machine. Hopefully, though, by the end of this series you'll see why provisioning is a more robust solution than installing software directly.

Lesson Outcomes

By the end of this lesson, you will be able to log into your virtual machine, and use the command line to install new software.

Lesson Summary

1. Navigate to www.vagrantbox.es.
2. Locate a base box you would like to use. Ensure you are matching the "provider" to what you have. e.g. VirtualBox for these lessons (not VMware).
3. At the command lines, initialize your new server:
   • $ vagrant init <box name> <box URL>
     • box name: ringtail64
     • box URL (mind the line wrap): http://cloud-images.ubuntu.com/vagrant/precise/current/precise-server-cloudimg-amd64-vagrant-disk1.box
   • $ vagrant up

Ensure your server is up and running, and then log in with the command: vagrant ssh. This command must be issued from within the directory which contains the file Vagrantfile.

Install an AMP server using the directions for your base box. We'll use the same technique as is covered in the lesson Installing a Web Server on Ubuntu.

• $ sudo apt-get install tasksel
• $ sudo tasksel install lamp-server

This will install Apache, MySQL, and PHP.

To confirm the server is running, use the command: pstree.

Troubleshooting and Gotchas

• OSX can use vagrant ssh; Windows will need to install PuTTY and use ssh vagrant. Using PuTTY is covered in the bonus lesson for this series.
• If you get the error tasksel: aptitude failed (100), run the following commands:
  1. $ sudo apt-get update
  2. $ sudo tasksel install lamp-server 
     (I got this error on a precise32 base box with a Windows 8 host running inside of Parallels on a Mac OSX machine.)

In order to "find" our virtual server in a Web browser, we need to make a map between the two host machine, and your guest server. To do this we will use a technique referred to as port forwarding. This allows any communication from the host machine (your Web browser) to be automatically redirected to the appropriate location on your guest machine (the Web server). Fortunately this is very simple to do. In this lesson we are going to map port 4567 traffic on the host machine, onto the standard Web port, 80, on the server. This means when you access Web traffic at http://localhost:4567, it will be automatically redirected to Apache on your server. It's almost like a sleight of hand magic trick where a rabbit appears in a hat, but way cooler.

Lesson Outcomes

By the end of this lesson you will be able to correctly configure your server's network settings so that Web pages can be viewed in a browser on your host machine.

Lesson Summary

1. Edit your Vagrantfile (Vagrant configuration file to set the following properties:
2. Configure port forwarding
   config.vm.network "forwarded_port", guest: 80, host: 4567
3. Reload the vagrant instance.
   $ vagrant reload
4. Log into the server, confirm Apache is running. (Hint: it's not running.)
   $ curl 'http://localhost:80'
5. Start Apache.
   $ /etc/init.d/apache2 start
6. In a Web browser, navigate to:
   http://127.0.0.1:4567
   (Hopefully) It works!

Gotchas

This can sometimes be the tricky bit, especially if you already have a lot of custom network configuration. If this lesson doesn't work for you, you will need to do an audit of your system to find any software which might be interfering with the connection. We're going to limit ourselves to one VM running at a time (all the same ports). This is mostly because of the hardware limitations I expect you'll have. If your machine is more powerful, great! But we're not covering it in this video series.

Typically when we work with a Web server, we edit our files locally, and then "push" them up to our Web server (perhaps using SCP, rsync, Git push, or maybe even FTP). The same will be true with our Vagrant server: you need a way to get files from your host machine, to the guest server. You could either use SCP, but we will enable file sharing to make life a lot easier. With file sharing enabled you will be able to drap-and-drop files into specific directories within your Vagrant instance using your local file manager (e.g. Finder or Windows Explorer). The files will be immediately shared, and recognized by your server, allowing you to continue working on the files with your favorite IDEs and code editing tools without the upload step. Technically, enabling file sharing isn't necessary, but I think you'll agree it is a lot more convenient than SCPing files to your guest server.

Lesson Outcomes

By the end of this lesson you will be able to share files between your host and guest machines without the use of SCP. After enabling file sharing, you should be able to copy a file into the shared folder in your Vagrantfile and have it automatically appear inside the Vagrant instance. e.g. you can load a static web page created on your local machine without having to use SCP.

Lesson Summary

As long as you're using basic file sharing (no NFS), it should work "out of the box" for Windows 8, and OSX.

1. Configure synced folder in Vagrantfile.

• Locate and remove: # config.vm.synced_folder "../data", "/vagrant_data"
• In its place, add: config.vm.synced_folder "docroot", "/var/www"

2. Create a new directory using the name identified in the file Vagrantfile.

• $ mkdir docroot

3. Reload the vagrant instance (and restart the server). The contents of /var/www will appear in docroot.

• $ vagrant reload
• $ vagrant ssh
• $ sudo /etc/init.d/apache start
• $ exit

4. Edit the Web page from the host machine.
5. Refresh the browser to see the changed file.

Gotchas

This lesson was recorded using VirtualBox 4.3.6 and Vagrant 1.4.3. There is a known issue for file sharing with VirtualBox 4.3.10. If you get the following error message: "Failed to mount folders in Linux guest. This is usually because the "vboxsf" file system is not available." you have encountered this bug. Consider downgrading VirtualBox to 4.3.8, or follow the troubleshooting tips in the issue queue for your particular host machine.

If you are having problems with file permissions / ownership, try editing the permisisons from the host machine, not the guest machine. This is most noticeable when you are creating a new Drupal instance and there are folders / files created automatically by the system. Vagrant won't give a warning to explain why it won't change permissions, it simply doesn't show any changes after running chommands such as: chmod +w <directory_name>.

If you are still having problems with silent file permissions, update your Vagrantfile as follows:

1. Locate the setting for config.vm.synced_folder
2. Add a server-friendly owner, by adding the following to the end: , :owner => "www-data"
3. Add a server-friendly group, by adding the following to the end: , :group => "www-data"

If you're STILL having problems, update your Vagrantfile to give more permissive defaults.

1. Locate the setting for config.vm.synced_folder and add the following to the end: , :mount_options => ['dmode=775', 'fmode=664']
2. The final line should be something like this (all one line): config.vm.synced_folder "docroot", "/var/www", :owner => "www-data", :group => "www-data", :mount_options => ['dmode=775', 'fmode=664']

Configuring new servers by hand is tedious and prone to error. Instead of running all the installationa commands by hand to customize our Vagrant setup, we'll use a configuration management (CM) tool to automate this process for us. CM allows system administrators to establish rules which maintain the software installed on one or many computer systems. By automating the setup of a server, configuration management ensures there are no inconsistencies between machines. It also makes it faster for your to create a virtual environment without having to manually install a Web server, like we did in a previous lesson.

Lesson Outcomes

By the end of this lesson, you will be able to explain how configuration management relates to virtual machines, and why you would want to use a configuration management tool to provision new virtual machines.

Lesson Summary

• Vagrant is a wrapper which creates virtual development environments from base boxes. It acts as a wrapper around a provider, such as VirtualBox, and configuration management software, such as Chef.
• Configuration Management: Configuration management is a process which allows system administrators to establish and maintain consistency of a computer system throughout its life against a specified set of rules. Configuration management enables consistency across one, or many, machines.
• Popular open source configuration management tools supported by Vagrant include: Puppet, Chef, and Ansible. Chef tends to be popular among Drupal developers. Puppet tends to be popular among system administrators (who are not necessarily Web developers first-and-foremost).
• Provisioning is the process of creating, or altering, a system in order to prepare it for service.
• Vagrant allows you to use one or more configuration management tools from the same Vagrantfile to provision a machine; as well as use shell scripts.

Additional resources

• Configuration Management
• Provisioning
• Comparison of Configuration Management Tools
• Chef Overview
• Chef Cookbooks

In the previous lesson we discussed why you would want to use a configuration management tool. In this lesson we'll dive into how you automate the customization of new servers using the configuration management tool, Chef. Most of the work in assembling Chef recipes is already done for you. In this lesson you will be able to see how the pieces fit together; however, you will not be required to download each of the individual recipes to get everything working.

Lesson Outcomes

By the end of this lesson you will be able to describe how to add a Chef recipe to your setup, and re-provision Vagrant.

Lesson Summary

In the video, I've already setup Chef recipes, roles, and cookbooks for you. So instead of having to download all the pieces separately, you can just start with the code bundle for this lesson.

The outline provided below, however, includes each of the steps that I went through to prepare the configuration Chef recipes and roles that you're downloading.

Locating and Using Chef Cookbooks

1. Locate Chef cookbooks for AMP stack, drush, and Drupal-specific PHP libraries you want pre-loaded.

• http://community.opscode.com/cookbooks/

2. Place downloaded cookbooks into a sub-folder in your project directory. For example: chef-recipes/cookbooks.
3. Create a role file to include all of the recipes (from each of the cookbooks) you want to load. This file can be placed into its own roles sub-directory. For example: chef-recipes/roles/lamp_stack.rb.
4. Update the Vagrantfile to include:

• path to cookbooks folder
• path to roles folder
• role(s) to load for this server
• new values for any of the default settings for your recipes

5. Provision the machine to enable / set-up / trigger the Chef configuration settings:

• $ vagrant provision

The machine is now configured, but does not have Drupal installed. This is on purpose. You probably have a specific Drupal project you're working on.

Customizing Configuration Files to Use Chef Recipes

The role files contain a list of individual recipes, and/or roles that must be run to provision a specific type of server. Generally there are three or four parts to them.

• name
• description
• run list (recipes and roles to add)
• default settings for recipes (optional)

You should investigate the contents of the folder chef-recipes/roles. There is a detailed README tailored to this learning series, as well as the two roles that were created for this lesson.

The Vagrantfile is well commented, this section includes a quick references of the settings that have been updated in the file.

  config.vm.provision :chef_solo do |chef|
     # default settings
     chef.cookbooks_path = "path_to_cookbooks_folder"
     chef.roles_path = "path_to_roles_folder"

     # roles and recipes to load
     # recipes are generally loaded from within roles
     chef.add_role "name_of_role"
     chef.add_recipe "name_of_recipe"

     # overrides for settings in recipes
     chef.json = {
       "name_of_recipe" => {
         "name_of_setting" => "new_value",
       },
     }
  end

Gotchas

• If you are using these recipes for Drupal 8: the recipe provided for Drush won't work. You'll need to install Drush version 7 or greater (compatibility chart on the Drush project page).
• You will probably want to update Chef with the omnibus plugin for Vagrant if the cookbook you want to add requires a newer version of Chef. On the host machine, install the plugin: $ vagrant plugin install vagrant-omnibus. Note: Chef must be updated before it is "run". For this lesson, I opted to use older versions of the cookbooks. 20 hours of my life spent working on upgrades that didn't work. The later scripts provide more flexibility (e.g. install ANY version of Drush, not just 5.8), but they work well enough for our needs.
• Apt will only run if the cache is older than a day. The first time the machine is provisioned, this might be a problem. You can force updating the cache with the following setting in Vagrantfile: chef.json = { "apt" => {"compiletime" => true} }
• If you are running into problems with permissions, refer to the tips in Sharing Files Between Your Guest and Host Machine.
• Windows users will also need to download the following cookbooks, and add them to the directory you have configured for chef.cookbooks_path
• chef-handler
• chef-sugar
• iis
• windows
• xml
• yum
• yum-epel

In previous lessons you learned how to automate the setup of your Vagrant instance. We did not, however, automate the installation of Drupal. This is by design. It gives us the ability to quick create new virtual machines using standard pieces of a LAMP stack before finally installing the specific version of Drupal we want to use. In this lesson you will learn how to install Drupal from the command line using Drush. If you already know how to do this, you should review the Lesson Summary, but you are not required to watch the video as it will be entirely review for you.

Lesson Outcomes

By the end of this lesson you will be able to install Drupal via Drush from within your Vagrant instance.

Lesson Summary

The machine was configured in the previous lesson, but does not have Drupal installed. This is on purpose. You probably have a specific Drupal project you're working on. If you don't, you can use the following instructions to set up a generic instance of Drupal. Note: The Chef recipe we're using supports Drupal 6 and Drupal 7, but not Drupal 8. You'll need to update Drush first if you want to use these instructions to install Drupal 8.

• $ vagrant ssh
• $ cd /var/www/docroot
• $ drush dl drupal
• $ cd drupal-XXX (where XXX is the version number for Drupal you've just downloaded)
• $ drush si standard --db-url=mysql://root:root@localhost/drupal7 --db-su=root --db-su-pw=root --site-name="Drupal on Vagrant"
  (for the lessons, the MySQL database has the username root; and the password root, if you have deviated from these insecure passwords, you will need to update this line to get the site install to work).

Gotchas

This lesson assumes you want to install Drupal 7 using the Chef recipe which was given in the previous lesson. This lesson will not work if you are trying to install Drupal 8 as Drush 6 is not compatible with Drupal 8.

Everyone will use Vagrant a little differently. In this lesson, Emma shares some of her strategies for using Vagrant for her personal developer environment.

Lesson Objectives

By the end of this lesson, you will be able to describe how many Vagrant instances you will use, and why.

Lesson Summary

Emma started with one Vagrant instance per project but found that she switches tasks frequently enough that it was a problem--with only 8G RAM, it's hard to have more than one machine running at a time. Although the shut down + startup procedure only takes about five minutes, but it's still dead time. This is especially true as the shut down/start up time doesn't include pulling a fresh copy of the Git repository and updating the database. Emma recommends: grouping your projects with similar requirements into the same Vagrant instance IF you are limited by hardware resources AND you need to switch tasks frequently. Then, as needed, create new vagrant instances if you can justify the split. For example: if you need two different versions of PHP or two different servers (nginx vs. Apache).

Additional resources

• Drupal Deploy Cookbook

You can typically upgrade your Vagrant and VirtualBox installations without any problems. Occassionally you will run into problems though. If this does happen to you, you will want to remove all Vagrant and VirtualBox software, and then re-install it. Assuming you are using Configuration Management to provision your machines, the only thing you'll lose is your database.

Lesson Summary

You will need to delete files and applications as follows for OSX:

• /Applications/VirtualBox.app
• /Applications/Vagrant.app
• /usr/bin/vagrant
• ~/.vagrant.d
• ~/VirtualBox VMs

Lesson Outcomes

By the end of this lesson, you will be able to remove relevant Vagrant from your system to prepare yourself for a clean installation.

Additional resources

Uninstalling Vagrant

Due to path issues, vagrant ssh doesn't work on Windows. Although you can update some files to fix this, running PuTTY is slightly more accessible (and has a GUI configuration screen to fill in). In this lesson we cover how to install and use PuTTY to log into your virtual machine. Note: You can use PuTTY from any Windows machine into any Linux server.

Lesson Objectives

By the end of this lesson you will be able to SSH into a remote machine using PuTTY.

Additional resources

Download PuTTY