h1. cap-recipes

A collection of useful capistrano recipes I have been using in production on a number of sites.

This gem is best suited for ruby (and rails) projects which deploy using Apache and Phusion Passenger. Worth noting is that the installation tasks are for systems using aptitude package management.

The overall vision for this project is simply to collect a number of classic, generic recipes for common issues which can then be used by the community.

Feel free to improve upon this recipe collection by adding your own!

Currently included recipes in this gem:

• Ruby Setup
• Rubygems Management
• Apache Server
• Phusion Passenger
• Memcached Management
• ThinkingSphinx Daemon
• Juggernaut Daemon
• Backgroundrb Server
• DelayedJob Worker
• Whenever Cron Scheduling
• MongoDB Management
• Aptitude Package Management
• Gitosis Git Repository Hosting

Check out the USAGE section below for specific tasks included in the recipes.

h2. INSTALLATION

To install the gem, execute:

@$ sudo gem install cap-recipes --source http://gemcutter.org@

Then, include into your @deploy.rb@ configuration file for Capistrano:

  # use the complete deployment process (NOT RECOMMENDED)
  require 'cap_recipes'

  # RECOMMENDED
  # require necessary recipes according to your needs
  # (use hooks which tie all the recipes into the deployment process,
  # tasks for managing and tasks for installing):
  require 'cap_recipes/tasks/memcache'
  require 'cap_recipes/tasks/passenger'
  require 'cap_recipes/tasks/thinking_sphinx'
  require 'cap_recipes/tasks/rails'
  require 'cap_recipes/tasks/delayed_job'
  # or ruby, rubygems, apache, mongodb, juggernaut, backgroundrb, aptitude, gitosis, whenever

  # OR
  # only use managing tasks:
  require 'cap_recipes/tasks/memcache/manage'

  # OR
  #only use install tasks:
  require 'cap_recipes/tasks/memcache/install'

You can find full examples of what your @deploy.rb@ file should look like in the @examples@ folder.

h2. USAGE

h3. Apache

These recipes manage the apache web server

h4. Configuration

• apache_init_path - the path to the init.d apache file [default: '/etc/init.d/apache2']

h4. Tasks

manage.rb

• apache:stop - stops the apache server
• apache:start - starts the apache server
• apache:restart - restarts the apache server

install.rb

• apache:install - installs apache and dependencies onto a debian system

h3. Ruby

h4. Configuration

• None required

h4. Tasks

install.rb

• ruby:setup - Installs ruby 1.8 using standard aptitude packages

h3. Rubygems

h4. Configuration

• rubygem_paths - a path or array of paths to your gem binaries [default '/usr/bin/gem' ]
• rubygems_version - which version of rubygems to install [default '1.3.5']

h4. Tasks

manage.rb

• rubygems:full_update - Upgrades rubygems, updates all installed rubygems and performs a cleanup
• rubygems:upgrade - Upgrades rubygems version (if available)
• rubygems:update - Updates all installed rubygems
• rubygems:cleanup - Performs a cleanup for all outdated rubygems
• rubygems:install - Installs a specifed gem from name inputted on console
• rubygems:uninstall - Removes a specified rubygem from name inputted on console

install.rb

• rubygems:install - Installs rubygems by downloading package and running setup.rb

h3. Passenger

These recipes manage the passenger module for apache

h4. Configuration

• base_ruby_path - the base path to the ruby installation [default: '/usr']
• local_ping_path - the localhost path to ping to start passenger [default: "http://localhost"]

The following files and folders are expected to exist:

• "#{base_ruby_path}/lib/ruby"
• "#{base_ruby_path}/bin/ruby"
• "#{base_ruby_path}/bin/gem"

h4. Tasks

manage.rb

• deploy:start - Starts the apache server (if needed)
• deploy:stop - Stops the apache server (if needed)
• deploy:restart - Touches the restart.txt file

install.rb

• passenger:install - Installs the passenger gem, compiles the module silently, and adds the necessary configuration

h3. Aptitude

h4. Tasks

manage.rb

• aptitude:install - Installs a specified aptitude package from name inputted on console
• aptitude:remove - Removes a specified aptitude package from name inputted on console
• aptitude:updates - Updates all installed aptitude packages

h3. Rails

These recipes support rails-specific functionality

h4. Tasks

manage.rb

• rails:symlink_db_config - Symlinks the database.yml file from shared/config to release path
• rails:repair_permissions - Forces the permissions on the rails app to make permission errors a thing of the past
• rails:tail - tail production log - Provides a stream tailing the production log
• rails:ping - pings the server to start a passenger instance (reduces downtime)
• rails:sweep:cache - performs a file cache sweep in production
• rails:sweep:log - performs a log sweep in production

hooks.rb

after "deploy:update_code", "rails:symlink_db_config" # copy database.yml file to release path
after "deploy:update_code", "rails:sweep:cache" # clear cache after updating code
after "deploy:restart"    , "rails:repair_permissions" # fix the permissions to work properly
after "deploy:restart"    , "rails:ping" # ping passenger to start the rails instance

h3. DelayedJob

These recipes are for tobi's delayed_job plugin for background job queue processing

h4. Configuration

• delayed_script_path - the path to the delayed job script [default: '#{current_path}/script/delayed_job']
• delayed_job_env - the rails environment [default: 'production']

h4. Tasks

manage.rb

• delayed_job:stop - stops the delayed_job workers
• delayed_job:start - starts the delayed_job workers
• delayed_job:restart - restarts the delayed_job workers

hooks.rb

after "deploy:start",   "delayed_job:start"
after "deploy:stop",    "delayed_job:stop"
after "deploy:restart", "delayed_job:restart"

h3. Backgroundrb

These recipes are for backgroundrb job queue processing

h4. Configuration

• backgroundrb_log - the path to the backgroundrb log file
• backgroundrb_host - the background host machine ip [default: 'localhost']
• backgroundrb_env - the rails environment [default: 'production']

h4. Tasks

manage.rb

• backgroundrb:stop - stop backgroundrb workers
• backgroundrb:start - start backgroundrb workers
• backgroundrb:restart - restart backgroundrb workers
• backgroundrb:symlink_config - copy backgroundrb.yml from shared/config to release
• backgroundrb:tail - tails the backgroundrb log file in production

hooks.rb

after "deploy:update_code"   , "backgroundrb:symlink_config" # copy backgroundrb config to release
after "deploy:restart"       , "backgroundrb:restart"     # restart backgroundrb daemon
after "backgroundrb:restart" , "backgroundrb:repair_permissions" # restart backgroundrb damon

h3. Juggernaut

These recipes are for managing the juggernaut push server

h4. Configuration

• juggernaut_config - path to juggernaut config file [default: "#{current_path}/config/juggernaut.yml"]
• juggernaut_pid - path to juggernaut pid file [default: "#{current_path}/tmp/pids/juggernaut.pid"]
• juggernaut_log - path to juggernaut log file [default: "#{current_path}/log/juggernaut.log"]

h4. Tasks

manage.rb

• juggernaut:start - starts the juggernaut push server
• juggernaut:stop - stop the juggernaut push server
• juggernaut:restart - restart the juggernaut push server
• juggernaut:symlink_config - copy juggernaut.yml from shared/config to release
• juggernaut:tail - tails the juggernaut log file in production

hooks.rb

after "deploy:update_code", "juggernaut:symlink_config" # copy juggernaut.yml to release
after "deploy:restart"    , "juggernaut:restart"     # restart juggernaut daemon

h3. ThinkingSphinx

These recipes are for managing the thinking_sphinx search index daemon

h4. Configuration

• None required

h4. Tasks

manage.rb

• thinking_sphinx:start - starts the thinking_sphinx search daemon
• thinking_sphinx:index - executes the thinking_sphinx search indexer
• thinking_sphinx:stop - stop the thinking_sphinx search daemon
• thinking_sphinx:restart - restart (and index) the thinking_sphinx search daemon
• thinking_sphinx:symlink_config - copy sphinx.yml from shared/config to release
• thinking_sphinx:tail - tails the juggernaut log file in production

install.rb

• thinking_sphinx:install - installs sphinx, dependencies, and thinking_sphinx gem

hooks.rb

after "deploy:update_code", "thinking_sphinx:symlink_config" # sym thinking_sphinx.yml on update code
after "deploy:restart"    , "thinking_sphinx:restart"     # restart thinking_sphinx on app restart

h3. Memcache

These recipes are for managing the memcached caching mechanism

h4. Configuration

• memcache_init_path - path to memcache config file [default: "/etc/init.d/memcache"]
• memcache_size - the total size of memory to use [default: 64]
• memcache_port - the port to start memcache [default: '11211']
• memcache_host - the host for memcache [default: '127.0.0.1']
• memcache_user - the user to run memcache [default: 'nobody']

h4. Tasks

manage.rb

• memcache:start - starts the memcache daemon
• memcache:stop - stops the memcache daemon
• memcache:restart - restarts the memcache daemon

install.rb

• memcache:install - Installs memcache aptitude package and rubygem

hooks.rb

after "deploy:restart", "memcache:restart" # clear cache after updating code

h3. MongoDB

These recipes are for installing and managing the mongodb document-oriented database

h4. Configuration

• mongodb_data_path - the location to store the mongodb data [default: "/data/db"]
• mongodb_bin_path - the location to install mongodb [default: "/opt/mongo"]
• mongodb_log - the path to the mongodb log file [default: "/var/log/mongodb.log"]

h4. Tasks

install.rb

• mongodb:install - Performs the full installation of mongodb and dependencies

manage.rb

• mongodb:start - Starts the mongodb process
• mongodb:stop - Stops the mongodb process
• mongodb:restart - Restarts the mongodb process

h3. Gitosis

These recipes are for installing Gitosis Git Repository Hosting

h4. Configuration

• None required

h4. Tasks

install.rb

• gitosis:install

h3. Whenever

These recipes are for managing whenever cron job scheduling

h4. Configuration

• None required

h4. Tasks

manage.rb

• whenever:update_crontab - Performs an update applying the schedule.rb file to your server's cron

hooks.rb

after "deploy:symlink", "whenever:update_crontab"

h2. EXAMPLE

Here is a sample deploy.rb file using cap_recipes:

# =============================================================================
# GENERAL SETTINGS
# =============================================================================

set :application,  "app_name"
set :deploy_to,  "/var/apps/#{application}"
set :scm, :git
set :repository, "git@repos.site.com:/home/git/repos.git"

# =============================================================================
# CAP RECIPES
# =============================================================================

# Note this happens after the general settings have been defined
require 'rubygems'

# PASSENGER
require 'cap_recipes/tasks/passenger'
set :base_ruby_path, '/opt/ruby-enterprise' # defaults to "/usr"
set :apache_init_path, '/etc/init.d/apache2' # defaults to "/etc/init.d/apache2"

# BACKGROUNDRB
require 'cap_recipes/tasks/backgroundrb'
set :backgroundrb_log, "/var/log/backgroundrb.log" # defaults to "#{release_path}/log/backgroundrb.log"
set :backgroundrb_host, "worker.site.com" # defaults to localhost
set :backgroundrb_env, "staging" # defaults to production

# DELAYED_JOB
require 'cap_recipes/tasks/delayed_job'
set :delayed_script_path, 'script/djworker' # defaults to 'script/delayed_job'
set :delayed_job_env, 'staging' # defaults to production

# JUGGERNAUT
require 'cap_recipes/tasks/juggernaut'
set :juggernaut_config, "/some/path/juggernaut.yml" # defaults to "#{current_path}/config/juggernaut.yml"
set :juggernaut_pid, "/some/path/juggernaut.pid" # defaults to "#{current_path}/tmp/pids/juggernaut.pid"
set :juggernaut_log, "/var/log/juggernaut.log" # defaults to #{release_path}/log/juggernaut.log

# MEMCACHE
require 'cap_recipes/tasks/memcache'
set :memcache_init_path, "/etc/init.d/memcache" # defaults to "/etc/init.d/memcache"

You can find more examples of what your @deploy.rb@ file should look like in the @examples@ folder.

h2. UTILITIES

In addition to the recipes themselves, this gem provides a bunch of useful utility methods which make writing your own recipes or extending existing ones much easier by creating reusable commands for common subtasks in a recipe.

There are too many to mention all of them directly, but check out @lib/cap_recipes/tasks/utilities.rb@ to browse all available utility methods. A few are listed below:

• utilities.config_gsub(file, findPattern, replaceString) Replaces the @findPattern@ with @replaceString@ within specified file on server # utilities.config_gsub('/etc/example', /#(option:.*?\n)/im, "\1")

• utilities.ask(question, default) Asks the user a question on the command-line and returns the response utilities.ask('What is your name?', 'John')

• utilities.yes?(question) Asks the user a yes or no question on the command-line and returns boolean result utilities.yes?('Proceed with installation?')

• utilities.apt_install(packages) Installs all specified aptitude packages silently without user intervention utilities.apt_install %w[package1 package2]

• utilities.sudo_upload(local_path, remote_dest, options) Uploads a file to a temporary location and then sudo moves it to specified remote destination utilities.sudo_upload('/local/path/to/file', '/remote/path/to/destination', :mode => 'u+rwx')

• utilities.with_role(role) { ... } Forces tasks in block to execute only within specific role(s) This is useful because of certain limitations in the role declaration in capistrano

• utilities.with_credentials(:user => 'jsmith', :password => 'secret') { ... } Forces tasks in block to execute using the given user/password credentials This is useful because of certain limitations in capistrano

h2. CONTRIBUTORS

The following people are the reason this library exists:

• nesquena [Nathan Esquenazi] - created and maintaining the library
• achiu [Arthur Chiu] - contributed gitosis, ruby, mongodb and other recipes
• hubertlepicki - contributed thinking_sphinx recipes

h2. LICENSE

(The MIT License)

Copyright (c) 2008 Nathan Esquenazi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.