mitchellh-sprinkle 0.1.5 → 0.1.6

data/Manifest.txt

@@ -7,7 +7,6 @@ Rakefile
 bin/sprinkle
 config/hoe.rb
 config/requirements.rb
-examples/merb/deploy.rb
 examples/rails/README
 examples/rails/deploy.rb
 examples/rails/packages/database.rb
@@ -41,6 +40,8 @@ lib/sprinkle/script.rb
 lib/sprinkle/verifiers/directory.rb
 lib/sprinkle/verifiers/executable.rb
 lib/sprinkle/verifiers/file.rb
+lib/sprinkle/verifiers/process.rb
+lib/sprinkle/verifiers/ruby.rb
 lib/sprinkle/verifiers/symlink.rb
 lib/sprinkle/verify.rb
 lib/sprinkle/version.rb

data/lib/sprinkle/package.rb

@@ -1,4 +1,96 @@
 module Sprinkle
+  # = Packages
+  #
+  # A package defines one or more things to provision onto the server.
+  # There is a lot of flexibility in a way a package is defined but
+  # let me give you a basic example:
+  #
+  #   package :ruby do
+  #     description 'Ruby MRI'
+  #     version '1.8.6'
+  #     apt 'ruby'
+  #
+  #     verify { has_executable 'ruby' }
+  #   end
+  #
+  # The above would define a package named 'ruby' and give it a description
+  # and explicitly say its version. It is installed via apt and to verify
+  # the installation was successful sprinkle will check for the executable
+  # 'ruby' being availble. Pretty simple, right?
+  #
+  # <b>Note:</b> Defining a package does not INSTALL it. To install a
+  # package, you must require it in a Sprinkle::Policy block. 
+  #
+  # == Pre-Requirements
+  #
+  # Most packages have some sort of pre-requisites in order to be installed.
+  # Sprinkle allows you to define the requirements of the package, which
+  # will be installed before the package itself. An example below:
+  #
+  #   package :rubygems do
+  #     source 'http://rubyforge.org/rubygems.tgz'
+  #     requires :ruby
+  #   end
+  #
+  # In this case, when rubygems is being installed, Sprinkle will first
+  # provision the server with Ruby to make sure the requirements are met.
+  # In turn, if ruby has requirements, it installs those first, and so on.
+  #
+  # == Verifications
+  #
+  # Most of the time its important to know whether the software you're 
+  # attempting to install was installed successfully or not. For this,
+  # Sprinkle provides verifications. Verifications are one or more blocks
+  # which define rules with which Sprinkle can check if it installed
+  # the package successfully. If these verification blocks fail, then 
+  # Sprinkle will gracefully stop the entire process. An example below:
+  #
+  #   package :rubygems do
+  #     source 'http://rubyforge.org/rubygems.tgz'
+  #     requires :ruby
+  #
+  #     verify { has_executable 'gem' }
+  #   end
+  #
+  # In addition to verifying an installation was successfully, by default
+  # Sprinkle runs these verifications <em>before</em> the installation to
+  # check if the package is already installed. If the verifications pass
+  # before installing the package, it skips the package. To override this
+  # behavior, set the -f flag on the sprinkle script or set the
+  # :force option to true in Sprinkle::OPTIONS
+  #
+  # For more information on verifications and to see all the available
+  # verifications, see Sprinkle::Verify
+  #
+  # == Virtual Packages
+  #
+  # Sometimes, there are multiple packages available for a single task. An
+  # example is a database package. It can contain mySQL, postgres, or sqlite!
+  # This is where virtual packages come in handy. They are defined as follows:
+  #
+  #   package :sqlite3, :provides => :database do
+  #     apt 'sqlite3'
+  #   end
+  #
+  # The :provides option allows you to reference this package either by :sqlite3
+  # or by :database. But whereas the package name is unique, multiple packages may
+  # share the same provision. If this is the case, when running Sprinkle, the 
+  # script will ask you which provision you want to install. At this time, you
+  # can only install one. 
+  #
+  # == Meta-Packages
+  #
+  # A package doesn't require an installer. If you want to define a package which
+  # merely encompasses other packages, that is fine too. Example:
+  #
+  #   package :meta do
+  #     requires :magic_beans
+  #     requires :magic_sauce
+  #   end
+  #
+  #--
+  # FIXME: Should probably document recommendations.
+  #++
   module Package
     PACKAGES = {}
 
@@ -13,7 +105,7 @@ module Sprinkle
       package
     end
 
-    class Package
+    class Package #:nodoc:
       include ArbitraryOptions
       attr_accessor :name, :provides, :installer, :dependencies, :recommends, :verifications
 

data/lib/sprinkle/policy.rb

@@ -1,16 +1,56 @@
 require 'highline/import'
 
 module Sprinkle
+  # = Policies
+  #
+  # A policy defines a set of packages which are required for a certain
+  # role (app, database, etc.). All policies defined will be run and all
+  # packages required by the policy will be installed. So whereas defining
+  # a Sprinkle::Package merely defines it, defining a Sprinkle::Policy 
+  # actually causes those packages to install. 
+  #
+  # == A Basic Example
+  #
+  #   policy :blog, :roles => :app do
+  #     require :webserver
+  #     require :database
+  #     require :rails
+  #   end
+  #
+  # This says that for the blog on the app role, it requires certain 
+  # packages. The :roles option is <em>exactly</em> the same as a capistrano
+  # or vlad role. A role merely defines what server the commands are run
+  # on. This way, a single Sprinkle script can provision an entire group
+  # of servers. 
+  #
+  # To define a role, put in your actor specific configuration file (recipe or
+  # script file):
+  #
+  #   role :app, "208.28.38.44"
+  #
+  # The capistrano and vlad syntax is the same for that. If you're using a
+  # custom actor, you may have to do it differently.
+  #
+  # == Multiple Policies
+  #
+  # You may specify as many policies as you'd like. If the packages you're
+  # requiring are properly defined with verification blocks, then
+  # no software will be installed twice, so you may require a webserver on
+  # multiple packages within the same role without having to wait for
+  # that package to install repeatedly.
   module Policy
-    POLICIES = []
+    POLICIES = [] #:nodoc:
 
+    # Defines a single policy. Currently the only option, which is also
+    # required, is :roles, which defines which servers a policy is
+    # used on.
     def policy(name, options = {}, &block)
       p = Policy.new(name, options, &block)
       POLICIES << p
       p
     end
 
-    class Policy
+    class Policy #:nodoc:
       attr_reader :name, :packages
 
       def initialize(name, metadata = {}, &block)

data/lib/sprinkle/script.rb

@@ -1,12 +1,22 @@
 module Sprinkle
+  # = Programmatically Run Sprinkle
+  #
+  # Sprinkle::Script gives you a way to programatically run a given
+  # sprinkle script. 
   class Script
+    # Run a given sprinkle script. This method is <b>blocking</b> so
+    # it will not return until the sprinkling is complete or fails.
+    #--
+    # FIXME: Improve documentation, possibly notify user how to tell
+    # if a sprinkling failed.
+    #++
     def self.sprinkle(script, filename = '__SCRIPT__')
       powder = new
       powder.instance_eval script, filename
       powder.sprinkle
     end
 
-    def sprinkle
+    def sprinkle #:nodoc:
       @deployment.process if @deployment
     end
   end

data/lib/sprinkle/verifiers/directory.rb

@@ -1,8 +1,13 @@
 module Sprinkle
   module Verifiers
+    # = Directory Verifier
+    #
+    # Defines a verify which can be used to test the existence of a 
+    # directory.
     module Directory
       Sprinkle::Verify.register(Sprinkle::Verifiers::Directory)
       
+      # Tests that the directory <tt>dir</tt> exists.
       def has_directory(dir)
         @commands << "test -d #{dir}"
       end

data/lib/sprinkle/verifiers/executable.rb

@@ -1,15 +1,34 @@
 module Sprinkle
   module Verifiers
+    # = Executable Verifier
+    #
+    # Contains a verifier to check the existance of an executable
+    # script on your server.
+    # 
+    # == Example Usage
+    #
+    # First, absolute path to an executable:
+    #
+    #   verify { has_executable '/usr/special/secret/bin/scipt' }
+    #
+    # Second, a global executable which would be available anywhere on the
+    # command line:
+    #
+    #   verify { has_executable 'grep' }
     module Executable
       Sprinkle::Verify.register(Sprinkle::Verifiers::Executable)
       
+      # Checks if <tt>path</tt> is an executable script. This verifier is "smart" because
+      # if the path contains a forward slash '/' then it assumes you're checking an 
+      # absolute path to an executable. If no '/' is in the path, it assumes you're
+      # checking for a global executable that would be available anywhere on the command line.
       def has_executable(path)
         # Be smart: If the path includes a forward slash, we're checking
         # an absolute path. Otherwise, we're checking a global executable
         if path.include?('/')
           @commands << "test -x #{path}"
         else
-          @commands << "[ -n \"`which #{path}`\"]"
+          @commands << "[ -n \"`echo \\`which #{path}\\``\" ]"
         end
       end
     end

data/lib/sprinkle/verifiers/file.rb

@@ -1,8 +1,17 @@
 module Sprinkle
   module Verifiers
+    # = File Verifier
+    #
+    # Contains a verifier to check the existance of a file.
+    # 
+    # == Example Usage
+    #
+    #   verify { has_file '/etc/apache2/apache2.conf' }
+    #
     module File
       Sprinkle::Verify.register(Sprinkle::Verifiers::File)
       
+      # Checks to make sure <tt>path</tt> is a file on the remote server.
       def has_file(path)
         @commands << "test -f #{path}"
       end

data/lib/sprinkle/verifiers/process.rb

@@ -0,0 +1,21 @@
+module Sprinkle
+  module Verifiers
+    # = Process Verifier
+    #
+    # Contains a verifier to check that a process is running.
+    # 
+    # == Example Usage
+    #
+    #   verify { has_process 'httpd' }
+    #
+    module Process
+      Sprinkle::Verify.register(Sprinkle::Verifiers::Process)
+      
+      # Checks to make sure <tt>process</tt> is a process running
+      # on the remote server.
+      def has_process(process)
+        @commands << "ps aux | grep '#{process}' | grep -v grep"
+      end
+    end
+  end
+end

data/lib/sprinkle/verifiers/ruby.rb

@@ -0,0 +1,19 @@
+module Sprinkle
+  module Verifiers
+    # = Ruby Verifiers
+    #
+    # The verifiers in this module are ruby specific. 
+    module Ruby
+      Sprinkle::Verify.register(Sprinkle::Verifiers::Ruby)
+      
+      # Checks if ruby can require the <tt>files</tt> given. <tt>rubygems</tt>
+      # is always included first.
+      def ruby_can_load(*files)
+        # Always include rubygems first
+        files = files.unshift('rubygems').collect { |x| "require '#{x}'" }
+        
+        @commands << "ruby -e \"#{files.join(';')}\""
+      end
+    end
+  end
+end

data/lib/sprinkle/verifiers/symlink.rb

@@ -1,8 +1,23 @@
 module Sprinkle
   module Verifiers
+    # = Symlink Verifier
+    #
+    # Contains a verifier to check the existance of a symbolic link.
+    # 
+    # == Example Usage
+    #
+    # First, checking for the existence of a symlink:
+    #
+    #   verify { has_symlink '/usr/special/secret/pointer' }
+    #
+    # Second, checking that the symlink points to a specific place:
+    #
+    #   verify { has_symlink '/usr/special/secret/pointer', '/usr/local/realfile' }
     module Symlink
       Sprinkle::Verify.register(Sprinkle::Verifiers::Symlink)
       
+      # Checks that <tt>symlink</tt> is a symbolic link. If <tt>file</tt> is 
+      # given, it checks that <tt>symlink</tt> points to <tt>file</tt>
       def has_symlink(symlink, file = nil)
         if file.nil?
           @commands << "test -L #{symlink}"

data/lib/sprinkle/verify.rb

@@ -1,7 +1,66 @@
 module Sprinkle
+  # = Verification Methods
+  #
+  # As documented in Sprinkle::Package, you may define a block on a package
+  # which verifies that a package was installed correctly. If this verification
+  # block fails, Sprinkle will stop the script gracefully, raising the error.
+  # 
+  # In addition to checking post install if it was successfully, verification
+  # blocks are also ran before an install to see if a package is <em>already</em>
+  # installed. If this is the case, the package is skipped and Sprinkle continues
+  # with the next package. This behavior can be overriden by setting the -f flag on
+  # the sprinkle script or setting Sprinkle::OPTIONS[:force] to true if you're
+  # using sprinkle programmatically. 
+  #
+  # == An Example
+  #
+  # The following verifies that rails was installed correctly be checking to see
+  # if the 'rails' command is available on the command line:
+  #
+  #   package :rails do
+  #     gem 'rails'
+  #     
+  #     verify do
+  #       has_executable 'rails'
+  #     end
+  #   end
+  #
+  # == Available Verifiers
+  #
+  # There are a variety of available methods for use in the verification block.
+  # The standard methods are defined in the Sprinkle::Verifiers module, so see
+  # their corresponding documentation.
+  #
+  # == Custom Verifiers
+  # 
+  # If you feel that the built-in verifiers do not offer a certain aspect of
+  # verification which you need, you may create your own verifier! Simply wrap
+  # any method in a module which you want to use:
+  #
+  #   module MagicBeansVerifier
+  #     def has_magic_beans(sauce)
+  #       @commands << '[ -z "`echo $' + sauce + '`"]'
+  #     end
+  #   end
+  #
+  # The method can append as many commands as it wishes to the @commands array. 
+  # These commands will be run on the remote server and <b>MUST</b> give an
+  # exit status of 0 if successful or other if unsuccessful.
+  #
+  # To register your verifier, call the register method on Sprinkle::Verify:
+  #
+  #   Sprinle::Verify.register(MagicBeansVerifier)
+  #
+  # And now you may use it like any other verifier:
+  #
+  #   package :magic_beans do
+  #     gem 'magic_beans'
+  #     
+  #     verify { has_magic_beans('ranch') }
+  #   end
   class Verify
     include Sprinkle::Configurable
-    attr_accessor :package, :description, :commands
+    attr_accessor :package, :description, :commands #:nodoc:
     
     class <<self
       # Register a verification module
@@ -10,7 +69,7 @@ module Sprinkle
       end
     end
     
-    def initialize(package, description = '', &block)
+    def initialize(package, description = '', &block) #:nodoc:
       raise 'Verify requires a block.' unless block
       
       @package = package
@@ -22,7 +81,7 @@ module Sprinkle
       self.instance_eval(&block)
     end
     
-    def process(roles, pre = false)
+    def process(roles, pre = false) #:nodoc:
       assert_delivery
       
       description = @description.empty? ? @package.name : @description
@@ -42,7 +101,7 @@ module Sprinkle
     end
   end
   
-  class VerificationFailed < Exception
+  class VerificationFailed < Exception #:nodoc:
     attr_accessor :package, :description
     
     def initialize(package, description)

data/lib/sprinkle/version.rb

@@ -2,7 +2,7 @@ module Sprinkle #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 1
-    TINY  = 5
+    TINY  = 6
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/spec/sprinkle/verify_spec.rb

@@ -23,6 +23,12 @@ describe Sprinkle::Verify do
         
         # Check if a global executable exists (in PATH)
         has_executable 'rails'
+        
+        # Check for a process
+        has_process 'httpd'
+        
+        # Check that ruby can include files
+        ruby_can_load 'a', 'b', 'c'
       end
     end
     @verification = @package.verifications[0]
@@ -58,7 +64,15 @@ describe Sprinkle::Verify do
     end
     
     it 'should test the "which" command to look for a global executable' do
-      @verification.commands.should include('[ -n "`which rails`"]')
+      @verification.commands.should include('[ -n "`echo \`which rails\``" ]')
+    end
+    
+    it 'should test the process list to find a process' do
+      @verification.commands.should include("ps aux | grep 'httpd' | grep -v grep")
+    end
+    
+    it 'should check if ruby can include a, b, c' do
+      @verification.commands.should include("ruby -e \"require 'rubygems';require 'a';require 'b';require 'c'\"")
     end
   end
   

data/sprinkle.gemspec

@@ -1,16 +1,16 @@
 Gem::Specification.new do |s|
   s.name = %q{sprinkle}
-  s.version = "0.1.5"
+  s.version = "0.1.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Marcus Crafter"]
-  s.date = %q{2008-07-16}
+  s.authors = ["Marcus Crafter", "Mitchell Hashimoto"]
+  s.date = %q{2008-07-19}
   s.default_executable = %q{sprinkle}
   s.description = %q{Ruby DSL based software provisioning tool}
-  s.email = ["crafterm@redartisan.com"]
+  s.email = ["crafterm@redartisan.com", "mitchell.hashimoto@citrusbyte.com"]
   s.executables = ["sprinkle"]
   s.extra_rdoc_files = ["History.txt", "Manifest.txt", "README.txt"]
-  s.files = ["CREDITS", "History.txt", "MIT-LICENSE", "Manifest.txt", "README.txt", "Rakefile", "bin/sprinkle", "config/hoe.rb", "config/requirements.rb", "examples/merb/deploy.rb", "examples/rails/README", "examples/rails/deploy.rb", "examples/rails/packages/database.rb", "examples/rails/packages/essential.rb", "examples/rails/packages/rails.rb", "examples/rails/packages/search.rb", "examples/rails/packages/server.rb", "examples/rails/rails.rb", "examples/sprinkle/sprinkle.rb", "lib/sprinkle.rb", "lib/sprinkle/actors/actors.rb", "lib/sprinkle/actors/capistrano.rb", "lib/sprinkle/actors/vlad.rb", "lib/sprinkle/configurable.rb", "lib/sprinkle/deployment.rb", "lib/sprinkle/extensions/arbitrary_options.rb", "lib/sprinkle/extensions/array.rb", "lib/sprinkle/extensions/blank_slate.rb", "lib/sprinkle/extensions/dsl_accessor.rb", "lib/sprinkle/extensions/string.rb", "lib/sprinkle/extensions/symbol.rb", "lib/sprinkle/installers/apt.rb", "lib/sprinkle/installers/gem.rb", "lib/sprinkle/installers/installer.rb", "lib/sprinkle/installers/rake.rb", "lib/sprinkle/installers/rpm.rb", "lib/sprinkle/installers/source.rb", "lib/sprinkle/package.rb", "lib/sprinkle/policy.rb", "lib/sprinkle/script.rb", "lib/sprinkle/verifiers/directory.rb", "lib/sprinkle/verifiers/executable.rb", "lib/sprinkle/verifiers/file.rb", "lib/sprinkle/verifiers/symlink.rb", "lib/sprinkle/verify.rb", "lib/sprinkle/version.rb", "script/destroy", "script/generate", "spec/spec.opts", "spec/spec_helper.rb", "spec/sprinkle/actors/capistrano_spec.rb", "spec/sprinkle/configurable_spec.rb", "spec/sprinkle/deployment_spec.rb", "spec/sprinkle/extensions/array_spec.rb", "spec/sprinkle/extensions/string_spec.rb", "spec/sprinkle/installers/apt_spec.rb", "spec/sprinkle/installers/gem_spec.rb", "spec/sprinkle/installers/installer_spec.rb", "spec/sprinkle/installers/rpm_spec.rb", "spec/sprinkle/installers/source_spec.rb", "spec/sprinkle/package_spec.rb", "spec/sprinkle/policy_spec.rb", "spec/sprinkle/script_spec.rb", "spec/sprinkle/sprinkle_spec.rb", "spec/sprinkle/verify_spec.rb", "sprinkle.gemspec", "tasks/deployment.rake", "tasks/environment.rake", "tasks/rspec.rake"]
+  s.files = ["CREDITS", "History.txt", "MIT-LICENSE", "Manifest.txt", "README.txt", "Rakefile", "bin/sprinkle", "config/hoe.rb", "config/requirements.rb", "examples/rails/README", "examples/rails/deploy.rb", "examples/rails/packages/database.rb", "examples/rails/packages/essential.rb", "examples/rails/packages/rails.rb", "examples/rails/packages/search.rb", "examples/rails/packages/server.rb", "examples/rails/rails.rb", "examples/sprinkle/sprinkle.rb", "lib/sprinkle.rb", "lib/sprinkle/actors/actors.rb", "lib/sprinkle/actors/capistrano.rb", "lib/sprinkle/actors/vlad.rb", "lib/sprinkle/configurable.rb", "lib/sprinkle/deployment.rb", "lib/sprinkle/extensions/arbitrary_options.rb", "lib/sprinkle/extensions/array.rb", "lib/sprinkle/extensions/blank_slate.rb", "lib/sprinkle/extensions/dsl_accessor.rb", "lib/sprinkle/extensions/string.rb", "lib/sprinkle/extensions/symbol.rb", "lib/sprinkle/installers/apt.rb", "lib/sprinkle/installers/gem.rb", "lib/sprinkle/installers/installer.rb", "lib/sprinkle/installers/rake.rb", "lib/sprinkle/installers/rpm.rb", "lib/sprinkle/installers/source.rb", "lib/sprinkle/package.rb", "lib/sprinkle/policy.rb", "lib/sprinkle/script.rb", "lib/sprinkle/verifiers/directory.rb", "lib/sprinkle/verifiers/executable.rb", "lib/sprinkle/verifiers/file.rb", "lib/sprinkle/verifiers/process.rb", "lib/sprinkle/verifiers/ruby.rb", "lib/sprinkle/verifiers/symlink.rb", "lib/sprinkle/verify.rb", "lib/sprinkle/version.rb", "script/destroy", "script/generate", "spec/spec.opts", "spec/spec_helper.rb", "spec/sprinkle/actors/capistrano_spec.rb", "spec/sprinkle/configurable_spec.rb", "spec/sprinkle/deployment_spec.rb", "spec/sprinkle/extensions/array_spec.rb", "spec/sprinkle/extensions/string_spec.rb", "spec/sprinkle/installers/apt_spec.rb", "spec/sprinkle/installers/gem_spec.rb", "spec/sprinkle/installers/installer_spec.rb", "spec/sprinkle/installers/rpm_spec.rb", "spec/sprinkle/installers/source_spec.rb", "spec/sprinkle/package_spec.rb", "spec/sprinkle/policy_spec.rb", "spec/sprinkle/script_spec.rb", "spec/sprinkle/sprinkle_spec.rb", "spec/sprinkle/verify_spec.rb", "sprinkle.gemspec", "tasks/deployment.rake", "tasks/environment.rake", "tasks/rspec.rake"]
   s.has_rdoc = true
   s.homepage = %q{http://sprinkle.rubyforge.org}
   s.rdoc_options = ["--main", "README.txt"]

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification 
 name: mitchellh-sprinkle
 version: !ruby/object:Gem::Version 
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors: 
 - Marcus Crafter
+- Mitchell Hashimoto
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2008-07-16 00:00:00 -07:00
+date: 2008-07-19 00:00:00 -07:00
 default_executable: sprinkle
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -51,6 +52,7 @@ dependencies:
 description: Ruby DSL based software provisioning tool
 email: 
 - crafterm@redartisan.com
+- mitchell.hashimoto@citrusbyte.com
 executables: 
 - sprinkle
 extensions: []
@@ -69,7 +71,6 @@ files:
 - bin/sprinkle
 - config/hoe.rb
 - config/requirements.rb
-- examples/merb/deploy.rb
 - examples/rails/README
 - examples/rails/deploy.rb
 - examples/rails/packages/database.rb
@@ -103,6 +104,8 @@ files:
 - lib/sprinkle/verifiers/directory.rb
 - lib/sprinkle/verifiers/executable.rb
 - lib/sprinkle/verifiers/file.rb
+- lib/sprinkle/verifiers/process.rb
+- lib/sprinkle/verifiers/ruby.rb
 - lib/sprinkle/verifiers/symlink.rb
 - lib/sprinkle/verify.rb
 - lib/sprinkle/version.rb

data/examples/merb/deploy.rb

@@ -1,5 +0,0 @@
-set :application, "application"
-
-role :app, "yourhost.com"
-role :web, "yourhost.com"
-role :db,  "yourhost.com", :primary => true