about summary refs log tree commit homepage
path: root/Documentation/unicorn_rails.1
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/unicorn_rails.1')
-rw-r--r--Documentation/unicorn_rails.1207
1 files changed, 207 insertions, 0 deletions
diff --git a/Documentation/unicorn_rails.1 b/Documentation/unicorn_rails.1
new file mode 100644
index 0000000..71c80be
--- /dev/null
+++ b/Documentation/unicorn_rails.1
@@ -0,0 +1,207 @@
+.TH "UNICORN_RAILS" "1" "September 17, 2009" "Unicorn User Manual" ""
+.hy
+.SH NAME
+.PP
+unicorn_rails \- unicorn launcher for Rails 1.x and 2.x users
+.SH SYNOPSIS
+.PP
+unicorn_rails [\-c CONFIG_FILE] [\-E RAILS_ENV] [\-D] [RACKUP_FILE]
+.SH DESCRIPTION
+.PP
+A rackup(1)\-like command to launch ancient Rails (2.x and earlier)
+applications using Unicorn.  Rails 3 (and later) support Rack natively,
+so users are encouraged to use unicorn(1) instead of unicorn_rails(1).
+.PP
+It is expected to be started in your Rails application root (RAILS_ROOT),
+but the "working_directory" directive may be used in the CONFIG_FILE.
+.PP
+The outward interface resembles rackup(1), the internals and default
+middleware loading is designed like the \f[C]script/server\f[] command
+distributed with Rails.
+.PP
+While Unicorn takes a myriad of command\-line options for compatibility
+with ruby(1) and rackup(1), it is recommended to stick to the few
+command\-line options specified in the SYNOPSIS and use the CONFIG_FILE
+as much as possible.
+.SH UNICORN OPTIONS
+.TP
+.B \-c, \-\-config\-file CONFIG_FILE
+Path to the Unicorn\-specific config file.  The config file is
+implemented as a Ruby DSL, so Ruby code may executed.
+See the RDoc/ri for the \f[I]Unicorn::Configurator\f[] class for the full
+list of directives available from the DSL.
+Using an absolute path for for CONFIG_FILE is recommended as it
+makes multiple instances of Unicorn easily distinguishable when
+viewing ps(1) output.
+.RS
+.RE
+.TP
+.B \-D, \-\-daemonize
+Run daemonized in the background.  The process is detached from
+the controlling terminal and stdin is redirected to "/dev/null".
+Unlike many common UNIX daemons, we do not chdir to "/" upon
+daemonization to allow more control over the startup/upgrade
+process.
+Unless specified in the CONFIG_FILE, stderr and stdout will
+also be redirected to "/dev/null".
+Daemonization will \f[I]skip\f[] loading of the
+\f[I]Rails::Rack::LogTailer\f[]
+middleware under Rails >= 2.3.x.
+By default, unicorn_rails(1) will create a PID file in
+\f[I]"RAILS_ROOT/tmp/pids/unicorn.pid"\f[].  You may override this
+by specifying the "pid" directive to override this Unicorn config file.
+.RS
+.RE
+.TP
+.B \-E, \-\-env RAILS_ENV
+Run under the given RAILS_ENV.  This sets the RAILS_ENV environment
+variable.  Acceptable values are exactly those you expect in your Rails
+application, typically "development" or "production".
+.RS
+.RE
+.TP
+.B \-l, \-\-listen ADDRESS
+Listens on a given ADDRESS.  ADDRESS may be in the form of
+HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
+and PATH is meant to be a path to a UNIX domain socket.
+Defaults to "0.0.0.0:8080" (all addresses on TCP port 8080).
+For production deployments, specifying the "listen" directive in
+CONFIG_FILE is recommended as it allows fine\-tuning of socket
+options.
+.RS
+.RE
+.SH RACKUP COMPATIBILITY OPTIONS
+.TP
+.B \-o, \-\-host HOST
+Listen on a TCP socket belonging to HOST, default is
+"0.0.0.0" (all addresses).
+If specified multiple times on the command\-line, only the
+last\-specified value takes effect.
+This option only exists for compatibility with the rackup(1) command,
+use of "\-l"/"\-\-listen" switch is recommended instead.
+.RS
+.RE
+.TP
+.B \-p, \-\-port PORT
+Listen on the specified TCP PORT, default is 8080.
+If specified multiple times on the command\-line, only the last\-specified
+value takes effect.
+This option only exists for compatibility with the rackup(1) command,
+use of "\-l"/"\-\-listen" switch is recommended instead.
+.RS
+.RE
+.TP
+.B \-\-path PATH
+Mounts the Rails application at the given PATH (instead of "/").
+This is equivalent to setting the RAILS_RELATIVE_URL_ROOT
+environment variable.  This is only supported under Rails 2.3
+or later at the moment.
+.RS
+.RE
+.SH RUBY OPTIONS
+.TP
+.B \-e, \-\-eval LINE
+Evaluate a LINE of Ruby code.  This evaluation happens
+immediately as the command\-line is being parsed.
+.RS
+.RE
+.TP
+.B \-d, \-\-debug
+Turn on debug mode, the $DEBUG variable is set to true.
+For Rails >= 2.3.x, this loads the \f[I]Rails::Rack::Debugger\f[]
+middleware.
+.RS
+.RE
+.TP
+.B \-w, \-\-warn
+Turn on verbose warnings, the $VERBOSE variable is set to true.
+.RS
+.RE
+.TP
+.B \-I, \-\-include PATH
+specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
+The \[aq]:\[aq] character may be used to delimit multiple directories.
+This directive may be used more than once.  Modifications to
+$LOAD_PATH take place immediately and in the order they were
+specified on the command\-line.
+.RS
+.RE
+.TP
+.B \-r, \-\-require LIBRARY
+require a specified LIBRARY before executing the application.  The
+"require" statement will be executed immediately and in the order
+they were specified on the command\-line.
+.RS
+.RE
+.SH RACKUP FILE
+.PP
+This defaults to "config.ru" in RAILS_ROOT.  It should be the same
+file used by rackup(1) and other Rack launchers, it uses the
+\f[I]Rack::Builder\f[] DSL.  Unlike many other Rack applications, RACKUP_FILE
+is completely \f[I]optional\f[] for Rails, but may be used to disable
+some of the default middleware for performance.
+.PP
+Embedded command\-line options are mostly parsed for compatibility
+with rackup(1) but strongly discouraged.
+.SH ENVIRONMENT VARIABLES
+.PP
+The RAILS_ENV variable is set by the aforementioned \-E switch.  The
+RAILS_RELATIVE_URL_ROOT is set by the aforementioned \-\-path switch.
+Either of these variables may also be set in the shell or the Unicorn
+CONFIG_FILE.  All application or library\-specific environment variables
+(e.g. TMPDIR, RAILS_ASSET_ID) may always be set in the Unicorn
+CONFIG_FILE in addition to the spawning shell.  When transparently
+upgrading Unicorn, all environment variables set in the old master
+process are inherited by the new master process.  Unicorn only uses (and
+will overwrite) the UNICORN_FD environment variable internally when
+doing transparent upgrades.
+.SH SIGNALS
+.PP
+The following UNIX signals may be sent to the master process:
+.IP \[bu] 2
+HUP \- reload config file, app, and gracefully restart all workers
+.IP \[bu] 2
+INT/TERM \- quick shutdown, kills all workers immediately
+.IP \[bu] 2
+QUIT \- graceful shutdown, waits for workers to finish their current
+request before finishing.
+.IP \[bu] 2
+USR1 \- reopen all logs owned by the master and all workers
+See Unicorn::Util.reopen_logs for what is considered a log.
+.IP \[bu] 2
+USR2 \- reexecute the running binary.  A separate QUIT
+should be sent to the original process once the child is verified to
+be up and running.
+.IP \[bu] 2
+WINCH \- gracefully stops workers but keep the master running.
+This will only work for daemonized processes.
+.IP \[bu] 2
+TTIN \- increment the number of worker processes by one
+.IP \[bu] 2
+TTOU \- decrement the number of worker processes by one
+.PP
+See the SIGNALS (https://bogomips.org/unicorn/SIGNALS.html) document for
+full description of all signals used by Unicorn.
+.SH SEE ALSO
+.IP \[bu] 2
+unicorn(1)
+.IP \[bu] 2
+\f[I]Rack::Builder\f[] ri/RDoc
+.IP \[bu] 2
+\f[I]Unicorn::Configurator\f[] ri/RDoc
+.UR https://bogomips.org/unicorn/Unicorn/Configurator.html
+.UE
+.IP \[bu] 2
+unicorn RDoc
+.UR https://bogomips.org/unicorn/
+.UE
+.IP \[bu] 2
+Rack RDoc
+.UR https://www.rubydoc.info/github/rack/rack/
+.UE
+.IP \[bu] 2
+Rackup HowTo
+.UR https://github.com/rack/rack/wiki/(tutorial)-rackup-howto
+.UE
+.SH AUTHORS
+The Unicorn Community <unicorn-public@bogomips.org>.