sunshine 1.0.3 → 1.1.0

data/lib/sunshine/app.rb

@@ -1,15 +1,18 @@
 module Sunshine
 
   ##
-  # App objects are the core of sunshine deployment. The sunshine paradygm
+  # App objects are the core of Sunshine deployment. The Sunshine paradygm
   # is to construct an app object, and run custom deploy code by passing
   # a block to its deploy method:
   #
-  #  options = {
+  #   someserver = Sunshine::RemoteShell.new "user@someserver.com",
+  #                                          :roles => [:web, :app]
+  #
+  #   options = {
   #     :name => 'myapp',
   #     :repo => {:type => :svn, :url => 'svn://blah...'},
   #     :root_path => '/usr/local/myapp',
-  #     :remote_shells => ['user@someserver.com']
+  #     :remote_shells => 'user@someserver.com'
   #   }
   #
   #   app = Sunshine::App.new(options)
@@ -19,10 +22,12 @@ module Sunshine
   #     app_server = Sunshine::Rainbows.new(app)
   #     app_server.restart
   #
-  #     Sunshine::Nginx.new(app, :point_to => app_server).restart
+  #     Sunshine::Nginx.new(app, :point_to => app_server).setup
   #
   #   end
   #
+  #   app.start :force => true
+  #
   # Multiple apps can be defined, and deployed from a single deploy script.
   # The constructor also supports passing a yaml file path:
   #
@@ -31,8 +36,104 @@ module Sunshine
   # Deployment can be expressed more concisely by calling App::deploy:
   #
   #   App.deploy("path/to/config.yml") do |app|
-  #     Sunshine::Rainbows.new(app).restart
+  #     Sunshine::Rainbows.new(app).setup
   #   end
+  #
+  #
+  # An App holds information about where to deploy an application to and
+  # how to deploy it, as well as many convenience methods to setup and
+  # manipulate the deployment process. Most of these methods support passing
+  # remote shell find options:
+  #
+  #   app.rake 'db:migrate', :role => :db
+  #   app.deploy :host => 'server1.com'
+  #
+  # See App#find for more information.
+  #
+  # App instantiation can be done in several ways:
+  #  App.new instantiation_hash
+  #  App.new "path/to/config.yml", optional_extra_hash
+  #  App.new #=> will attempt to load ruby's file DATA as yaml
+  #
+  # Yaml files must define settings on a per-environment basis. The default
+  # environment will be used if the deploy_env is not found in the config.
+  # Let's consider the following config:
+  #
+  #   #config.yml:
+  #   ---
+  #   :default:
+  #     :repo:
+  #       :type: :svn
+  #       :url:  http://subversion/repo/tags/release-001
+  #     :remote_shells: dev.myserver.com
+  #
+  #   :qa:
+  #     :remote_shells:
+  #       - qa1.myserver.com
+  #       - qa2.myserver.com
+  #
+  #   :qa_special:
+  #     :inherits: :qa
+  #     :root_path: /path/to/application
+  #
+  # By default, environment definitions inherit the :default environment. In
+  # this instance, :qa_special also inherits from :qa.
+  # With the given config, I could setup the App instance as so:
+  #
+  #   App.new "config.yml", :deploy_env => :development
+  #   # Note: by default, App will get the deploy_env value
+  #   # from Sunshine.deploy_env
+  #
+  # The above will simply load the default config. The following, however,
+  # will load the :qa_special config which inherits from
+  # both :qa and :default:
+  #
+  #   App.new "config.yml", :deploy_env => :qa_special
+  #
+  #
+  # Another way of instantiating an App is to pass it a hash. Unlike the yaml
+  # config file, the hash is not on a per-environment basis and isexpected
+  # to already have the correct values for the given environment.
+  # The following is equivalent to loading the above :default environment:
+  #
+  #   App.new :remote_shells => "dev.myserver.com",
+  #           :repo => {
+  #             :type => :svn,
+  #             :url => "http://subversion/repo/tags/release-001"
+  #           }
+  #
+  # In theory, the minimum amount of information required to instantiate
+  # an app is the repo and remote_shells. If the repo option is omitted,
+  # the App will attempt to detect if the pwd is a checkout out repo and
+  # use that information. If you would like to deploy an application that
+  # is not under source countrol, you may do so by using Sunshine::RsyncRepo,
+  # or passing :rsync in your hash as your repo type.
+  #
+  #
+  # Options supported by App.new are the following:
+  #
+  # :deploy_env:: String - specify the env to deploy with; defaults to
+  # Sunshine#deploy_env.
+  #
+  # :deploy_name:: String - if you want to specify a name for your deploy and
+  # checkout directory (affects the checkout_path); defaults to Time.now.to_i.
+  #
+  # :remote_shells:: String|Array|Sunshine::Shell - the shell(s) to use for
+  # deployment. Accepts any single instance or array of a Sunshine::Shell
+  # type instance or Sunshine::Shell instantiator-friendly arguments.
+  #
+  # :repo:: Hash|Sunshine::Repo - the scm and repo to use for deployment.
+  # Accepts any hash that can be passed to Sunshine::Repo::new_of_type
+  # or any Sunshine::Repo object.
+  #
+  # :root_path:: String - the absolute path the deployed application
+  # should live in; defaults to "#{Sunshine.web_directory}/#{@name}".
+  #
+  # :shell_env:: Hash - environment variables to add to deploy shells.
+  #
+  # :sudo:: true|false|nil|String - which sudo value should be assigned to
+  # deploy shells; defaults to Sunshine#sudo. For more information on using
+  # sudo, see the Using Permissions section in README.txt.
 
   class App
 
@@ -51,6 +152,11 @@ module Sunshine
     attr_reader :root_path, :checkout_path, :current_path, :deploys_path
     attr_reader :shared_path, :log_path, :deploy_name, :deploy_env
 
+    ##
+    # App instantiation can be done in several ways:
+    #  App.new instantiation_hash
+    #  App.new "path/to/config.yml", optional_extra_hash
+    #  App.new #=> will attempt to load ruby's file DATA as yaml
 
     def initialize config_file=Sunshine::DATA, options={}
       options, config_file = config_file, Sunshine::DATA if Hash === config_file
@@ -833,13 +939,13 @@ module Sunshine
     #   server_apps_from_config ["svr1", "svr2", "svr3"]
     #   #=> [<ServerApp @host="svr1">,<ServerApp @host="svr2">, ...]
     #
-    #   d_servers = [["svr1", {:roles => "web db app"}], "svr2", "svr3"]
-    #   server_apps_from_config d_servers
+    #   remote_shells = [["svr1", {:roles => "web db app"}], "svr2", "svr3"]
+    #   server_apps_from_config remote_shells
     #   #=> [<ServerApp @host="svr1">,<ServerApp @host="svr2">, ...]
 
-    def server_apps_from_config d_servers
-      d_servers = [*d_servers].compact
-      d_servers.map{|ds| ServerApp.new(*[self,*ds]) }
+    def server_apps_from_config shells
+      shells = [*shells].compact
+      shells.map{|shell| ServerApp.new(*[self,*shell]) }
     end
 
 

data/lib/sunshine/crontab.rb

@@ -1,8 +1,8 @@
 module Sunshine
 
   ##
-  # A simple namespaced grouping of cron jobs that can be written
-  # to a deploy server.
+  # A simple namespaced grouping of cron jobs that can be read and written
+  # to a shell.
 
   class Crontab
 
@@ -117,11 +117,17 @@ module Sunshine
 
     private
 
+    ##
+    # Write the string to the shell's crontab.
+
     def write_crontab content
       @shell.call("echo '#{content.gsub(/'/){|s| "'\\''"}}' | crontab")
     end
 
 
+    ##
+    # Deletes all jobs of a given namespace in a crontab string.
+
     def delete_jobs crontab, namespace=nil
       start_id, end_id = get_job_ids namespace
 
@@ -131,6 +137,9 @@ module Sunshine
     end
 
 
+    ##
+    # Returns the cronjob begin and end flags.
+
     def get_job_ids namespace=nil
       namespace ||= "[^\n]*"
 

data/lib/sunshine/daemon.rb

@@ -17,8 +17,17 @@ module Sunshine
     # for template rendering.
 
     def self.binder_methods
-      [:app, :name, :target, :bin, :pid, :port,
-      :processes, :config_path, :log_file, :timeout]
+      [:app, :name, :bin, :pid, :processes, :config_path, :log_file, :timeout]
+    end
+
+
+    ##
+    # Returns the short, snake-case version of the class:
+    #   Sunshine::Daemon.short_name
+    #   #=> "daemon"
+
+    def self.short_name
+      @short_name ||= self.underscore self.to_s.split("::").last
     end
 
 
@@ -31,7 +40,7 @@ module Sunshine
     end
 
 
-    attr_reader :app, :name, :target
+    attr_reader :app, :name
 
     attr_accessor :bin, :pid, :processes, :timeout, :sudo, :server_apps
 
@@ -43,34 +52,31 @@ module Sunshine
     # Daemon objects need only an App object to be instantiated but many options
     # are available for customization:
     #
-    # :pid:: pid_path - set the pid; default: app.shared_path/pids/svr_name.pid
-    #                   defaults to app.shared_path/pids/svr_name.pid
-    #
-    # :bin:: bin_path - set the daemon app bin path (e.g. usr/local/nginx)
-    #                   defaults to svr_name
+    # :bin:: bin_path - Set the daemon app bin path (e.g. usr/local/nginx)
+    # defaults to svr_name.
     #
-    # :sudo:: bool|str - define if sudo should be used and with what user
+    # :processes:: prcss_num - Number of processes daemon should run;
+    # defaults to 1.
     #
-    # :timeout:: int|str - timeout to use for daemon config
-    #                      defaults to 1
+    # :config_file:: name - Remote file name the daemon should load;
+    # defaults to svr_name.conf
     #
-    # :processes:: prcss_num - number of processes daemon should run
-    #                          defaults to 0
+    # :config_path:: path - Remote path daemon configs will be uploaded to;
+    # defaults to app.current_path/daemons/svr_name
     #
-    # :config_template:: path - glob path to tempates to render and upload
-    #                           defaults to sunshine_path/templates/svr_name/*
+    # :config_template:: path - Glob path to tempates to render and upload;
+    # defaults to sunshine_path/templates/svr_name/*
     #
-    # :config_path:: path - remote path daemon configs will be uploaded to
-    #                       defaults to app.current_path/daemons/svr_name
+    # :log_path:: path - Path to where the log files should be output;
+    # defaults to app.log_path.
     #
-    # :config_file:: name - remote file name the daemon should load
-    #                       defaults to svr_name.conf
+    # :pid:: pid_path - Set the pid; default: app.shared_path/pids/svr_name.pid
+    # defaults to app.shared_path/pids/svr_name.pid.
     #
-    # :log_path:: path - path to where the log files should be output
-    #                    defaults to app.log_path
+    # :sudo:: bool|str - Define if sudo should be used to run the daemon,
+    # and/or with what user.
     #
-    # :point_to:: app|daemon - an abstract target to point to
-    #                                 defaults to the passed app
+    # :timeout:: int - Timeout to use for daemon config, defaults to 0.
     #
     # The Daemon constructor also supports any App#find options to narrow
     # the server apps to use. Note: subclasses such as Server already have
@@ -78,27 +84,24 @@ module Sunshine
 
     def initialize app, options={}
       @options = options
+      @app     = app
 
-      @app    = app
-      @target = options[:point_to] || @app
-
-      @short_class_name = self.class.underscore self.class.to_s.split("::").last
-
-      @name        = options[:name] || @short_class_name
-
-      @pid         = options[:pid] || "#{@app.shared_path}/pids/#{@name}.pid"
-      @bin         = options[:bin] || @name
+      @name        = options[:name] || self.class.short_name
+      @pid         = options[:pid]  || "#{@app.shared_path}/pids/#{@name}.pid"
+      @bin         = options[:bin]  || self.class.short_name
       @sudo        = options[:sudo]
-      @timeout     = options[:timeout] || 0
-      @dep_name    = options[:dep_name] || @name
+      @timeout     = options[:timeout]   || 0
+      @dep_name    = options[:dep_name]  || self.class.short_name
       @processes   = options[:processes] || 1
+      @sigkill     = 'QUIT'
 
-      @config_template   = options[:config_template]
-      @config_template ||= "#{Sunshine::ROOT}/templates/#{@short_class_name}/*"
+      @config_template = options[:config_template] ||
+        "#{Sunshine::ROOT}/templates/#{self.class.short_name}/*"
 
       @config_path     = options[:config_path] ||
         "#{@app.current_path}/daemons/#{@name}"
-      @config_file     = options[:config_file] || "#{@name}.conf"
+
+      @config_file = options[:config_file] || "#{self.class.short_name}.conf"
 
       log_path  = options[:log_path] || @app.log_path
       @log_files = {
@@ -195,6 +198,20 @@ module Sunshine
     end
 
 
+    ##
+    # Check if the daemon is running on all servers
+
+    def status
+      each_server_app do |server_app|
+        server_app.shell.call status_cmd, :sudo => pick_sudo(server_app.shell)
+      end
+      true
+
+    rescue CmdError => e
+      false
+    end
+
+
     ##
     # Stop the daemon app.
 
@@ -248,12 +265,11 @@ module Sunshine
 
 
     ##
-    # Gets the command that stops the daemon.
-    # Should be overridden by child classes.
+    # Default daemon stop command.
 
     def stop_cmd
-      return @stop_cmd ||
-        raise(CriticalDeployError, "@stop_cmd undefined. Can't stop #{@name}")
+      "test -f #{@pid} && kill -#{@sigkill} $(cat #{@pid}) && sleep 1 && "+
+        "rm -f #{@pid} || echo 'Could not kill #{@name} pid for #{@app.name}';"
     end
 
 
@@ -304,7 +320,7 @@ module Sunshine
     # Upload config files and run them through erb with the provided
     # binding if necessary.
 
-    def upload_config_files(shell, setup_binding=binding)
+    def upload_config_files shell, setup_binding=binding
       config_template_files.each do |config_file|
 
         if File.extname(config_file) == ".erb"
@@ -343,10 +359,6 @@ module Sunshine
         shell.expand_path path
       end
 
-      binder.set :target_server do
-        target.server_name || server_name
-      end
-
       binder
     end
 
@@ -399,6 +411,8 @@ module Sunshine
 
     def register_after_user_script
       @app.after_user_script do |app|
+        next unless has_setup?
+
         each_server_app do |sa|
           sudo = pick_sudo sa.shell
 

data/lib/sunshine/daemons/apache.rb

@@ -2,6 +2,10 @@ module Sunshine
 
   ##
   # A wrapper for configuring the apache2 server.
+  # Note: Due to Apache default limitations, the @connections attribute
+  # defaults to 256.
+  #
+  # Note: The minimum timeout supported by Apache is 1 second.
 
   class Apache < Server
 
@@ -12,8 +16,12 @@ module Sunshine
 
       @sigkill = 'WINCH'
 
-      # TODO: have a separate max_clients and processes
-      @max_clients = options[:max_clients] || options[:processes] || 128
+      @supports_rack      = false
+      @supports_passenger = true
+
+      @connections = options[:connections] || 256
+
+      @timeout = 1 if @timeout < 1
 
       @dep_name = options[:dep_name] ||
         use_passenger? ? 'passenger-apache' : 'apache2'

data/lib/sunshine/daemons/ar_sendmail.rb

@@ -18,11 +18,5 @@ module Sunshine
     def start_cmd
       "cd #{@app.current_path} && #{@bin} -p #{@pid} -d"
     end
-
-
-    def stop_cmd
-      "test -f #{@pid} && kill `cat #{@pid}` || "+
-        "echo 'No #{@name} process to stop for #{@app.name}'; rm -f #{@pid};"
-    end
   end
 end

data/lib/sunshine/daemons/delayed_job.rb

@@ -4,6 +4,8 @@ module Sunshine
   # Simple daemon wrapper for delayed_job daemon setup and control.
   # By default, uses server apps with the :dj role. Supports
   # the :processes option.
+  #
+  # Note: The pid location is fixed at [current_path]/tmp/pids/delayed_job.pid"
 
   class DelayedJob < Daemon
 

data/lib/sunshine/daemons/mongrel_rails.rb

@@ -0,0 +1,32 @@
+module Sunshine
+
+  ##
+  # Simple wrapper around mongrel setup and commands. For clustering,
+  # look at using Sunshine's ServerCluster method, e.g.:
+  #   MongrelRails.new_cluster 10, app, :port => 5000
+  #
+  # Note: This is a rails-only server, implemented for compatibility
+  # with older non-rack rails applications. Consider upgrading your
+  # application to run on rack and/or thin.
+  #
+  # Note: Mongrel only supports a single log file.
+  # The default stdout file is used.
+
+  class MongrelRails < Server
+
+    def initialize app, options={}
+      super
+
+      @dep_name = options[:dep_name] || "mongrel"
+
+      @supports_rack      = false
+      @supports_passenger = false
+    end
+
+
+    def start_cmd
+      "cd #{@app.current_path} && mongrel_rails start "+
+        "-C #{self.config_file_path}"
+    end
+  end
+end