These instructions are for Mac OSX and Linux host machines, Windows support is untested (see also: Aquia Dev Desktop).
System Tools Installs
- Mac-only: If you have not previously done so, install the XCode Command Line Tools. To intall:
- Download & install Virtualbox unless you have done so previously.
- Download & install Vagrant, or ensure you have 1.7.2 or later. To check version:
Plugins & Modules Installs
- Change to the ucsfp directory, then run
git submodule update --initwhich pulls various tools into your repo, mostly related to Puppet.
- 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)'!”
- 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)'!”
If you have previously used
Edit your hostfile (
/etc/hosts on most systems) as needed to add the local versions of your sites using
10.10.10.20. As the IP the
local.dev.* 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.
- Copy the default.local.settings.inc file from ucsf/docroot/sites/default to your dev site folder, changing the name to local.settings.inc (this file is ignored by git).
- Example (from ucsfp/docroot/sites folder):
cp default/default.local.settings.inc dev.mysite.ucsf.edu/local.settings.inc
- Edit your new
local.settings.inc.Uncomment the 'Vagrant version" of the databases array, then change the database name to whatever you plan to use (usually your site name).
- Save the
local.settings.inc(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).
- Carefully follow local settings file's instructions for adding the else if for local settings to your
dev.mysite.ucsf.edu/settings.phpfile (this change should probably be committed, and is safe to copy to your 'production' folder as well).
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).
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
10.10.10.20/phpmyadmin 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 dev.mysite.ucsf.edu 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'
OSX users can shortcut startup and shutdown, opening all of the logs and watchers in terminal tabs by using the the ucsf/scripts/gypsy script.
gypsy up .. run gypsy with no argument for more usage.