h1. cap-recipes
A collection of useful Capistrano 2 provisioning recipes.
This gem is best suited for ruby (and rails) projects hosted on Ubuntu or Debian servers.
The overall vision for this project is simply to collect a number of recipes for common applications 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
- Rubygems Management
- Aptitude Package Management
- NGINX
- Unicorn
- MySQL
- Redis
- Apache Server
- Phusion Passenger
- Memcached Management
- ThinkingSphinx Daemon
- Juggernaut Daemon
- Backgroundrb Server
- DelayedJob Worker
- Whenever Cron Scheduling
- MongoDB Management
- Gitosis Git Repository Hosting
Check out the USAGE section below for specific tasks included in the recipes.
h2. INSTALLATION
To use the gem, add the following to your Gemfile:
gem 'cap-recipes', :git => '[email protected]:donnoman/cap-recipes.git', :require => false
Then, include into your @deploy.rb@ configuration file for Capistrano:
# 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'
# etc for any recipe directory or file under tasks.
# 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, "[email protected]:/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 no longer maintaining the library
- achiu [Arthur Chiu] - contributed gitosis, ruby, mongodb and other recipes
- hubertlepicki - contributed thinking_sphinx recipes
- donnoman [Donovan Bray] - maintaining the library and contributed autossh, bprobe, bundler, cassandra, datadog, denyhosts, dovecot, dphys-swapfile, erlang, git, haproxy, hlds, hosts, jenkins, logrotate, munin, mysql, newrelic_rpm, newrelic_sysmond, nginx, nginx_unicorn, nginx_passenger, openjdk, phantomjs, postfix, provision, resque, ree, redis, riak, ripple, ruby, ruby19, s3cmd, s3fs, s3sync, sdagent, ssmtp, stingray, teelogger, unicorn, wkhtmltopdf, and others.
- rickrussell [Rick Russell] - contributed csgo_ds, graphite, ssh, statsd, ufw, leap_second, xtrabackup, and others.
- zpatten [Zachary Patten] - contributed chef_client, chef_server
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.