vlad 1.3.1 → 1.3.2

data/History.txt

@@ -1,4 +1,16 @@
-== 1.3.1 / 2009-03-06
+=== 1.3.2 / 2009-03-16
+
+* 3 minor enhancements:
+
+  * Added 'Deploying Merb with Vlad' by Graham Ashton.
+  * Added 'Deploying Sinatra with Vlad' by Graham Ashton.
+  * Core update task calls update with the actual revision once again
+
+* 1 bug fix:
+
+  * Fix Git checkout/export methods. (Wilson)
+
+=== 1.3.1 / 2009-03-06
 
 * 4 minor enhancements:
 

data/Manifest.txt

@@ -3,6 +3,8 @@ Manifest.txt
 README.txt
 Rakefile
 considerations.txt
+doco/deploying-merb-with-vlad.txt
+doco/deploying-sinatra-with-vlad.txt
 doco/faq.txt
 doco/getting_started.txt
 doco/migration.txt

data/doco/deploying-merb-with-vlad.txt

@@ -0,0 +1,155 @@
+# Deploying Merb with Vlad
+
+This tutorial has been adapted from [Deploying Merb with Vlad](http://effectif.com/articles/deploying-merb-with-vlad) by [Graham Ashton](http://effectif.com "Effectif Development").
+
+You've built your Merb app, and you want to get it running on your web server. You could use Capistrano, but if you prefer the simple things in life you might find that [Vlad](http://rubyhitsquad.com/Vlad_the_Deployer.html "Vlad the Deployer") is a better fit.
+
+This is a Merb version of the [Deploying Sinatra with Vlad](deploying-sinatra-with-vlad "Deploying Sinatra with Vlad") article that I wrote yesterday. There are big similarities to that article, but in this one we also look at how to restart Merb automatically after the code has been deployed.
+
+## Creating a sample application
+
+Let's start by making ourselves a test app:
+
+    $ merb-gen flat hi
+    $ cd hi
+
+We can check that the app works locally by running it...
+
+    $ merb
+
+...and then opening [http://localhost:4000](http://localhost:4000) in a web browser.
+
+We need to create a `public` directory too (because this is a flat app I don't already have one), as Vlad assumes that we have a `public` directory for our static assets. I'm also going to make an empty CSS file so that the directory doesn't get ignored by Git:
+
+    $ mkdir public
+    $ touch public/master.css
+
+We'll deploy our application from version control. I'm using Git, but you can use any system that Vlad supports; just check your files into a repository that will be accessible from your web server.
+
+## Configuring Vlad
+
+Okay, we're ready for Vlad. It's a Ruby gem, so it's very easy to install:
+
+    $ sudo gem install vlad
+    Successfully installed vlad-1.2.0
+    1 gem installed
+    Installing ri documentation for vlad-1.2.0...
+    Installing RDoc documentation for vlad-1.2.0...
+
+There's no need to install Vlad on your server, just your workstation.
+
+You access Vlad's functionality through Rake tasks. Add the following code to a file called `lib/tasks/vlad.rake` (you may have to make the directory first, but Merb will automatically find it):
+
+    begin
+      $TESTING = true # workaround a conflict between DataMapper and Vlad
+      require "vlad"
+      Vlad.load(:app => nil, :scm => "git")
+    rescue LoadError
+      # do nothing
+    end
+
+Note that we've told Vlad that we intend to use Git (subversion is the default). We've set `:app` to `nil` as Vlad assumes that we'll run our application with `mongrel_rails` (it seems to think everybody who uses Mongrel is using Rails). Merb has support for clusters built in, so we'll setup some simple replacements later.
+
+If you run `rake -T` now you should see a bunch of vlad tasks that are available to you. You can't run them yet; you need to configure Vlad. Create a `config/deploy.rb` file in your editor and set the following variables in it:
+
+    set :application, "hi"
+    set :repository, "ssh://your.git.server/path/to/project/hi.git"
+    set :domain, "your.web.server"
+    set :deploy_to, "/var/apps/#{application}"
+
+Make sure that `:repository` correctly references your source control system, and that `:domain` is set to the hostname of your server.
+
+I won't be able to create any directories under the `/var/apps` directory (I'm going to run vlad using my own username in this example), so I need to login to my server and make sure that I can create files in the `hi` directory:
+
+    $ ssh your.web.server
+    $ sudo mkdir -p /var/apps/hi
+    $ sudo chown yourusername /var/apps/hi
+
+Now you can try running Vlad, to create all the directories necessary to serve your project. Back on your workstation, type:
+
+    $ rake vlad:setup
+
+You should find that some directories have been created within `/var/apps/hi` on your server.
+
+Let's trying deploying some code:
+
+    $ rake vlad:update
+    (in /Users/graham/data/effectif/projects/hi)
+    Initialized empty Git repository in /var/apps/hi/scm/repo/.git/
+    Switched to a new branch "deployed-HEAD"
+
+You should now find that if you ssh into your server that you can run the application:
+
+    $ ssh your.web.server
+    $ cd /var/apps/hi/current
+    $ merb
+
+Try making a change to your source, committing it to your repository, then run `vlad:update` again. Your code will be updated. If you restart Merb in the new directory you'll see your changes in the browser.
+
+If you're following along with these commands, be careful that you're running `merb` in the freshly deployed directory. `current` is a symlink to a specific release directory, so you'll need to leave the directory and return to it to see the new source code (i.e. symlinks don't get updated under your shell's feet). This should do it:
+
+    $ cd ~ && cd -
+    $ merb
+
+Okay, we're nearly there. All we need to do now is to automatically restart Merb when we deploy a new copy of the code with the `vlad:update` task. Add the following code to the bottom of your `config/deploy.rb` file:
+
+    Rake.clear_tasks("vlad:stop", "vlad:start")
+
+    namespace :vlad do
+      def stop
+        run "merb -m #{deploy_to}/current -K all"
+      end
+  
+      def start
+        run "merb -m #{deploy_to}/current -e production -c 2"
+      end
+  
+      remote_task :start, :roles => :app do
+        stop
+        start
+      end
+  
+      remote_task :stop, :roles => :app do
+        stop
+      end
+  
+      remote_task :update do
+        Rake::Task["vlad:start"].invoke
+      end
+    end
+
+Note that in this example we've started a two process cluster with the `-c` option in the `start` method.
+
+You'll find (with the `vlad:start` command I've shown above) that Merb is running on port 4000. If you want to run Merb on port 80 then I would recommend running these Merb processes behind Nginx, but I'll leave configuring Nginx as an exercise for the reader (Google will help you out there).
+
+Let's just make sure that it's working. Run `rake vlad:update` a couple of times and check that Merb is getting stopped and started properly (it fails to stop Merb on the first run below simply because this was the first time I'd started it):
+
+    $ rake vlad:update
+    (in /Users/graham/data/effectif/projects/hi)
+    Loading init file from /Users/graham/data/effectif/projects/hi/config/init.rb
+    Initialized empty Git repository in /var/apps/hi/scm/repo/.git/
+    Switched to a new branch "deployed-HEAD"
+     ~ Could not find a PID file at /var/apps/hi/current/log/merb.main.pid. Most likely the process is no longer running and the pid file was not cleaned up.
+     ~ In 7643
+    $ rake vlad:update
+    (in /Users/graham/data/effectif/projects/hi)
+    Loading init file from /Users/graham/data/effectif/projects/hi/config/init.rb
+    Initialized empty Git repository in /var/apps/hi/scm/repo/.git/
+    Switched to a new branch "deployed-HEAD"
+     ~ Killing pid 7643 with INT
+     ~ In 7840
+
+Now point your browser at port 4000 of your server – your application should be running!
+
+## Deploying from a Git branch
+
+If you want to deploy from a specific Git branch (`master` is the default) you can set the `:revision` variable in `deploy.rb`:
+
+    set :revision, "origin/mybranch"
+
+## Deploying as a different user
+
+It's not a great idea to deploy and run applications as your own login name (it's better practice to run web applications as users that don't have many privileges). I've not really addressed users in this article in order to focus on the basics of Vlad, but if you're interested you can deploy as a different user with these settings in `deploy.rb`:
+
+    set :user, "deploy"
+    set :domain, "#{user}@domain.com"

data/doco/deploying-sinatra-with-vlad.txt

@@ -0,0 +1,119 @@
+# Deploying Sinatra with Vlad
+
+This tutorial has been adapted from [Deploying Sinatra with Vlad](http://effectif.com/articles/deploying-sinatra-with-vlad) by [Graham Ashton](http://effectif.com "Effectif Development").
+
+So you've just written a nice new [Sinatra application](http://www.sinatrarb.com/ "Sinatra"), and you want to get it running on your web server. How hard can it be? Well with [Vlad the Deployer](http://rubyhitsquad.com/Vlad_the_Deployer.html "Vlad the Deployer"), it's actually rather easy.
+
+## Creating a sample application
+
+Let's start by making ourselves a test app:
+
+    $ mkdir hello
+    $ cd hello
+    $ touch app.rb
+
+Open `app.rb` in your editor and put this code in it:
+
+    require "rubygems"
+    require "sinatra"
+
+    get "/" do
+      "Hello!"
+    end
+
+We can check that the app works locally by running it...
+
+    $ ruby app.rb
+
+...and then opening [http://localhost:4567](http://localhost:4567) in a web browser.
+
+We need to create a `public` directory too, as Vlad assumes that we have a `public` directory for our static assets. I'm also going to make an empty CSS file so that the directory doesn't get ignored by Git:
+
+    $ mkdir public
+    $ touch public/master.css
+
+We'll deploy our application from version control. I'm using Git, but you can use any system that Vlad supports; just check your files into a repository that will be accessible from your web server.
+
+## Configuring Vlad
+
+Okay, we're ready for Vlad. It's a Ruby gem, so it's very easy to install:
+
+    $ sudo gem install vlad
+    Successfully installed vlad-1.2.0
+    1 gem installed
+    Installing ri documentation for vlad-1.2.0...
+    Installing RDoc documentation for vlad-1.2.0...
+
+There's no need to install Vlad on your server, just your workstation.
+
+You access Vlad's functionality through Rake tasks. This means that we need a `Rakefile` which loads the Vlad code. Create `Rakefile` in the same directory as `app.rb`, then add the following code to it:
+
+    begin
+      require "vlad"
+      Vlad.load(:app => nil, :scm => "git")
+    rescue LoadError
+      # do nothing
+    end
+
+Note that we've told Vlad that we intend to use Git (subversion is the default). We've set `:app` to `nil` as Vlad assumes that we'll run our application with [Mongrel](http://mongrel.rubyforge.org/ "Mongrel - Trac"). I'm not going to use Mongrel here, so we don't want Vlad to load its Mongrel recipes.
+
+If you run `rake -T` now you should see a bunch of vlad tasks that are available to you. You can't run them yet; you need to configure Vlad with a `config/deploy.rb` file:
+
+    $ mkdir config
+    $ touch config/deploy.rb
+
+Open `deploy.rb` in your editor and set the following variables:
+
+    set :application, "hello"
+    set :repository, "ssh://your.git.server/path/to/project/hello.git"
+    set :domain, "your.web.server"
+    set :deploy_to, "/var/apps/#{application}"
+
+Make sure that `:repository` correctly references your source control system, and that `:domain` is set to the hostname of your server.
+
+I won't be able to create any directories under the `/var/apps` directory (I'm going to run vlad using my own username in this example), so I need to login to my server and make sure that I can create files in the `hello` directory:
+
+    $ ssh your.web.server
+    $ sudo mkdir -p /var/apps/hello
+    $ sudo chown yourusername /var/apps/hello
+
+Now you can try running Vlad, to create all the directories necessary to serve your project. Back on your workstation, type:
+
+    $ rake vlad:setup
+
+You should find that some directories have been created within `/var/apps/hello` on your server.
+
+Let's trying deploying some code:
+
+    $ rake vlad:update
+    (in /Users/graham/data/effectif/projects/hello)
+    Initialized empty Git repository in /var/apps/hello/scm/repo/.git/
+    Switched to a new branch "deployed-HEAD"
+
+You should now find that if you ssh into your server that you can run the application:
+
+    $ ssh your.web.server
+    $ cd /var/apps/hello/current
+    $ ruby app.rb
+
+Try making a change to your source, committing it to your repository, then run `vlad:update` again. Your code will be updated. If you restart Sinatra in the new directory you'll see your changes in the browser.
+
+If you're following along with these commands, be careful that you're running `app.rb` in the freshly deployed directory. `current` is a symlink to a specific release directory, so you'll need to leave the directory and return to it to see the new source code (i.e. symlinks don't get updated under your shell's feet). This should do it:
+
+    $ cd ~ && cd -
+    $ ruby app.rb
+
+You may now be wondering how to get Thin running automatically, and how to re-start it when you run `vlad:update`. That should be the subject of my next blog post (you can [subscribe](/articles.xml) if you need it).
+
+## Deploying from a Git branch
+
+If you want to deploy from a specific Git branch (`master` is the default) you can set the `:revision` variable in `deploy.rb`:
+
+    set :revision, "origin/mybranch"
+
+## Deploying as a different user
+
+It's not a great idea to deploy and run applications as your own login name (it's better practice to run web applications as users that don't have many privileges). I've not really addressed users in this article in order to focus on the basics of Vlad, but if you're interested you can deploy as a different user with these settings in `deploy.rb`:
+
+    set :user, "deploy"
+    set :domain, "#{user}@domain.com"

data/lib/vlad.rb

@@ -20,7 +20,7 @@ module Vlad
 
   ##
   # This is the version of Vlad you are running.
-  VERSION = '1.3.1'
+  VERSION = '1.3.2'
 
   ##
   # Base error class for all Vlad errors.

data/lib/vlad/core.rb

@@ -54,7 +54,7 @@ namespace :vlad do
     begin
       run [ "cd #{scm_path}",
             "#{source.checkout revision, scm_path}",
-            "#{source.export scm_path, release_path}",
+            "#{source.export revision, release_path}",
             "chmod -R g+w #{latest_release}",
             "rm -rf #{latest_release}/log #{latest_release}/public/system #{latest_release}/tmp/pids",
             "mkdir -p #{latest_release}/db #{latest_release}/tmp"

data/lib/vlad/darcs.rb

@@ -12,9 +12,9 @@ class Vlad::Darcs
     ].join(" && ")
   end
 
-  def export(dir, dest)
-    [ %{mkdir -p #{dest}},
-      %{ls | grep ^[^_] | xargs -I vlad cp -R vlad #{dest}}
+  def export(revision, destination)
+    [ %{mkdir -p #{destination}},
+      %{ls | grep ^[^_] | xargs -I vlad cp -R vlad #{destination}}
     ].join(" && ")
   end
 

data/lib/vlad/git.rb

@@ -9,25 +9,31 @@ class Vlad::Git
   # SHA1 or equivalent (e.g. branch, tag, etc...)
 
   def checkout(revision, destination)
-    destination = 'repo' if destination == '.'
+    destination = File.join(destination, 'repo')
     revision = 'HEAD' if revision =~ /head/i
 
     [ "rm -rf #{destination}",
       "#{git_cmd} clone #{repository} #{destination}",
       "cd #{destination}",
-      "#{git_cmd} checkout -f -b deployed-#{revision} #{revision}"
+      "#{git_cmd} checkout -f -b deployed-#{revision} #{revision}",
+      "cd -"
     ].join(" && ")
   end
 
   ##
-  # Returns the command that will export +revision+ from the repository into
-  # the directory +destination+.
+  # Returns the command that will export +revision+ from the current directory
+  # into the directory +destination+.
+  # Expects to be run from +scm_path+ after Vlad::Git#checkout
 
   def export(revision, destination)
-    revision = 'HEAD' if revision == "."
+    revision = 'HEAD' if revision =~ /head/i
+    revision = "deployed-#{revision}"
 
     [ "mkdir -p #{destination}",
-      "#{git_cmd} archive --format=tar #{revision} | (cd #{destination} && tar xf -)"
+      "cd repo",
+      "#{git_cmd} archive --format=tar #{revision} | (cd #{destination} && tar xf -)",
+      "cd -",
+      "cd .."
     ].join(" && ")
   end
 

data/test/test_vlad_git.rb

@@ -9,24 +9,26 @@ class TestVladGit < VladTestCase
     set :repository, "git@myhost:/home/john/project1"
   end
 
+  # Checkout the way the default :update task invokes the method
   def test_checkout
-    # Checkout to the current directory (which is what the :update task passes)
-    cmd = @scm.checkout 'master', '.'
-    assert_equal 'rm -rf repo && git clone git@myhost:/home/john/project1 repo && cd repo && git checkout -f -b deployed-master master', cmd
+    cmd = @scm.checkout 'head', '/the/scm/path'
+    assert_equal 'rm -rf /the/scm/path/repo && git clone git@myhost:/home/john/project1 /the/scm/path/repo && cd /the/scm/path/repo && git checkout -f -b deployed-HEAD HEAD && cd -', cmd
+  end
 
-    # Mimic :update task
-    # 'head' should become HEAD
-    cmd = @scm.checkout 'head', '.'
-    assert_equal 'rm -rf repo && git clone git@myhost:/home/john/project1 repo && cd repo && git checkout -f -b deployed-HEAD HEAD', cmd
+  # This is not how the :update task invokes the method
+  def test_checkout_revision
+    # Checkout to the current directory
+    cmd = @scm.checkout 'master', '.'
+    assert_equal 'rm -rf ./repo && git clone git@myhost:/home/john/project1 ./repo && cd ./repo && git checkout -f -b deployed-master master && cd -', cmd
 
     # Checkout to a relative path
     cmd = @scm.checkout 'master', 'some/relative/path'
-    assert_equal 'rm -rf some/relative/path && git clone git@myhost:/home/john/project1 some/relative/path && cd some/relative/path && git checkout -f -b deployed-master master', cmd
+    assert_equal 'rm -rf some/relative/path/repo && git clone git@myhost:/home/john/project1 some/relative/path/repo && cd some/relative/path/repo && git checkout -f -b deployed-master master && cd -', cmd
   end
 
   def test_export
     cmd = @scm.export 'master', 'the/release/path'
-    assert_equal 'mkdir -p the/release/path && git archive --format=tar master | (cd the/release/path && tar xf -)', cmd
+    assert_equal 'mkdir -p the/release/path && cd repo && git archive --format=tar deployed-master | (cd the/release/path && tar xf -) && cd - && cd ..', cmd
   end
 
   def test_revision

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: vlad
 version: !ruby/object:Gem::Version 
-  version: 1.3.1
+  version: 1.3.2
 platform: ruby
 authors: 
 - Ryan Davis
@@ -32,7 +32,7 @@ cert_chain:
   FBHgymkyj/AOSqKRIpXPhjC6
   -----END CERTIFICATE-----
 
-date: 2009-03-06 00:00:00 -08:00
+date: 2009-03-16 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -63,7 +63,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.9.0
+        version: 1.10.0
     version: 
 description: Vlad the Deployer is pragmatic application deployment automation, without mercy. Much like Capistrano, but with 1/10th the complexity. Vlad integrates seamlessly with Rake, and uses familiar and standard tools like ssh and rsync.  Impale your application on the heartless spike of the Deployer.
 email: 
@@ -79,6 +79,8 @@ extra_rdoc_files:
 - Manifest.txt
 - README.txt
 - considerations.txt
+- doco/deploying-merb-with-vlad.txt
+- doco/deploying-sinatra-with-vlad.txt
 - doco/faq.txt
 - doco/getting_started.txt
 - doco/migration.txt
@@ -90,6 +92,8 @@ files:
 - README.txt
 - Rakefile
 - considerations.txt
+- doco/deploying-merb-with-vlad.txt
+- doco/deploying-sinatra-with-vlad.txt
 - doco/faq.txt
 - doco/getting_started.txt
 - doco/migration.txt