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 = "/some/path/to/bin/unicorn"
Then use HUP to reload, and then continue with the USR2+QUIT upgrade sequence.
Environment variable pollution when exec-ing a new process (with USR2) is the primary issue with sandboxing tools such as Bundler and Isolate.
If you’re bundling unicorn, use “bundle exec unicorn” (or “bundle exec unicorn_rails”) to start unicorn with the correct environment variables
Otherwise (if you choose to not sandbox your unicorn installation), we expect the tips for Isolate (below) apply, too.
This is no longer be an issue as of bundler 0.9.17
You may need to set or reset the BUNDLE_GEMFILE environment variable in the before_exec hook:
before_exec do |server| ENV["BUNDLE_GEMFILE"] = "/path/to/app/current/Gemfile" end
If you’re using an older Bundler version (0.9.x), you may need to set or reset GEM_HOME, GEM_PATH and PATH environment variables in the before_exec hook as illustrated by gist.github.com/534668
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:
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.
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.9.1/gems/unicorn-VERSION/lib)
If you are using Isolate, using Isolate 2.x is strongly recommended as environment modifications are idempotent.
If you are stuck with 1.x versions of Isolate, it is recommended that you disable it with the before_exec 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