capistrano-runit-tasks 0.1.0 → 0.2.0

data/ChangeLog

@@ -0,0 +1,17 @@
+*0.2.0* (March 23rd 2006)
+
+* Added RunitServiceHelper which adds service.add to allow easy creation of
+  services. Refactored other code to use new functionality.
+
+* Made runner.create handle file based templates, changed it's API slightly
+
+* Added RunitCommandHelper, which adds an sv command to send signals to
+  services e.g. sv.up. Can set :sv_command to :sv or :runsvctrl to choose
+  which binary to run on there server
+
+* Changed default master_service_dir to ~/service to match the defendem.com
+  instructions
+
+* Changed default fcgi_listener_base_port to 9000
+
+* Added tests for 0.1.0

data/README

@@ -10,12 +10,10 @@ make it easy to add other services in your deploy.rb.
 
 == Status
 
-capistrano-runit-tests 0.1.0 (known as cap-runit from now on) is the first
+capistrano-runit-tests 0.2.0 (known as cap-runit from now on) is the second
 release of the library. It will need more work to be useful to everybody who
-uses runit. The intention of releasing it now is to find out which areas need
-improvement first and get working on them. It's was developed and tested with
-the Debian sarge version of runit, 1.0.5 so currently uses runsvctrl rather
-than sv.
+uses runit. It supports both the sv and runsvctrl/runsvstat versions of runit.
+Support for daemontools svc command will be added at a later date.
 
 The current version assumes you have a runit setup similar to the one created
 in http://www.defendem.com/read/chapter/5#page6, i.e. a supervised directory
@@ -30,7 +28,7 @@ Install the package via gems or .tgz / .zip and setup.rb.
 
 Include it in your deploy.rb with: 
 
-require 'capistrano-runit-tasks'
+require "capistrano-runit-tasks"
 
 Then run:
 
@@ -42,8 +40,8 @@ and point your webserver at the new listener.
 
 == Usage
 
-When you require 'runit-tasks' it replaces the following cap tasks with runit
-versions:
+When you require "capistrano-runit-tasks" it replaces the following cap tasks
+with runit versions:
 
 * cold_deploy
 * restart
@@ -72,7 +70,13 @@ Then adds the following tasks, helpers and variables:
                           (Default: 1)
 
 [fcgi_listener_base_port] The base port number to use for the fcgi listeners.
-                          (Default: 8000)
+                          (Default: 9000)
+
+[sv_command]               Either :sv or :runsvctrl
+                           (Default: sv)
+                           
+[runner_template_path]     The path to search for custom templates.
+                           (Default: templates/runit)
 
 cap-runit creates a directory for each listener you ask for. At the moment the
 directories are created by setup_service_dirs. Later versions should allow for
@@ -93,36 +97,48 @@ in deploy.rb you'll get foo-8500, foo-8501 etc.
                      fcgi_count to yield each of the fcgi port numbers back to
                      the calling block
 
-[runner.create]      Creates runner scripts, see the rdoc or comments above
-                     the method for how it's used.
+[fcgi_listener_dirs] Returns an array containing the path to each of the fcgi
+                     listener dirs. This is useful when sending commands using
+                     sv as it accepts an array of directories as an argument
+                     
+[service.add]        Adds a new service to the application, see the
+                     documentation in RunitServiceHelper for more
+                     
+[sv.<signal>]        Sends the signal given to services you choose. See the 
+                     documentation in RunitCommandHelper for more details.
+
+[runner.create]      Creates runner scripts, see the documentation in
+                     RunitRunnerHelper method for how it's used.
 
 == Logging
 
-The default tasks create a log directory under each service directory. For
-your own services, this has do be done manually for now. The intention
-is to make it automatic and then allow the generic template to be overridden
-easily.
+The default tasks create a log directory under each service directory. You can
+override the default log template as described below if you need something
+different.
+
+== Overriding the default templates
+
+The directory pointed to by the runner_template_path variable is searched
+before the directory containing the default templates. If you want to override
+the default templates, create default_fcgi_runner.rhtml and/or
+default_log_runner.rhtml and cap-runit will pick your custom versions first.
 
 == Adding your own services
 
-To add your own service directories and run scripts, add
-after_setup_service_dirs, after_spinner and after_restart tasks to your
-deploy.rb that look something like these:
+The example below assumes you are creating a service called mailer.
 
- task :after_setup_service_dirs do
-   puts 'Creating mailer service directory'
-   mailer_service_dir = "#{deploy_to}/#{service_dir}/mailer"
-   run "mkdir -p #{mailer_service_dir}/log/main"
+To add your own service directories and run scripts, add a template to
+templates/runit called mailer_runner with contents:
 
-   mailer_run_template = <<-TEMPLATE
  #!/bin/sh -e
  export RAILS_ENV=production
  exec 2>&1  /usr/bin/env ruby <%= application_dir %>/current/script/mailer
-   TEMPLATE
 
-   runner.create :runner, mailer_service_dir,
-                  mailer_run_template, :application_dir => deploy_to
-   runner.create :log, mailer_service_dir  
+Then, in your deploy.rb create after_setup_service_dirs, after_spinner and
+after_restart tasks that look something like these:
+
+ task :after_setup_service_dirs do
+   service.add 'mailer'
  end
 
  task :after_spinner do
@@ -138,12 +154,10 @@ deploy.rb that look something like these:
 
 So the process is:
 
-* make the service directory
-* create a rhtml template for your runner (string only for now, sorry)
-* create a runner from the template
-* create the logger
-
-This is will be wrapped in a helper function at the earliest opportunity.
+* create the runner template (and logger if you need, see docs)
+* add the service
+* add a spinner task to get runit to start supervising
+* add the tasks to stop and start as needed
 
 == Switching from spinner/spawner/reaper
 
@@ -160,12 +174,12 @@ This again should be automated, the manual steps I used were:
 
 == TODO
 
-* Make runner.create use file based templates
-* Intead of run "runsvctrl ..." have an sv helper method like sv :up, svc_dir
-* Setting for sv program to use, runsvctrl or sv
-* Automatically create log directories with custom templates
-* add_service(path, runner, logger = nil) helper function
-  e.g. add_service(path, {:template => 'my_runner', :port => 1234})
-  Which would set a custom runner and a standard logger
 * Allow add_service to create more than one directory to be supervised 
-* Add task to automate switching from spinner
+* Add task to automate switching from spinner
+* Make which servers the code runs on configurable
+* Make the rails env configurable
+* Allow creation of other files such as log/config
+* Add support for daemontools svc command
+* Make the RAILS_ENV configurable
+* Add helper methods to make linking the services into the master service
+  directory easier

data/lib/capistrano-runit-tasks-templates/default_fcgi_runner.rhtml

@@ -0,0 +1,3 @@
+#!/bin/sh -e
+export RAILS_ENV=production
+exec 2>&1  /usr/bin/env spawn-fcgi -n -f <%= deploy_to %>/current/public/dispatch.fcgi -p <%= fcgi_port %>

data/lib/capistrano-runit-tasks-templates/default_log_runner.rhtml

@@ -0,0 +1,2 @@
+#!/bin/sh -e
+exec svlogd -t ./main

data/lib/capistrano-runit-tasks.rb

@@ -1,10 +1,14 @@
 require 'runit_runner_helper'
+require 'runit_command_helper'
+require 'runit_service_helper'
 
 Capistrano.configuration(:must_exist).load do
   set :service_dir, 'service'
   set :fcgi_count, 1
-  set :master_service_dir, '~/services'
-  set :fcgi_listener_base_port, 8000
+  set :master_service_dir, '~/service'
+  set :fcgi_listener_base_port, 9000
+  set :sv_command, :sv # can be :sv or :runsvctrl
+  set :runner_template_path, File.join('templates', 'runit')
    
   # We need our own task for this as the default cold_deploy
   # calls restart, which won't work until we've setup the 
@@ -21,15 +25,11 @@ Capistrano.configuration(:must_exist).load do
 
   desc "Sets up services directories for supervising fcgi using runit"
   task :setup_service_dirs do
-    puts 'Creating service directories'
     application_service_dir = "#{deploy_to}/#{service_dir}"
     run  "mkdir -p #{application_service_dir}"
         
     each_fcgi_listener do |fcgi_listener_port|
-      fcgi_service_dir = "#{application_service_dir}/#{fcgi_listener_port}"
-      run "mkdir -p #{fcgi_service_dir}/log/main"
-      runner.create :runner, fcgi_service_dir, :fcgi, :application_dir => deploy_to, :fcgi_port => fcgi_listener_port
-      runner.create :log, fcgi_service_dir
+      service.add fcgi_listener_port, :template => :fcgi, :fcgi_port => fcgi_listener_port
     end
   end
     
@@ -43,12 +43,7 @@ Capistrano.configuration(:must_exist).load do
   
   desc "restart task for runit supervised fcgis"
   task :restart do
-    each_fcgi_listener do |fcgi_listener_port|
-      fcgi_service_dir = "#{deploy_to}/#{service_dir}/#{fcgi_listener_port}"      
-
-      # Signal USR2 is what reaper does
-      run  "runsvctrl 2 #{fcgi_service_dir}"
-    end
+    sv.usr2 fcgi_listener_dirs      
   end
   
   desc "Hook into after setup to create the runit service directory"
@@ -61,4 +56,10 @@ Capistrano.configuration(:must_exist).load do
       yield fcgi_listener_port
     end
   end
+  
+  def fcgi_listener_dirs
+    dirs = []
+    each_fcgi_listener { |port| dirs << "#{deploy_to}/#{service_dir}/#{port}" }
+    dirs
+  end
 end

data/lib/runit_command_helper.rb

@@ -0,0 +1,52 @@
+begin
+  require 'capistrano'
+rescue LoadError
+  require 'rubygems'
+  require 'capistrano'
+end
+
+# This module provides a facade to allow signals to be set to runit managed
+# service directories from Capistrano. It uses the <tt>sv_command</tt> variable to decide
+# which command to run on the server and currently supports both <tt>sv</tt> and <tt>runsvctrl</tt>.
+#
+# The <tt>:sv_command</tt> variable can be set to <tt>:sv</tt> or <tt>:runsvctrl</tt> to choose.
+#
+# The supported signals are shown in the <tt>SIGNALS</tt> constant below.
+#
+# Usage examples:
+# * <tt>sv.usr2 "/path/to/service/dir"</tt>
+# * <tt>sv.down ["foo1", "foo2"]</tt>
+#
+# As daemontools is very similar, support for that will be added at a later date.
+#
+# The methods are available through sv.<method name> in your deploy.rb
+module RunitCommandHelper
+  SIGNALS = %w(up down once pause cont hup alarm interrupt quit usr1 usr2 term kill status)
+
+  SIGNALS.each do |signal|
+    if signal =~ /usr([1|2])/ then
+      cmd = $1
+    else
+      cmd = signal
+    end
+
+    define_method(signal) do |service_dirs|
+      service_dirs = service_dirs.join(" ") if service_dirs.is_a? Array
+      run "#{get_command(signal, cmd)} #{service_dirs}"
+    end
+  end
+
+  protected
+  def get_command(signal, cmd)
+    case configuration.sv_command
+      when :sv
+        "sv #{cmd}"
+      when :runsvctrl
+        signal == 'status' ? 'runsvstat' : "runsvctrl #{cmd}"
+      else
+        raise "Error: sv_command setting of #{configuration.sv_command} is unsupported"
+    end
+  end  
+end
+
+Capistrano.plugin :sv, RunitCommandHelper

data/lib/runit_runner_helper.rb

@@ -1,32 +1,79 @@
-require 'capistrano'
+begin
+  require 'capistrano'
+rescue LoadError
+  require 'rubygems'
+  require 'capistrano'
+end
 
+# This module provides methods to ease creating run scripts in service directories.
+#
+# The methods are available through runner.<method name> in your deploy.rb 
 module RunitRunnerHelper
-  FCGI_TEMPLATE = <<-TEMPLATE
-#!/bin/sh -e
-export RAILS_ENV=production
-exec 2>&1  /usr/bin/env spawn-fcgi -n -f <%= application_dir %>/current/public/dispatch.fcgi -p <%= fcgi_port %>
-    TEMPLATE
-
-  LOG_TEMPLATE = <<-TEMPLATE
-#!/bin/sh -e
-exec svlogd -t ./main
-    TEMPLATE
-
-  # Wrapper to render a file from a string template (file template not supported yet)
-  # and put it on the server at the given path. The file permissions are set to 0700.
-  # options are passed through to the call to render.
-  # runner_type can be :log or :runner
-  def create(runner_type, path, template = nil, options = {})
-    runner_path = "#{path}#{runner_type == :log ? '/log/run' : '/run'}"
-    case runner_type
+  # Creates a runner from a template, puts it on the server at the given
+  # path and sets file permissions to 0700.
+  #
+  # * service_dir should be the path to your service directory, it should not 
+  #   include run or log/run, these are added by create.
+  # * template can be :log, :fcgi, the name of a file or a string.
+  #   :log and :fcgi create the standard logger/fcgi templates,
+  #   see get_template below for a list of places searched for template files.
+  # * If you're making a custom log runner, include :log_runner => true in the 
+  #   options so create knows to put the contents in service_dir/log/run, you  
+  #   don't need this if you're using the standard :log template.
+  # * options except for :log_runner are assumed to be for the template and 
+  #   are passed through to render. 
+  def create(service_dir, template, options = {})
+    case template
       when :log
-        template = LOG_TEMPLATE
-      else
-        template = FCGI_TEMPLATE if template == :fcgi  
+        template = 'default_log_runner'
+        options.merge!(:log_runner => true)
+      when :fcgi
+        template = 'default_fcgi_runner'
     end
     
-    put render(options.merge(:template => template)), runner_path, :mode => 0700    
+    path = "#{service_dir}/#{options[:log_runner] ? 'log/run' : 'run'}" 
+    options.delete(:log_runner)
+    
+    options = add_default_options(options)
+
+    runner = render options.merge(:template => get_template(template))
+
+    put runner, path, :mode => 0700    
   end  
+  
+  # Works out whether the given template is a file or string containing rhtml.
+  # 
+  # Checks:
+  # * current directory
+  # * runner_templates path (defaults to templates/runit)
+  # * capistrano-runit-tasks-templates dir where cappy-runit is installed
+  #   (the standard templates are here)
+  # 
+  # If it can't find the file it assumes it's a one line string template and 
+  # returns that
+  def get_template(template)
+    if template =~ /<%/ or template =~ /\n/
+      template
+    else
+      [ ".",
+        configuration.runner_template_path,
+        File.join(File.dirname(__FILE__), 'capistrano-runit-tasks-templates')
+      ].each do |dir|
+        if File.file?(File.join(dir, template))
+          return File.read(File.join(dir, template))
+        elsif File.file?(File.join(dir, template + ".rhtml"))
+          @file_template_full_path = File.join(dir, template + ".rhtml")
+          return File.read(File.join(dir, template + ".rhtml"))
+        end
+      end
+    end
+    template
+  end
+  
+  protected
+  def add_default_options(options)
+    {:deploy_to => configuration.deploy_to}.merge(options)
+  end
 end
 
 Capistrano.plugin :runner, RunitRunnerHelper

data/lib/runit_service_helper.rb

@@ -0,0 +1,65 @@
+begin
+  require 'capistrano'
+rescue LoadError
+  require 'rubygems'
+  require 'capistrano'
+end
+
+require 'runit_runner_helper'
+
+# This module provides an easy method to create service directories in your application and have them
+# populated with runner scripts.
+# 
+# The methods are available through service.<method name> in your deploy.rb
+module RunitServiceHelper
+  # Adds a service to the applications service directory and creates run and log/run scripts
+  # 
+  # If no runner or logger options are passed, looks for a runner template called <service_name>_runner
+  # and a log runner template called <service_name>_log_runner. These should be in the templates directory set
+  # with runner_template_path in your deploy.rb.
+  #
+  # * If the runner template does not exist an exception will be raised
+  # * If the logger template does not exist the standard logger template will be used.
+  #
+  # If you want to use your own template or a string containing rhtml pass a :template option to the appropriate
+  # options hash. 
+  #
+  # The default options will be passed through to the template as described in RunitRunnerHelper#create
+  def add(service_name, runner_options = {}, logger_options = {})
+    make_service_dir service_name
+    create_service(service_name, runner_options)
+    create_service(service_name, logger_options.merge(:log_runner => true))
+  end
+
+  # Returns the full path to the service directory given a service name.
+  # Doesn't check the service name is valid.
+  def service_dir(service_name)
+    "#{configuration.deploy_to}/#{configuration.service_dir}/#{service_name}"
+  end
+  
+  protected
+  def create_service(service_name, options)
+    if options[:template].nil?
+      runner_template_path = options[:log_runner] ? "#{service_name.to_s}_log_runner" : "#{service_name.to_s}_runner"        
+      runner_template = runner.get_template(runner_template_path)
+      if runner_template == runner_template_path # didn't find a template
+        if options[:log_runner]
+          # Just use the standard template
+          runner_template = :log
+        else
+          raise "Couldn't find runner template #{runner_template_path} and no runner template provided"
+        end
+      end 
+    else
+      runner_template = options[:template]
+    end
+    options.delete(:template)
+    runner.create service_dir(service_name), runner_template, options
+  end
+
+  def make_service_dir(service_name)
+    run "mkdir -p #{service_dir(service_name)}/log/main"
+  end
+end
+
+Capistrano.plugin :service, RunitServiceHelper  

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: capistrano-runit-tasks
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2006-03-18 00:00:00 +00:00
+  version: 0.2.0
+date: 2006-03-23 00:00:00 +00:00
 summary: Adds tasks to capistrano for use with the runit supervision scheme.
 require_paths: 
   - lib
@@ -29,9 +29,15 @@ cert_chain:
 authors: 
   - Chris McGrath
 files: 
+  - lib/capistrano-runit-tasks-templates
   - lib/capistrano-runit-tasks.rb
+  - lib/runit_command_helper.rb
   - lib/runit_runner_helper.rb
+  - lib/runit_service_helper.rb
+  - lib/capistrano-runit-tasks-templates/default_fcgi_runner.rhtml
+  - lib/capistrano-runit-tasks-templates/default_log_runner.rhtml
   - README
+  - ChangeLog
 test_files: []
 rdoc_options: 
   - "--title"
@@ -40,6 +46,7 @@ rdoc_options:
   - README
 extra_rdoc_files: 
   - README
+  - ChangeLog
 executables: []
 extensions: []
 requirements: []