From f636f7c31acd6d84bdc058a921e969608ae4b19e Mon Sep 17 00:00:00 2001
From: Eric Wong <normalperson@yhbt.net>
Date: Fri, 7 May 2010 12:03:06 -0700
Subject: doc: add Sandbox document for bundler/isolate users

This may be expanded to cover other similar tools, as well,
including tools that don't use RubyGems.
---
 Sandbox | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 Sandbox

(limited to 'Sandbox')

diff --git a/Sandbox b/Sandbox
new file mode 100644
index 0000000..210add4
--- /dev/null
+++ b/Sandbox
@@ -0,0 +1,78 @@
+= Tips for using \Unicorn with Sandbox installation tools
+
+Since unicorn includes executables and is usually used to start a Ruby
+process, there are certain caveats to using it with tools that sandbox
+RubyGems installations such as
+{Bundler}[http://github.com/carlhuda/bundler] or
+{Isolate}[http://github.com/jbarnette/isolate].
+
+== General deployment
+
+If you're sandboxing your unicorn installation and using Capistrano (or
+similar), it's required that you sandbox your RubyGems in a per-application
+shared directory that can be used between different revisions.
+
+unicorn will stash its original command-line at startup for the USR2
+upgrades, and cleaning up old revisions will cause revision-specific
+installations of unicorn to go missing and upgrades to fail.   If you
+find yourself in this situation and can't afford downtime, you can
+override the existing unicorn executable path in the config file like
+this:
+
+        Unicorn::HttpServer::START_CTX[0] = "/some/path/to/bin/unicorn"
+
+Then use HUP to reload, and then continue with the USR2+QUIT upgrade
+sequence.
+
+== Bundler
+
+=== Running
+
+If you're bundling unicorn, use "bundle exec unicorn" (or "bundle exec
+unicorn_rails") to start unicorn with the correct environment variables
+
+ref: http://mid.gmane.org/9ECF07C4-5216-47BE-961D-AFC0F0C82060@internetfamo.us
+
+Otherwise (if you choose to not sandbox your unicorn installation), we
+expect the tips for Isolate (below) apply, too.
+
+=== RUBYOPT pollution from SIGUSR2 upgrades
+
+This is no longer be an issue as of bundler 0.9.17
+
+ref: http://mid.gmane.org/8FC34B23-5994-41CC-B5AF-7198EF06909E@tramchase.com
+
+== Isolate
+
+=== Running
+
+Installing "unicorn" as a system-wide Rubygem and using the
+isolate gem may cause issues if you're using any of the bundled
+application-level libraries in unicorn/app/* (for compatibility
+with CGI-based applications, Rails <= 2.2.2, or ExecCgi).
+For now workarounds include doing one of the following:
+
+1. Isolating unicorn, setting GEM_HOME to your isolate path,
+   and running the isolated version of unicorn.  You *must* set
+   GEM_HOME before running your isolated unicorn install in this way.
+
+2.  Installing the same version of unicorn as a system-wide Rubygem
+    *and* isolating unicorn as well.
+
+3. Explicitly setting RUBYLIB or $LOAD_PATH to include any gem path
+   where the unicorn gem is installed
+   (e.g. /usr/lib/ruby/gems/1.9.1/gems/unicorn-VERSION/lib)
+
+=== RUBYOPT pollution from SIGUSR2 upgrades
+
+With 1.x versions of isolate, it is also recommended that you
+disable it with the <tt>before_exec</tt> hook prevent the PATH and
+RUBYOPT environment variable modifications from propagating between
+upgrades in your unicorn config file:
+
+        before_exec do |server|
+          Isolate.disable
+        end
+
+Isolate 2.x (in prerelease as of 2010.05.07) will not require this as
+environment variable modifications will be idempotent.
-- 
cgit v1.2.3-24-ge0c7