nuex-vlad 1.3.2

data/doco/faq.txt

@@ -0,0 +1,131 @@
+== Rake & Recipes
+
+=== Q: Why is there no vlad:restart?
+=== A: It is cleaner!
+
+We don't want to have to think about what state we're in and where. So vlad:start does a restart if necessary. Restart is just "start again" after all... That is what start does.
+
+=== Q: Why is there no vlad:deploy?
+=== A: Because everyone is a unique beautiful flower.
+
+Everyone's deployment is different. Everyone. Unique scaling
+requirements. Yadda yadda yadda. So rather than supply something that
+nobody will use, we decided not to supply anything at all. Here is an
+example deploy that I stole from the web (and improved) that you may like:
+
+    desc "Full deployment cycle"
+    task "vlad:deploy" => %w[
+      vlad:update
+      vlad:migrate
+      vlad:reset_session
+      vlad:start
+      vlad:cleanup
+    ]
+
+Just pop that in your config/deploy.rb, tweak it as necessary, and have at it.
+
+=== Q: Why are there no before_action and after_action hooks?
+=== A: Because we use rake!
+
+Rake don't need no stinkin' hooks! They're too clever. Last I checked before_after_before_start worked in cap... how? why? I dunno...
+
+To extend a task (adding something after), just define it again:
+
+  task :action1 do
+    puts "one fish, two fish"
+  end
+
+  task :action1 do
+    puts "red fish, blue fish"
+  end
+
+To prepend on a task, add a dependency:
+
+  task :action2 do
+    puts "red fish, blue fish"
+  end
+
+  task :myaction do
+    puts "one fish, two fish"
+  end
+
+  task :action2 => :myaction
+
+=== Q: How can I replace a rake task instead of just adding to it?
+=== A: Use Rake.clear_tasks str_or_regexp
+
+  namespace :vlad do
+    # Clear existing update task so that we can redefine instead of adding to it.
+    Rake.clear_tasks('vlad:update') 
+  
+    remote_task :update, :roles => :app do
+      #custom update stuff
+    end
+  end
+
+=== Q: How do I invoke another rule?
+=== A: The easiest way is via dependencies.
+
+  task :shazam! => [:action1, :action2]
+
+ The other way is to look it up and call invoke:
+
+  task :shazam! do
+    Rake::Task[:action1].invoke
+    Rake::Task[:action2].invoke
+  end
+
+(Or, cheat and call out to rake again: sh "rake action1")
+
+== Using SSH
+
+=== Q: Is there any way to set the ssh user?
+=== A: Yes, using ~/.ssh/config
+
+  Host example.com
+    User fluffy_bunny
+
+OR: Alternatively, you can do this within your recipes like so:
+
+  set :user, "fluffy_bunny"
+  set :domain, "#{user}@example.com"
+
+=== Q: Is there any way to speed up ssh connections?
+=== A: Yes, add to your Host entry in ~/.ssh/config:
+
+  ControlMaster auto
+  ControlPath ~/.ssh/master-%r@%h:%p
+
+=== Q: I'm tired of typing in my password!
+=== A: Me too!
+
+Put a password on your key, distribute your public key to the server and then use ssh-agent.
+
+Check out this tiny tutorial at LBL: A brief ssh-agent tutorial <http://upc.lbl.gov/docs/user/sshagent.html>
+
+If you're on a mac (on tiger, not leopard), use SSHKeychain, we love it. <http://www.sshkeychain.org/>. If you are on leopard, you get all of this for free.
+
+=== Q: How do I use Vlad with a gateway?
+=== A: Add the following to your deploy.rb variables:
+
+  set :ssh_flags, "-A #{mygateway}"
+  set :rsync_flags, "--rsh ssh -A #{mygateway} ssh"
+
+=== Q: OMG subversion is stupid! It keeps asking for "Authentication Realm"
+=== A: Yes, yes it is.
+
+If you're seeing local checkouts work fine but they don't over ssh
+(even to localhost!) then ssh into that machine (yes, even localhost)
+and do a checkout there to a temporary directory. From then on,
+checkout over ssh should work fine.
+
+  % svn co https://blah/blah /tmp/happy
+    ... works fine ...
+  % ssh localhost svn co https://blah/blah /tmp/sad
+    ... asks for authentication and then hangs ...
+  % ssh localhost
+  % svn co https://blah/blah /tmp/sad-no-happy
+    ... asks for authentication ...
+    ... works fine ...
+  % ssh localhost svn co https://blah/blah /tmp/happy2
+    ... works fine ...

data/doco/getting_started.txt

@@ -0,0 +1,61 @@
+
+== Quick Start for a 1-Server Solution:
+
+=== Setup
+
+* Create a deploy file, usually in "config/deploy.rb":
+
+    set :application, "project"
+    set :domain, "example.com"
+    set :deploy_to, "/path/to/install"
+    set :repository, 'http://svn.example.com/project/branches/stable/'
+    
+This defaults to using 'svn export' from +repository+, and a single
+server for +app+, +db+, and +www+. If you need to tweak these things,
+refer to the variable documentation.
+
+* If you want a multi-config environment, change your config like so:
+
+    set :application, "project"
+    set :repository, 'http://svn.example.com/project/branches/stable/'
+    
+    task :beta do
+      set :domain,    "beta.example.com"
+      set :deploy_to, "/path/to/install-beta"
+    end
+    
+    task :dev do
+      set :domain,    "dev.example.com"
+      set :deploy_to, "/path/to/install-dev"
+    end
+    
+    task :prod do
+      set :domain,    "example.com"
+      set :deploy_to, "/path/to/install"
+    end
+
+* Add the following to your Rakefile:
+
+    begin
+      require 'vlad'
+      Vlad.load
+    rescue LoadError
+      # do nothing
+    end
+
+Vlad.load has a lot of flexibility. See the rdoc for full information.
+
+You don't need the begin/rescue/end block if you ensure that Vlad is
+installed on all your servers. To be lazy, you can install vlad via:
+
+    % rake vlad:invoke COMMAND='sudo gem install vlad -y'
+
+=== Initial Launch
+
+* Run <tt>rake vlad:setup vlad:update vlad:migrate vlad:start</tt>
+
+=== Subsequent Updates:
+
+* <tt>rake vlad:update vlad:migrate vlad:start</tt>
+
+Each step may be run separately.

data/doco/migration.txt

@@ -0,0 +1,43 @@
+== Converting from Capistrano
+
+* 'set scm' is removed. Vlad.load :scm => :something if you don't use subversion.
+* 'task' blocks are renamed to 'remote_task'.
+* Most variables are the same. See variables.txt for details.
+* No +with_command+ / +sudo+ / +via+ wonkiness
+* Uses real ssh so env vars and the like are not a problem
+  - no +with_env+ as a result.
+* Vlad doesn't use ':no_release' or ':primary'.
+  - If you have a task that needs to run on only one host from a role,
+    you should declare a new role for that host:
+
+      role :master_db, "master.example.com"
+
+    ..and then override the role for the task you want to limit:
+
+      Rake::Task["mytask"].options[:roles] = :master_db
+
+* The 'host' method can be used to consolidate multiple 'role' calls.
+  - host "www.example.com", :app, :web, :db
+    specifies a host with three roles.
+* migrate_env is now migrate_args.
+* Vlad doesn't have before/after magic add-on tasks.
+
+== BEFORE:
+
+  set :application, "rubyholic"
+  set :domain,      "zenspider.textdriven.com"
+  set :repository,  "svn://svn.example.com/rubyholic/branches/stable"
+  set :deploy_to,   "/users/home/zenspider/domains/new.rubyholic.com"
+  
+  set :user,        "zenspider"
+  set :use_sudo,    false
+  
+  role :web, domain
+  role :app, domain
+  role :db,  domain, :primary => true
+
+== AFTER:
+
+  set :domain,      "zenspider.textdriven.com"
+  set :repository,  "svn://svn.example.com/rubyholic/branches/stable"
+  set :deploy_to,   "/users/home/zenspider/domains/new.rubyholic.com"

data/doco/perforce.txt

@@ -0,0 +1,5 @@
+# Using Perforce
+
+TODO: write real doco.
+
+Set up a .p4config file and put it in the client's scm directories.

data/doco/variables.txt

@@ -0,0 +1,79 @@
+
+== Core Variables
+
+repository::           REQUIRED: Repository path: e.g. http://repo.example.com/svn
+deploy_to::            REQUIRED: Deploy path on target machines. e.g. /var/www/app
+domain::               REQUIRED: Used for the common case of a single target
+                       server. e.g. example.com
+current_path::         The full path on the remote host that will be symlinked
+                       as 'current'. Defaults to "#{deploy_to}/current".
+current_release::      The full path to the current release's actual location.
+                       Defaults to "#{releases_path}/#{releases.last}".
+deploy_timestamped::   Create timestamped release directories instead of using
+                       revision numbers. Defaults to true.
+deploy_via::           Which SCM command should be used when deploying the app.
+                       Defaults to "export".
+latest_release::       The most recent release, which may not yet have been
+                       symlinked. Defaults to release_path.
+migrate_args::         Set this to change the RAILS_ENV that 'rake db:migrate'
+                       will run under. Defaults to "".
+migrate_target::       Set this if you need to specify a particular migration
+                       'VERSION' number. Defaults to "latest".
+rails_env::            Specifies the RAILS_ENV environment variable that will
+                       be used. Defaults to "production".
+rake_cmd::             Set this if you need to specify an alternate path to
+                       'rake'. Defaults to "rake".
+release_name::         Name of the release directory, if deploy_timestamped is
+                       true. Defaults to timestamp: "YYYYMMDDHHMMSS".
+release_path::         Path to this release, which may not have been created
+                       yet. Defaults to "#{releases_path}/#{release_name}".
+releases::             An array of all existing releases, oldest first.
+                       Defaults to latest release directory name.
+releases_path::        Full path to the 'releases' directory on the remote host.
+                       Defaults to "#{deploy_to}/releases".
+revision::             Revision to use for release. Defaults to 'head'.
+rsync_cmd::            Path to rsync command. Defaults to "rsync".
+rsync_flags::          Flags for rsync. Defaults to ['-azP', '--delete'].
+scm_path::             Path on the remote host that will be used as 'working
+                       space' for SCM tasks. Defaults to "#{deploy_to}/scm".
+shared_path::          Full path to remote 'shared' directory, symlinked into
+                       your app by default. Defaults to "#{deploy_to}/shared".
+ssh_cmd::              Path to ssh. Defaults to "ssh".
+ssh_flags::            Flags for ssh. Defaults to [].
+sudo_cmd::             Path to sudo command. Defaults to "sudo".
+sudo_flags::           Flogs for sudo. Defaults to ["-p Password:"].
+sudo_prompt::          Regexp for sudo password prompt. Defaults to /^Password:/.
+sudo_password::        Asks for password when referenced.
+umask::                Sets your umask value. Defaults to "02".
+
+== Apache Web Variables:
+
+web_command::          Command to execute when controlling the web server.
+                       Defaults to "apachectl".
+
+== Mongrel App Variables:
+
+mongrel_address::       Defaults to "127.0.0.1"
+mongrel_clean::         Defaults to false
+mongrel_command::       Defaults to 'mongrel_rails'
+mongrel_conf::          Defaults to "#{shared_path}/mongrel_cluster.conf"
+mongrel_config_script:: Defaults to nil
+mongrel_environment::   Defaults to "production"
+mongrel_group::         Defaults to nil
+mongrel_log_file::      Defaults to nil
+mongrel_pid_file::      Defaults to nil
+mongrel_port::          Defaults to 8000
+mongrel_prefix::        Defaults to nil
+mongrel_servers::       Defaults to 2
+mongrel_user::          Defaults to nil
+
+== Perforce SCM Variables:
+
+p4_cmd::                The perforce command to use. Defaults to "p4"
+source::                A perforce SCM worker instance.
+
+== Subversion SCM Variables:
+
+source::                A subversion SCM worker instance.
+svn_cmd::               The subversion command to use. Defaults to "svn"
+