Scholars' Lab Chef Cookbook and Vagrant Utilities

This is a collection of Chef Solo recipes that we've accumulated at the Scholars' Lab to use with Vagrant. At the moment, the primary recipe is to set up an Omeka installation for developing either on Omeka or on plugins or themes. This also has a Rakefile that makes testing and working with PHP code in the Vagrant VM easier.

Installation and Use

Installing Vagrant and VirtualBox

Vagrant's written in Ruby, so assuming you have Ruby and RubyGems installed, just do this:

gem install vagrant

Getting VirtualBox is more complicated. Check the VirtualBox website for how to install it.

Set up a Working Directory

Once the software is installed, you'll need to set up a working directory and initialize it for Vagrant. You'll also need to download the Chef cookbooks that you'll use.

mkdir omeka-project
cd omeka-project
git clone https://github.com/opscode/cookbooks.git
git clone git://github.com/scholarslab/cookbooks.git slab-cookbooks
vagrant init omeka-project http://files.vagrantup.com/lucid32.box

The last command created a file called "Vagrantfile". (It also pointed to a file that won't exist on your system. We're working on a URL for hosting the base box. When it's available, use that URL in place of PATH-TO.) Go ahead and open it up in your favorite text editor. Vagrantfile is just Ruby, nothing scary there. We need to add a few lines. At the bottom of the file, just before the "end," insert these:

config.vm.provision :chef_solo do |chef|
  chef.cookbooks_path = ["cookbooks", "slab-cookbooks"]
  chef.add_recipe "omeka"

  # :omeka_version can be a version number tag (e.g., '1.4', '1.3.2') or
  # 'HEAD' or a branch name.
  chef.json.merge!({
    :omeka => {
      :version => 'stable-1.4',
      :themes => [
        {:name => 'dark', :url => 'git://github.com/omeka/theme-dark.git'},
        {:name => 'something', :url => 'http://svn.something.org/svn/themes/something/trunk',
         :type => 'svn', :svn_username => 'someuser', :svn_password => 'somepass'}
      ],
      :plugins => [
        {:name => 'BagIt', :url => 'https://github.com/scholarslab/BagItPlugin.git'},
        {:name => 'Dropbox', :url => 'git://github.com/omeka/plugin-Dropbox.git',
         :revision => 'tags/1.3-0.5'}
      ]
    }
  })
end
config.vm.forward_port('mysql', 3306, 3333)
config.vm.forward_port('apache2', 80, 8080)

The first four lines tell Vagrant to set up the system using Chef Solo, and they tell Chef to use the cookbooks we downloaded from GitHub and to use the "omeka" recipe. The last two lines tell Vagrant to set up port forwarding so we can access the web server and database from the host machine, without needing to log onto the VM.

The chef.json.merge! part tell it to download Omeka from the GitHub, using the "stable-1.4" branch. It tells it to also download the "dark" theme and the "BagIt" and "Dropbox" plugins, as well as the default plugins. Currently, this only works with Git repositories.

It also has a Hash to check out a Subversion repository. These look just like the Git Hashes, but they also include a :type key value the value 'svn' and the keys :svn_username and :svn_password.

Install Information

You can also supply information for the installation page in the Vagrantfile. This information is included in the chef.json.merge! expression, keyed by these fields:

• :username — Default Superuser Account Username (required)
• :password — Default Superuser Account Password (required)
• :super_email — Default Superuser Account Email (required)
• :administrator_email — Site Administrator Email (required)
• :site_title — Site Title (required)
• :description — Site Description
• :copyright — Site Copyright Information
• :author — Site Author Information
• :tag_delimiter — Tag Delimiter (default is ',')
• :fullsize_constraint — Fullsize Image Size (required, default is 800)
• :thumbnail_constraint — Thumbnail Size (required, default is 200)
• :square_thumbnail_constraint — Square Thumbnail Size (required, default is 200)
• :per_page_admin — Items Per Page (admin) (required, default is 10)
• :per_page_public — Items Per Page (public) (required, default is 10)
• :show_empty_elements — Show Empty Elements (default is false)
• :path_to_convert — Imagemagick Directory Path (default is '/usr/bin')

For example, a minimal specification would look like this:

    chef.json.merge!({
      :omeka => {
        # ...
        :username => 'root',
        :password => 'omeka',
        :super_email => 'root@whatever.org',
        :administrator_email => 'admin@whatever.org',
        :site_title => 'Whatever Site'
      }
    })

Hacks

Ah, life on the bleeding edge. There are a few issues with (as far as I can tell) using the OpsCode with Vagrant and Chef Solo.

First, it includes a set of recipes for Windows, and Chef attempts to use this whether you're on Windows or not. You can get around that by including this at the top of your Vagrant file:

if File.directory?('cookbooks/windows')
  FileUtils.remove_dir('cookbooks/windows', true)
end

Second, it attempts to access several attributes that don't exist, so you have to include them in your settings, whether you need them or not. Include this in Vagrantfile in the chef.json.merge! expression:

    chef.json.merge!({
      :omeka => {
        # ...
      },
      :domain => [],
      :openldap => {}
    })

Set up Omeka

Umm. There used to be stuff you had to do for this, but the Chef recipe takes care of all that now.

Start the VM

Everything's in place. Now it's time to start the VM. From the console, just enter this command:

vagrant up

A lot of lines will scroll by. Many minutes will pass. Apache, PHP, and MySQL will be installed. When you get your prompt back, you should be ready to go.

You probably missed it, but these lines were near the beginning of all that output:

[default] -- mysql: 3306 => 3333 (adapter 1)
[default] -- apache2: 80 => 8080 (adapter 1)
[default] -- ssh: 22 => 2222 (adapter 1)

These tell how you can communicate with your newly minted VM. Since it's using port forwarding, you can pretend like you're talking to your host box, but using the ports listed above:

mysql -uomeka -pomeka --protocol=TCP --port=3333 omeka
open http://localhost:8080/
vagrant ssh

Finishing the Omeka Installation

If you didn't supply the information in the Vagrantfile, then you'll need to finish setting up Omeka now. Just point your browser to http://localhost:8080 running on the VM and fill in the installation information like you normally would. Nothing special here.

For Example

There is an example of using Rake and Vagrant to manage your development environment. You can check it out at https://github.com/scholarslab/FalmouthDevEnv.

Developing

The Omeka code running the site is on your host machine, in the omeka/ directory that you created above. You can put the plugins and themes that you want to use into there, and you can edit them as you like.

Closing Down

When you're done for the day and you want your resources back, you can just suspend the VM by calling this:

vagrant suspend

When you're done with the project and you want to destroy the VM, the database, and everything on it, give this command:

vagrant destroy

Rakefile

You can use the Rakefile by copying it into your Vagrant project directory. Or better yet, create a link to it from that directory or import it a primary Rakefile in your project directory.

Note: Unless otherwise noted, all paths below are paths on the VM. That is, <project-directory>/subdir/ should be /vagrant/subdir/.

Here are the targets defined in this Rakefile. This briefly describes what each target does, the command-line arguments each accepts, and sample usage:

rake phpunit

This runs phpunit on a file.

• base_dir — The directory to run phpunit in.
• phpunit_xml — The phpunit.xml file relative to base_dir to configure the run.
• target — The class or PHP file relative to base_dir to run the tests on.
• coverage — The directory to put the HTML coverage reports into.

Example:

rake phpunit base_dir=/vagrant/site/plugins/SimplePages/tests \
             phpunit_xml=phpunit.xml \
             target=AllTests.php

rake phpdoc

This runs PHP Documentor on a directory.

• base_dir — The directory to run phpdoc in.
• output_dir — The output directory.

rake phpdoc base_dir=/vagrant/site/plugins/BagIt \
            output_dir=/vagrant/docs

rake phpmd

This run PHP Mess Detector on a directory.

• base_dir — The directory to run phpmd in.
• output_dir — The output directory

rake phpmd base_dir=/vagrant/site/plugins/BagIt \
           output_dir=/vagrant/phpmd

rake pdepend

Create a PHP Depend static code analysis report.

• base_dir — The directory to analyze.
• output_dir — The output directory.

rake pdepend base_dir=/vagrant/site/plugins/BagIt \
             output_dir=/vagrant/pdepend

rake phpcpd

Generate a PHP Copy/Paste Detection report.

• base_dir — The directory to analyze.
• output_dir — The output directory.

rake phpcpd base_dir=/vagrant/site/plugins/BagIt \
            output_dir=/vagrant/phpcpd

rake phpcs

Generate a PHP Code Sniffer report.

• base_dir — The directory to analyze.
• output_dir — The output directory.
• standard — The standard to check against (default is 'Zend').

rake phpcs base_dir=/vagrant/site/plugins/BagIt \
           output_dir=/vagrant/phpcs \
           standard=Zend

Overriding Tasks

If you don't want to have to provide all of the options everytime, you can include this Rakefile in your Rakefile and provide the default there. For instance, if you've checked this cookbook repository out to slab-cookbooks, you could create a Rakefile with these contents:

import "slab-cookbooks/Rakefile"

namespace :bagit do

  desc 'Call PHP Mess Detector on BagIt.'
  task :phpmd do
    ENV['base_dir'] = '/vagrant/omeka/plugins/BagIt'
    ENV['output_dir'] = '/vagrant/phpmd'
    Rake::Task['phpmd'].invoke
  end

end

Then you could simply call this from your directory:

rake bagit:phpmd

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: Eric Rochester err8n@virginia.edu Copyright: 2010 The Board and Visitors of the University of Virginia License: http://www.apache.org/licenses/LICENSE-2.0.html Apache 2 License