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
* Mongodb Management
* Bundler Tasks
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"
h3. Bundler
These recipes are for managing bundler with your project
h4. Configuration
* None required
h4. Tasks
manage.rb
* bundle:install - Performs bundle install
* bundle:lock - Performs bundle lock
* bundle:unlock - Performs bundle unlock
* bundle:show - Performs bundle show
* bundle:check - Performs bundle check
hooks.rb
after "deploy:symlink", "bundle:lock"
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. CAP-RECIPES
cap-recipes allows you to create config with the desired recipes. It's capify for cap-recipes.
USAGE:
cap-recipes [path] [task1] [task2] [task3]
include memcache,apache, and passenger recipes
cap-recipes . memcache apache passenger
show all available recipes
cap-recipes --list | cap-recipes -l
show help
cap-recipes --help | cap-recipes -h
generate standard capify
cap-recipes . | cap-recipes
this defaults path to '.'
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.