capitate 0.2.11 → 0.2.13

data/History.txt

@@ -1,3 +1,12 @@
+== 0.2.13 2008-03-26
+
+* Fixing monit re/start for mongrel cluster and backgroundrb
+
+== 0.2.12 2008-03-26
+
+* Re-formatting some documentation, experimenting with getting source in the docs (FAIL!)
+* Including backgroundrb logrotate, monit, restart
+
 == 0.2.11 2008-03-25
 
 * Backgroundrb recipes and templates

data/Manifest.txt

@@ -38,6 +38,7 @@ lib/recipes/centos/nginx.rb
 lib/recipes/centos/ruby.rb
 lib/recipes/centos/sphinx.rb
 lib/recipes/docs.rb
+lib/recipes/logrotate/backgroundrb.rb
 lib/recipes/logrotate/mongrel_cluster.rb
 lib/recipes/logrotate/monit.rb
 lib/recipes/logrotate/nginx.rb
@@ -45,8 +46,14 @@ lib/recipes/logrotate/rails.rb
 lib/recipes/logrotate/sphinx.rb
 lib/recipes/logrotated.rb
 lib/recipes/memcached.rb
-lib/recipes/mongrel_cluster.rb
 lib/recipes/monit.rb
+lib/recipes/monit/backgroundrb.rb
+lib/recipes/monit/memcached.rb
+lib/recipes/monit/mongrel_cluster.rb
+lib/recipes/monit/mysql.rb
+lib/recipes/monit/nginx.rb
+lib/recipes/monit/sphinx.rb
+lib/recipes/monit/sshd.rb
 lib/recipes/mysql.rb
 lib/recipes/nginx.rb
 lib/recipes/rails.rb
@@ -54,6 +61,7 @@ lib/recipes/sphinx.rb
 lib/recipes/sshd.rb
 lib/recipes/syslogd.rb
 lib/templates/backgroundrb/backgroundrb.initd.centos.erb
+lib/templates/backgroundrb/backgroundrb.monitrc.erb
 lib/templates/backgroundrb/backgroundrb.yml.erb
 lib/templates/capistrano/Capfile
 lib/templates/logrotated/conf.erb
@@ -92,7 +100,9 @@ test/test_roles.rb
 test/test_templates.rb
 website/index.html
 website/index.txt
+website/javascripts/code_highlighter.js
 website/javascripts/rounded_corners_lite.inc.js
+website/javascripts/ruby.js
 website/stylesheets/screen.css
 website/template.rhtml
 website/template_recipe.rhtml

data/lib/capitate/cap_ext/connections.rb

@@ -12,13 +12,21 @@ module Capitate
       # establishes connections to them, and then yields that list of
       # servers.
       #
-      # Overriden to handle NoMatchingServersError as NON-FATAL
+      # If you set:
+      #
+      #   set :ignore_missing_roles, true
+      #
+      # Overriden to handle NoMatchingServersError as NON-FATAL.      
       #  
-      def execute_on_servers_with_capitate(options={}, &block)
-        begin
+      def execute_on_servers_with_capitate(options={}, &block)        
+        if exists?(:ignore_missing_roles) && fetch(:ignore_missing_roles)        
+          begin
+            execute_on_servers_without_capitate(options, &block)
+          rescue Capistrano::NoMatchingServersError => e
+            logger.important "`#{current_task.fully_qualified_name}' is only run for servers matching #{current_task.options.inspect}, but no servers matched"
+          end
+        else
           execute_on_servers_without_capitate(options, &block)
-        rescue Capistrano::NoMatchingServersError => e
-          logger.important "`#{current_task.fully_qualified_name}' is only run for servers matching #{current_task.options.inspect}, but no servers matched"
         end
       end
   
@@ -59,7 +67,7 @@ module Capitate
         clear_sessions
       end
   
-      # Yields the previous user.
+      # Perform action as a different user. Yields the previous user to the block.
       #
       # ==== Options
       # +new_user+:: User to become
@@ -81,8 +89,7 @@ module Capitate
         clear_sessions
       end
   
-      # Close all open sessions.
-      # Will force user to re-login.
+      # Close all open sessions, and will force user to re-login.
       def clear_sessions    
         sessions.each do |key, session|
           logger.info "Closing: #{key}"

data/lib/capitate/cap_ext/run_via.rb

@@ -2,6 +2,8 @@ module Capitate::CapExt::RunVia
   
   # Invoke command with current run_method setting.
   #
+  # Chooses +sudo+ or +run+ based on <tt>:run_method</tt> setting.
+  #
   # ==== Options
   # +cmd+:: Command to run
   # +options+:: Options (see invoke_command options)

data/lib/capitate/cap_ext/variables.rb

@@ -7,7 +7,7 @@ module Capitate
         base.send :alias_method, :fetch, :fetch_with_capitate
       end
     
-      # Fetch (alias method chained) variable.
+      # Fetch.
       # Displays usage message from recipe docs if variable not found.
       #
       # See capistrano fetch for usage info.
@@ -72,7 +72,7 @@ module Capitate
         nil        
       end
       
-      # Fetch roles with name and options
+      # Fetch roles with name and options.
       # I don't actually use this.
       #
       # ==== Options
@@ -124,6 +124,13 @@ module Capitate
         return matched.first if matched
         nil
       end
+      
+      
+      def link_to_source(recipe_path)
+        full_path = File.expand_path(recipe_path)
+        project_path = File.expand_path(File.dirname(__FILE__) + "/../../../")
+        "http://github.com/gabriel/capitate/tree/master#{full_path.sub(project_path, "")}"
+      end
     
     end
   end

data/lib/capitate/plugins/base.rb

@@ -5,17 +5,16 @@ require 'yaml'
 module Capitate::Plugins::Base
   
   # Project root. Fetch from :project_root, or fall back to RAILS_ROOT.
-  #
   def root
-    if respond_to?(:fetch)
-      return fetch(:project_root)
-    else
-      RAILS_ROOT
-    end
+    return fetch(:project_root) if exists?(:project_root)
+    RAILS_ROOT
   end
     
   # Path relative to project root.
-  # Project root is set via, set :project_root, "path/to/project" in Capfile.
+  #
+  # To set the project root:
+  #
+  #   set :project_root, "path/to/project" in Capfile.
   #
   # ==== Options
   # +path+:: Relative path
@@ -48,7 +47,7 @@ module Capitate::Plugins::Base
   # Usage for current task.
   #
   # ==== Options
-  # +variable+:: Missing variable setting
+  # +variable+:: Missing variable setting (to display as not set)
   #
   # ==== Examples
   #   usage(:gem_list) => "Description from task definition."
@@ -86,7 +85,13 @@ module Capitate::Plugins::Base
     s.split("\n").collect { |sp| "#{indentation}#{sp}"}.join("\n")
   end
   
-  # Unindent, lifted from capistrano bin/capify
+  # Unindent.
+  #
+  # Lifted from capistrano bin/capify
+  #
+  # ==== Options
+  # +string+:: String to unindent
+  #
   def unindent(string)
     return "" if string.blank?
     if string =~ /\A(\s*)/
@@ -96,7 +101,7 @@ module Capitate::Plugins::Base
     string
   end  
   
-  # Load all tasks
+  # Load all tasks into an array.
   def load_all_tasks
     tasks = []
     top.namespaces.each do |namespace|
@@ -105,7 +110,7 @@ module Capitate::Plugins::Base
     tasks
   end
   
-  # Task tree
+  # Build a task tree, consisting of task nodes.  
   def task_tree
     top_node = Capitate::TaskNode.new("top")
     
@@ -116,7 +121,7 @@ module Capitate::Plugins::Base
   end
 
 protected
-  
+    
   def load_tasks(namespace, tasks = [])    
     recipe = namespace.last
     

data/lib/capitate/plugins/build.rb

@@ -4,16 +4,17 @@ module Capitate::Plugins::Build
   #
   # ==== Options
   # +name+:: Name for app
-  # +options+:: Options 
-  # - +build_dest+:: Place to build from, ex. /usr/src, defaults to /tmp/name
-  # - +url+:: URL to download package from
-  # - +configure_options+:: Options for ./configure
-  # - +symlink+:: After install, list of source, dest pairs to symlink 
+  # +options+:: Options (See Make install options)
+  #
+  # ==== Make install options
+  # +build_dest+:: Place to build from, ex. /usr/src, defaults to /tmp/name
+  # +url+:: URL to download package from
+  # +configure_options+:: Options for ./configure
+  # +symlink+:: After install, list of source, dest pairs to symlink 
   #    [ { "/usr/local/sphinx-0.9.8-rc1" => "/usr/local/sphinx" }, ... ]
   #    ln -s /usr/local/sphinx-0.9.8-rc1 /usr/local/sphinx
-  #
-  # - +unpack_dir+:: Directory that is unpacked from tgz (if not matching the file name)
-  # - +to_log+:: If specified, will redirect output to this path
+  # +unpack_dir+:: Directory that is unpacked from tgz (if not matching the file name)
+  # +to_log+:: If specified, will redirect output to this path
   #
   # ==== Examples (in capistrano task)
   #   build.make_install("nginx", { :url => "http://sysoev.ru/nginx/nginx-0.5.35.tar.gz", ... })
@@ -44,9 +45,11 @@ module Capitate::Plugins::Build
   # 
   # ==== Options
   # +name+:: Name for app
-  # +options+:: Options
-  # - +build_dest+:: Place to build from, ex. /usr/src, defaults to /tmp/name
-  # - +url+:: URL to download package from
+  # +options+:: Options (see Install options)
+  #
+  # ==== Install options
+  # +build_dest+:: Place to build from, ex. /usr/src, defaults to /tmp/name
+  # +url+:: URL to download package from
   # 
   # ==== Examples (in capistrano task)
   #   script.make("rubygems", { :url => :url => "http://rubyforge.org/frs/download.php/29548/rubygems-1.0.1.tgz" }) do |dir|

data/lib/capitate/plugins/prompt.rb

@@ -16,10 +16,12 @@ module Capitate::Plugins::Prompt
   #
   # ==== Options
   # +label+:: Label
-  # +options+:: Options
-  # - +verify+:: If true, prompt twice and verify
-  # - +lazy+:: If true, returns a Proc. _Defaults to true_
-  # - +check_hash+:: If present, checks that md5 is same as password md5
+  # +options+:: Options (see Password options)
+  #
+  # ==== Password options
+  # +verify+:: If true, prompt twice and verify
+  # +lazy+:: If true, returns a Proc. _Defaults to true_
+  # +check_hash+:: If present, checks that md5 is same as password md5
   #
   def password(label, options = {})
     
@@ -67,10 +69,6 @@ module Capitate::Plugins::Prompt
     password_prompt.call
   end  
   
-  def check_password_hash(password, hash)
-    MD5.md5()
-  end
-  
 end
 
 Capistrano.plugin :prompt, Capitate::Plugins::Prompt

data/lib/capitate/plugins/script.rb

@@ -36,9 +36,11 @@ module Capitate::Plugins::Script
   # ==== Options
   # +url+:: URL to download
   # +dest+:: Destination directory
-  # +options+::
-  # - +clean+:: If true will remove the unpacked directory. _Defaults to true_
-  # - +unpack_dir+:: Directory that is unpacked from tgz (if not matching the file name)
+  # +options+:: Options (see Unpack options)
+  #
+  # ==== Unpack options
+  # +clean+:: If true will remove the unpacked directory. _Defaults to true_
+  # +unpack_dir+:: Directory that is unpacked from tgz (if not matching the file name)
   #
   # ==== Examples
   #   script.unpack("http://rubyforge.org/frs/download.php/29548/rubygems-1.0.1.tgz", "/tmp/rubygems") do
@@ -80,7 +82,7 @@ module Capitate::Plugins::Script
   #
   # ==== Options
   # +cmds+:: Commands (separated by newlines)
-  # +options+:: See invoke_command options
+  # +options+:: See Capistrano invoke_command options
   #
   def run_all(cmds, options = {}, &block)    
     cmds.split("\n").each do |cmd|

data/lib/capitate/plugins/templates.rb

@@ -1,6 +1,6 @@
 module Capitate::Plugins::Templates
   
-  # Load template. If extension is erb will be evaluated with binding.
+  # Load template. If the extension is .erb will be evaluated with binding.
   #
   # You can add to the list of places we search for templates by setting:
   #
@@ -17,8 +17,9 @@ module Capitate::Plugins::Templates
   # +override_binding+:: Binding to override, otherwise uses current (task) binding
   #
   # ==== Examples
-  #   template.load("memcached/memcached.monitrc.erb")
-  #   put template.load("memcached/memcached.monitrc.erb"), "/tmp/memcached.monitrc"
+  #   template.load("memcached/memcached.monitrc.erb") => "This is the text of eval'ed template found at ..."
+  #
+  #   put template.load("memcached/memcached.monitrc.erb"), "/tmp/memcached.monitrc" # Uploads eval'ed template to remote /tmp/ directory
   #
   def load(path, override_binding = nil)
     template_dirs_found = template_dirs.select { |dir| File.exist?("#{dir}/#{path}") }
@@ -69,9 +70,16 @@ module Capitate::Plugins::Templates
     
 protected
 
-  # Load all possible places for templates
+  # Load all possible places for templates.
+  #
+  # Returns:
+  # * the <tt>:templates_dirs</tt> setting (if set)
+  # * the current directory
+  # * the <tt>:project_root</tt> setting (if set)
+  # * the gem templates path
+  #
   def template_dirs
-    @template_dir ||= begin
+    @template_dirs ||= begin
       template_dirs = []      
       template_dirs += fetch(:templates_dirs) if exists?(:templates_dirs)      
       template_dirs << "."
@@ -88,11 +96,12 @@ protected
   
   # Get full template path from relative path.
   #
-  # Something like <tt>monit/monit.cnf => /usr/lib/..../capitate/lib/templates/monit/monit.cnf</tt>.
-  #
   # ==== Options 
   # +template_path+:: Relative path
   #
+  # ==== Examples
+  #    gem_template_path("monit/monit.cnf") => /usr/lib/..../capitate/lib/templates/monit/monit.cnf
+  #
   def gem_template_path(template_path)
     File.join(gem_templates_root, template_path)
   end

data/lib/capitate/plugins/upload.rb

@@ -1,11 +1,12 @@
 module Capitate::Plugins::Upload
   
   # Upload file with source path.
+  #
   # Data is streamed.
   #
   # ==== Options
   # +src_path+:: Source path
-  # +dest_path:: Remote destination path
+  # +dest_path+:: Remote destination path
   # +options+:: Options (see capistrano 'put')
   #
   # ==== Examples

data/lib/capitate/plugins/utils.rb

@@ -27,12 +27,14 @@ module Capitate::Plugins::Utils
   # ==== Options
   # +template_path+:: Path to template
   # +destination+:: Remote path to evaluated template
-  # +options+::
-  # - +user+:: User to install (-o)
-  # - +mode+:: Mode to install file (-m)
+  # +options+:: Options (see Install template options)
+  #
+  # ==== Install template options
+  # +user+:: User to install (-o). Defaults to *root*.
+  # +mode+:: Mode to install file (-m)
   #
   # ==== Example
-  #   utils.install_template("monit/memcached.monitrc.erb", "/etc/monit/memcached.monitrc")
+  #   utils.install_template("monit/memcached.monitrc.erb", "/etc/monit/memcached.monitrc", :user => "root", :mode => "600")
   #
   def install_template(template_path, destination, options = {})
     # Truncate extension
@@ -96,7 +98,7 @@ module Capitate::Plugins::Utils
   # ==== Options
   # +path+:: Path to file to append to
   # +data+:: String data to append
-  # +check+:: If not nil, will check to see if egrep matches "^string_to_check" and will not re-append
+  # +check+:: If not nil, will check to see if egrep matches this regex and will not re-append
   # +left_strip+:: If true (default), remove whitespace before lines
   # +should_exist+:: If true (default), raise error if file does not exist
   #

data/lib/capitate/task_node.rb

@@ -50,13 +50,11 @@ class Capitate::TaskNode
   end
   
   # Get "child" nodes (sorted).
-  #
   def sorted_nodes
     nodes.sort_by(&:name)
   end
   
   # Get tasks (sorted).
-  #
   def sorted_tasks
     tasks.sort_by(&:fully_qualified_name) # { |t| t.name.to_s }
   end
@@ -107,6 +105,8 @@ class Capitate::TaskNode
     file_name ||= full_name
     title ||= full_name(":")
     
+    
+    
     path = "#{dir}/#{file_name}.txt"
     puts "%10s %-30s" % [ "create", path ]
     
@@ -159,15 +159,18 @@ class Capitate::TaskNode
       unless tasks.empty?
         file.puts "\n\nh2. Task documentation\n\n"        
         sorted_tasks.each do |task|
+          file.puts %{<div class="recipe">\n\n}
           file.puts "h3(##{task.fully_qualified_name}). #{task.fully_qualified_name}\n\n"
-          file.puts "#{unindent(task.desc)}\n\n\n\n"
+          file.puts "#{unindent(task.desc)}\n\n"                    
+          file.puts "</div>\n\n\n"
         end
       end
       
       #
       # Write doc (recursively for "child" namespace)
+      #
       sorted_nodes.each do |snode|
-        snode.write_doc(dir)
+        snode.write_doc(dir, nil, nil, options)
       end
       
       # If block then let it do stuff with open file
@@ -179,7 +182,6 @@ class Capitate::TaskNode
   end
   
   # Node to string. 
-  #
   def to_s(level = 0)
     spaces = "     "
     indent = (0...level).collect { spaces }.join("") 
@@ -197,37 +199,33 @@ class Capitate::TaskNode
       s += node.to_s(level + 1)
     end
     s
-  end
+  end    
     
-  # Class methods  
-  class << self
+  # Create nodes and and task to node.
+  #
+  # If task is "mysql:centos:install", the nodes will look like:
+  #
+  #   (top node) -> (mysql node) -> (centos node; w/ tasks: install)
+  #
+  # ==== Options
+  # +top_node+:: Node to start at
+  # +task+:: Task to add
+  #    
+  def self.populate_with_task(top_node, task)
+    node_names = task.namespace.fully_qualified_name.split(":")
     
-    # Create nodes and and task to node.
-    #
-    # If task is "mysql:centos:install", the nodes will look like:
-    #
-    #   (top node) -> (mysql node) -> (centos node; w/ tasks: install)
-    #
-    # ==== Options
-    # +top_node+:: Node to start at
-    # +task+:: Task to add
-    #    
-    def populate_with_task(top_node, task)
-      node_names = task.namespace.fully_qualified_name.split(":")
-      
-      node = top_node
-      
-      node_names.each do |name|
-        parent_node = node
-        node = parent_node.find(name)
-        if !node
-          node = self.new(name, parent_node)
-          parent_node.add_node(node)
-        end
+    node = top_node
+    
+    node_names.each do |name|
+      parent_node = node
+      node = parent_node.find(name)
+      if !node
+        node = self.new(name, parent_node)
+        parent_node.add_node(node)
       end
-      node.add_task(task)      
     end
-  
+    node.add_task(task)      
   end
+
 end
   

data/lib/capitate/version.rb

@@ -2,7 +2,7 @@ module Capitate #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 2
-    TINY  = 11
+    TINY  = 13
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/recipes/backgroundrb.rb

@@ -7,9 +7,21 @@ namespace :backgroundrb do
   
     pid_file = "\#{CONFIG_FILE[:backgroundrb][:pid_file]}"
   
-  *backgroundrb_host*: Backgroundrb host. _Defaults to 0.0.0.0_\n
-  *backgroundrb_port*: Backgroundrb port. _Defaults to 11006_\n
-  *backgroundrb_yml_template*: Backgroundrb yml template. _Defaults to @backgroundrb/backgroundrb.yml.erb@ in this gem.\n
+  <dl>
+    <dt>backgroundrb_host</dt>
+    <dd>Backgroundrb host</dd>
+    <dd class="default">Defaults to @0.0.0.0@</dd>
+    
+    <dt>backgroundrb_port</dt>
+    <dd>Backgroundrb port</dd>
+    <dd class="default">Defaults to @11006@</dd>
+  
+    <dt>backgroundrb_yml_template</dt>
+    <dd>Backgroundrb yml template</dd>
+    <dd class="default">Defaults to @backgroundrb/backgroundrb.yml.erb@ in this gem.</dd>
+  </dl>
+  
+  "Source":#{link_to_source(__FILE__)}
   DESC
   task :setup do
     fetch_or_default(:backgroundrb_host, "0.0.0.0")
@@ -21,7 +33,9 @@ namespace :backgroundrb do
   end
   
   desc <<-DESC
-  Symlink backgroundrb config into release path.  
+  Symlink backgroundrb config into current path.  
+  
+  "Source":#{link_to_source(__FILE__)}
   DESC
   task :update_code do
     run "ln -nfs #{shared_path}/config/backgroundrb.yml #{release_path}/config/backgroundrb.yml" 

data/lib/recipes/centos/backgroundrb.rb

@@ -5,13 +5,20 @@ namespace :backgroundrb do
     desc <<-DESC
     Setup backgroundrb for application.
     
-    *backgroundrb_bin_path*: Path to start. _Defaults to @{current_path}/script/backgroundrb start@_\n
-    *backgroundrb_pid_path*: Path to backgroundrb pid file. _Defaults to @{shared_path}/pids/backgroundrb.pid@_\n
+    <dl>
+    <dt>backgroundrb_bin_path</dt>
+    <dd>Path to start.
+    <dd class="default">Defaults to @\#{current_path}/script/backgroundrb -e production start@</dd>
+    <dt>backgroundrb_pid_path</dt>
+    <dd>Path to backgroundrb pid file</dd>
+    <dd class="default">Defaults to @\#{shared_path}/pids/backgroundrb.pid@</dd>
+    </dl>
+    "Source":#{link_to_source(__FILE__)}
     DESC
     task :setup do       
       
       # Settings
-      fetch_or_default(:backgroundrb_bin_path, "#{current_path}/script/backgroundrb -e production")
+      fetch_or_default(:backgroundrb_bin_path, "#{current_path}/script/backgroundrb -e production start")
       fetch_or_default(:backgroundrb_pid_path, "#{shared_path}/pids/backgroundrb.pid")
 
       # Install initscript      

data/lib/recipes/centos/centos.rb

@@ -5,14 +5,27 @@ namespace :centos do
   desc <<-DESC
   Add user and set user password for application. Adds user to specified groups. 
   
-  *user_add*: User to add.\n
-  @set :user_add, "app_user"@
-  *groups*: Groups for user to be in. _Defaults to none_\n
-  @set :groups, "admin,foo"@\n
-  *home*: Home directory for user. _Defaults to <tt>:deploy_to</tt> setting_\n
-  @set :home, "/var/www/apps/app_name"@\n
-  *home_readable*: Whether home permissions are readable by all. Needed if using deploy dir as home. _Defaults to true_\n
-  @set :home_readable, true@\n
+  <dl>
+  <dt>user_add</dt>
+  <dd>User to add.</dd>
+  <dd>@set :user_add, "app_user"@</dd>
+
+  <dt>groups</dt>
+  <dd>Groups for user to be in.</dd>
+  <dd class="default">Defaults to @nil@</dd>
+  <dd>@set :groups, "admin,foo"@</dd>
+  
+  <dt>home</dt>
+  <dd>Home directory for user.</dd>
+  <dd class="default">Defaults to @:deploy_to@ setting_</dd>  
+  <dd>@set :home, "/var/www/apps/app_name"@</dd>
+  
+  <dt>home_readable</dt>
+  <dd>Whether home permissions are readable by all. Needed if using deploy dir as home.</dd>
+  <dd class="default">Defaults to @true@</dd>
+  <dd>@set :home_readable, true@</dd>  
+  </dl>
+  "Source":#{link_to_source(__FILE__)}
   DESC
   task :add_user do
     

data/lib/recipes/centos/imagemagick.rb

@@ -3,13 +3,16 @@ namespace :imagemagick do
   
     desc <<-DESC
     Install imagemagick.\n    
-    *imagemagick_build_options*: Imagemagick build options.
+    <dl><dt>imagemagick_build_options</dt><dd>Imagemagick build options</dd></dl>
     <pre>
+    <code class="ruby">
     set :imagemagick_build_options, {
       :url => "ftp://ftp.imagemagick.org/pub/ImageMagick/ImageMagick.tar.gz",
       :unpack_dir => "ImageMagick-*"
     }
+    </code>
     </pre>
+    "Source":#{link_to_source(__FILE__)}
     DESC
     task :install do