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 # RUBY OPTIONS
  82 -e, \--eval LINE
  83 :   Evaluate a LINE of Ruby code.  This evaluation happens
  84     immediately as the command-line is being parsed.
  85
  86 -d, \--debug
  87 :   Turn on debug mode, the $DEBUG variable is set to true.
  88     For Rails \>\= 2.3.x, this loads the *Rails::Rack::Debugger*
  89     middleware.
  90
  91 -w, \--warn
  92 :   Turn on verbose warnings, the $VERBOSE variable is set to true.
  93
  94 -I, \--include PATH
  95 :   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
  96     The \':\' character may be used to delimit multiple directories.
  97     This directive may be used more than once.  Modifications to
  98     $LOAD_PATH take place immediately and in the order they were
  99     specified on the command-line.
 100
 101 -r, \--require LIBRARY
 102 :   require a specified LIBRARY before executing the application.  The
 103     \"require\" statement will be executed immediately and in the order
 104     they were specified on the command-line.
 105
 106 # RACKUP FILE
 107
 108 This defaults to \"config.ru\" in RAILS_ROOT.  It should be the same
 109 file used by rackup(1) and other Rack launchers, it uses the
 110 *Rack::Builder* DSL.  Unlike many other Rack applications, RACKUP_FILE
 111 is completely _optional_ for Rails, but may be used to disable some
 112 of the default middleware for performance.
 113
 114 Embedded command-line options are mostly parsed for compatibility
 115 with rackup(1) but strongly discouraged.
 116
 117 # SIGNALS
 118
 119 The following UNIX signals may be sent to the master process:
 120
 121 * HUP - reload config file, app, and gracefully restart all workers
 122 * INT/TERM - quick shutdown, kills all workers immediately
 123 * QUIT - graceful shutdown, waits for workers to finish their
 124   current request before finishing.
 125 * USR1 - reopen all logs owned by the master and all workers
 126   See Unicorn::Util.reopen_logs for what is considered a log.
 127 * USR2 - reexecute the running binary.  A separate QUIT
 128   should be sent to the original process once the child is verified to
 129   be up and running.
 130 * WINCH - gracefully stops workers but keep the master running.
 131   This will only work for daemonized processes.
 132 * TTIN - increment the number of worker processes by one
 133 * TTOU - decrement the number of worker processes by one
 134
 135 See the [SIGNALS][4] document for full description of all signals
 136 used by Unicorn.
 137
 138 # SEE ALSO
 139
 140 * unicorn(1)
 141 * *Rack::Builder* ri/RDoc
 142 * *Unicorn::Configurator* ri/RDoc
 143 * [Unicorn RDoc][1]
 144 * [Rack RDoc][2]
 145 * [Rackup HowTo][3]
 146
 147 [1]: http://unicorn.bogomips.org/
 148 [2]: http://rack.rubyforge.org/doc/
 149 [3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
 150 [4]: http://unicorn.bogomips.org/SIGNALS.html