mitchellh-sprinkle 0.1.5

data/examples/rails/rails.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env sprinkle -s
+
+# Annotated Example Sprinkle Rails deployment script
+#
+# This is an example Sprinkle script configured to install Rails from gems, Apache, Ruby and
+# Sphinx from source, and mysql from apt on an Ubuntu system.
+#
+# Installation is configured to run via capistrano (and an accompanying deploy.rb recipe script).
+# Source based packages are downloaded and built into /usr/local on the remote system.
+#
+# A sprinkle script is separated into 3 different sections. Packages, policies and deployment:
+
+
+# Packages (separate files for brevity)
+#
+#  Defines the world of packages as we know it. Each package has a name and
+#  set of metadata including its installer type (eg. apt, source, gem, etc). Packages can have
+#  relationships to each other via dependencies.
+
+require 'packages/essential'
+require 'packages/rails'
+require 'packages/database'
+require 'packages/server'
+require 'packages/search'
+
+
+# Policies
+#
+#  Names a group of packages (optionally with versions) that apply to a particular set of roles:
+#
+#   Associates the rails policy to the application servers. Contains rails, and surrounding
+#   packages. Note, appserver, database, webserver and search are all virtual packages defined above.
+#   If there's only one implementation of a virtual package, it's selected automatically, otherwise
+#   the user is requested to select which one to use.
+
+policy :rails, :roles => :app do
+  requires :rails, :version => '2.1.0'
+  requires :appserver
+  requires :database
+  requires :webserver
+  requires :search
+end
+
+
+# Deployment
+#
+#  Defines script wide settings such as a delivery mechanism for executing commands on the target
+#  system (eg. capistrano), and installer defaults (eg. build locations, etc):
+#
+#   Configures spinkle to use capistrano for delivery of commands to the remote machines (via
+#   the named 'deploy' recipe). Also configures 'source' installer defaults to put package gear
+#   in /usr/local
+
+deployment do
+
+  # mechanism for deployment
+  delivery :capistrano do
+    recipes 'deploy'
+  end
+
+  # source based package installer defaults
+  source do
+    prefix   '/usr/local'
+    archives '/usr/local/sources'
+    builds   '/usr/local/build'
+  end
+
+end
+
+# End of script, given the above information, Spinkle will apply the defined policy on all roles using the
+# deployment settings specified.

data/examples/sprinkle/sprinkle.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env sprinkle -c -s
+
+# Example of the simplest Sprinkle script to install a single gem on a remote host. This
+# particular script assumes that rubygems (and ruby, etc) are already installed on the remote
+# host. To see a larger example of installing an entire ruby, rubygems, gem stack from source,
+# please see the rails example.
+
+# Packages, only sprinkle is defined in this world
+
+package :sprinkle do
+  description 'Sprinkle Provisioning Tool'
+  gem 'crafterm-sprinkle' do
+    source 'http://gems.github.com' # use alternate gem server
+    #repository '/opt/local/gems'   # specify an alternate local gem repository
+  end
+end
+
+
+# Policies, sprinkle policy requires only the sprinkle gem
+
+policy :sprinkle, :roles => :app do
+  requires :sprinkle
+end
+
+
+# Deployment settings
+
+deployment do
+
+  # use vlad for deployment
+  delivery :vlad do
+    role :app, 'yourhost.com'
+  end
+
+end
+
+# End of script, given the above information, Spinkle will apply the defined policy on all roles using the
+# deployment settings specified.

data/lib/sprinkle/actors/actors.rb

@@ -0,0 +1,17 @@
+#--
+# The only point of this file is to give RDoc a definition for
+# Sprinkle::Actors. This file in production is never actually included
+# since ActiveSupport only on-demand loads classes which are needed
+# and this module is never explicitly needed.
+#++
+
+module Sprinkle
+  # An actor is a method of command delivery to a remote machine. It is the
+  # layer between sprinkle and the SSH connection to run commands. This gives
+  # you the flexibility to define custom actors, for whatever purpose you need.
+  #
+  # 99% of the time, however, the two built-in actors Sprinkle::Actors::Capistrano
+  # and Sprinkle::Actors::Vlad will be enough.
+  module Actors
+  end
+end

data/lib/sprinkle/actors/capistrano.rb

@@ -0,0 +1,117 @@
+require 'capistrano/cli'
+
+module Sprinkle
+  module Actors
+    # = Capistrano Delivery Method
+    #
+    # Capistrano is one of the delivery method options available out of the
+    # box with Sprinkle. If you have the capistrano gem install, you may use
+    # this delivery. The only configuration option available, and which is 
+    # mandatory to include is +recipes+. An example:
+    #
+    #   deployment do
+    #     delivery :capistrano do
+    #       recipes 'deploy'
+    #     end
+    #   end
+    #
+    # Recipes is given a list of files which capistrano will include and load.
+    # These recipes are mainly to set variables such as :user, :password, and to 
+    # set the app domain which will be sprinkled. 
+    class Capistrano
+      attr_accessor :config, :loaded_recipes #:nodoc:
+
+      def initialize(&block) #:nodoc:
+        @config = ::Capistrano::Configuration.new
+        @config.logger.level = Sprinkle::OPTIONS[:verbose] ? ::Capistrano::Logger::INFO : ::Capistrano::Logger::IMPORTANT
+        @config.set(:password) { ::Capistrano::CLI.password_prompt }
+        if block
+          self.instance_eval &block
+        else
+          @config.load 'deploy' # normally in the config directory for rails
+        end
+      end
+
+      # Defines a recipe file which will be included by capistrano. Use these
+      # recipe files to set capistrano specific configurations. Default recipe
+      # included is "deploy." But if any other recipe is specified, it will
+      # include that instead. Multiple recipes may be specified through multiple
+      # recipes calls, an example:
+      #
+      #   deployment do
+      #     delivery :capistrano do
+      #       recipes 'deploy'
+      #       recipes 'magic_beans'
+      #     end
+      #   end
+      def recipes(script)
+        @loaded_recipes ||= []
+        @config.load script
+        @loaded_recipes << script
+      end
+
+      def process(name, commands, roles, suppress_and_return_failures = false) #:nodoc:
+        define_task(name, roles) do
+          via = fetch(:run_method, :sudo)
+          commands.each do |command|
+            invoke_command command, :via => via
+          end
+        end
+        
+        begin
+          run(name)
+          return true
+        rescue ::Capistrano::CommandError => e
+          return false if suppress_and_return_failures
+          
+          # Reraise error if we're not suppressing it
+          raise
+        end
+      end
+
+      private
+
+        # REVISIT: can we set the description somehow?
+        def define_task(name, roles, &block)
+          @config.task task_sym(name), :roles => roles, &block
+        end
+
+        def run(task)
+          @config.send task_sym(task)
+        end
+
+        def task_sym(name)
+          "install_#{name.to_task_name}".to_sym
+        end
+    end
+  end
+end
+
+
+=begin
+
+# channel: the SSH channel object used for this response
+# stream: either :err or :out, for stderr or stdout responses
+# output: the text that the server is sending, might be in chunks
+run "apt-get update" do |channel, stream, output|
+   if output =~ /Are you sure?/
+     answer = Capistrano::CLI.ui.ask("Are you sure: ")
+     channel.send_data(answer + "\n")
+   else
+     # allow the default callback to be processed
+     Capistrano::Configuration.default_io_proc.call[channel, stream, output]
+   end
+ end
+
+
+
+ You can tell subversion to use a different username+password by
+ setting a couple variables:
+    set :svn_username, "my svn username"
+    set :svn_password, "my svn password"
+ If you don't want to set the password explicitly in your recipe like
+ that, you can make capistrano prompt you for it like this:
+    set(:svn_password) { Capistrano::CLI.password_prompt("Subversion
+ password: ") }
+ - Jamis
+=end

data/lib/sprinkle/actors/vlad.rb

@@ -0,0 +1,65 @@
+module Sprinkle
+  module Actors
+    # = Vlad Delivery Method
+    #
+    # Vlad is one of the delivery method options available out of the
+    # box with Sprinkle. If you have the vlad the deployer gem install, you 
+    # may use this delivery. The only configuration option available, and 
+    # which is mandatory to include is +script+. An example:
+    #
+    #   deployment do
+    #     delivery :vlad do
+    #       script 'deploy'
+    #     end
+    #   end
+    #
+    # script is given a list of files which capistrano will include and load.
+    # These recipes are mainly to set variables such as :user, :password, and to 
+    # set the app domain which will be sprinkled.
+    class Vlad
+      require 'vlad'
+      attr_accessor :loaded_recipes #:nodoc:
+
+      def initialize(&block) #:nodoc:
+        self.instance_eval &block if block
+      end
+
+      # Defines a script file which will be included by vlad. Use these
+      # script files to set vlad specific configurations. Multiple scripts
+      # may be specified through multiple script calls, an example:
+      #
+      #   deployment do
+      #     delivery :vlad do
+      #       script 'deploy'
+      #       script 'magic_beans'
+      #     end
+      #   end
+      def script(name)
+        @loaded_recipes ||= []
+        self.load name
+        @loaded_recipes << script
+      end
+
+      def process(name, commands, roles, suppress_and_return_failures = false) #:nodoc:
+        commands = commands.join ' && ' if commands.is_a? Array
+        t = remote_task(task_sym(name), :roles => roles) { run commands }
+        
+        begin
+          t.invoke
+          return true
+        rescue ::Vlad::CommandFailedError => e
+          return false if suppress_and_return_failures
+          
+          # Reraise error if we're not suppressing it
+          raise
+        end
+      end
+
+      private
+
+        def task_sym(name)
+          "install_#{name.to_task_name}".to_sym
+        end
+    end
+  end
+end

data/lib/sprinkle/configurable.rb

@@ -0,0 +1,27 @@
+module Sprinkle
+  #--
+  # TODO: Possible documentation?
+  #++
+  module Configurable #:nodoc:
+    attr_accessor :delivery
+    
+    def defaults(deployment)
+      defaults = deployment.defaults[self.class.name.split(/::/).last.downcase.to_sym]
+      self.instance_eval(&defaults) if defaults
+      @delivery = deployment.style
+    end
+    
+    def assert_delivery
+      raise 'Unknown command delivery target' unless @delivery
+    end
+    
+    def method_missing(sym, *args, &block)
+      unless args.empty? # mutate if not set
+        @options ||= {}
+        @options[sym] = *args unless @options[sym]
+      end
+
+      @options[sym] || @package.send(sym, *args, &block) # try the parents options if unknown
+    end
+  end
+end

data/lib/sprinkle/deployment.rb

@@ -0,0 +1,73 @@
+module Sprinkle
+  # Deployment blocks specify deployment specific information about a 
+  # sprinkle script. An example:
+  #
+  #   deployment do
+  #     # mechanism for deployment
+  #     delivery :capistrano do
+  #       recipes 'deploy'
+  #     end
+  # 
+  #     # source based package installer defaults
+  #     source do
+  #       prefix   '/usr/local'
+  #       archives '/usr/local/sources'
+  #       builds   '/usr/local/build'
+  #     end
+  #   end
+  #
+  # What the above example does is tell sprinkle that we will be using
+  # *capistrano* (Sprinkle::Actors::Capistrano) for deployment and
+  # everything within the block is capistrano specific configuration.
+  # For more information on what options are available, check the corresponding
+  # Sprinkle::Actors doc page.
+  #
+  # In addition to what delivery mechanism we're using, we specify some
+  # configuration options for the "source" command. The only things
+  # configurable, at this time, in the deployment block other than
+  # the delivery method are installers. If installers are configurable,
+  # they will say so on their corresponding documentation page. See
+  # Sprinkle::Installers
+  #
+  # <b>Only one deployment block is on any given sprinkle script</b>
+  module Deployment
+    # The method outlined above which specifies deployment specific information
+    # for a sprinkle script. For more information, read the header of this module.
+    def deployment(&block)
+      @deployment = Deployment.new(&block)
+    end
+
+    class Deployment
+      attr_accessor :style, :defaults #:nodoc:
+
+      def initialize(&block) #:nodoc:
+        @defaults = {}
+        self.instance_eval(&block)
+        raise 'No delivery mechanism defined' unless @style
+      end
+
+      # Specifies which Sprinkle::Actors to use for delivery. Although all
+      # actors jobs are the same: to run remote commands on a server, you
+      # may have a personal preference. The block you pass is used to configure
+      # the actor. For more information on what configuration options are
+      # available, view the corresponding Sprinkle::Actors page.
+      def delivery(type, &block) #:doc:
+        @style = Actors.const_get(type.to_s.titleize).new &block
+      end
+
+      def method_missing(sym, *args, &block) #:nodoc:
+        @defaults[sym] = block
+      end
+
+      def respond_to?(sym) #:nodoc:
+        !!@defaults[sym]
+      end
+
+      def process #:nodoc:
+        POLICIES.each do |policy|
+          policy.process(self)
+        end
+      end
+    end
+  end
+end

data/lib/sprinkle/extensions/arbitrary_options.rb

@@ -0,0 +1,10 @@
+module ArbitraryOptions #:nodoc:
+  def self.included(base)
+    base.alias_method_chain :method_missing, :arbitrary_options
+  end
+  
+  def method_missing_with_arbitrary_options(sym, *args, &block)
+    self.class.dsl_accessor sym
+    send(sym, *args, &block)
+  end
+end

data/lib/sprinkle/extensions/array.rb

@@ -0,0 +1,5 @@
+class Array #:nodoc:
+  def to_task_name
+    collect(&:to_task_name).join('_')
+  end
+end

data/lib/sprinkle/extensions/blank_slate.rb

@@ -0,0 +1,5 @@
+class BlankSlate #:nodoc:
+  instance_methods.each do |m| 
+    undef_method(m) unless %w( __send__ __id__ send class inspect instance_eval instance_variables ).include?(m)
+  end
+end

data/lib/sprinkle/extensions/dsl_accessor.rb

@@ -0,0 +1,15 @@
+class Module #:nodoc:
+  def dsl_accessor(*symbols)
+    symbols.each do |sym|
+      class_eval %{
+        def #{sym}(*val)
+          if val.empty?
+            @#{sym}
+          else
+            @#{sym} = val.size == 1 ? val[0] : val
+          end
+        end
+      }
+    end
+  end
+end

data/lib/sprinkle/extensions/string.rb

@@ -0,0 +1,10 @@
+class String #:nodoc:
+  
+  # REVISIT: what chars shall we allow in task names?
+  def to_task_name
+    s = downcase
+    s.gsub!(/-/, '_') # all - to _ chars
+    s
+  end
+  
+end

data/lib/sprinkle/extensions/symbol.rb

@@ -0,0 +1,7 @@
+class Symbol #:nodoc:
+  
+  def to_task_name
+    to_s.to_task_name
+  end
+  
+end

data/lib/sprinkle/installers/apt.rb

@@ -0,0 +1,51 @@
+module Sprinkle
+  module Installers
+    # = Apt Package Installer
+    #
+    # The Apt package installer uses the +apt-get+ command to install
+    # packages. The apt installer has only one option which can be
+    # modified which is the +dependencies_only+ option. When this is
+    # set to true, the installer uses +build-dep+ instead of +install+
+    # to only build the dependencies.
+    # 
+    # == Example Usage
+    #
+    # First, a simple installation of the magic_beans package:
+    #
+    #   package :magic_beans do
+    #     description "Beans beans they're good for your heart..."
+    #     apt 'magic_beans_package'
+    #   end
+    #
+    # Second, only build the magic_beans dependencies:
+    #
+    #   package :magic_beans_depends do
+    #     apt 'magic_beans_package' { dependencies_only true }
+    #   end
+    #
+    # As you can see, setting options is as simple as creating a
+    # block and calling the option as a method with the value as 
+    # its parameter.
+    class Apt < Installer
+      attr_accessor :packages #:nodoc:
+
+      def initialize(parent, *packages, &block) #:nodoc:
+        super parent, &block
+        packages.flatten!
+        
+        options = { :dependencies_only => false }
+        options.update(packages.pop) if packages.last.is_a?(Hash)
+        
+        @command = options[:dependencies_only] ? 'build-dep' : 'install'
+        @packages = packages
+      end
+
+      protected
+
+        def install_commands #:nodoc:
+          "DEBCONF_TERSE='yes' DEBIAN_PRIORITY='critical' DEBIAN_FRONTEND=noninteractive apt-get -qyu #{@command} #{@packages.join(' ')}"
+        end
+
+    end
+  end
+end

data/lib/sprinkle/installers/gem.rb

@@ -0,0 +1,61 @@
+module Sprinkle
+  module Installers
+    # = Ruby Gem Package Installer
+    #
+    # The gem package installer installs ruby gems.
+    #
+    # The installer has a single optional configuration: source.
+    # By changing source you can specify a given ruby gems
+    # repository from which to install.
+    # 
+    # == Example Usage
+    #
+    # First, a simple installation of the magic_beans gem:
+    #
+    #   package :magic_beans do
+    #     description "Beans beans they're good for your heart..."
+    #     gem 'magic_beans'
+    #   end
+    #
+    # Second, install magic_beans gem from github:
+    #
+    #   package :magic_beans do
+    #     gem 'magic_beans_package' do
+    #       source 'http://gems.github.com'
+    #     end
+    #   end
+    #
+    # As you can see, setting options is as simple as creating a
+    # block and calling the option as a method with the value as 
+    # its parameter.
+    class Gem < Installer
+      attr_accessor :gem #:nodoc:
+
+      def initialize(parent, gem, options = {}, &block) #:nodoc:
+        super parent, options, &block
+        @gem = gem
+      end
+
+      def source(location = nil) #:nodoc:
+        # package defines an installer called source so here we specify a method directly
+        # rather than rely on the automatic options processing since packages' method missing
+        # won't be run
+        return @options[:source] unless location
+        @options[:source] = location
+      end
+
+      protected
+
+        # rubygems 0.9.5+ installs dependencies by default, and does platform selection
+
+        def install_commands #:nodoc:
+          cmd = "gem install #{gem}"
+          cmd << " --version '#{version}'" if version
+          cmd << " --source #{source}" if source
+          cmd << " --install-dir #{repository}" if repository
+          cmd
+        end
+
+    end
+  end
+end