capistrano-offroad 0.0.1 → 0.1.0

data/README

@@ -0,0 +1,334 @@
+                          Capistrano-offroad
+                          ==================
+
+Author: Maciej Pasternacki <maciej@pasternacki.net>
+Date: 2010-05-28 Fri
+
+
+Capistrano-offroad is a support package for using Capistrano with
+non-rails projects.  It contains basic reset of Rails-specific tasks,
+a handful of utility functions, and modules with recipes.
+
+Capistrano-offroad is available on terms of BSD license.  See LICENSE
+file for details.
+
+Table of Contents
+=================
+1 Installation 
+    1.1 System-wide installation 
+    1.2 Project-local installation 
+2 Usage 
+3 Features 
+    3.1 Reset 
+    3.2 Utilities 
+        3.2.1 `:run' dependency type 
+        3.2.2 `set_from_env_or_ask' 
+        3.2.3 `offroad_modules' 
+    3.3 Version 
+        3.3.1 `require_version' 
+    3.4 Modules 
+        3.4.1 defaults 
+        3.4.2 django 
+        3.4.3 supervisord 
+        3.4.4 daemontools 
+        3.4.5 monit 
+
+
+1 Installation 
+~~~~~~~~~~~~~~~
+
+1.1 System-wide installation 
+=============================
+
+   Capistrano-offroad is available as a Ruby Gem, so in most cases you
+   should simply call:
+
+   gem install capistrano-offroad
+
+   This requires fairly recent version of Ruby gems (1.3.6 or later),
+   so it's possible you'll need to upgrade rubygems itself:
+
+   gem update --system
+
+   You can also download source code directly from Github page
+   [http://github.com/mpasternacki/capistrano-offroad] and install it by
+   rebuilding the gem manually.
+
+1.2 Project-local installation 
+===============================
+
+   You can download source code from Github and use it as a Git
+   submodule, or just drop it into your code base in whatever way
+   suits you.  Then, you should add to you Capfile the magic line
+   adding capistrano-offroad's `lib/' subdirectory to the require
+   path.
+
+   $:.unshift File.join( File.dirname(__FILE__), 'relative/path/to/capistrano-offroad/lib' )
+
+2 Usage 
+~~~~~~~~
+
+  When you've got capistrano-offroad on your require path, whether
+  globally from a gem, or by extending require path, you simply
+  `require' it.
+
+  require 'capistrano-offroad'
+
+  For some reason, this line should appear *after* the
+  `set :application' declaration.
+
+  After that, you either `require' desired modules yourself, or use
+  `offroad_modules' helper function.
+
+  require 'capistrano-offroad/modules/defaults'
+  require 'capistrano-offroad/modules/django'
+
+  offroad_modules 'defaults', 'django'
+
+3 Features 
+~~~~~~~~~~~
+
+3.1 Reset 
+==========
+   By default, capistrano-offroad empties Rails-specific tasks:
+   `deploy:migrate', `deploy:start', `deploy:stop', `deploy:restart'.
+
+   The `:deploy:finalize_update' task is cut down to only run `chgrp'
+   and `chmod' when `:group_writable' setting is true.  `chgrp'
+   behaviour can be modified by setting `:group_writable' to:
+   - `:no_chgrp' - don't run `chgrp' command
+   - `:sudo_chgrp' - use `sudo' to make sure `chgrp' has proper permissions
+
+   The setting `:shared_children' is set to an empty list.  This gives
+   comfortable enough blank slate for working on non-rails projects,
+   without redefining all the workflow that is already present in
+   Capistrano.
+
+3.2 Utilities 
+==============
+   By default, two extensions to Capistrano are defined.
+
+3.2.1 `:run' dependency type 
+-----------------------------
+    Usage:
+    depend :remote, :run, "full shell command"=
+
+    When running `cap deploy:check', run the supplied shell command.
+    If its exit status is non-zero, the dependency has failed.
+
+3.2.2 `set_from_env_or_ask' 
+----------------------------
+    Usage:
+    set_from_env_or_ask :setting_name, "Query prompt: "
+
+    If there is `SETTING_NAME' (uppercased first argument) in
+    environment (i.e. supplied from command line), set `:setting_name'
+    to value of this environment variable.
+
+    If the environment variable is not defined, ask user interactively
+    for a value, using query prompt supplied as a second argument.
+
+3.2.3 `offroad_modules' 
+------------------------
+    Loads capistrano-offroad modules named as arguments.  Convenience
+    function, so that user doesn't have to type `require' lines by himself.
+
+3.3 Version 
+============
+   Three constants defining version of capistrano-offroad are defined:
+
+   CapistranoOffroad::VERSION::MAJOR
+   CapistranoOffroad::VERSION::MINOR
+   CapistranoOffroad::VERSION::TINY
+
+   Convenience string constant with full version number, separated
+   with dots, is provided:
+
+   CapistranoOffroad::VERSION::STRING
+
+3.3.1 `require_version' 
+------------------------
+    A helper function, which can be used in Capfile to enforce a minimum
+    version of capistrano-offroad:
+
+    CapistranoOffroad::VERSION.require_version(major, minor=0, tiny=0)
+
+3.4 Modules 
+============
+   Modules are packs of recipes and helpers for dealing with specific
+   software.
+
+   To load a module, either use the `require' function:
+
+   require 'capistrano-offroad/modules/module-name'
+
+   or use supplied `offroad_modules' helper function:
+
+   offroad_modules "foo", "bar", "baz", ...
+
+   When using a module, it is advised to at least browse through its
+   source to know what to expect.
+
+   Following modules are defined:
+
+3.4.1 defaults 
+---------------
+
+    Contains my personal defaults for settings.  For me it's part of
+    reset, but I moved it out to a separate module, because other
+    users may have different opinions.  The settings are:
+
+    set :scm, :git
+    set :ssh_options, { :forward_agent => true }
+    set :use_sudo, false
+    set :deploy_to, "/srv/#{application}"
+
+3.4.2 django 
+-------------
+    Settings, utilities and recipes for deploying [Django] projects.
+
+    [Django]: http://djangoproject.org/
+
+* Settings 
+  Following settings are defined.
+  + :python 
+    Python interpreter command.  Defaults to "python".
+    
+    Module also adds a dependency on this command to `deploy:check'.
+  + :django_project_subdirectory 
+    Directory in your repository that contains Django project (one
+    with the the `manage.py' file).  Defaults to "project".
+  + :django_use_south 
+    Assume [South] is used for database migrations.  Defaults to true.
+
+    [South]: http://south.aeracode.org/
+
+* Functions and utilities 
+  django_manage cmd, options={}
+  Runs the `manage.py' command `cmd'.  Optional keyword argument
+  `:path' provides path to a Capistrano release where the command
+  should be run.  It defaults to `:latest_release'.
+  
+  `:python_module' dependency type is defined to name Python
+  modules in `deploy:check' dependencies:
+  
+  depend :remote, :python_module, "MySQLdb"
+* Tasks 
+  + django:manage 
+    Run custom Django management command in latest release.
+    
+    Pass the management command and arguments in COMMAND="..."
+    variable.  If COMMAND variable is not provided, Capistrano will
+    ask for a command.
+    
+  + deploy:migrate 
+    Runs `manage.py syncdb' in the latest release.  If
+    `:django_use_south' is true, it `--migrate' switch is used.
+    - TODO make it run in specified release, as vanilla Rails `deploy:migrate' 
+  + TODO separate `python' module 
+    Stuff that is not Django-specific should be moved to a separate
+    `python' module that could be used with Python-related
+    non-Django projects.  The `python' module would be automatically
+    loaded by `django' module.
+    
+
+3.4.3 supervisord 
+------------------
+    Control processes with [the supervisor daemon].
+
+
+    [the supervisor daemon]: http://supervisord.org/
+
+* Settings 
+  set :supervisord_path, ""     # directory where supervisord binaries reside
+  set :supervisord_command, "supervisord"
+  set :supervisorctl_command, "supervisorctl"
+  set :supervisord_conf, "supervisord_conf"
+  set :supervisord_pidfile, "supervisord.pid"
+  set :supervisord_start_group, nil # process group to start on deploy:start - nil means all processes
+  set :supervisord_stop_group, nil  # process group to stop on deploy:stop - nil means all processes
+  
+* Utilities 
+  supervisorctl(cmd, options={})
+  Run a `supervisorctl' command specified as first argument.  If
+  optional keyword argument `:try_start' is true (the default, you
+  may specify as false), start `supervisord' if not already
+  running.
+  
+* Tasks 
+  + Standard tasks 
+    Stock Capistrano tasks `deploy:start', `deploy:stop',
+    `deploy:restart' are defined.  They optionally accept `GROUP' or
+    `PROGRAM' environment variables, which can specify a single,
+    specific process group or a single process name to start, stop
+    or restart.
+  + deploy:status 
+    Runs `supervisorctl status'.
+  + deploy:processes 
+    Runs `pstree' with root in supervisord if supervisord is
+    running.
+  + deploy:reload_supervisord 
+    Reloads supervisor daemon's config.  Starts it if not started.
+  + deploy:supervisorctl 
+    Runs supplied supervisorctl command.  Command should be provided
+    in COMMAND variable; if no variable is provided,
+    capistrano-offroad will ask for the command.
+    
+
+3.4.4 daemontools 
+------------------
+    Recipes and settings for controlling processes with Dan
+    Bernstein's [daemontools].  It expects that `run' script lives in
+    top level of your repository.
+
+    *WARNING*: this is legacy code, used only in old projects and not
+    very well supported.
+
+    Also, this is probably not the best way to deal with the problem -
+    it would be easier to manage, start and restart with the `run'
+    script in the `:deploy_to' root, which would `cd' to `current' and
+    `exec ./run'.  If anybody wants to write a patch to support that,
+    it would be great :)
+
+    [daemontools]: http://cr.yp.to/daemontools.html
+
+* Settings 
+  set :svscan_root, "/service"
+  set :supervise_name, "#{application}"
+* Utilities 
+  `svc' function runs `svc' with supplied arguments for the
+  supervised directory.
+* Tasks 
+  - `daemontools:create_symlink' - creates a symlink in `:svscan_root'
+  - `daemontools:remove_symlink' - removes symlink from
+    `:svscan_root' and stops the app
+  - `daemontools:status' - displays `svstat' output for current release
+  - `daemontools:relstatus' - displays `svstat' output for all
+    releases (use it after restart to make sure that previous
+    release has actually stopped)
+  - `deploy:start', `deploy:stop', `deploy:restart' - standard
+    Capistrano tasks
+  - `deploy:symlink' internal target is redefined; `on_rollback'
+    handler is currently broken
+  
+
+3.4.5 monit 
+------------
+    Module to run processes with monit.
+    *This is legacy, unsupported, unused code*. Use it (and monit) on
+    your own risk.  I'm leaving it in only because the code is already
+    written and it would be waste to throw it away only because monit
+    sucks.
+* Settings 
+  set :monit_group, nil         # process group to start/stop/reload
+  set :monit_command, "monit"
+  
+* Tasks 
+  - `deploy:start', `deploy:stop', `deploy:restart' - standard
+    Capistrano tasks.  They accept an extra optional variable
+    PROCESS which, if given, specifies a single process to start,
+    stop or restart.  If PROCESS is not given, all processes (of
+    `:monit_group' group, if configured) are started/stopped/restarted.
+  - `deploy:status' - displays `monit summary' output
+  - `deploy:status:full' - displays `monit status' output
+  - `deploy:reload_monit' - reloads monit configuration

data/lib/capistrano-offroad/modules/daemontools.rb

@@ -16,13 +16,13 @@ Capistrano::Configuration.instance(:must_exist).load do
     end
 
     desc "[internal] Remove symlink from svscan directory"
-    task :remove_symlink do
+    task :do_remove_symlink do
       sudo "rm -v #{svscan_root}/#{supervise_name}"
     end
 
     desc "Remove symlink from svscan directory and stop supervise"
-    task :remove do
-      remove_symlink
+    task :remove_symlink do
+      do_remove_symlink
       sudo "svc -x -t #{current_path}"
     end
 

data/lib/capistrano-offroad/modules/django.rb

@@ -33,8 +33,8 @@ EOF
     desc "Run manage.py syncdb in latest release."
     task :migrate, :roles => :db, :only => { :primary => true } do
       # FIXME: path, see default railsy deploy:migrate
-      django_manage "syncdb --noinput"
-      django_manage "migrate" if fetch(:django_use_south, false)
+      m = if fetch(:django_use_south, false) then "--migrate" else "" end
+      django_manage "syncdb --noinput #{m}"
     end
   end
 

data/lib/capistrano-offroad/modules/monit.rb

@@ -1,7 +1,7 @@
 require 'capistrano'
 
 Capistrano::Configuration.instance(:must_exist).load do
-  set :monit_group, nil
+  set :monit_group, nil         # process group to start/stop/reload
   set :monit_command, "monit"
 
   def _monit_args()

data/lib/capistrano-offroad/modules/supervisord.rb

@@ -1,13 +1,13 @@
 require 'capistrano'
 
 Capistrano::Configuration.instance(:must_exist).load do
-  set :supervisord_path, ""
+  set :supervisord_path, ""     # directory where supervisord binaries reside
   set :supervisord_command, "supervisord"
   set :supervisorctl_command, "supervisorctl"
   set :supervisord_conf, "supervisord_conf"
   set :supervisord_pidfile, "supervisord.pid"
-  set :supervisord_start_group, nil
-  set :supervisord_stop_group, nil
+  set :supervisord_start_group, nil # process group to start on deploy:start - nil means all processes
+  set :supervisord_stop_group, nil  # process group to stop on deploy:stop - nil means all processes
 
   namespace :deploy do
     def supervisord_pidfile_path ; "#{shared_path}/#{supervisord_pidfile}" end
@@ -86,7 +86,7 @@ Capistrano::Configuration.instance(:must_exist).load do
       supervisorctl "reload"
     end
 
-    task :run_supervisorctl do
+    task :supervisorctl do
       set_from_env_or_ask :command, "supervisorctl command: "
       supervisorctl "#{command}", :try_start => false
     end

data/lib/capistrano-offroad/reset.rb

@@ -8,7 +8,13 @@ Capistrano::Configuration.instance(:must_exist).load do
   namespace :deploy do
     task :finalize_update, :except => { :no_release => true } do
       if fetch(:group_writable, true)
-        sudo "chgrp -R #{deploy_group} #{latest_release}"
+        if :no_chgrp == fetch(:group_writable, true)
+          # skip step
+        elsif :sudo_chgrp == fetch(:group_writable, true)
+          sudo "chgrp -R #{deploy_group} #{latest_release}"
+        else
+          run "chgrp -R #{deploy_group} #{latest_release}"
+        end
         run "chmod -R g+w #{latest_release}"
       end
     end

data/lib/capistrano-offroad/utils.rb

@@ -12,13 +12,15 @@ class Capistrano::Deploy::RemoteDependency
   end
 end
 
-# set_from_env_or_ask :variable, "Please enter variable name: "
-# If there is VARIABLE in enviroment, set :variable to it, otherwise
-# ask user for a value
-def set_from_env_or_ask(sym, question)
-  if ENV.has_key? sym.to_s.upcase then
-    set sym, ENV[sym.to_s.upcase]
-  else
-    set sym do Capistrano::CLI.ui.ask question end
+class Capistrano::Configuration
+  # set_from_env_or_ask :variable, "Please enter variable name: "
+  # If there is VARIABLE in enviroment, set :variable to it, otherwise
+  # ask user for a value
+  def set_from_env_or_ask(sym, question)
+    if ENV.has_key? sym.to_s.upcase then
+      set sym, ENV[sym.to_s.upcase]
+    else
+      set sym do Capistrano::CLI.ui.ask question end
+    end
   end
 end

data/lib/capistrano-offroad/version.rb

@@ -1,8 +1,14 @@
 module CapistranoOffroad
   module VERSION
     MAJOR = 0
-    MINOR = 0
-    TINY  = 1
+    MINOR = 1
+    TINY  = 0
     STRING = [MAJOR, MINOR, TINY].join('.')
+
+    def VERSION.require_version(major, minor=0, tiny=0)
+      unless ([MAJOR, MINOR, TINY] <=> [major, minor, tiny]) >= 0
+        raise Capistrano::Error, "capistrano-offroad version #{MAJOR}.#{MINOR}.#{TINY} is below required #{major}.#{minor}.#{tiny}"
+      end
+    end
   end
 end

data/lib/capistrano-offroad.rb

@@ -1,3 +1,4 @@
+require 'capistrano-offroad/version'
 require 'capistrano-offroad/reset'
 require 'capistrano-offroad/utils'
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: capistrano-offroad
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: false
   segments: 
   - 0
-  - 0
   - 1
-  version: 0.0.1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Maciej Pasternacki
@@ -15,11 +15,30 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-27 00:00:00 +02:00
+date: 2010-05-28 00:00:00 +02:00
 default_executable: 
-dependencies: []
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: capistrano
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 5
+        - 8
+        version: 2.5.8
+  type: :runtime
+  version_requirements: *id001
+description: |
+  Capistrano-offroad is a support package for using Capistrano with
+  non-rails projects.  It contains basic reset of Rails-specific tasks,
+  a handful of utility functions, and modules with recipes.
 
-description: Capistrano add-ons and recipes for non-rails projects
 email: maciej@pasternacki.net
 executables: []
 
@@ -41,8 +60,8 @@ files:
 - LICENSE
 has_rdoc: true
 homepage: http://github.com/mpasternacki/capistrano-offroad
-licenses: []
-
+licenses: 
+- BSD
 post_install_message: 
 rdoc_options: []