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}[https://bundler.io/] or
   7 {Isolate}[https://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 Environment variable pollution when exec-ing a new process (with USR2)
  28 is the primary issue with sandboxing tools such as Bundler and Isolate.
  29
  30 == Bundler
  31
  32 === Running
  33
  34 If you're bundling unicorn, use "bundle exec unicorn" (or "bundle exec
  35 unicorn_rails") to start unicorn with the correct environment variables
  36
  37 ref: https://yhbt.net/unicorn-public/9ECF07C4-5216-47BE-961D-AFC0F0C82060@internetfamo.us/
  38
  39 Otherwise (if you choose to not sandbox your unicorn installation), we
  40 expect the tips for Isolate (below) apply, too.
  41
  42 === RUBYOPT pollution from SIGUSR2 upgrades
  43
  44 This is no longer be an issue as of bundler 0.9.17
  45
  46 ref:
  47 https://yhbt.net/unicorn-public/8FC34B23-5994-41CC-B5AF-7198EF06909E@tramchase.com/
  48
  49 === BUNDLE_GEMFILE for Capistrano users
  50
  51 You may need to set or reset the BUNDLE_GEMFILE environment variable in
  52 the before_exec hook:
  53
  54         before_exec do |server|
  55           ENV["BUNDLE_GEMFILE"] = "/path/to/app/current/Gemfile"
  56         end
  57
  58 === Other ENV pollution issues
  59
  60 If you're using an older Bundler version (0.9.x), you may need to set or
  61 reset GEM_HOME, GEM_PATH and PATH environment variables in the
  62 before_exec hook as illustrated by https://gist.github.com/534668
  63
  64 === Ruby 2.0.0 close-on-exec and SIGUSR2 incompatibility
  65
  66 Ruby 2.0.0 enforces FD_CLOEXEC on file descriptors by default.  unicorn
  67 has been prepared for this behavior since unicorn 4.1.0, and bundler
  68 needs the "--keep-file-descriptors" option for "bundle exec":
  69 https://bundler.io/man/bundle-exec.1.html
  70
  71 == Isolate
  72
  73 === Running
  74
  75 Installing "unicorn" as a system-wide Rubygem and using the
  76 isolate gem may cause issues if you're using any of the bundled
  77 application-level libraries in unicorn/app/* (for compatibility
  78 with CGI-based applications, Rails <= 2.2.2, or ExecCgi).
  79 For now workarounds include doing one of the following:
  80
  81 1. Isolating unicorn, setting GEM_HOME to your Isolate path,
  82    and running the isolated version of unicorn.  You *must* set
  83    GEM_HOME before running your isolated unicorn install in this way.
  84
  85 2.  Installing the same version of unicorn as a system-wide Rubygem
  86     *and* isolating unicorn as well.
  87
  88 3. Explicitly setting RUBYLIB or $LOAD_PATH to include any gem path
  89    where the unicorn gem is installed
  90    (e.g. /usr/lib/ruby/gems/3.0.0/gems/unicorn-VERSION/lib)
  91
  92 === RUBYOPT pollution from SIGUSR2 upgrades
  93
  94 If you are using Isolate, using Isolate 2.x is strongly recommended as
  95 environment modifications are idempotent.
  96
  97 If you are stuck with 1.x versions of Isolate, it is recommended that
  98 you disable it with the <tt>before_exec</tt> hook prevent the PATH and
  99 RUBYOPT environment variable modifications from propagating between
 100 upgrades in your Unicorn config file:
 101
 102         before_exec do |server|
 103           Isolate.disable
 104         end