marionetta 0.4.0 → 0.4.1

data/README.md

@@ -59,7 +59,7 @@ of servers:
 ``` ruby
 require 'marionetta/group'
 
-servers = Marionetta::Group.new
+servers = Marionetta::Group.new(:production)
 
 servers.add_server do |s|
   s[:hostname] = 'ubuntu@example.com'
@@ -102,7 +102,7 @@ Marionetta to orchestrate a number instances.
 ``` ruby
 require 'marionetta/group'
 
-servers = Marionetta::Group.new
+servers = Marionetta::Group.new(:production)
 
 servers.add_server do |s|
   s[:hostname] = 'ubuntu@example.com'

data/Rakefile

@@ -34,11 +34,11 @@ task(:publish => :gem) do
   system(cmd.join(' && '))
 end
 
-task(:docs) do
+task(:doc) do
   docs_cmd = [
     'rm -rf docs',
     'cd lib',
-    'rocco -o ../docs -l ruby marionetta.rb',
+    'rocco -o ../docs -l ruby {*,*/*,*/*/*}.rb',
   ]
   system(docs_cmd.join(' && '))
 end

data/lib/marionetta/command_runner.rb

@@ -1,14 +1,40 @@
+# `CommandRunner` is the beast behind Marionetta. It has a
+# number of methods for executing commands both locally and
+# remotely.
+# 
+# The external requirement for this file is `open4` so that
+# we can easily capture output of commands executed.
+# 
 require 'open4'
 
 module Marionetta
   class CommandRunner
-    attr_reader :server
-    attr_reader :last
 
+    ### Server hash requirements
+
+    # The most important requirement is `:logger`. All methods
+    # depend upon this property being set since `.system()`
+    # (the local command execution method) logs commands,
+    # outputs and fatal exceptions using it. It should
+    # implement the ruby stdlib `Logger` interface.
+    # 
+    # Other requirements will be listed with their appropriate
+    # methods.
+    # 
     def initialize(server)
       @server = server
     end
     
+    ### Local execution
+
+    # Local commands are executed with `.system()`. You can
+    # optionally pass in a block which receives `stdout` and
+    # `stderr` as arguments:
+    # 
+    #     cmd.system('ls ~') do |out, err|
+    #       puts out
+    #     end
+    # 
     def system(*args)
       @last = args.join(' ')
       server[:logger].info(last)
@@ -31,26 +57,32 @@ module Marionetta
       return status.exitstatus == 0
     end
 
-    def rsync(from, to)
-      rsync_cmd = [server[:rsync][:command]]
-
-      if server[:rsync].has_key?(:flags)
-        rsync_cmd << server[:rsync][:flags]
-      end
-      
-      rsync_cmd << [from, to]
-
-      system(*rsync_cmd.flatten)
-    end
-
-    def get(file_path, save_to = File.dirname(file_path))
-      rsync("#{server[:hostname]}:#{file_path}", save_to)
-    end
-
-    def put(file_path, save_to = File.dirname(file_path))
-      rsync(file_path, "#{server[:hostname]}:#{save_to}")
-    end
+    # The last command run by `.system()` is accessible via
+    # the `.last` attribute.
+    # 
+    attr_reader :last
 
+    ### Remote execution
+
+    # Requirements for remote executions `server[:hostname]`
+    # must be set along with `server[:ssh][:command]`.
+    # Optionally `server[:ssh][:flags]` can be used to pass in
+    # flags such as `-i` for setting SSH keys.
+    # 
+    # A block can be called against this method just like
+    # `.system()` in order to get `stdout` and `stderr`.
+    # 
+    # An example:
+    # 
+    #     server = Marionetta.default_server
+    #     server[:hostname] = 'example.com'
+    #     server[:ssh][:flags] << ['-i', 'keys/private.key']
+    #     
+    #     cmd = Marionetta::CommandRunner.new(server)
+    #     cmd.ssh('ls -l') do |out, err|
+    #       puts out
+    #     end
+    # 
     def ssh(command, &block)
       ssh_cmd = [server[:ssh][:command]]
 
@@ -99,5 +131,29 @@ module Marionetta
 
       ssh(cmds.join(' && '))
     end
+
+    def rsync(from, to)
+      rsync_cmd = [server[:rsync][:command]]
+
+      if server[:rsync].has_key?(:flags)
+        rsync_cmd << server[:rsync][:flags]
+      end
+      
+      rsync_cmd << [from, to]
+
+      system(*rsync_cmd.flatten)
+    end
+
+    def get(file_path, save_to = File.dirname(file_path))
+      rsync("#{server[:hostname]}:#{file_path}", save_to)
+    end
+
+    def put(file_path, save_to = File.dirname(file_path))
+      rsync(file_path, "#{server[:hostname]}:#{save_to}")
+    end
+
+  private
+
+    attr_reader :server
   end
 end

data/lib/marionetta/manipulators/debloyer.rb

@@ -1,3 +1,11 @@
+# `Debloyer` was a way of deploying your application using
+# .deb files. However I quickly realised using the .deb format
+# was limiting since you can only install them on debian and
+# ubuntu. Also it's an inefficient way of copying a folder to
+# another system!
+# 
+# **This class is deprecated please take a look at `Deployer`.**
+# 
 require 'marionetta/command_runner'
 
 module Marionetta

data/lib/marionetta/manipulators/deployer.rb

@@ -1,18 +1,44 @@
+# `Deployer` is a class for rsyncing your application to a
+# remote machine.
+# 
+# Using a directory structure similar to capistrano `Deployer`
+# maintains a folder of releases so you may rollback quickly.
+# 
 require 'marionetta/command_runner'
 
 module Marionetta
   module Manipulators
     class Deployer
+
+      ### RakeHelper tasks
+
+      # `Deployer` provides two rake tasks when used with
+      # `RakeHelper` namely `:deploy` and `:rollback`. When
+      # applied through `RakeHelper` they will appear
+      # namespaced under `:deployer` and your group name.
+      # 
+      # With a group name of `:staging` would appear as:
+      # 
+      #     deployer:staging:deploy
+      #     deployer:staging:rollback
+      # 
       def self.tasks()
         [:deploy, :rollback]
       end
-      
-      attr_writer :cmd
 
+      ### Server hash requirements
+
+      # The keys `[:deployer][:from]` and `[:deployer][:to]`
+      # must be set in your `server` hash in order for
+      # `Deployer` to work.
+      # 
       def initialize(server)
         @server = server
       end
 
+      # Call `.can?()` to check if the correct keys have be
+      # passed in as the server.
+      # 
       def can?()
         d = server[:deployer]
         
@@ -23,11 +49,29 @@ module Marionetta
         end
       end
 
+      ### Deploying
+
+      # Call `.deploy()` to run a deploy to your remote
+      # server. The process involves:
+      # 
+      #  - `:from` directory copied to temporary directory
+      #  - `:exclude` files are removed
+      #  - rsync'd to a releases directory
+      #  - `:before_script` run
+      #  - release directory symlinked to a current directory
+      #  - `:after_script` run
+      # 
+      # The directory structure under `server[:deployer][:to]`
+      # looks something like this:
+      # 
+      #   current/ -> ./releases/2012-09-20_14:04:39
+      #   releases/
+      #     2012-09-20_13:59:15
+      #     2012-09-20_14:04:39
+      # 
       def deploy()
         release = timestamp
-
         create_tmp_release_dir(release)
-
         cmd.ssh("mkdir -p #{release_dir}")
 
         unless cmd.put(tmp_release_dir(release), release_dir)
@@ -39,6 +83,10 @@ module Marionetta
         run_script(:after, release)
       end
 
+      # To get an array of all releases call `.releases()`.
+      # Any release that is subsequently rolled back will not
+      # be listed.
+      # 
       def releases()
         releases = []
 
@@ -51,6 +99,10 @@ module Marionetta
         return releases
       end
 
+      # If you push out and need to rollback to the previous
+      # version you can use `.rollback()` to do just that.
+      # Currently you can only rollback once at a time.
+      # 
       def rollback()
         rollback_to_release = releases[-2]
 
@@ -63,6 +115,13 @@ module Marionetta
           symlink_release_dir(rollback_to_release)
         end
       end
+      
+      ### Dependency Injection
+
+      # To use your own alternative to `CommandRunner` you can
+      # set an object of your choice via the `.cmd=` method.
+      # 
+      attr_writer :cmd
 
     private
       
@@ -77,7 +136,7 @@ module Marionetta
       end
 
       def tmp_release_dir(release)
-        "/tmp/#{release}"
+        "/tmp/#{server[:hostname]}/#{release}"
       end
 
       def to_dir()
@@ -113,12 +172,19 @@ module Marionetta
 
       def create_tmp_release_dir(release)
         tmp_release_dir = tmp_release_dir(release)
-        cmd.system("cp -r #{from_dir} #{tmp_release_dir}")
+
+        create_tmp_dir_cmds = [
+          "mkdir -p #{File.dirname(tmp_release_dir)}",
+          "cp -rf #{from_dir} #{tmp_release_dir}",
+        ]
+        cmd.system(create_tmp_dir_cmds.join(' && '))
 
         if server[:deployer].has_key?(:exclude)
           exclude_files = server[:deployer][:exclude]
           exclude_files.map! {|f| Dir["#{tmp_release_dir}/#{f}"]}
-          cmd.system("rm -rf #{exclude_files.flatten.join(' ')}")
+          exclude_files.flatten!
+
+          cmd.system("rm -rf #{exclude_files.join(' ')}") unless exclude_files.empty?
         end
       end
 

data/lib/marionetta/manipulators/puppet_manipulator.rb

@@ -1,37 +1,83 @@
+# `PuppetManipulator` copies a puppet manifest and optionally
+# modules to a remote machine and applies them.
+# 
+# You could do this with a puppet master instance, and that
+# could (and most likely is) the right option for you. However
+# if you do not want to host an additional node as your puppet
+# master or want to push changes from your machine directly to
+# nodes them this class maybe what you're looking for.
+# 
 require 'marionetta/command_runner'
 
 module Marionetta
   module Manipulators
     class PuppetManipulator
+
+      ### RakeHelper tasks
+
+      # `PupperManipulator` provides two rake tasks when used
+      # with `RakeHelper` namely `:install` and `:update`. 
+      # When applied through `RakeHelper` they will appear
+      # namespaced under `:puppet` and your group name.
+      #
+      # With a group name of `:staging` would appear as:
+      # 
+      #     puppet:staging:install
+      #     puppet:staging:update
+      # 
       def self.tasks()
         [:install, :update]
       end
 
-      attr_writer :cmd
-      
+      ### Server hash requirements
+
+      # The key `[:puppet][:manifest]` must be set in your
+      # `server` hash in order for `PuppetManipulator` to
+      # function correctly.
+      # 
       def initialize(server)
         @server = server
       end
 
+      # Call `.can?()` to check if the `:manifest` key has
+      # been set in the `server[:puppet]`.
+      # 
       def can?()
         server[:puppet].has_key?(:manifest)
       end
 
+      ### Installing puppet
+
+      # `PuppetManipulator` provides the `.install()` method
+      # to install puppet on debian or ubuntu servers.
+      # 
       def install()
         install_deb_repo
         install_deb
       end
 
-      def installed?()
-        cmd.ssh('which puppet')
-      end
+      ### Updating puppet
 
+      # Use `.update()` to package up your manifest and
+      # optionally modules and send them to your remote
+      # machine. Once there they will be applied.
+      # 
+      # If puppet is not installed, we attempt to install it
+      # before applying the manifest.
+      # 
       def update()
         install unless installed?
         archive_files
         send_archive
         apply_archive
       end
+      
+      ### Dependency Injection
+
+      # To use your own alternative to `CommandRunner` you can
+      # set an object of your choice via the `.cmd=` method.
+      # 
+      attr_writer :cmd
 
     private
     
@@ -41,6 +87,10 @@ module Marionetta
         @cmd ||= CommandRunner.new(server)
       end
 
+      def installed?()
+        cmd.ssh('which puppet')
+      end
+
       def install_deb_repo()
         deb_file = 'puppetlabs-release-stable.deb'
       
@@ -64,9 +114,11 @@ module Marionetta
         cmd.ssh("which puppet || { #{install_cmd}; }")
       end
 
-      def archive_files()
-        puppet_tmp = '/tmp/puppet'
+      def puppet_tmp()
+        "/tmp/puppet_#{server[:hostname]}"
+      end
 
+      def archive_files()
         cmds = [
           "rm -rf #{puppet_tmp}",
           "mkdir #{puppet_tmp}",
@@ -82,12 +134,12 @@ module Marionetta
       end
 
       def send_archive()
-        cmd.put('/tmp/puppet.tar.gz')
+        cmd.put("#{puppet_tmp}.tar.gz")
       end
 
       def apply_archive()
-        cmd.ssh_extract('/tmp/puppet.tar.gz')
-        cmds = ['cd /tmp/puppet']
+        cmd.ssh_extract("#{puppet_tmp}.tar.gz")
+        cmds = ["cd #{puppet_tmp}"]
 
         puppet_cmd = ['sudo puppet apply']
 

data/lib/marionetta/rake_helper.rb

@@ -4,9 +4,9 @@ require 'rake'
 
 module Marionetta
   module RakeHelper
-    extend self
-
     include ::Rake::DSL if defined?(::Rake::DSL)
+    
+    extend self
 
     def install_group_tasks(group)
       install_group_tasks_for(group)

data/lib/marionetta.rb

@@ -9,12 +9,12 @@
 # Installing the gem is the best way to start using
 # Marionetta. You can do this from command line:
 # 
-#   gem install marionetta
+#     gem install marionetta
 # 
 # Or – better yet – in your Gemfile:
 # 
-#   source 'http://rubygems.org'
-#   gem 'marionetta'
+#     source 'http://rubygems.org'
+#     gem 'marionetta'
 # 
 # Marionetta is written by [Luke Morton][author] and licensed
 # under the MIT license. The project is [hosted on github][github]
@@ -23,14 +23,15 @@
 # 
 # [author]: http://lukemorton.co.uk
 # [github]: https://github.com/DrPheltRight/marionetta
+# 
 module Marionetta
 
-  VERSION = '0.4.0'
+  VERSION = '0.4.1'
 
   ### Defining Servers
 
   # In order to connect to servers you must define configs for
-  # each. This method provides a default map describing some
+  # each. This method provides a default hash describing some
   # common settings including command binaries, default flags
   # and more.
   # 
@@ -41,6 +42,10 @@ module Marionetta
   # elsewhere in Marionetta where you can better define your
   # servers. You should consult this method in order to see
   # the defaults.
+  # 
+  # Any place in this library you see a variable called
+  # `server` you can be certain it is a server hash.
+  # 
   def self.default_server()
     {
       :logger => Logger.new($stdout),

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: marionetta
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-20 00:00:00.000000000 Z
+date: 2012-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: open4