Setting Up a Local Development Environment via Vagrant

These instructions are for Mac OSX and Linux host machines, Windows support is untested (see also: Aquia Dev Desktop).


System Tools Installs

  1. Mac-only: If you have not previously done so, install the XCode Command Line Tools. To intall: xcode-select --install
  2. Download & install Virtualbox unless you have done so previously.
  3. Download & install Vagrant, or ensure you have 1.7.2 or later. To check version: vagrant -v

Plugins & Modules Installs

  1. Change to the ucsfp directory, then run git submodule update --init which pulls various tools into your repo, mostly related to Puppet.
  2. Install the Vagrant Triggers helper plug-in by running vagrant plugin install vagrant-triggers. If successful, you’ll see a message similar to “Installed the plugin 'vagrant-triggers (0.5.0)'!”
  3. Install the Vagrant VirtualBox Guest Additions plugin by running vagrant plugin install vagrant-vbguest.
  4. Mac-only: Install the improved rsync watcher recommended for Mac by running vagrant plugin install vagrant-gatling-rsync. If successful, you’ll see a message similar to “Installed the plugin 'vagrant-gatling-rsync (0.1.0)'!”

Server Connectivity

If you have previously used 

Domain Names

Edit your hostfile (/etc/hosts on most systems) as needed to add the local versions of your sites using As the IP the* domain name convention (if your site has no dev.* folder in the repo, use local.* instead. Example:

# Host Database
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
## localhost broadcasthost
::1 localhost
fe80::1%lo0 localhost


Database details

  1. Copy the file from ucsf/docroot/sites/default to your dev site folder, changing the name to (this file is ignored by git).  
  2. Example (from ucsfp/docroot/sites folder):
  3. cp default/
  4. Edit your new Uncomment the 'Vagrant version" of the databases array, then change the database name to whatever you plan to use (usually your site name).
  5. Save the (this file is ignored by git) and review the instructions at the top of the file for editing your settings.php (also in your site folder).
  6. Carefully follow local settings file's instructions for adding the else if for local settings to your file (this change should probably be committed, and is safe to copy to your 'production' folder as well).

Files connection

View ucsfp/scripts/syncfiles in an editor and follow the instructions for enabling ssh agent forwarding, to make pulling down files easier (also consider adding ucsfp/scripts to your terminal path for convenience).

Starting Vagrant

Initial load

From anywhere in the repository run vagrant up and cross your fingers!  The first load will take a while, especially if it has to download a box.  Hopefully it completes successfully.

Once it's up and running, navigate to in your web browser.  Create a database with the same name, then import a SQL file you got from your production or dev version of the site. (the import process tends to spin on Vagrant, but it works, just continue working in a new tab).

Within a minute or two, your DB load should be complete. You site should now load, but likely is missing images and may have broken CSS. Time to sync /files!

From anywhere in the repo run the syncfiles script mentioned previously, syncing your site from prod or dev to vagrant. Example: syncfiles mysite prod vagrant (consider doing a dry-run the first time, run syncfiles for usage).

From anywhere in the repo, run vagrant ssh to tunnel into the machine, this drops you in to /vagrant/docroot/sites.  Change directory to your dev folder cd then run a drush clear cache "all": drush cc all 

Your site probably loads now!

Subsequent Loads & Tips

To stop the VM, vagrant halt is the normal shutdown command.

Dedicate a terminal window to running the rsync watcher vagrant rsync-auto or optionally vagrant gatling-rsync-auto on mac. --this is necessary to immediately reflect codebase changes

Host machine commands for quick access to syslog vagrant ssh -c 'tail -f /var/log/syslog' and error log vagrant ssh -c 'tail -f /var/log/apache2/localhost_error.log' 

Mac only:

OSX users can shortcut startup and shutdown, opening all of the logs and watchers in terminal tabs by using the the ucsf/scripts/mystic script.
Example: mystic up .. run mystic with no argument for more usage.