Documentation/rainbows.1.txt

   1 % rainbows(1) Unicorn User Manual
   2 % The Unicorn Community <mongrel-unicorn@rubyforge.org>
   3 % September 15, 2009
   4
   5 # NAME
   6
   7 rainbows - rackup-like command to launch Rainbows!
   8
   9 # SYNOPSIS
  10
  11 rainbows [-c CONFIG_FILE] [-E RACK_ENV] [-D] [RACKUP_FILE]
  12
  13 # DESCRIPTION
  14
  15 A rackup(1)-like command to launch Rack applications using
  16 Rainbows!.  It is expected to be started in your application root
  17 (APP_ROOT), but "Dir.chdir" may also be executed in the CONFIG_FILE or
  18 RACKUP_FILE.
  19
  20 While Rainbows! takes a myriad of command-line options for
  21 compatibility with ruby(1) and rackup(1), it is recommended to stick
  22 to the few command-line options specified in the SYNOPSIS and use
  23 the CONFIG_FILE as much as possible.
  24
  25 # RACKUP FILE
  26
  27 This defaults to \"config.ru\" in APP_ROOT.  It should be the same
  28 file used by rackup(1) and other Rack launchers, it uses the
  29 *Rack::Builder* DSL.
  30
  31 Embedded command-line options are mostly parsed for compatibility
  32 with rackup(1) but strongly discouraged.
  33
  34 # UNICORN OPTIONS
  35 -c, \--config-file CONFIG_FILE
  36 :   Path to the Unicorn-specific config file.  The config file is
  37     implemented as a Ruby DSL, so Ruby code may executed (e.g.
  38     "Dir.chdir", "Process::UID.change_privilege").  See the RDoc/ri
  39     for the *Unicorn::Configurator* class for the full list of
  40     directives available from the DSL.
  41
  42 -D, \--daemonize
  43 :   Run daemonized in the background.  The process is detached from
  44     the controlling terminal and stdin is redirected to "/dev/null".
  45     Unlike many common UNIX daemons, we do not chdir to \"/\"
  46     upon daemonization to allow more control over the startup/upgrade
  47     process.
  48     Unless specified in the CONFIG_FILE, stderr and stdout will
  49     also be redirected to "/dev/null".
  50
  51 -E, \--env RACK_ENV
  52 :   Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
  53     for more details.
  54
  55 -l, \--listen ADDRESS
  56 :   Listens on a given ADDRESS.  ADDRESS may be in the form of
  57     HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
  58     and PATH is meant to be a path to a UNIX domain socket.
  59     Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080)
  60     For production deployments, specifying the "listen" directive in
  61     CONFIG_FILE is recommended as it allows fine-tuning of socket
  62     options.
  63
  64 # RACKUP COMPATIBILITY OPTIONS
  65 -o, \--host HOST
  66 :   Listen on a TCP socket belonging to HOST, default is
  67     "0.0.0.0" (all addresses).
  68     If specified multiple times on the command-line, only the
  69     last-specified value takes effect.
  70     This option only exists for compatibility with the rackup(1) command,
  71     use of "-l"/"\--listen" switch is recommended instead.
  72
  73 -p, \--port PORT
  74 :   Listen on the specified TCP PORT, default is 8080.
  75     If specified multiple times on the command-line, only the last-specified
  76     value takes effect.
  77     This option only exists for compatibility with the rackup(1) command,
  78     use of "-l"/"\--listen" switch is recommended instead.
  79
  80 -s, \--server SERVER
  81 :   No-op, this exists only for compatibility with rackup(1).
  82
  83 # RUBY OPTIONS
  84 -e, \--eval LINE
  85 :   Evaluate a LINE of Ruby code.  This evaluation happens
  86     immediately as the command-line is being parsed.
  87
  88 -d, \--debug
  89 :   Turn on debug mode, the $DEBUG variable is set to true.
  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 # SIGNALS
 107
 108 The following UNIX signals may be sent to the master process:
 109
 110 * HUP - reload config file, app, and gracefully restart all workers
 111 * INT/TERM - quick shutdown, kills all workers immediately
 112 * QUIT - graceful shutdown, waits for workers to finish their
 113   current request before finishing.
 114 * USR1 - reopen all logs owned by the master and all workers
 115   See Unicorn::Util.reopen_logs for what is considered a log.
 116 * USR2 - reexecute the running binary.  A separate QUIT
 117   should be sent to the original process once the child is verified to
 118   be up and running.
 119 * WINCH - gracefully stops workers but keep the master running.
 120   This will only work for daemonized processes.
 121 * TTIN - increment the number of worker processes by one
 122 * TTOU - decrement the number of worker processes by one
 123
 124 See the [SIGNALS][4] document for full description of all signals
 125 used by Rainbows!.
 126
 127 #  RACK ENVIRONMENT
 128
 129 Accepted values of RACK_ENV and the middleware they automatically load
 130 (outside of RACKUP_FILE) are exactly as those in rackup(1):
 131
 132 * development - loads Rack::CommonLogger, Rack::ShowExceptions, and
 133                 Rack::Lint middleware
 134 * deployment  - loads Rack::CommonLogger middleware
 135 * none        - loads no middleware at all, relying
 136                 entirely on RACKUP_FILE
 137
 138 All unrecognized values for RACK_ENV are assumed to be
 139 "none".  Production deployments are strongly encouraged to use
 140 "deployment" or "none" for maximum performance.
 141
 142 Note that the Rack::ContentLength and Rack::Chunked middlewares
 143 are never loaded by default.  If needed, they should be
 144 individually specified in the RACKUP_FILE, some frameworks do
 145 not require them.
 146
 147 # SEE ALSO
 148
 149 * unicorn(1)
 150 * *Rack::Builder* ri/RDoc
 151 * *Unicorn::Configurator* ri/RDoc
 152 * [Rainbows! RDoc][1]
 153 * [Rack RDoc][2]
 154 * [Rackup HowTo][3]
 155
 156 [1]: http://rainbows.rubyforge.org/
 157 [2]: http://rack.rubyforge.org/doc/
 158 [3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
 159 [4]: http://rainbows.rubyforge.org/SIGNALS.html