capistrano-runit-tasks 0.1.0

data/README

@@ -0,0 +1,171 @@
+= Capistrano runit tasks
+
+Adds tasks to Capistrano for use with the runit supervision scheme.
+
+This library extends Capistrano to allow processes to be supervised using the
+runit package. It replaces some of the standard tasks with runit versions and
+includes tasks and helpers to create the service directory layout and populate
+it with run scripts. It currently only supports fcgi listeners, but tries to
+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
+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.
+
+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
+where links can be created to get tasks monitored.
+
+== Quick Start
+
+This assumes you're creating a fresh install, not migrating an app from
+spinner/spawner/reaper.
+
+Install the package via gems or .tgz / .zip and setup.rb.
+
+Include it in your deploy.rb with: 
+
+require 'capistrano-runit-tasks'
+
+Then run:
+
+* cap setup
+* cap cold_deploy
+
+This sets up one fcgi listener on port 8000. Make sure your database is setup
+and point your webserver at the new listener.
+
+== Usage
+
+When you require 'runit-tasks' it replaces the following cap tasks with runit
+versions:
+
+* cold_deploy
+* restart
+* spinner
+	
+Then adds the following tasks, helpers and variables:
+
+=== Tasks
+
+[setup_service_dirs] Creates the skeleton directory structure for the services
+
+[after_setup]        Calls setup_service_dirs so they're created as part of
+                     the standard cap setup
+
+=== Variables
+
+[service_dir]             Change this if you want to change the name
+                          of the service directory in the app on the server(s).
+                          (Default: service)
+
+[master_service_dir]      Supervised directory where cap-runit will link the
+                          service directories to to start the service.
+                          (Default: ~/services)
+
+[fcgi_count]              Number of fcgi listener service dirs to create.
+                          (Default: 1)
+
+[fcgi_listener_base_port] The base port number to use for the fcgi listeners.
+                          (Default: 8000)
+
+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
+dynamic creation / deletion.
+
+The directories are named after the port number the fcgi listener will run on.
+If you specified 8500 for the base port and 3 for the fcgi_count then
+service/8500, service/8501 and service/8502 directories will be created and
+populated with run scripts that launch the fcgis on the corresponding port.
+
+When the service directories are linked into the master service dir to run,
+they are named <application>-<port number>. So if :application is set to "foo"
+in deploy.rb you'll get foo-8500, foo-8501 etc.
+
+=== Helpers
+
+[each_fcgi_listener] Uses the values for fcgi_listener_base_port and
+                     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.
+
+== 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.
+
+== 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:
+
+ 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"
+
+   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  
+ end
+
+ task :after_spinner do
+   mailer_service_dir = "#{deploy_to}/#{service_dir}/mailer"
+   run "ln -sf #{mailer_service_dir} #{master_service_dir}/#{application}-mailer"
+ end
+
+ task :after_restart do
+   mailer_service_dir = "#{deploy_to}/#{service_dir}/mailer"
+   run "runsvctrl down #{mailer_service_dir}"
+   run "runsvctrl up #{mailer_service_dir}"
+ end
+
+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.
+
+== Switching from spinner/spawner/reaper
+
+This again should be automated, the manual steps I used were:
+
+* Modify deploy.rb and do a test deploy to a new directory on a different port
+* Check the deploy worked ok
+* Revert deploy.rb
+* cap setup_service_dirs to create the structure (Won't touch what's running)
+* Kill the spinner process
+* use script/process/reaper to kill the running fcgis
+* cap cold_deploy to start the service
+* Check everything is running OK
+
+== 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

data/lib/capistrano-runit-tasks.rb

@@ -0,0 +1,64 @@
+require 'runit_runner_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
+   
+  # We need our own task for this as the default cold_deploy
+  # calls restart, which won't work until we've setup the 
+  # symlink, perhaps we could add a test to restart to check if the
+  # link exists, but that's beyond my current (very bad) shell-foo 
+  desc "Used only for deploying when the services haven't been setup"
+  task :cold_deploy do
+    transaction do
+      update_code
+      symlink
+    end
+    spinner
+  end
+
+  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
+    end
+  end
+    
+  desc "Links created service dir into master service dir so runit starts the fcgi"
+  task :spinner do
+    each_fcgi_listener do |fcgi_listener_port|
+      fcgi_service_dir = "#{deploy_to}/#{service_dir}/#{fcgi_listener_port}"
+      run "ln -sf #{fcgi_service_dir} #{master_service_dir}/#{application}-#{fcgi_listener_port}"    
+    end
+  end
+  
+  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
+  end
+  
+  desc "Hook into after setup to create the runit service directory"
+  task :after_setup do
+    setup_service_dirs
+  end
+
+  def each_fcgi_listener
+    fcgi_listener_base_port.upto(fcgi_listener_base_port + fcgi_count - 1) do |fcgi_listener_port|
+      yield fcgi_listener_port
+    end
+  end
+end

data/lib/runit_runner_helper.rb

@@ -0,0 +1,32 @@
+require 'capistrano'
+
+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
+      when :log
+        template = LOG_TEMPLATE
+      else
+        template = FCGI_TEMPLATE if template == :fcgi  
+    end
+    
+    put render(options.merge(:template => template)), runner_path, :mode => 0700    
+  end  
+end
+
+Capistrano.plugin :runner, RunitRunnerHelper

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification 
+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
+summary: Adds tasks to capistrano for use with the runit supervision scheme.
+require_paths: 
+  - lib
+email: chris@octopod.info
+homepage: http://cappy-runit.rubyforge.org
+rubyforge_project: cappy-runit
+description: 
+autorequire: capistrano-runit-tasks
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+  - Chris McGrath
+files: 
+  - lib/capistrano-runit-tasks.rb
+  - lib/runit_runner_helper.rb
+  - README
+test_files: []
+rdoc_options: 
+  - "--title"
+  - Capistrano runit tasks documentation
+  - "--main"
+  - README
+extra_rdoc_files: 
+  - README
+executables: []
+extensions: []
+requirements: []
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: capistrano
+    version_requirement: 
+    version_requirements: !ruby/object:Gem::Version::Requirement 
+      requirements: 
+        - 
+          - ">="
+          - !ruby/object:Gem::Version 
+            version: 1.1.0
+      version: