Creating a site using Vagrant

Before you begin this workflow, you should have completed configuring your environment. The below steps assume you have successfully completed the steps appropriate for your machine. You will also need a VPN account if you are attempting to perform this work off-campus.

Vagrant is a tool which allows us to specify the configuration of a Virtual Machine, using various configuration management tools. Our Vagrant configuration specifies a CentOS 6.3 machine that is configured in a similar fashion to the actual server environment that new code will be deployed to, with a few exceptions.

In general, we expect developers to build and test their code using a Vagrant version of uoWeb. We recommend that they update their build at the start of each sprint.

Basic Instructions

These instructions are aimed at getting you started quickly, with little in the way of configuration options. Additional options are described below.

  1. Make sure you are connected to the University's VPN network, if you are off-campus or using a wireless connection.
  2. Start by opening up your Terminal / Cygwin, and execute the following commands: cd ~/sites git clone ./first_site cd first_site/vagrant # You may need to sudo this command. # This process takes a very long time (over 30 minutes in some cases). Please be patient. # If the process stalls, you can follow the instructions below to restart it. vagrant up # You may also need to sudo this command. vagrant rsync-back # If you had to sudo your vagrant commands, first run this command to learn your # username and groupname. It should look like this: # drwxr-xr-x 40 username groupname 4096 Dec 16 10:36 . ls -al ~ # Then you can set the ownership of the files to the correct username and group, so # that you can edit them in NetBeans: chown -R username:groupname ~/sites/first_site/webcms
  3. Edit your host file, and add the following line: webcms.local
  4. Turn off your VPN connection, if you are off-campus or using the wireless. VPN interferes with the proper functioning of the virtual network.
  5. Open http://webcms.local in your browser. You should see a blank, Corporate-themed site.
  6. Create a new PHP project from existing sources in NetBeans, and direct it to the ~/sites/first_site/webcms directory.

Helpful Commands

Seeing your changes

For performance reasons, we use rsync to share the directories between your host machine and the VM. In order to make your code changes appear on the site, you will need to run vagrant rsync from the vagrant directory. You may also need to run the drush cc all command to clear the Drupal cache sometimes, especially if you add or modify a hook.

Stopping and restarting the VM

If you need to temporarily turn off the VM, you can do it with vagrant halt from your vagrant directory. vagrant up will bring it back online.

Accessing the machine using SSH

If you want to run commands directly on the machine, you can run vagrant ssh from the vagrant directory.

Restarting a failed build

If the build stalls or fails for some reason, you can cancel the build with CTRL-C, close and reopen the window, browse back to the same directory and run vagrant provision.

Fixing a corrupted installation

Sometimes the Vagrant build can become corrupted. When this happens, you can run these commands to rebuild the Vagrant box. Note that you will lose your code if you do this, so we recommend you work in a topic branch and push it to the server before you execute these commands.

# Remove the virtual machine vagrant destroy # Recreate the virtual machine vagrant up # Resync the folders vagrant rsync-back

Creating a Drush alias file

In order to manipulate the Vagrant site using a drush alias, you will need a specially crafted Drush alias file.

  1. Create the file /etc/drush/webcms.alias.drushrc.php using nano or vim.
  2. Paste the following into it: '/vagrant_data/webcms', 'remote-host' => '', 'remote-user' => 'vagrant', 'ssh-options' => "-i $home/.vagrant.d/insecure_private_key", 'uri' => 'http://webcms.local', );
  3. Test the command by running drush @webcms status. You may need to sudo the command, if you need to sudo your vagrant commands.

Tweaking the configuration

Changing the site URL

Instead of "webcms.local", you can change the URL by modifying the file "vagrant/provisioning/". In that file, there are two lines with the site's URL in it. Changing it in both places will update the URL. You will also need to update your host file and the Drush alias file.

Running multiple sites

To run multiple copies of the uoWeb Vagrant build, you will need to follow the Basic Install instructions once for each site. For each Vagrant build after the first, you will need to edit the file vagrant/Vagrantfile and change the private IP address from to another IP address that is unused. You will also need to pick a different URL for the site, following the instructions above. In addition, the IP address in the host file and Drush alias file will need to be updated.

Connecting to Vagrant using Workbench

To connect MySQL workbench to your Drupal site on Vagrant, follow these steps:

  1. SSH to Vagrant using vagrant ssh from your site's vagrant directory.
  2. Run the command vim /vagrant_data/webcms/sites/default/settings.php to look at the settings information. At the bottom of this file, there is a password to the database. Copy it.
  3. Configure MySQL Workbench to use the TCP/IP over SSH option:
    • SSH Host: (if you are running multiple VMs, you will need to change this for the second ones)
    • SSH Username: vagrant
    • SSH Password: vagrant
    • MySQL Host:
    • MySQL Username: webcms
    • MySQL Password: (as copied from settings.php)
» Submit feedback
  • Developers
  • Getting Started
  • Vagrant
  • Tools
Back to top