Documentation/unicorn_rails.1.txt

   1 % UNICORN_RAILS(1) Unicorn User Manual
   2 % The Unicorn Community <mongrel-unicorn@rubyforge.org>
   3 % September 17, 2009
   4
   5 # NAME
   6
   7 unicorn_rails - a rackup-like command to launch the Unicorn HTTP server
   8
   9 # SYNOPSIS
  10
  11 unicorn_rails [-c CONFIG_FILE] [-E RAILS_ENV] [-D] [RACKUP_FILE]
  12
  13 # DESCRIPTION
  14
  15 A rackup(1)-like command to launch Rails applications using Unicorn.  It
  16 is expected to be started in your Rails application root (RAILS_ROOT),
  17 but "Dir.chdir" may also be executed in the CONFIG_FILE or
  18 optionally, RACKUP_FILE.
  19
  20 The outward interface resembles rackup(1), the internals and default
  21 middleware loading is designed like the `script/server` command
  22 distributed with Rails.
  23
  24 While Unicorn takes a myriad of command-line options for compatibility
  25 with ruby(1) and rackup(1), it is recommended to stick to the few
  26 command-line options specified in the SYNOPSIS and use the CONFIG_FILE
  27 as much as possible.
  28
  29 # UNICORN OPTIONS
  30 -c, \--config-file CONFIG_FILE
  31 :   Path to the Unicorn-specific config file.  The config file is
  32     implemented as a Ruby DSL, so Ruby code may executed (e.g.
  33     "Dir.chdir", "Process::UID.change_privilege").  See the RDoc/ri
  34     for the *Unicorn::Configurator* class for the full list of
  35     directives available from the DSL.
  36
  37 -D, \--daemonize
  38 :   Run daemonized in the background.  The process is detached from
  39     the controlling terminal and stdin is redirected to "/dev/null".
  40     Unlike many common UNIX daemons, we do not chdir to \"/\"
  41     upon daemonization to allow more control over the startup/upgrade
  42     process.
  43     Unless specified in the CONFIG_FILE, stderr and stdout will
  44     also be redirected to "/dev/null".
  45     Daemonization will _skip_ loading of the *Rails::Rack::LogTailer*
  46     middleware under Rails \>\= 2.3.x.
  47     By default, unicorn\_rails(1) will create a PID file in
  48     _\"RAILS\_ROOT/tmp/pids/unicorn.pid\"_.  You may override this
  49     by specifying the "pid" directive to override this Unicorn config file.
  50
  51 -E, \--env RAILS_ENV
  52 :   Run under the given RAILS_ENV.  This sets the RAILS_ENV environment
  53     variable.  Acceptable values are exactly those you expect in your Rails
  54     application, typically "development" or "production".
  55
  56 -l, \--listen ADDRESS
  57 :   Listens on a given ADDRESS.  ADDRESS may be in the form of
  58     HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
  59     and PATH is meant to be a path to a UNIX domain socket.
  60     Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080).
  61     For production deployments, specifying the "listen" directive in
  62     CONFIG_FILE is recommended as it allows fine-tuning of socket
  63     options.
  64
  65 # RACKUP COMPATIBILITY OPTIONS
  66 -o, \--host HOST
  67 :   Listen on a TCP socket belonging to HOST, default is
  68     "0.0.0.0" (all addresses).
  69     If specified multiple times on the command-line, only the
  70     last-specified value takes effect.
  71     This option only exists for compatibility with the rackup(1) command,
  72     use of "-l"/"\--listen" switch is recommended instead.
  73
  74 -p, \--port PORT
  75 :   Listen on the specified TCP PORT, default is 8080.
  76     If specified multiple times on the command-line, only the last-specified
  77     value takes effect.
  78     This option only exists for compatibility with the rackup(1) command,
  79     use of "-l"/"\--listen" switch is recommended instead.
  80
  81 \--path PATH
  82 :   Mounts the Rails application at the given PATH (instead of "/").
  83     This is equivalent to setting the RAILS_RELATIVE_URL_ROOT
  84     environment variable.  This is only supported under Rails 2.3
  85     or later at the moment.
  86
  87 # RUBY OPTIONS
  88 -e, \--eval LINE
  89 :   Evaluate a LINE of Ruby code.  This evaluation happens
  90     immediately as the command-line is being parsed.
  91
  92 -d, \--debug
  93 :   Turn on debug mode, the $DEBUG variable is set to true.
  94     For Rails \>\= 2.3.x, this loads the *Rails::Rack::Debugger*
  95     middleware.
  96
  97 -w, \--warn
  98 :   Turn on verbose warnings, the $VERBOSE variable is set to true.
  99
 100 -I, \--include PATH
 101 :   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
 102     The \':\' character may be used to delimit multiple directories.
 103     This directive may be used more than once.  Modifications to
 104     $LOAD_PATH take place immediately and in the order they were
 105     specified on the command-line.
 106
 107 -r, \--require LIBRARY
 108 :   require a specified LIBRARY before executing the application.  The
 109     \"require\" statement will be executed immediately and in the order
 110     they were specified on the command-line.
 111
 112 # RACKUP FILE
 113
 114 This defaults to \"config.ru\" in RAILS_ROOT.  It should be the same
 115 file used by rackup(1) and other Rack launchers, it uses the
 116 *Rack::Builder* DSL.  Unlike many other Rack applications, RACKUP_FILE
 117 is completely _optional_ for Rails, but may be used to disable some
 118 of the default middleware for performance.
 119
 120 Embedded command-line options are mostly parsed for compatibility
 121 with rackup(1) but strongly discouraged.
 122
 123 # ENVIRONMENT VARIABLES
 124
 125 The RAILS_ENV variable is set by the aforementioned \-E switch.  The
 126 RAILS_RELATIVE_URL_ROOT is set by the aforementioned \--path switch.
 127 Either of these variables may also be set in the shell or the Unicorn
 128 CONFIG_FILE.  All application or library-specific environment variables
 129 (e.g. TMPDIR, RAILS_ASSET_ID) may always be set in the Unicorn
 130 CONFIG_FILE in addition to the spawning shell.  When transparently
 131 upgrading Unicorn, all environment variables set in the old master
 132 process are inherited by the new master process.  Unicorn only uses (and
 133 will overwrite) the UNICORN_FD environment variable internally when
 134 doing transparent upgrades.
 135
 136 # SIGNALS
 137
 138 The following UNIX signals may be sent to the master process:
 139
 140 * HUP - reload config file, app, and gracefully restart all workers
 141 * INT/TERM - quick shutdown, kills all workers immediately
 142 * QUIT - graceful shutdown, waits for workers to finish their
 143   current request before finishing.
 144 * USR1 - reopen all logs owned by the master and all workers
 145   See Unicorn::Util.reopen_logs for what is considered a log.
 146 * USR2 - reexecute the running binary.  A separate QUIT
 147   should be sent to the original process once the child is verified to
 148   be up and running.
 149 * WINCH - gracefully stops workers but keep the master running.
 150   This will only work for daemonized processes.
 151 * TTIN - increment the number of worker processes by one
 152 * TTOU - decrement the number of worker processes by one
 153
 154 See the [SIGNALS][4] document for full description of all signals
 155 used by Unicorn.
 156
 157 # SEE ALSO
 158
 159 * unicorn(1)
 160 * *Rack::Builder* ri/RDoc
 161 * *Unicorn::Configurator* ri/RDoc
 162 * [Unicorn RDoc][1]
 163 * [Rack RDoc][2]
 164 * [Rackup HowTo][3]
 165
 166 [1]: http://unicorn.bogomips.org/
 167 [2]: http://rack.rubyforge.org/doc/
 168 [3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
 169 [4]: http://unicorn.bogomips.org/SIGNALS.html