crafterm-sprinkle 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. data/CREDITS +2 -1
  2. data/Manifest.txt +11 -2
  3. data/{README.rdoc → README.txt} +25 -5
  4. data/bin/sprinkle +7 -0
  5. data/config/hoe.rb +2 -2
  6. data/examples/rails/rails.rb +4 -2
  7. data/lib/sprinkle.rb +8 -2
  8. data/lib/sprinkle/actors/actors.rb +17 -0
  9. data/lib/sprinkle/actors/capistrano.rb +41 -4
  10. data/lib/sprinkle/actors/vlad.rb +39 -4
  11. data/lib/sprinkle/configurable.rb +31 -0
  12. data/lib/sprinkle/deployment.rb +46 -6
  13. data/lib/sprinkle/extensions/arbitrary_options.rb +1 -1
  14. data/lib/sprinkle/extensions/array.rb +1 -3
  15. data/lib/sprinkle/extensions/blank_slate.rb +1 -1
  16. data/lib/sprinkle/extensions/dsl_accessor.rb +1 -1
  17. data/lib/sprinkle/extensions/string.rb +1 -1
  18. data/lib/sprinkle/extensions/symbol.rb +1 -1
  19. data/lib/sprinkle/installers/apt.rb +33 -6
  20. data/lib/sprinkle/installers/gem.rb +34 -6
  21. data/lib/sprinkle/installers/installer.rb +64 -29
  22. data/lib/sprinkle/installers/rake.rb +15 -2
  23. data/lib/sprinkle/installers/rpm.rb +20 -3
  24. data/lib/sprinkle/installers/source.rb +74 -16
  25. data/lib/sprinkle/package.rb +127 -2
  26. data/lib/sprinkle/policy.rb +42 -2
  27. data/lib/sprinkle/script.rb +11 -1
  28. data/lib/sprinkle/verifiers/directory.rb +16 -0
  29. data/lib/sprinkle/verifiers/executable.rb +36 -0
  30. data/lib/sprinkle/verifiers/file.rb +20 -0
  31. data/lib/sprinkle/verifiers/process.rb +21 -0
  32. data/lib/sprinkle/verifiers/ruby.rb +25 -0
  33. data/lib/sprinkle/verifiers/symlink.rb +30 -0
  34. data/lib/sprinkle/verify.rb +114 -0
  35. data/lib/sprinkle/version.rb +1 -1
  36. data/spec/sprinkle/actors/capistrano_spec.rb +21 -1
  37. data/spec/sprinkle/configurable_spec.rb +46 -0
  38. data/spec/sprinkle/installers/apt_spec.rb +1 -5
  39. data/spec/sprinkle/installers/gem_spec.rb +1 -1
  40. data/spec/sprinkle/installers/installer_spec.rb +55 -29
  41. data/spec/sprinkle/package_spec.rb +137 -0
  42. data/spec/sprinkle/verify_spec.rb +160 -0
  43. data/sprinkle.gemspec +6 -6
  44. metadata +17 -4
  45. data/examples/merb/deploy.rb +0 -5
@@ -1,4 +1,96 @@
1
1
  module Sprinkle
2
+ # = Packages
3
+ #
4
+ # A package defines one or more things to provision onto the server.
5
+ # There is a lot of flexibility in a way a package is defined but
6
+ # let me give you a basic example:
7
+ #
8
+ # package :ruby do
9
+ # description 'Ruby MRI'
10
+ # version '1.8.6'
11
+ # apt 'ruby'
12
+ #
13
+ # verify { has_executable 'ruby' }
14
+ # end
15
+ #
16
+ # The above would define a package named 'ruby' and give it a description
17
+ # and explicitly say its version. It is installed via apt and to verify
18
+ # the installation was successful sprinkle will check for the executable
19
+ # 'ruby' being availble. Pretty simple, right?
20
+ #
21
+ # <b>Note:</b> Defining a package does not INSTALL it. To install a
22
+ # package, you must require it in a Sprinkle::Policy block.
23
+ #
24
+ # == Pre-Requirements
25
+ #
26
+ # Most packages have some sort of pre-requisites in order to be installed.
27
+ # Sprinkle allows you to define the requirements of the package, which
28
+ # will be installed before the package itself. An example below:
29
+ #
30
+ # package :rubygems do
31
+ # source 'http://rubyforge.org/rubygems.tgz'
32
+ # requires :ruby
33
+ # end
34
+ #
35
+ # In this case, when rubygems is being installed, Sprinkle will first
36
+ # provision the server with Ruby to make sure the requirements are met.
37
+ # In turn, if ruby has requirements, it installs those first, and so on.
38
+ #
39
+ # == Verifications
40
+ #
41
+ # Most of the time its important to know whether the software you're
42
+ # attempting to install was installed successfully or not. For this,
43
+ # Sprinkle provides verifications. Verifications are one or more blocks
44
+ # which define rules with which Sprinkle can check if it installed
45
+ # the package successfully. If these verification blocks fail, then
46
+ # Sprinkle will gracefully stop the entire process. An example below:
47
+ #
48
+ # package :rubygems do
49
+ # source 'http://rubyforge.org/rubygems.tgz'
50
+ # requires :ruby
51
+ #
52
+ # verify { has_executable 'gem' }
53
+ # end
54
+ #
55
+ # In addition to verifying an installation was successfully, by default
56
+ # Sprinkle runs these verifications <em>before</em> the installation to
57
+ # check if the package is already installed. If the verifications pass
58
+ # before installing the package, it skips the package. To override this
59
+ # behavior, set the -f flag on the sprinkle script or set the
60
+ # :force option to true in Sprinkle::OPTIONS
61
+ #
62
+ # For more information on verifications and to see all the available
63
+ # verifications, see Sprinkle::Verify
64
+ #
65
+ # == Virtual Packages
66
+ #
67
+ # Sometimes, there are multiple packages available for a single task. An
68
+ # example is a database package. It can contain mySQL, postgres, or sqlite!
69
+ # This is where virtual packages come in handy. They are defined as follows:
70
+ #
71
+ # package :sqlite3, :provides => :database do
72
+ # apt 'sqlite3'
73
+ # end
74
+ #
75
+ # The :provides option allows you to reference this package either by :sqlite3
76
+ # or by :database. But whereas the package name is unique, multiple packages may
77
+ # share the same provision. If this is the case, when running Sprinkle, the
78
+ # script will ask you which provision you want to install. At this time, you
79
+ # can only install one.
80
+ #
81
+ # == Meta-Packages
82
+ #
83
+ # A package doesn't require an installer. If you want to define a package which
84
+ # merely encompasses other packages, that is fine too. Example:
85
+ #
86
+ # package :meta do
87
+ # requires :magic_beans
88
+ # requires :magic_sauce
89
+ # end
90
+ #
91
+ #--
92
+ # FIXME: Should probably document recommendations.
93
+ #++
2
94
  module Package
3
95
  PACKAGES = {}
4
96
 
@@ -13,9 +105,9 @@ module Sprinkle
13
105
  package
14
106
  end
15
107
 
16
- class Package
108
+ class Package #:nodoc:
17
109
  include ArbitraryOptions
18
- attr_accessor :name, :provides, :installer, :dependencies, :recommends
110
+ attr_accessor :name, :provides, :installer, :dependencies, :recommends, :verifications
19
111
 
20
112
  def initialize(name, metadata = {}, &block)
21
113
  raise 'No package name supplied' unless name
@@ -24,6 +116,7 @@ module Sprinkle
24
116
  @provides = metadata[:provides]
25
117
  @dependencies = []
26
118
  @recommends = []
119
+ @verifications = []
27
120
  self.instance_eval &block
28
121
  end
29
122
 
@@ -44,12 +137,44 @@ module Sprinkle
44
137
  @recommends << :build_essential # Ubuntu/Debian
45
138
  @installer = Sprinkle::Installers::Source.new(self, source, options, &block)
46
139
  end
140
+
141
+ def verify(description = '', &block)
142
+ @verifications << Sprinkle::Verify.new(self, description, &block)
143
+ end
47
144
 
48
145
  def process(deployment, roles)
49
146
  return if meta_package?
147
+
148
+ # Run a pre-test to see if the software is already installed. If so,
149
+ # we can skip it, unless we have the force option turned on!
150
+ unless @verifications.empty? || Sprinkle::OPTIONS[:force]
151
+ begin
152
+ process_verifications(deployment, roles, true)
153
+
154
+ logger.info "--> #{self.name} already installed for roles: #{roles}"
155
+ return
156
+ rescue Sprinkle::VerificationFailed => e
157
+ # Continue
158
+ end
159
+ end
50
160
 
51
161
  @installer.defaults(deployment)
52
162
  @installer.process(roles)
163
+
164
+ process_verifications(deployment, roles)
165
+ end
166
+
167
+ def process_verifications(deployment, roles, pre = false)
168
+ if pre
169
+ logger.info "--> Checking if #{self.name} is already installed for roles: #{roles}"
170
+ else
171
+ logger.info "--> Verifying #{self.name} was properly installed for roles: #{roles}"
172
+ end
173
+
174
+ @verifications.each do |v|
175
+ v.defaults(deployment)
176
+ v.process(roles)
177
+ end
53
178
  end
54
179
 
55
180
  def requires(*packages)
@@ -1,16 +1,56 @@
1
1
  require 'highline/import'
2
2
 
3
3
  module Sprinkle
4
+ # = Policies
5
+ #
6
+ # A policy defines a set of packages which are required for a certain
7
+ # role (app, database, etc.). All policies defined will be run and all
8
+ # packages required by the policy will be installed. So whereas defining
9
+ # a Sprinkle::Package merely defines it, defining a Sprinkle::Policy
10
+ # actually causes those packages to install.
11
+ #
12
+ # == A Basic Example
13
+ #
14
+ # policy :blog, :roles => :app do
15
+ # require :webserver
16
+ # require :database
17
+ # require :rails
18
+ # end
19
+ #
20
+ # This says that for the blog on the app role, it requires certain
21
+ # packages. The :roles option is <em>exactly</em> the same as a capistrano
22
+ # or vlad role. A role merely defines what server the commands are run
23
+ # on. This way, a single Sprinkle script can provision an entire group
24
+ # of servers.
25
+ #
26
+ # To define a role, put in your actor specific configuration file (recipe or
27
+ # script file):
28
+ #
29
+ # role :app, "208.28.38.44"
30
+ #
31
+ # The capistrano and vlad syntax is the same for that. If you're using a
32
+ # custom actor, you may have to do it differently.
33
+ #
34
+ # == Multiple Policies
35
+ #
36
+ # You may specify as many policies as you'd like. If the packages you're
37
+ # requiring are properly defined with verification blocks, then
38
+ # no software will be installed twice, so you may require a webserver on
39
+ # multiple packages within the same role without having to wait for
40
+ # that package to install repeatedly.
4
41
  module Policy
5
- POLICIES = []
42
+ POLICIES = [] #:nodoc:
6
43
 
44
+ # Defines a single policy. Currently the only option, which is also
45
+ # required, is :roles, which defines which servers a policy is
46
+ # used on.
7
47
  def policy(name, options = {}, &block)
8
48
  p = Policy.new(name, options, &block)
9
49
  POLICIES << p
10
50
  p
11
51
  end
12
52
 
13
- class Policy
53
+ class Policy #:nodoc:
14
54
  attr_reader :name, :packages
15
55
 
16
56
  def initialize(name, metadata = {}, &block)
@@ -1,12 +1,22 @@
1
1
  module Sprinkle
2
+ # = Programmatically Run Sprinkle
3
+ #
4
+ # Sprinkle::Script gives you a way to programatically run a given
5
+ # sprinkle script.
2
6
  class Script
7
+ # Run a given sprinkle script. This method is <b>blocking</b> so
8
+ # it will not return until the sprinkling is complete or fails.
9
+ #--
10
+ # FIXME: Improve documentation, possibly notify user how to tell
11
+ # if a sprinkling failed.
12
+ #++
3
13
  def self.sprinkle(script, filename = '__SCRIPT__')
4
14
  powder = new
5
15
  powder.instance_eval script, filename
6
16
  powder.sprinkle
7
17
  end
8
18
 
9
- def sprinkle
19
+ def sprinkle #:nodoc:
10
20
  @deployment.process if @deployment
11
21
  end
12
22
  end
@@ -0,0 +1,16 @@
1
+ module Sprinkle
2
+ module Verifiers
3
+ # = Directory Verifier
4
+ #
5
+ # Defines a verify which can be used to test the existence of a
6
+ # directory.
7
+ module Directory
8
+ Sprinkle::Verify.register(Sprinkle::Verifiers::Directory)
9
+
10
+ # Tests that the directory <tt>dir</tt> exists.
11
+ def has_directory(dir)
12
+ @commands << "test -d #{dir}"
13
+ end
14
+ end
15
+ end
16
+ end
@@ -0,0 +1,36 @@
1
+ module Sprinkle
2
+ module Verifiers
3
+ # = Executable Verifier
4
+ #
5
+ # Contains a verifier to check the existance of an executable
6
+ # script on your server.
7
+ #
8
+ # == Example Usage
9
+ #
10
+ # First, absolute path to an executable:
11
+ #
12
+ # verify { has_executable '/usr/special/secret/bin/scipt' }
13
+ #
14
+ # Second, a global executable which would be available anywhere on the
15
+ # command line:
16
+ #
17
+ # verify { has_executable 'grep' }
18
+ module Executable
19
+ Sprinkle::Verify.register(Sprinkle::Verifiers::Executable)
20
+
21
+ # Checks if <tt>path</tt> is an executable script. This verifier is "smart" because
22
+ # if the path contains a forward slash '/' then it assumes you're checking an
23
+ # absolute path to an executable. If no '/' is in the path, it assumes you're
24
+ # checking for a global executable that would be available anywhere on the command line.
25
+ def has_executable(path)
26
+ # Be smart: If the path includes a forward slash, we're checking
27
+ # an absolute path. Otherwise, we're checking a global executable
28
+ if path.include?('/')
29
+ @commands << "test -x #{path}"
30
+ else
31
+ @commands << "[ -n \"`echo \\`which #{path}\\``\" ]"
32
+ end
33
+ end
34
+ end
35
+ end
36
+ end
@@ -0,0 +1,20 @@
1
+ module Sprinkle
2
+ module Verifiers
3
+ # = File Verifier
4
+ #
5
+ # Contains a verifier to check the existance of a file.
6
+ #
7
+ # == Example Usage
8
+ #
9
+ # verify { has_file '/etc/apache2/apache2.conf' }
10
+ #
11
+ module File
12
+ Sprinkle::Verify.register(Sprinkle::Verifiers::File)
13
+
14
+ # Checks to make sure <tt>path</tt> is a file on the remote server.
15
+ def has_file(path)
16
+ @commands << "test -f #{path}"
17
+ end
18
+ end
19
+ end
20
+ end
@@ -0,0 +1,21 @@
1
+ module Sprinkle
2
+ module Verifiers
3
+ # = Process Verifier
4
+ #
5
+ # Contains a verifier to check that a process is running.
6
+ #
7
+ # == Example Usage
8
+ #
9
+ # verify { has_process 'httpd' }
10
+ #
11
+ module Process
12
+ Sprinkle::Verify.register(Sprinkle::Verifiers::Process)
13
+
14
+ # Checks to make sure <tt>process</tt> is a process running
15
+ # on the remote server.
16
+ def has_process(process)
17
+ @commands << "ps aux | grep '#{process}' | grep -v grep"
18
+ end
19
+ end
20
+ end
21
+ end
@@ -0,0 +1,25 @@
1
+ module Sprinkle
2
+ module Verifiers
3
+ # = Ruby Verifiers
4
+ #
5
+ # The verifiers in this module are ruby specific.
6
+ module Ruby
7
+ Sprinkle::Verify.register(Sprinkle::Verifiers::Ruby)
8
+
9
+ # Checks if ruby can require the <tt>files</tt> given. <tt>rubygems</tt>
10
+ # is always included first.
11
+ def ruby_can_load(*files)
12
+ # Always include rubygems first
13
+ files = files.unshift('rubygems').collect { |x| "require '#{x}'" }
14
+
15
+ @commands << "ruby -e \"#{files.join(';')}\""
16
+ end
17
+
18
+ # Checks if a gem exists by calling "sudo gem list" and grepping against it.
19
+ def has_gem(name, version=nil)
20
+ version = version.nil? ? '' : version.gsub('.', '\.')
21
+ @commands << "sudo gem list | grep -e '^#{name} (.*#{version}.*)$'"
22
+ end
23
+ end
24
+ end
25
+ end
@@ -0,0 +1,30 @@
1
+ module Sprinkle
2
+ module Verifiers
3
+ # = Symlink Verifier
4
+ #
5
+ # Contains a verifier to check the existance of a symbolic link.
6
+ #
7
+ # == Example Usage
8
+ #
9
+ # First, checking for the existence of a symlink:
10
+ #
11
+ # verify { has_symlink '/usr/special/secret/pointer' }
12
+ #
13
+ # Second, checking that the symlink points to a specific place:
14
+ #
15
+ # verify { has_symlink '/usr/special/secret/pointer', '/usr/local/realfile' }
16
+ module Symlink
17
+ Sprinkle::Verify.register(Sprinkle::Verifiers::Symlink)
18
+
19
+ # Checks that <tt>symlink</tt> is a symbolic link. If <tt>file</tt> is
20
+ # given, it checks that <tt>symlink</tt> points to <tt>file</tt>
21
+ def has_symlink(symlink, file = nil)
22
+ if file.nil?
23
+ @commands << "test -L #{symlink}"
24
+ else
25
+ @commands << "test '#{file}' = `readlink #{symlink}`"
26
+ end
27
+ end
28
+ end
29
+ end
30
+ end
@@ -0,0 +1,114 @@
1
+ module Sprinkle
2
+ # = Verification Methods
3
+ #
4
+ # As documented in Sprinkle::Package, you may define a block on a package
5
+ # which verifies that a package was installed correctly. If this verification
6
+ # block fails, Sprinkle will stop the script gracefully, raising the error.
7
+ #
8
+ # In addition to checking post install if it was successfully, verification
9
+ # blocks are also ran before an install to see if a package is <em>already</em>
10
+ # installed. If this is the case, the package is skipped and Sprinkle continues
11
+ # with the next package. This behavior can be overriden by setting the -f flag on
12
+ # the sprinkle script or setting Sprinkle::OPTIONS[:force] to true if you're
13
+ # using sprinkle programmatically.
14
+ #
15
+ # == An Example
16
+ #
17
+ # The following verifies that rails was installed correctly be checking to see
18
+ # if the 'rails' command is available on the command line:
19
+ #
20
+ # package :rails do
21
+ # gem 'rails'
22
+ #
23
+ # verify do
24
+ # has_executable 'rails'
25
+ # end
26
+ # end
27
+ #
28
+ # == Available Verifiers
29
+ #
30
+ # There are a variety of available methods for use in the verification block.
31
+ # The standard methods are defined in the Sprinkle::Verifiers module, so see
32
+ # their corresponding documentation.
33
+ #
34
+ # == Custom Verifiers
35
+ #
36
+ # If you feel that the built-in verifiers do not offer a certain aspect of
37
+ # verification which you need, you may create your own verifier! Simply wrap
38
+ # any method in a module which you want to use:
39
+ #
40
+ # module MagicBeansVerifier
41
+ # def has_magic_beans(sauce)
42
+ # @commands << '[ -z "`echo $' + sauce + '`"]'
43
+ # end
44
+ # end
45
+ #
46
+ # The method can append as many commands as it wishes to the @commands array.
47
+ # These commands will be run on the remote server and <b>MUST</b> give an
48
+ # exit status of 0 if successful or other if unsuccessful.
49
+ #
50
+ # To register your verifier, call the register method on Sprinkle::Verify:
51
+ #
52
+ # Sprinle::Verify.register(MagicBeansVerifier)
53
+ #
54
+ # And now you may use it like any other verifier:
55
+ #
56
+ # package :magic_beans do
57
+ # gem 'magic_beans'
58
+ #
59
+ # verify { has_magic_beans('ranch') }
60
+ # end
61
+ class Verify
62
+ include Sprinkle::Configurable
63
+ attr_accessor :package, :description, :commands #:nodoc:
64
+
65
+ class <<self
66
+ # Register a verification module
67
+ def register(new_module)
68
+ class_eval { include new_module }
69
+ end
70
+ end
71
+
72
+ def initialize(package, description = '', &block) #:nodoc:
73
+ raise 'Verify requires a block.' unless block
74
+
75
+ @package = package
76
+ @description = description
77
+ @commands = []
78
+ @options ||= {}
79
+ @options[:padding] = 4
80
+
81
+ self.instance_eval(&block)
82
+ end
83
+
84
+ def process(roles, pre = false) #:nodoc:
85
+ assert_delivery
86
+
87
+ description = @description.empty? ? @package.name : @description
88
+
89
+ if logger.debug?
90
+ logger.debug "#{@package.name}#{description} verification sequence: #{@commands.join('; ')} for roles: #{roles}\n"
91
+ end
92
+
93
+ unless Sprinkle::OPTIONS[:testing]
94
+ logger.info "#{" " * @options[:padding]}--> Verifying #{description}..."
95
+
96
+ unless @delivery.process(@package.name, @commands, roles, true)
97
+ # Verification failed, halt sprinkling gracefully.
98
+ raise Sprinkle::VerificationFailed.new(@package, description)
99
+ end
100
+ end
101
+ end
102
+ end
103
+
104
+ class VerificationFailed < Exception #:nodoc:
105
+ attr_accessor :package, :description
106
+
107
+ def initialize(package, description)
108
+ super("Verifying #{package.name}#{description} failed.")
109
+
110
+ @package = package
111
+ @description = description
112
+ end
113
+ end
114
+ end