The guide setup assumes you’re running a relatively modern version of OSX. But if you can get your non-OSX environment into shape, you should be able to follow along with the rest of the guide quite easily.

Install Homebrew

Homebrew is a package manager for OSX. Follow the instructions on the Homebrew Installation Page to install Homebrew.

Install Homebrew

$ ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

This guide will assume that you have Homebrew installed.

Install Git

Git is a distributed version control system that is used heavily by Chef. We need this too.

Install GIT

$ brew install git
$ git --version
git version 1.8.2

Install rbenv and ruby-build

OSX comes with its own outdated version of Ruby. Simply upgrading it can cause trouble. You need something to manage multiple versions of Ruby; enter rbenv and ruby-build.

Install rbenv

$ brew install rbenv
$ if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi
$ brew install ruby-build

EDIT: need to see if the command line entry is good enough or if we should be updating the bash profile.

Install Ruby

Ruby 1.9 is a requirement of Berkshelf. We will be using 2.0.0-p0 which is the latest patch level of 2.0.0.

Install Ruby

$ rbenv install 2.0.0-p0

Set Ruby 2.0.0-p0 as your default Ruby version

Set Global Ruby Version

$ rbenv global 2.0.0-p0

And install bundler for dependency resolution

Install Ruby Bundler

$ gem install bundler

Install Berkshelf

Berkshelf is a dependency resolver and retriever for Chef Cookbooks.

Install Berkshelf

$ gem install berkshelf

Note: This guide requires Berkshelf (1.0.0) or later.

Install Foodcritic

Foodcritic is a linting tool for Chef Cookbooks that helps you find problems and improve your code.

Install Foodcritic

$ gem install foodcritic

Install VirtualBox

VirtualBox is a virtualization solution for creating virtual machines on your local computer. We will be using it to build our development environment.

Download Virtualbox from the Virtualbox Downloads Page and then install it. We will be using version 4.2.10 in this guide.

Install Vagrant

Vagrant provides easy to configure, reproducible, and portable work environment built on top of VirtualBox, VMWare, or AWS.

Vagrant can be installed by downloading the installer for your operating system and using standard procedures to install that package. We will be using version 1.1.5.

Install Berkshelf plugin

Install the Berkshelf plugin for Vagrant.

Install Berkshelf Plugin

$ vagrant plugin install berkshelf-vagrant

Creating the Cookbook

Create a new cookbook called “workbench” to bake our sample development environment. Berkshelf will do all the hard work, and set up a standard set of templates. Don’t forget the --foodcritic attribute. This will create a skeleton for a new cookbook named ‘workbench’ in the directory workbench in your current working directory.

Create A Cookbook

$ berks cookbook workbench --foodcritic
      create  workbench/files/default
      create  workbench/templates/default
      create  workbench/attributes
      create  workbench/definitions
      create  workbench/libraries
      create  workbench/providers
      create  workbench/recipes
      create  workbench/resources
      create  workbench/recipes/default.rb
      create  workbench/metadata.rb
      create  workbench/LICENSE
      create  workbench/README.md
      create  workbench/Berksfile
      create  workbench/chefignore
      create  workbench/.gitignore
         run  git init from "./workbench"
      create  workbench/Thorfile
      create  workbench/Gemfile
      create  workbench/Vagrantfile
Using workbench (0.1.0) at path: '/Users/modius/Kitchen/workbench'

Passing the additional --foodcritic option generates additional boilerplate files for your cookbook that will enable lint testing with Foodcritic later.

Prepare your virtual environment

Switch into the directory of the newly created cookbook and install the Gem dependencies with bundler

Install Gem Dependencies

$ cd workbench
$ bundle install

Bundler will install all of the dependent RubyGems and guarantee that you have the right versions.

Starting your virtual machine

A Vagrantfile was generated for you by Berkshelf with a boilerplate configuration. The Vagrantfile defines the configuration of the virtual machine we’ll be working with. By default this is configured to download and boot a CentOS 6.3 Vagrant Box and provision it with chef-solo.

First thing we’re going to do is switch this to an Ubuntu virtual instead. Open the Vagrantfile inside your cookbook with your favorite editor and edit the values of the config.vm.box and config.vm.box_url attributes.

Edit Vagrantfile

Vagrant::Config.run do |config|
  ...
  config.vm.box = "precise64"
  config.vm.box_url = "http://files.vagrantup.com/precise64.box"
  ...
end

Start up your virtual machine

Vagrant Up

$ vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
[default] Importing base box 'precise64'...
[default] Matching MAC address for NAT networking...
[default] Setting the name of the VM...
[default] Clearing any previously set forwarded ports...
[Berkshelf] Updating Vagrant's berkshelf: '/Users/modius/.berkshelf/vagrant/berkshelf-20130409-26494-18obao1'
[Berkshelf] Using workbench (0.1.0) at path: '/Users/modius/Kitchen/workbench'
[default] Fixed port collision for 22 => 2222. Now on port 2203.
[default] Creating shared folders metadata...
[default] Clearing any previously set network interfaces...
[default] Preparing network interfaces based on configuration...
[default] Forwarding ports...
[default] -- 22 => 2203 (adapter 1)
[default] Booting VM...
[default] Waiting for VM to boot. This can take a few minutes.
[default] VM booted and ready for use!
[default] Setting hostname...
[default] Configuring and enabling network interfaces...
[default] Mounting shared folders...
[default] -- /vagrant
[default] -- /tmp/vagrant-chef-1/chef-solo-1/cookbooks
[default] Running provisioner: VagrantPlugins::Chef::Provisioner::ChefSolo...
Generating chef JSON and uploading...
Running chef-solo...
stdin: is not a tty
[2013-04-09T11:45:33+00:00] INFO: *** Chef 10.14.2 ***
[2013-04-09T11:45:34+00:00] INFO: Setting the run_list to ["recipe[workbench::default]"] from JSON
[2013-04-09T11:45:34+00:00] INFO: Run List is [recipe[workbench::default]]
[2013-04-09T11:45:34+00:00] INFO: Run List expands to [workbench::default]
[2013-04-09T11:45:34+00:00] INFO: Starting Chef Run for workbench-berkshelf
[2013-04-09T11:45:34+00:00] INFO: Running start handlers
[2013-04-09T11:45:34+00:00] INFO: Start handlers complete.
[2013-04-09T11:45:34+00:00] INFO: Chef Run complete in 0.027968 seconds
[2013-04-09T11:45:34+00:00] INFO: Running report handlers
[2013-04-09T11:45:34+00:00] INFO: Report handlers complete

This may take a little while if this is your first time; Vagrant will need to download the Precise64 base box first. But once the box package is local, any request for a new box of the same name and url will reuse your local copy. If Ubuntu is not your thing, there’s a convenient list of pre-prepped and popular Vagrant boxen online.

Check the full Vagrant Documentation for future reference.

If at anytime your virtual machine becomes unstable or if you’d like to start over you can destroy your virtual machine with one command

The Green Needle

$ vagrant destroy
Are you sure you want to destroy the 'default' VM? [y/N] y
[default] Forcing shutdown of VM...
[default] Destroying VM and associated drives...
[Berkshelf] Cleaning Vagrant's berkshelf

If you destroyed your VM just now becuase you couldn’t help yourself, make sure to recreate it with vagrant up before moving on with the guide ;)

I’m in search of the perfect development environment. It’s something that runs anywhere (Windows, OSX, Linux), runs a complete production ready stack, is a doddle to set up, can be completely packed into version control and delivered to a friend at a moments notice.

I want something:

  • portable
  • mirrors production
  • re-created with a couple of commands
  • GIT friendly
  • always distributable

What follows is a blow by blow guide, built to help the Daemonites improve their development process. Daemon creates and manages large bespoke CFML solutions for many different clients. Each development environment is often quite elaborate and getting set up to contribute to a project can take a fair bit of mucking around… until now ;)

While you will be able to use these services on Windows and Linux workstations, all the walkthroughs assume you’re working in an OSX environment. Don’t let that scare you, things are remarkably similar cross platform.

The Tools

The workbench is based on having a number of development tools in place:

  • Virtualbox for virtual servers
  • Vagrant for managing virtual servers
  • Ruby for fairy dust (no need to understand any ruby, just need some useful ruby apps)
  • Chef for cooking up infrastructure via code
  • Berkshelf for Chef cookbook and recipe management

Don’t race to download these apps right now; a step by step set up guide follows.

The Stack

For the sake of the guide, I’m going with a completely open source stack, with a sample, database-driven web application, installed and ready to run on Tomcat. With any luck this should touch on enough areas to help you get up and running with any web stack.

  • Ubuntu Precise 64 cloud instance
  • Apache (web server)
  • Tomcat6 (Java servlet container)
  • Railo (open source CFML application engine)
  • mySQL (database platform)
  • FarCry CMS (open source publishing platform for CFML)

If you are into CFML/ColdFusion (and Railo in particular) this should be right up your alley. If you’re not, the principles in the guide should have you well on the way to success. And hey, you might just enjoy ColdFusion to boot.

The Vagrant Workbench Guide

First we get to grips with Vagrant and VirtualBox; this combo provides a myriad of server operating environments from linux to windows. We’ll focus on Ubuntu Precise 64bit for this guide.

Next use Chef for provisioning our virtual machines; coding up the automated installation of our application and all the apps it needs to function properly. This “ops code” is divided up into “Cookbooks” full of “Recipes” for specific application installations.

The ruby app “Berkshelf” will be handy for retrieving existing cookbooks and resolving their dependencies. And we’ll have to roll our own application cookbook to tie it all together.

  • Part 1: Getting Started <--- YOU ARE HERE
  • Part 2 Setting Up
  • [Part 3] Coming on the never never…
  • [Part 4] Coming soon…
  • [Part 5] Coming soon…
  • [Part 6] Coming soon…
  • [Part 7] Coming soon…

Many thanks to Jamie Winsor (aka reset) for potent coding skills, his open nature and the awesome cookbook guide that got me started.

Once you have your Octopress blog in place, you might wonder how you start contributing from another computer; either yours or a friends.

You need to setup Octopress for each computer but not from scratch. Clone your repo, switch to the source branch, then manually set up a _deploy folder and bind it to the master branch.

Setting Up an Existing Octopress Blog

$ git clone git@github.com:usr/usr.github.com.git
$ cd usr.github.com
$ git checkout source
$ mkdir _deploy
$ cd _deploy
$ git init
$ git remote add origin git@github.com:usr/usr.github.com.git
$ git pull origin master

All done. Courtesy of code.dblock.org

Assumes you have a fully functional Octopress blogging environment. This cheat sheet is a one page reminder of how to generate a blog post, and the markup for the default plugins.

Working with Blog Posts

Create a new blog post

$ rake new_post["Zombie Ninjas Attack: A survivor's retrospective"]
# Creates source/_posts/2011-07-03-zombie-ninjas-attack-a-survivors-retrospective.markdown

Save your source files

$ git add .
$ git commit -m 'your message'
$ git push origin source

Publish to live site

$ rake generate   # Generates posts and pages into the public directory
$ rake deploy     # Pushes it to your GIT master for publication

Other options

$ rake watch      # Watches source/ and sass/ for changes and regenerates
$ rake preview    # Watches, and mounts a webserver at http://localhost:4000

Excerpt

Create a teaser using <!-- more --> where you want the “Read More” button.

Working with DRAFT posts

Just don’t $ rake deploy or use published: false in post header.

Markup

Generally its Markdown.

Code blocks

Backticks

	``` [language] [title] [url] [link text]
	code snippet
	```

Some language options: java, js, cfm, apacheconf, sql. Complete list of Pygments Lexers

Gist blocks

	{ % gist gist_id [filename] %}    # Syntax (no spaces in liquid templates)
	{ % gist 996818 %}                # Example

Image

Image embed

{ % img [class names] /path/to/image [width] [height] [title text [alt text]] %}
{ % img http://placekitten.com/890/280 %}

Quotes

Formatted block quote

{ % blockquote [author[, source]] [link] [source_link_title] %}
Quote string
{ % endblockquote %}

Inline pull quote

{ % pullquote %}
Surround your paragraph with the pull quote tags. Then when you come to
the text you want to pull, { " surround it like this "} and that's all there is to it.
{ % endpullquote %}

Base16 Styles by Chris Kempson

Always good to have some colour when your hacking away in a text heavy environment. Whether its the terminal or a textmate I seem to fall back to a base16 theme from chriskempson.

Base16 via https://github.com/chriskempson/base16

Base16 is available in a range of styles for just about every popular text environment. Enjoy!