uhl-cap-recipes 0.1.0

data/Capfile

@@ -0,0 +1,4 @@
+load 'deploy' if respond_to?(:namespace) # cap2 differentiator
+Dir['vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
+
+load 'config/deploy' # remove this line to skip loading any of the default tasks

data/LICENSE

@@ -0,0 +1,20 @@
+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.

data/README.textile

@@ -0,0 +1,586 @@
+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:
+
+<pre><code>
+  # 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'
+</code></pre>
+
+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
+
+<pre><code>
+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
+</code></pre>
+
+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
+
+<pre><code>
+after "deploy:start",   "delayed_job:start"
+after "deploy:stop",    "delayed_job:stop"
+after "deploy:restart", "delayed_job:restart"
+</code></pre>
+
+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
+
+<pre><code>
+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
+</code></pre>
+
+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
+
+<pre><code>
+after "deploy:update_code", "juggernaut:symlink_config" # copy juggernaut.yml to release
+after "deploy:restart"    , "juggernaut:restart"     # restart juggernaut daemon
+</code></pre>
+
+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
+
+<pre><code>
+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
+</code></pre>
+
+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
+
+<pre><code>
+after "deploy:restart", "memcache:restart" # clear cache after updating code
+</code></pre>
+
+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
+
+<pre><code>
+after "deploy:symlink", "whenever:update_crontab"
+</code></pre>
+
+
+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
+
+<pre><code>
+after "deploy:symlink", "bundle:lock"
+</code></pre>
+
+
+
+
+h2. EXAMPLE
+
+Here is a sample deploy.rb file using cap_recipes:
+
+<pre><code>
+# =============================================================================
+# 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"
+</code></pre>
+
+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:
+
+<code>
+  cap-recipes [path] [task1] [task2] [task3]
+</code>
+
+
+include memcache,apache, and passenger recipes
+
+<code>
+  cap-recipes . memcache apache passenger
+</code>
+
+show all available recipes
+
+<code>
+  cap-recipes --list | cap-recipes -l
+</code>
+
+show help
+
+<code>
+  cap-recipes --help | cap-recipes -h
+</code>
+
+generate standard capify
+
+<code>
+  cap-recipes . | cap-recipes
+</code>
+
+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.