@@ -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 lib/sprinkle/package.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) lib/sprinkle/policy.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 lib/sprinkle/verifiers/directory.rb @@ -1,8 +1,27 @@ 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 lib/sprinkle/verifiers/executable.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 lib/sprinkle/verifiers/file.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}" lib/sprinkle/verifiers/symlink.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) lib/sprinkle/verify.rb 355b3aedf7c0303a5d7132ef70f70687043b11e9 Mitchell Hashimoto mitchell.hashimoto@gmail.com http://github.com/crafterm/sprinkle/commit/3bcd0d51918273fa111f16228e0ccf65d2307304 3bcd0d51918273fa111f16228e0ccf65d2307304 2008-07-19T12:05:11-07:00 2008-07-19T12:05:11-07:00 Full RDoc coverage! Sprinkle::Package, Sprinkle::Policy, Sprinkle::Verify and all the built-in verifiers have been documented. f0e898cfcb7f7d4497bb73d44777e88b87712bba Mitchell Hashimoto mitchell.hashimoto@gmail.com