diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/.gitignore | 5 | ||||
-rw-r--r-- | Documentation/GNUmakefile | 33 | ||||
-rw-r--r-- | Documentation/unicorn.1.txt | 159 |
3 files changed, 197 insertions, 0 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 0000000..46679d6 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1,5 @@ +*.1 +*.5 +*.7 +*.gz +*.html diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile new file mode 100644 index 0000000..bd64133 --- /dev/null +++ b/Documentation/GNUmakefile @@ -0,0 +1,33 @@ +all:: + +PANDOC = pandoc +PANDOC_OPTS = -s -f markdown --email-obfuscation=none --sanitize-html +pandoc = $(PANDOC) $(PANDOC_OPTS) +pandoc_html = $(pandoc) --toc -t html --no-wrap + +man1 := unicorn + +all:: html man +doc-gz: man-gz html-gz + +html: $(addsuffix .1.html,$(man1)) +man: $(addsuffix .1,$(man1)) +html-gz: $(addsuffix .1.html.gz,$(man1)) +man-gz: $(addsuffix .1.gz,$(man1)) + +%.1: %.1.txt + $(pandoc) -t man < $< > $@+ && mv $@+ $@ +%.1.html: %.1.txt + $(pandoc_html) -T $(basename $@) < $< > $@+ && mv $@+ $@ + +%.1.gz: %.1 + gzip --rsyncable < $< > $@+ && mv $@+ $@ + +%.1.html.gz: %.1.html + gzip --rsyncable < $< > $@+ && mv $@+ $@ + +clean:: + $(RM) $(addsuffix .1.html,$(man1)) + $(RM) $(addsuffix .1,$(man1)) + $(RM) $(addsuffix .1.html.gz,$(man1)) + $(RM) $(addsuffix .1.gz,$(man1)) diff --git a/Documentation/unicorn.1.txt b/Documentation/unicorn.1.txt new file mode 100644 index 0000000..a8fa3ac --- /dev/null +++ b/Documentation/unicorn.1.txt @@ -0,0 +1,159 @@ +% UNICORN(1) Unicorn User Manual +% The Unicorn Community <mongrel-unicorn@rubyforge.org> +% September 15, 2009 + +# NAME + +unicorn - a rackup-like command to launch the Unicorn HTTP server + +# SYNOPSIS + +unicorn [*-c CONFIG_FILE*] [*-E* *ENVIRONMENT*] [*-D*] [*RACKUP_FILE*] + +# DESCRIPTION + +A rackup(1)-like command to launch Rack applications using Unicorn. +It is expected to be started in your application root (APP_ROOT), but +"Dir.chdir" may also be executed in the *CONFIG_FILE* or *RACKUP_FILE*. + +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. + +# RACKUP FILE + +This defaults to \"config.ru\" in APP_ROOT. It should be the same +file used by rackup(1) and other Rack launchers, it uses the +*Rack::Builder* DSL. + +Embedded command-line options are mostly parsed for compatibility +with rackup(1) but strongly discouraged. + +# UNICORN OPTIONS +-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 (e.g. + "Dir.chdir", "Process::UID.change_privilege"). See the RDoc/ri + for the *Unicorn::Configurator* class for the full list of + directives available from the DSL. + +-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". + +-E, \--env *ENVIRONMENT* +: Run under the given *ENVIRONMENT*. Accepted values and the + middleware they automatically load (outside of *RACKUP_FILE*) + are exactly as those in rackup(1) and detailed below: + + * development - loads Rack::CommonLogger, + Rack::ShowExceptions, and + Rack::Lint middleware + * deployment - loads Rack::CommonLogger middleware + * none - loads no middleware at all, relying + entirely on RACKUP_FILE + + All unrecognized values for ENVIRONMENT are assumed to be + "none". Production deployments are strongly encouraged to use + "deployment" or "none" for maximum performance. + + Note that the Rack::ContentLength and Rack::Chunked middlewares + are never loaded by default. If needed, they should be + individually specified in the RACKUP_FILE, some frameworks do + not require them. + +-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. + +# RACKUP COMPATIBILITY OPTIONS +-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. + +-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. + +-P, \--pid FILE +: Store the Process ID of the Unicorn master process. + This option only exists for compatibility with the rackup(1) command, + use of the "pid" directive in *CONFIG_FILE* is recommended. + +-s, \--server *SERVER* +: No-op, this exists only for compatibility with rackup(1). + +# RUBY OPTIONS +-e, \--eval *LINE* +: Evaluate a *LINE* of Ruby code. This evaluation happens + immediately as the command-line is being parsed. + +-d, \--debug +: Turn on debug mode, the $DEBUG variable is set to true. + +-w, \--warn +: Turn on verbose warnings, the $VERBOSE variable is set to true. + +-I, \--include *PATH* +: specify $LOAD_PATH. *PATH* will be prepended to $LOAD_PATH. + The \':\' 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. + +-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. + +# SIGNALS + +The following UNIX signals may be sent to the master process: + +* HUP - reload config file, app, and gracefully restart all workers +* INT/TERM - quick shutdown, kills all workers immediately +* QUIT - graceful shutdown, waits for workers to finish their + current request before finishing. +* USR1 - reopen all logs owned by the master and all workers + See Unicorn::Util.reopen_logs for what is considered a log. +* 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. +* WINCH - gracefully stops workers but keep the master running. + This will only work for daemonized processes. +* TTIN - increment the number of worker processes by one +* TTOU - decrement the number of worker processes by one + +See the [SIGNALS][4] document for full description of all signals +used by Unicorn. + +# SEE ALSO + +* *Rack::Builder* ri/RDoc +* *Unicorn::Configurator* ri/RDoc +* [Unicorn RDoc][1] +* [Rack RDoc][2] +* [Rackup HowTo][3] + +[1]: http://unicorn.bogomips.org/ +[2]: http://rack.rubyforge.org/doc/ +[3]: http://wiki.github.com/rack/rack/tutorial-rackup-howto +[4]: http://unicorn.bogomips.org/SIGNALS.html |