Documentation/zbatery.1.txt

   1 % zbatery(1) Zbatery User Manual
   2 % Zbatery hackers <rainbows-talk@rubyforge.org>
   3 % December 9, 2009
   4
   5 # NAME
   6
   7 zbatery - rackup-like command to launch Zbatery
   8
   9 # SYNOPSIS
  10
  11 zbatery [-c CONFIG_FILE] [-E RACK_ENV] [-D] [RACKUP_FILE]
  12
  13 # DESCRIPTION
  14
  15 A rackup(1)-like command to launch Rack applications using Zbatery.
  16 It is expected to be started in your application root (APP_ROOT),
  17 but the "working_directory" directive may be used in the CONFIG_FILE.
  18
  19 While Zbatery takes a myriad of command-line options for
  20 compatibility with ruby(1) and rackup(1), it is recommended to stick
  21 to the few command-line options specified in the SYNOPSIS and use
  22 the CONFIG_FILE as much as possible.
  23
  24 # RACKUP FILE
  25
  26 This defaults to \"config.ru\" in APP_ROOT.  It should be the same
  27 file used by rackup(1) and other Rack launchers, it uses the
  28 *Rack::Builder* DSL.
  29
  30 Embedded command-line options are mostly parsed for compatibility
  31 with rackup(1) but strongly discouraged.
  32
  33 # UNICORN OPTIONS
  34 -c, \--config-file CONFIG_FILE
  35 :   Path to the Unicorn-specific config file.  The config file is
  36     implemented as a Ruby DSL, so Ruby code may executed.
  37     See the RDoc/ri for the *Unicorn::Configurator* class for the full
  38     list of directives available from the DSL.
  39
  40 -D, \--daemonize
  41 :   Run daemonized in the background.  The process is detached from
  42     the controlling terminal and stdin is redirected to "/dev/null".
  43     Unlike many common UNIX daemons, we do not chdir to \"/\"
  44     upon daemonization to allow more control over the startup/upgrade
  45     process.
  46     Unless specified in the CONFIG_FILE, stderr and stdout will
  47     also be redirected to "/dev/null".
  48
  49 -E, \--env RACK_ENV
  50 :   Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
  51     for more details.
  52
  53 -l, \--listen ADDRESS
  54 :   Listens on a given ADDRESS.  ADDRESS may be in the form of
  55     HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
  56     and PATH is meant to be a path to a UNIX domain socket.
  57     Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080)
  58     For production deployments, specifying the "listen" directive in
  59     CONFIG_FILE is recommended as it allows fine-tuning of socket
  60     options.
  61
  62 # RACKUP COMPATIBILITY OPTIONS
  63 -o, \--host HOST
  64 :   Listen on a TCP socket belonging to HOST, default is
  65     "0.0.0.0" (all addresses).
  66     If specified multiple times on the command-line, only the
  67     last-specified value takes effect.
  68     This option only exists for compatibility with the rackup(1) command,
  69     use of "-l"/"\--listen" switch is recommended instead.
  70
  71 -p, \--port PORT
  72 :   Listen on the specified TCP PORT, default is 8080.
  73     If specified multiple times on the command-line, only the last-specified
  74     value takes effect.
  75     This option only exists for compatibility with the rackup(1) command,
  76     use of "-l"/"\--listen" switch is recommended instead.
  77
  78 -s, \--server SERVER
  79 :   No-op, this exists only for compatibility with rackup(1).
  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
  89 -w, \--warn
  90 :   Turn on verbose warnings, the $VERBOSE variable is set to true.
  91
  92 -I, \--include PATH
  93 :   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
  94     The \':\' character may be used to delimit multiple directories.
  95     This directive may be used more than once.  Modifications to
  96     $LOAD_PATH take place immediately and in the order they were
  97     specified on the command-line.
  98
  99 -r, \--require LIBRARY
 100 :   require a specified LIBRARY before executing the application.  The
 101     \"require\" statement will be executed immediately and in the order
 102     they were specified on the command-line.
 103
 104 # SIGNALS
 105
 106 The following UNIX signals may be sent to Zbatery
 107 (only supported on UNIX):
 108
 109 * HUP - reexecute the binary and exit the current one
 110 * INT/TERM - quick shutdown, quit immediately
 111 * QUIT - graceful shutdown, waits for current requests before exiting
 112 * USR1 - reopen all logs owned by the master and all workers
 113   See Unicorn::Util.reopen_logs for what is considered a log.
 114 * USR2 - reexecute the running binary.  A separate QUIT
 115   should be sent to the original process once the child is verified to
 116   be up and running.
 117
 118 #  RACK ENVIRONMENT
 119
 120 Accepted values of RACK_ENV and the middleware they automatically load
 121 (outside of RACKUP_FILE) are exactly as those in rackup(1):
 122
 123 * development - loads Rack::CommonLogger, Rack::ShowExceptions, and
 124                 Rack::Lint middleware
 125 * deployment  - loads Rack::CommonLogger middleware
 126 * none        - loads no middleware at all, relying
 127                 entirely on RACKUP_FILE
 128
 129 All unrecognized values for RACK_ENV are assumed to be
 130 "none".  Production deployments are strongly encouraged to use
 131 "deployment" or "none" for maximum performance.
 132
 133 Note that the Rack::ContentLength and Rack::Chunked middlewares
 134 are never loaded by default.  If needed, they should be
 135 individually specified in the RACKUP_FILE, some frameworks do
 136 not require them.
 137
 138 # SEE ALSO
 139
 140 * unicorn(1)
 141 * rainbows(1)
 142 * *Rack::Builder* ri/RDoc
 143 * *Unicorn::Configurator* ri/RDoc
 144 * [Zbatery RDoc][1]
 145 * [Rack RDoc][2]
 146 * [Rackup HowTo][3]
 147 * [Rainbows! RDoc][4]
 148
 149 [1]: http://zbatery.bogomip.org/
 150 [2]: http://rack.rubyforge.org/doc/
 151 [3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto
 152 [4]: http://rainbows.rubyforge.org/