deployml 0.3.0 → 0.4.0

data/ChangeLog.md

@@ -1,3 +1,29 @@
+### 0.4.0 / 2010-11-29
+
+* Require addressable ~> 2.2.0.
+* Added methods to {DeploYML::Environment} inorder to mirror
+  {DeploYML::Project}:
+  * `invoke`
+  * `setup!`
+  * `update!`
+  * `install!`
+  * `migrate!`
+  * `config!`
+  * `start!`
+  * `stop!`
+* Added {DeploYML::Shell#status} for printing ANSI colored status messages.
+* Added {DeploYML::RemoteShell#uri}.
+* Added {DeploYML::RemoteShell#history}.
+* Added missing documentation.
+* Give the root directory passed to {DeploYML::Project#initialize} the
+  default of `Dir.pwd`.
+* If the destination URI has the scheme of `file:`, have
+  {DeploYML::Environment#remote_shell} return a {DeploYML::LocalShell}.
+  * This should facilitate local deploys.
+* Perform a forced pull in {DeploYML::Environment#update}.
+* Override {DeploYML::Environment#rake} in {DeploYML::Frameworks::Rails}.
+* Escape all arguments of all commands in {DeploYML::RemoteShell#join}.
+
 ### 0.3.0 / 2010-11-21
 
 * Initial release:

data/README.md

@@ -2,6 +2,7 @@
 
 * [Source](http://github.com/postmodern/deployml)
 * [Issues](http://github.com/postmodern/deployml/issues)
+* [Documentation](http://rubydoc.info/gems/deployml/frames)
 * Postmodern (postmodern.mod3 at gmail.com)
 
 ## Description
@@ -63,6 +64,29 @@ Specifying a `server` with options:
 	socket: /var/run/thin.sock
 	rackup: true
 
+Multiple environments:
+
+    # config/deploy.yml
+    source: git@github.com:user/project.git
+    framework: rails3
+    orm: datamapper
+
+    # config/deploy/staging.yml
+    dest: ssh://deploy@www.example.com/srv/staging
+    server:
+      name: thin
+      options:
+        config: /etc/thin/staging.yml
+        socket: /tmp/thin.staging.sock
+
+    # config/deploy/production.yml
+    dest: ssh://deploy@www.example.com/srv/project
+    server:
+      name: thin
+      options:
+        config: /etc/thin/example.yml
+        socket: /tmp/thin.example.sock
+
 ## Synopsis
 
 Cold-Deploy a new project:
@@ -91,7 +115,7 @@ List available tasks:
 
 ## Requirements
 
-* [addressable](http://addressable.rubyforge.org/) ~> 2.1.1
+* [addressable](http://addressable.rubyforge.org/) ~> 2.2.0
 * [rprogram](http://github.com/postmodern/rprogram) ~> 0.2.0
 * [thor](http://github.com/wycats/thor) ~> 0.14.3
 

data/gemspec.yml

@@ -11,7 +11,7 @@ homepage: http://github.com/postmodern/deployml
 has_yard: true
 
 dependencies:
-  addressable: ~> 2.1.1
+  addressable: ~> 2.2.0
   rprogram: ~> 0.2.0
   thor: ~> 0.14.3
 

data/lib/deployml/cli.rb

@@ -4,31 +4,65 @@ require 'thor'
 require 'pathname'
 
 module DeploYML
+  #
+  # The command-line interface to {DeploYML} using
+  # [Thor](http://github.com/wycats/thor#readme).
+  #
   class CLI < Thor
 
     namespace 'deploy'
 
     desc 'exec', 'Runs a command on the deploy server'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
+
+    #
+    # Executes a command in the specified environment.
+    #
+    # @param [String] command
+    #   The full command to execute.
+    #
     def exec(command)
       environment.exec(command)
     end
 
     desc 'rake', 'Executes a rake task on the deploy server'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
     method_option :args, :type => :array
+
+    #
+    # Invokes a rake task in the specified environment.
+    #
+    # @param [String] task
+    #   The name of the rake task.
+    #
     def rake(task)
       environment.rake(task,*(options[:args]))
     end
 
     desc 'ssh', 'Starts a SSH session with the deploy server'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
+
+    #
+    # Starts an SSH session with the specified environment.
+    #
     def ssh
       environment.ssh
     end
 
     desc 'setup', 'Sets up the deployment repository for the project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
+
+    #
+    # Sets up the specified environment.
+    #
     def setup
       status 'Setting up ...'
 
@@ -38,7 +72,13 @@ module DeploYML
     end
 
     desc 'update', 'Updates the deployment repository of the project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
+
+    #
+    # Updates the deployment repository of the specified environment.
+    #
     def update
       status 'Updating'
 
@@ -48,7 +88,13 @@ module DeploYML
     end
 
     desc 'install', 'Installs the project on the deploy server'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
+
+    #
+    # Installs any needed dependencies in the specified environment.
+    #
     def install
       status 'Installing ...'
 
@@ -58,7 +104,13 @@ module DeploYML
     end
 
     desc 'migrate', 'Migrates the database for the project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
+
+    #
+    # Migrates the database for the specified environment.
+    #
     def migrate
       status 'Migrating ...'
 
@@ -68,7 +120,13 @@ module DeploYML
     end
 
     desc 'config', 'Configures the server for the project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
+
+    #
+    # Configures the server for the specified environment.
+    #
     def config
       status 'Configuring ...'
 
@@ -78,8 +136,13 @@ module DeploYML
     end
 
     desc 'start', 'Starts the server for the project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
 
+    #
+    # Starts the server in the specified environment.
+    #
     def start
       status 'Starting ...'
 
@@ -89,8 +152,13 @@ module DeploYML
     end
 
     desc 'stop', 'Stops the server for the project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
 
+    #
+    # Stops the server in the specified environment.
+    #
     def stop
       status 'Stopping ...'
 
@@ -100,8 +168,13 @@ module DeploYML
     end
 
     desc 'restart', 'Restarts the server for the project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
 
+    #
+    # Restarts the server in the specified environment.
+    #
     def restart
       status 'Restarting ...'
 
@@ -111,8 +184,13 @@ module DeploYML
     end
 
     desc 'deploy', 'Cold-Deploys a new project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
 
+    #
+    # Cold-deploys into the specified environment.
+    #
     def deploy
       status 'Deploying ...'
 
@@ -122,8 +200,13 @@ module DeploYML
     end
 
     desc 'redeploy', 'Redeploys the project'
-    method_option :environment, :type => :string, :default => 'production'
+    method_option :environment, :type => :string,
+                                :default => 'production',
+                                :aliases => '-E'
 
+    #
+    # Redeploys into the specified environment.
+    #
     def redeploy
       status 'Redeploying ...'
 
@@ -184,6 +267,12 @@ module DeploYML
       project.environment(options[:environment])
     end
 
+    #
+    # Prints a status message.
+    #
+    # @param [String] message
+    #   The message to print.
+    #
     def status(message)
       shell.say_status "[#{options[:environment]}]", message
     end

data/lib/deployml/environment.rb

@@ -8,6 +8,10 @@ require 'deployml/servers'
 require 'deployml/frameworks'
 
 module DeploYML
+  #
+  # Contains environment specific configuration loaded by {Project}
+  # from YAML files within `config/deploy/`.
+  #
   class Environment < Configuration
 
     # Mapping of possible 'server' names to their mixins.
@@ -82,13 +86,18 @@ module DeploYML
     # @yieldparam [RemoteShell] shell
     #   The remote shell.
     #
-    # @return [RemoteShell]
-    #   The remote shell.
+    # @return [RemoteShell, LocalShell]
+    #   The remote shell. If the destination is a local `file://` URI,
+    #   a local shell will be returned instead.
     #
     # @since 0.3.0
     #
     def remote_shell(&block)
-      RemoteShell.new(@dest,&block)
+      unless @dest.scheme == 'file'
+        RemoteShell.new(@dest,&block)
+      else
+        LocalShell.new(&block)
+      end
     end
 
     #
@@ -162,7 +171,7 @@ module DeploYML
     #
     def update(shell)
       shell.run 'git', 'reset', '--hard', 'HEAD'
-      shell.run 'git', 'pull'
+      shell.run 'git', 'pull', '-f'
     end
 
     #
@@ -231,6 +240,192 @@ module DeploYML
     def server_restart(shell)
     end
 
+    #
+    # Deploys the project.
+    #
+    # @param [Array<Symbol>] tasks
+    #   The tasks to run during the deployment.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def invoke(tasks)
+      remote_shell do |shell|
+        # setup the deployment repository
+        if tasks.include?(:setup)
+          shell.status "Cloning #{@source} ..."
+          setup(shell)
+          shell.status "Cloned."
+        end
+
+        # cd into the deployment repository
+        shell.cd @dest.path
+
+        # update the deployment repository
+        if tasks.include?(:update)
+          shell.status "Updating #{@dest.path} ..."
+          update(shell)
+          shell.status "Updated."
+        end
+
+        # framework tasks
+        if tasks.include?(:install)
+          shell.status "Installing additional dependencies ..."
+          install(shell)
+          shell.status "Dependencies installed."
+        end
+
+        if tasks.include?(:migrate)
+          shell.status "Migrating database ..."
+          migrate(shell)
+          shell.status "Database migrated."
+        end
+
+        # server tasks
+        if tasks.include?(:config)
+          shell.status "Configuring server ..."
+          server_config(shell)
+          shell.status "Server configured."
+        elsif tasks.include?(:start)
+          shell.status "Starting server ..."
+          server_start(shell)
+          shell.status "Server started."
+        elsif tasks.include?(:stop)
+          shell.status "Stopping server ..."
+          server_stop(shell)
+          shell.status "Server stopped."
+        elsif tasks.include?(:restart)
+          shell.status "Restarting server ..."
+          server_restart(shell)
+          shell.status "Server restarted."
+        end
+      end
+
+      return true
+    end
+
+    #
+    # Sets up the deployment repository for the project.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def setup!
+      invoke [:setup]
+    end
+
+    #
+    # Updates the deployed repository of the project.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def update!
+      invoke [:update]
+    end
+
+    #
+    # Installs the project on the destination server.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def install!
+      invoke [:install]
+    end
+
+    #
+    # Migrates the database used by the project.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def migrate!
+      invoke [:migrate]
+    end
+
+    #
+    # Configures the Web server to be ran on the destination server.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def config!
+      invoke [:config]
+    end
+
+    #
+    # Starts the Web server for the project.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def start!
+      invoke [:start]
+    end
+
+    #
+    # Stops the Web server for the project.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def stop!
+      invoke [:stop]
+    end
+
+    #
+    # Restarts the Web server for the project.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def restart!
+      invoke [:restart]
+    end
+
+    #
+    # Deploys a new project.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def deploy!
+      invoke [:setup, :install, :migrate, :config, :start]
+    end
+
+    #
+    # Redeploys a project.
+    #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
+    # @since 0.4.0
+    #
+    def redeploy!
+      invoke [:update, :install, :migrate, :restart]
+    end
+
     protected
 
     #

data/lib/deployml/frameworks/rails.rb

@@ -0,0 +1,20 @@
+module DeploYML
+  module Frameworks
+    #
+    # Provides common methods needed to deploy Rails 2 and 3 projects.
+    #
+    module Rails
+      #
+      # Overrides the default `rake` method to add a `RAILS_ENV`
+      # environment variable.
+      #
+      # @see {Environment#rake}
+      #
+      def rake(task,*args)
+        args += ["RAILS_ENV=#{@environment}"]
+
+        super(task,*args)
+      end
+    end
+  end
+end

data/lib/deployml/frameworks/rails2.rb

@@ -1,6 +1,19 @@
+require 'deployml/frameworks/rails'
+
 module DeploYML
   module Frameworks
+    #
+    # Provides methods for deploying Rails 2 projects.
+    #
     module Rails2
+      include Rails
+
+      #
+      # Migrates the database using the `db:migrate` task.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def migrate(shell)
         shell.run 'rake', 'db:migrate', "RAILS_ENV=#{@environment}"
       end

data/lib/deployml/frameworks/rails3.rb

@@ -1,10 +1,31 @@
+require 'deployml/frameworks/rails'
+
 module DeploYML
   module Frameworks
+    #
+    # Provides methods for deploying Rails 3 projects.
+    #
     module Rails3
+      include Rails
+
+      #
+      # Installs any dependencies using `bundle install --deployment`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def install(shell)
         shell.run 'bundle', 'install', '--deployment'
       end
 
+      #
+      # Migrates the database using the `db:autoupgrade` if
+      # [DataMapper](http://datamapper.org) is being used, or the typical
+      # `db:migrate` task.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def migrate(shell)
         task = case @orm
                when :datamapper

data/lib/deployml/local_shell.rb

@@ -1,6 +1,9 @@
 require 'deployml/shell'
 
 module DeploYML
+  #
+  # Represents a shell running on the local system.
+  #
   class LocalShell
 
     include Shell
@@ -39,15 +42,7 @@ module DeploYML
     #   the block has returned.
     #
     def cd(path,&block)
-      if block
-        cwd = Dir.pwd
-
-        Dir.chdir(path)
-        block.call()
-        Dir.chdir(cwd)
-      else
-        Dir.chdir(path)
-      end
+      Dir.chdir(path,&block)
     end
 
   end

data/lib/deployml/options/mongrel.rb

@@ -2,8 +2,12 @@ require 'rprogram/task'
 
 module DeploYML
   module Options
+    #
+    # Maps in command-line options for the `mongrel_rails` utility.
+    #
     class Mongrel < RProgram::Task
 
+      # Default options for Mongrel
       DEFAULTS = {
         :environment => :production,
         :address => '127.0.0.1',

data/lib/deployml/options/thin.rb

@@ -2,6 +2,9 @@ require 'rprogram/task'
 
 module DeploYML
   module Options
+    #
+    # Maps in command-line options for the `thin` utility.
+    #
     class Thin < RProgram::Task
 
       # Default options for Thin

data/lib/deployml/project.rb

@@ -37,7 +37,7 @@ module DeploYML
     #   The configuration file for the project could not be found
     #   in any of the common directories.
     #
-    def initialize(root)
+    def initialize(root=Dir.pwd)
       @root = File.expand_path(root)
       @config_file = File.join(@root,CONFIG_DIR,CONFIG_FILE)
       @environments_dir = File.join(@root,CONFIG_DIR,ENVIRONMENTS_DIR)
@@ -117,39 +117,12 @@ module DeploYML
     #   The environment to deploy to.
     #
     # @return [true]
+    #   Indicates that the tasks were successfully completed.
     #
     # @since 0.2.0
     #
     def invoke(tasks,env=:production)
-      env = environment(env)
-
-      env.remote_shell do |shell|
-        # setup the deployment repository
-        env.setup(shell) if tasks.include?(:setup)
-
-        # cd into the deployment repository
-        shell.cd env.dest.path
-
-        # update the deployment repository
-        env.update(shell) if tasks.include?(:update)
-
-        # framework tasks
-        env.install(shell) if tasks.include?(:install)
-        env.migrate(shell) if tasks.include?(:migrate)
-
-        # server tasks
-        if tasks.include?(:config)
-          env.server_config(shell)
-        elsif tasks.include?(:start)
-          env.server_start(shell)
-        elsif tasks.include?(:stop)
-          env.server_stop(shell)
-        elsif tasks.include?(:restart)
-          env.server_restart(shell)
-        end
-      end
-
-      return true
+      environment(env).invoke(tasks)
     end
 
     #
@@ -158,8 +131,11 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     def setup!(env=:production)
-      invoke [:setup], env
+      environment(env).setup!
     end
 
     #
@@ -168,8 +144,11 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     def update!(env=:production)
-      invoke [:update], env
+      environment(env).update!
     end
 
     #
@@ -178,8 +157,11 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     def install!(env=:production)
-      invoke [:install], env
+      environment(env).install!
     end
 
     #
@@ -188,8 +170,11 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     def migrate!(env=:production)
-      invoke [:migrate], env
+      environment(env).migrate!
     end
 
     #
@@ -198,8 +183,11 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     def config!(env=:production)
-      invoke [:config], env
+      environment(env).config!
     end
 
     #
@@ -208,8 +196,11 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     def start!(env=:production)
-      invoke [:start], env
+      environment(env).start!
     end
 
     #
@@ -218,8 +209,11 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     def stop!(env=:production)
-      invoke [:stop], env
+      environment(env).stop!
     end
 
     #
@@ -228,8 +222,11 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     def restart!(env=:production)
-      invoke [:restart], env
+      environment(env).restart!
     end
 
     #
@@ -238,10 +235,13 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     # @since 0.2.0
     #
     def deploy!(env=:production)
-      invoke [:setup, :install, :migrate, :config, :start], env
+      environment(env).deploy!
     end
 
     #
@@ -250,10 +250,13 @@ module DeploYML
     # @param [Symbol, String] env
     #   The environment to deploy to.
     #
+    # @return [true]
+    #   Indicates that the tasks were successfully completed.
+    #
     # @since 0.2.0
     #
     def redeploy!(env=:production)
-      invoke [:update, :install, :migrate, :restart], env
+      environment(env).redeploy!
     end
 
     protected

data/lib/deployml/remote_shell.rb

@@ -1,9 +1,22 @@
 require 'deployml/shell'
 
+require 'addressable/uri'
+require 'shellwords'
+
 module DeploYML
+  #
+  # Represents a shell running on a remote server.
+  #
   class RemoteShell
 
     include Shell
+    include Shellwords
+
+    # The URI of the remote shell
+    attr_reader :uri
+
+    # The history of the Remote Shell
+    attr_reader :history
 
     #
     # Initializes a remote shell session.
@@ -51,7 +64,7 @@ module DeploYML
     # @param [String] message
     #   The message to echo.
     #
-    def each(message)
+    def echo(message)
       run 'echo', message
     end
 
@@ -65,12 +78,11 @@ module DeploYML
     #   If a block is given, then the directory will be changed back after
     #   the block has returned.
     #
-    def cd(path,&block)
+    def cd(path)
       @history << ['cd', path]
 
-      if block
-        block.call() if block
-
+      if block_given?
+        yield
         @history << ['cd', '-']
       end
     end
@@ -83,7 +95,9 @@ module DeploYML
     #   A single command string.
     #
     def join
-      @history.map { |command| command.join(' ') }.join(' && ')
+      @history.map { |command|
+        command.map { |word| shellescape(word) }.join(' ')
+      }.join(' && ')
     end
 
     #

data/lib/deployml/servers/apache.rb

@@ -2,15 +2,37 @@ require 'deployml/exceptions/invalid_config'
 
 module DeploYML
   module Servers
+    #
+    # Provides methods for starting, stoping and restarting the
+    # [Apache](http://httpd.apache.org/) web server.
+    #
     module Apache
+      #
+      # Starts Apache using the `apachectl start` command.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_start(shell)
         shell.run 'apachectl', 'start'
       end
 
+      #
+      # Restarts Apache using the `apachectl restart` command.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_restart(shell)
         shell.run 'apachectl', 'restart'
       end
 
+      #
+      # Stops Apache using the `apachectl stop` command.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_stop(shell)
         shell.run 'apachectl', 'stop'
       end

data/lib/deployml/servers/mongrel.rb

@@ -3,18 +3,44 @@ require 'deployml/options/mongrel'
 
 module DeploYML
   module Servers
+    #
+    # Provides methods for configuring, starting, stoping and restarting
+    # the [Mongrel](https://github.com/fauna/mongrel) web server.
+    #
     module Mongrel
+      #
+      # Initializes options used when calling `mongrel`.
+      #
       def initialize_server
         @mongrel = Options::Mongrel.new(@server_options)
         @mongrel.environment ||= @name
       end
 
+      #
+      # Executes a command via the `mongrel_rails` command.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
+      # @param [Array] args
+      #   Additional arguments to call `mongrel_rails` with.
+      #
       def mongrel_cluster(shell,*args)
         options = args + ['-c', @mongrel.config]
 
         shell.run 'mongrel_rails', *options
       end
 
+      #
+      # Configures Mongrel by calling `mongrel_rails cluster::configure`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
+      # @raise [MissingOption]
+      #   No `config` option was listed under the `server` option in the
+      #   `deploy.yml` configuration file.
+      #
       def server_config(shell)
         unless @mongrel.config
           raise(MissingOption,"No 'config' option specified under server options",caller)
@@ -25,14 +51,32 @@ module DeploYML
         shell.run 'mongrel_rails', 'cluster::configure', *options
       end
 
+      #
+      # Starts Mongrel by calling `mongrel_rails cluster::start`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_start(shell)
         mongrel_cluster 'cluster::start'
       end
 
+      #
+      # Stops Mongrel by calling `mongrel_rails cluster::stop`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_stop(shell)
         mongrel_cluster 'cluster::stop'
       end
 
+      #
+      # Restarts Mongrel by calling `mongrel_rails cluster::restart`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_restart(shell)
         mongrel_cluster 'cluster::restart'
       end

data/lib/deployml/servers/thin.rb

@@ -3,18 +3,44 @@ require 'deployml/options/thin'
 
 module DeploYML
   module Servers
+    #
+    # Provides methods for configuring, starting, stoping and restarting
+    # the [Thin](http://code.macournoyer.com/thin/) web server.
+    #
     module Thin
+      #
+      # Initializes options used when calling `thin`.
+      #
       def initialize_server
         @thin = Options::Thin.new(@server_options)
         @thin.environment ||= @name
       end
 
+      #
+      # Runs a command via the `thin` command.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
+      # @param [Array] args
+      #   Additional arguments to call `thin` with.
+      #
       def thin(shell,*args)
         options = args + ['-C', @thin.config, '-s', @thin.servers]
 
         shell.run 'thin', *options
       end
 
+      #
+      # Configures Thin by calling `thin config`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
+      # @raise [MissingOption]
+      #   No `config` option was listed under the `server` option in the
+      #   `deploy.yml` configuration file.
+      #
       def server_config(shell)
         unless @thin.config
           raise(MissingOption,"No 'config' option specified under the server options",caller)
@@ -25,14 +51,32 @@ module DeploYML
         shell.run 'thin', 'config', *options
       end
 
+      #
+      # Starts Thin by calling `thin start`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_start(shell)
         thin shell, 'start'
       end
 
+      #
+      # Stops Thin by calling `thin stop`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_stop(shell)
         thin shell, 'stop'
       end
 
+      #
+      # Restarts Thin by calling `thin restart`.
+      #
+      # @param [LocalShell, RemoteShell] shell
+      #   The shell to execute commands in.
+      #
       def server_restart(shell)
         thin shell, 'restart'
       end

data/lib/deployml/shell.rb

@@ -1,20 +1,15 @@
+require 'thor/shell/color'
+
 module DeploYML
+  #
+  # Provides common methods used by both {LocalShell} and {RemoteShell}.
+  #
   module Shell
 
-    def initialize(&block)
-      block.call(self) if block
-    end
+    include Thor::Shell
 
-    #
-    # Place-holder method.
-    #
-    # @param [String] program
-    #   The name or path of the program to run.
-    #
-    # @param [Array<String>] args
-    #   Additional arguments for the program.
-    #
-    def run(program,*args)
+    def initialize
+      yield self if block_given?
     end
 
     #
@@ -30,8 +25,32 @@ module DeploYML
       run 'rake', rake_task(task,*args)
     end
 
+    #
+    # Prints a status message.
+    #
+    # @param [String] message
+    #   The message to print.
+    #
+    # @since 0.4.0
+    #
+    def status(message)
+      echo "#{Color::GREEN}>>> #{message}#{Color::CLEAR}"
+    end
+
     protected
 
+    #
+    # Builds a `rake` task name.
+    #
+    # @param [String, Symbol] name
+    #   The name of the `rake` task.
+    #
+    # @param [Array] args
+    #   Additional arguments to pass to the `rake` task.
+    #
+    # @param [String]
+    #   The `rake` task name to be called.
+    #
     def rake_task(name,*args)
       name = name.to_s
 

data/lib/deployml/version.rb

@@ -1,4 +1,4 @@
 module DeploYML
   # deploYML version
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/spec/remote_shell_spec.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+require 'deployml/remote_shell'
+
+describe RemoteShell do
+  let(:uri) { 'ssh://deploy@www.example.com/path' }
+
+  subject { RemoteShell.new(uri) }
+
+  it "should parse the given URI" do
+    subject.uri.should be_kind_of(Addressable::URI)
+
+    subject.uri.user.should == 'deploy'
+    subject.uri.host.should == 'www.example.com'
+    subject.uri.path.should == '/path'
+  end
+
+  it "should convert normal URIs to SSH URIs" do
+    subject.ssh_uri.should == 'deploy@www.example.com'
+  end
+
+  it "should enqueue programs to run" do
+    subject.run 'echo', 'one'
+    subject.run 'echo', 'two'
+
+    subject.history[0].should == ['echo', 'one']
+    subject.history[1].should == ['echo', 'two']
+  end
+
+  it "should enqueue echo commands" do
+    subject.echo 'one'
+    subject.echo 'two'
+
+    subject.history[0].should == ['echo', 'one']
+    subject.history[1].should == ['echo', 'two']
+  end
+
+  it "should enqueue directory changes" do
+    subject.cd '/other'
+
+    subject.history[0].should == ['cd', '/other']
+  end
+
+  it "should enqueue temporary directory changes" do
+    subject.cd '/other' do
+      subject.run 'pwd'
+    end
+
+    subject.history[0].should == ['cd', '/other']
+    subject.history[1].should == ['pwd']
+    subject.history[2].should == ['cd', '-']
+  end
+
+  it "should join all commands together into one command" do
+    subject.run 'echo', 'one'
+    subject.run 'echo', 'two'
+
+    subject.join.should == 'echo one && echo two'
+  end
+
+  it "should escape all command arguments" do
+    subject.run 'the program'
+    subject.run 'echo', '>>> status'
+
+    subject.join.should == "the\\ program && echo \\>\\>\\>\\ status"
+  end
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 3
+  - 4
   - 0
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Postmodern
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-21 00:00:00 -08:00
+date: 2010-11-29 00:00:00 -08:00
 default_executable: deployml
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -27,9 +27,9 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 2
-        - 1
-        - 1
-        version: 2.1.1
+        - 2
+        - 0
+        version: 2.2.0
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -139,6 +139,7 @@ files:
 - lib/deployml/exceptions/unknown_framework.rb
 - lib/deployml/exceptions/unknown_server.rb
 - lib/deployml/frameworks.rb
+- lib/deployml/frameworks/rails.rb
 - lib/deployml/frameworks/rails2.rb
 - lib/deployml/frameworks/rails3.rb
 - lib/deployml/local_shell.rb
@@ -167,6 +168,7 @@ files:
 - spec/helpers/projects/rails/config/deploy/production.yml
 - spec/helpers/projects/rails/config/deploy/staging.yml
 - spec/project_spec.rb
+- spec/remote_shell_spec.rb
 - spec/spec_helper.rb
 has_rdoc: yard
 homepage: http://github.com/postmodern/deployml
@@ -201,6 +203,7 @@ signing_key:
 specification_version: 3
 summary: A simple deployment solution that works.
 test_files: 
+- spec/remote_shell_spec.rb
 - spec/project_spec.rb
 - spec/environment_spec.rb
 - spec/configuration_spec.rb