Sandbox

   1 = Tips for using \Unicorn with Sandbox installation tools
   2
   3 Since unicorn includes executables and is usually used to start a Ruby
   4 process, there are certain caveats to using it with tools that sandbox
   5 RubyGems installations such as
   6 {Bundler}[http://github.com/carlhuda/bundler] or
   7 {Isolate}[http://github.com/jbarnette/isolate].
   8
   9 == General deployment
  10
  11 If you're sandboxing your unicorn installation and using Capistrano (or
  12 similar), it's required that you sandbox your RubyGems in a per-application
  13 shared directory that can be used between different revisions.
  14
  15 unicorn will stash its original command-line at startup for the USR2
  16 upgrades, and cleaning up old revisions will cause revision-specific
  17 installations of unicorn to go missing and upgrades to fail.   If you
  18 find yourself in this situation and can't afford downtime, you can
  19 override the existing unicorn executable path in the config file like
  20 this:
  21
  22         Unicorn::HttpServer::START_CTX[0] = "/some/path/to/bin/unicorn"
  23
  24 Then use HUP to reload, and then continue with the USR2+QUIT upgrade
  25 sequence.
  26
  27 == Bundler
  28
  29 === Running
  30
  31 If you're bundling unicorn, use "bundle exec unicorn" (or "bundle exec
  32 unicorn_rails") to start unicorn with the correct environment variables
  33
  34 ref: http://mid.gmane.org/9ECF07C4-5216-47BE-961D-AFC0F0C82060@internetfamo.us
  35
  36 Otherwise (if you choose to not sandbox your unicorn installation), we
  37 expect the tips for Isolate (below) apply, too.
  38
  39 === RUBYOPT pollution from SIGUSR2 upgrades
  40
  41 This is no longer be an issue as of bundler 0.9.17
  42
  43 ref: http://mid.gmane.org/8FC34B23-5994-41CC-B5AF-7198EF06909E@tramchase.com
  44
  45 == Isolate
  46
  47 === Running
  48
  49 Installing "unicorn" as a system-wide Rubygem and using the
  50 isolate gem may cause issues if you're using any of the bundled
  51 application-level libraries in unicorn/app/* (for compatibility
  52 with CGI-based applications, Rails <= 2.2.2, or ExecCgi).
  53 For now workarounds include doing one of the following:
  54
  55 1. Isolating unicorn, setting GEM_HOME to your isolate path,
  56    and running the isolated version of unicorn.  You *must* set
  57    GEM_HOME before running your isolated unicorn install in this way.
  58
  59 2.  Installing the same version of unicorn as a system-wide Rubygem
  60     *and* isolating unicorn as well.
  61
  62 3. Explicitly setting RUBYLIB or $LOAD_PATH to include any gem path
  63    where the unicorn gem is installed
  64    (e.g. /usr/lib/ruby/gems/1.9.1/gems/unicorn-VERSION/lib)
  65
  66 === RUBYOPT pollution from SIGUSR2 upgrades
  67
  68 With 1.x versions of isolate, it is also recommended that you
  69 disable it with the <tt>before_exec</tt> hook prevent the PATH and
  70 RUBYOPT environment variable modifications from propagating between
  71 upgrades in your unicorn config file:
  72
  73         before_exec do |server|
  74           Isolate.disable
  75         end
  76
  77 Isolate 2.x (in prerelease as of 2010.05.07) will not require this as
  78 environment variable modifications will be idempotent.