about summary refs log tree commit homepage
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2010-05-07 12:03:06 -0700
committerEric Wong <normalperson@yhbt.net>2010-05-07 12:13:38 -0700
commitf636f7c31acd6d84bdc058a921e969608ae4b19e (patch)
tree7e49c943d452f3210aa44fc6f40faea905c6db5c
parent935912a422cabfd323f9b4ff268ded09a2ebe7a6 (diff)
downloadunicorn-f636f7c31acd6d84bdc058a921e969608ae4b19e.tar.gz
This may be expanded to cover other similar tools, as well,
including tools that don't use RubyGems.
-rw-r--r--.document1
-rw-r--r--KNOWN_ISSUES24
-rw-r--r--Sandbox78
3 files changed, 79 insertions, 24 deletions
diff --git a/.document b/.document
index 459f863..7f77691 100644
--- a/.document
+++ b/.document
@@ -16,3 +16,4 @@ ext/unicorn_http/unicorn_http.c
 unicorn_1
 unicorn_rails_1
 ISSUES
+Sandbox
diff --git a/KNOWN_ISSUES b/KNOWN_ISSUES
index c32d751..a63006f 100644
--- a/KNOWN_ISSUES
+++ b/KNOWN_ISSUES
@@ -32,30 +32,6 @@ acceptable solution.  Those issues are documented here.
   Note: the workaround described in the article above only made
   the issue more subtle and we didn't notice them immediately.
 
-* Installing "unicorn" as a system-wide Rubygem and using the
-  {isolate}[http://github.com/jbarnette/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:
-
-  * installing the same version of unicorn as a system-wide Rubygem
-    _and_ isolating unicorn as well.
-  * explicitly setting RUBYLIB or $LOAD_PATH to include any gem path
-    where the unicorn gem is installed (e.g.
-    /usr/lib/ruby/gems/1.8/gems/unicorn-VERSION/lib)
-
-  With current 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
-
-  Future versions (unreleased as of 2010.04.20) of isolate will not
-  require this as environment variable modifications will be idempotent.
-
 * WONTFIX: code reloading and restarts with Sinatra 0.3.x (and likely older
   versions) apps is broken.  The workaround is to force production
   mode to disable code reloading as well as disabling "run" in your
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.