rack-campaign 0.0.2 → 0.0.3

data/README.textile

@@ -1 +1,137 @@
-More to come soon...
+h2. rack-campaign
+
+This is a "Rack":http://rack.rubyforge.org/ application (a gem is available by the same name) allowing you to maintain a "YAML":http://www.yaml.org/ file of short URLs that redirect to target URLs with a set of specified Google Analytics variables. It could be used to attach any number of parameters by any name to the query string.
+
+h2. What it does:
+
+*example promo url*:
+
+@http://zetetic.net/c/blog-rack-campaign@
+
+When the user visits this link, our web server sees the /c/ location and forwards it to rack-campaign, which looks up 'blog-rack-campaign' in the YAML file, and redirects the user to the full URL, with campaign variables attached.
+    
+*resulting full url*:
+
+@http://www.zetetic.net/blog/2010/06/11/introducing-rack-campaign?utm_campaign=rack-campaign&utm_source=blog&utm_medium=internets&utm_content=example%20link@
+
+The former is much better than the latter, especially for newsletters and other promotional links. And with a Rack application and a YAML file you can host it yourself, you don't need to rely on bit.ly or other URL shorteners, and you can "fix" any mistakes after publishing a URL simply by updating the YAML file and reloading Unicorn (taking advantage of zero down-time!) [ _You could use another Rack-server, we like Unicorn._ ]
+
+h2. Installation
+
+@gem install rack-campaign@
+
+The rest depends on how you intend to use it. 
+
+h2. Example Files
+
+In the @/examples@ directory of the source distribution are some sample configuration files. @config.ru@ is a @rackup@ file, initializing the rack-campaign middleware. You don't have to use rack-campaign as a stand-alone Rack application, you could instead use it in a middleware stack (although you might want to modify it's behavior). You probably want to use the map directive in that case to assign rack-campaign to a particular url path (we use /c).
+
+h2. Example Configuration
+
+This is how we use rack-campaign as a stand-alone Rack application. Nginx is our web-server, and we use Unicorn to serve up rack-campaign for the /c path:
+
+*/www/campaigns/campaigns.yml*:
+
+<pre><code>
+blog-rack-campaign:
+  url: http://dev.zetetic.net/blog/2010/06/11/introducing-rack-campaign
+  tokens:
+    campaign: rack-campaign
+    source: blog
+    medium: internets
+    content: example link
+
+blog-getstrip:
+  url: http://getstrip.com
+  tokens:
+    campaign: rack-campaign
+    source: blog
+    medium: internets
+    term: strip rocks!
+    content: example link
+</code></pre>
+    
+*/www/campaigns/config.ru*:
+
+<pre><code>
+# Rack-up application config
+
+require 'rubygems'
+require 'rack/zetetic/rack-campaign'
+
+run Rack::Zetetic::CampaignLink.new('/www/campaigns/campaigns.yml')
+</code></pre>
+
+*nginx.conf*:
+
+<pre><code>
+  # define upstream for campaign routing
+  upstream campaigns {
+    server unix:/www/campaigns/tmp/sockets/unicorn.sock;
+  }
+
+  location /c {
+    proxy_redirect     off;
+    proxy_set_header   Host             $host;
+    proxy_set_header   X-Real-IP        $remote_addr;
+    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
+    proxy_max_temp_file_size 0;
+
+    # forward everything else to the mongrel cluster
+    if (!-f $request_filename) {
+     proxy_pass http://campaigns;
+     break;
+    }
+  }
+</code></pre>
+    
+*/etc/init.d/unicorn_rack*:
+
+<pre><code>
+#!/bin/bash
+#
+# unicorn_rack       Startup script for Unicorn master processes
+#
+# chkconfig: - 85 15
+# description: unicorn is a magical process offering up workers to nginx
+#              
+
+USER=mongrel
+RETVAL=0
+APPS=( '/www/campaigns' )
+
+for APP in "${APPS[@]}"
+do
+  case "$1" in
+      start)
+        echo "Starting up $APP"
+        cd $APP
+        sudo -u $USER unicorn -c $APP/unicorn.rb -E production -D 
+        RETVAL=$?
+    ;;
+      stop)
+        echo "Stopping $APP"
+        PID=`ps auxw | grep 'unicorn master' | grep $APP | grep -v grep | awk '{ print $2 }'`
+        sudo -u $USER kill -INT $PID
+        RETVAL=$?
+    ;;
+      restart)
+      $0 stop
+      sleep 2
+      $0 start
+    ;;
+      reload)
+        echo "Re-loading $APPS"
+        PID=`ps auxw | grep 'unicorn master' | grep $APP | grep -v grep | awk '{ print $2 }'`
+        sudo -u $USER kill -HUP $PID
+        RETVAL=$?
+    ;;
+      *)
+        echo "Usage: unicorn_rack {start|stop|restart|reload}"
+        exit 1
+    ;;
+  esac      
+done
+
+exit $RETVAL
+</code></pre>

data/Rakefile

@@ -5,7 +5,7 @@ require 'date'
 require 'spec/rake/spectask'
 
 GEM = "rack-campaign"
-GEM_VERSION = "0.0.2"
+GEM_VERSION = "0.0.3"
 AUTHOR = "Billy Gray"
 EMAIL = "wgray@zetetic.net"
 HOMEPAGE = "http://github.com/billymeltdown/rack-campaign"
@@ -25,7 +25,7 @@ spec = Gem::Specification.new do |s|
   s.homepage = HOMEPAGE
   s.add_dependency "rack"
   s.require_path = 'lib'
-  s.files = %w(LICENSE README.textile Rakefile) + Dir.glob("{lib}/**/*")
+  s.files = %w(LICENSE README.textile Rakefile) + Dir.glob("{lib}/**/*") + Dir.glob("examples/**/*")
 end
 
 task :default => :spec

data/examples/campaigns.yml

@@ -0,0 +1,16 @@
+blog-rack-campaign:
+  url: http://dev.zetetic.net/blog/2010/06/11/introducing-rack-campaign
+  tokens:
+    campaign: rack-campaign
+    source: blog
+    medium: internets
+    content: example link
+
+blog-getstrip:
+  url: http://getstrip.com
+  tokens:
+    campaign: rack-campaign
+    source: blog
+    medium: internets
+    term: strip rocks!
+    content: example link

data/examples/config.ru

@@ -0,0 +1,6 @@
+# Rack application
+
+require 'rubygems'
+require 'rack/zetetic/rack-campaign'
+
+run Rack::Zetetic::CampaignLink.new('/path/to/your/campaigns.yml')

data/examples/initscript

@@ -0,0 +1,47 @@
+#!/bin/bash
+#
+# unicorn_rack       Startup script for Unicorn master processes
+#
+# chkconfig: - 85 15
+# description: unicorn is a magical process offering up workers to nginx
+#              
+
+USER=mongrel
+RETVAL=0
+APPS=( '/www/campaigns' )
+
+for APP in "${APPS[@]}"
+do
+  case "$1" in
+      start)
+        echo "Starting up $APP"
+        cd $APP
+        sudo -u $USER unicorn -c $APP/unicorn.rb -E production -D 
+        RETVAL=$?
+    ;;
+      stop)
+        echo "Stopping $APP"
+        PID=`ps auxw | grep 'unicorn master' | grep $APP | grep -v grep | awk '{ print $2 }'`
+        sudo -u $USER kill -INT $PID
+        RETVAL=$?
+    ;;
+      restart)
+      $0 stop
+      sleep 2
+      $0 start
+    ;;
+      reload)
+        echo "Re-loading $APPS"
+        PID=`ps auxw | grep 'unicorn master' | grep $APP | grep -v grep | awk '{ print $2 }'`
+        sudo -u $USER kill -HUP $PID
+        RETVAL=$?
+    ;;
+      *)
+        echo "Usage: unicorn_rack {start|stop|restart|reload}"
+        exit 1
+    ;;
+  esac      
+done
+
+exit $RETVAL
+

data/examples/unicorn.rb

@@ -0,0 +1,69 @@
+# unicorn -c /path/to/unicorn.rb -e production -D
+# Unicorn-specific config
+# Largely borrowed from the Github crew
+
+app_dir = '/www/campaign_link'
+worker_processes (ENV['RACK_ENV'] == 'production' ? 6 : 2)
+
+# Restart any workers that haven't responded in 30 seconds 
+timeout 30
+
+# Load the Rack app into the master before forking workers
+# for super-fast worker spawn times
+preload_app true
+
+# Listen on a Unix data socket
+listen 'unix:' + app_dir + '/tmp/sockets/unicorn.sock', :backlog => 2048
+
+##
+# REE
+# http://www.rubyenterpriseedition.com/faq.html#adapt_apps_for_cow
+if GC.respond_to?(:copy_on_write_friendly=)
+  GC.copy_on_write_friendly = true
+end
+
+before_fork do |server, worker|
+  ##
+  # When sent a USR2, Unicorn will suffix its pidfile with .oldbin and
+  # immediately start loading up a new version of itself (loaded with a new
+  # version of our app). When this new Unicorn is completely loaded
+  # it will begin spawning workers. The first worker spawned will check to
+  # see if an .oldbin pidfile exists. If so, this means we've just booted up
+  # a new Unicorn and need to tell the old one that it can now die. To do so
+  # we send it a QUIT.
+  #
+  # Using this method we get 0 downtime deploys.
+ 
+  old_pid = app_dir + '/tmp/pids/unicorn.pid.oldbin'
+  if File.exists?(old_pid) && server.pid != old_pid
+    begin
+      Process.kill("QUIT", File.read(old_pid).to_i)
+    rescue Errno::ENOENT, Errno::ESRCH
+      # someone else did our job for us
+    end
+  end
+end
+
+after_fork do |server, worker|
+  ##
+  # Unicorn master is started as root, which is fine, but let's
+  # drop the workers to mongrel:mongrel (or whatever you like...)
+  begin
+    uid, gid = Process.euid, Process.egid
+    user, group = 'mongrel', 'mongrel'
+    target_uid = Etc.getpwnam(user).uid
+    target_gid = Etc.getgrnam(group).gid
+    worker.tmp.chown(target_uid, target_gid)
+    if uid != target_uid || gid != target_gid
+      Process.initgroups(user, target_gid)
+      Process::GID.change_privilege(target_gid)
+      Process::UID.change_privilege(target_uid)
+    end
+  rescue => e
+    if ENV['RACK_ENV'] == 'development'
+      STDERR.puts "couldn't change user, oh well"
+    else
+      raise e
+    end
+  end
+end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Billy Gray
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-10 00:00:00 -04:00
+date: 2010-06-14 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -43,6 +43,10 @@ files:
 - README.textile
 - Rakefile
 - lib/rack/zetetic/campaign_link.rb
+- examples/campaigns.yml
+- examples/config.ru
+- examples/initscript
+- examples/unicorn.rb
 has_rdoc: true
 homepage: http://github.com/billymeltdown/rack-campaign
 licenses: []