jingrow/gunicorn
1
0
Fork 0
mirror of https://github.com/frappe/gunicorn.git synced 2026-01-14 11:09:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

Some edits to the new docs.

Browse Source
This commit is contained in:
Paul J. Davis 2010-03-26 14:50:00 -04:00
parent 8d52e1e77f
commit 4dbde5c2ef
13 changed files with 323 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.rst
View File

@ -1,9 +1,12 @@
About
-----
gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX handle fast clients **and** sleepy application.
gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX handle fast clients
**and** sleepy application.
This is a port of Unicorn (http://unicorn.bogomips.org/) in Python. Meet us on `#gunicorn irc channel <http://webchat.freenode.net/?channels=gunicorn>`_ on `Freenode`_.
This is a port of Unicorn (http://unicorn.bogomips.org/) in Python. Meet us
on `#gunicorn irc channel <http://webchat.freenode.net/?channels=gunicorn>`_
on `Freenode`_.
Installation
------------
@ -18,13 +21,21 @@ Or from Pypi::
$ easy_install -U gunicorn
If you want to handle `sleepy application <http://gunicorn.org/faq.html>`_ you will need to install `Eventlet`_ or `Gevent`_.
If you want to handle `sleepy applications <http://gunicorn.org/faq.html>`_
you will need to install `Eventlet`_ or `Gevent`_.
To install eventlet::
$ easy_install -U eventlet
Replace `eventlet` by **gevent** if you want to use `gevent`. You can now launch gunicorn with Eventlet or Gevent arbiter, see `Gunicorn usage <http://gunicorn.org/usage.html>`_ for more information.
Replace `eventlet` by **gevent** if you want to use `gevent`. You can now
launch gunicorn with Eventlet or Gevent arbiter, see `Gunicorn usage
<http://gunicorn.org/usage.html>`_ for more information.
If you encounter errors when compiling the extensions for `gevent` or
`eventlet` you probably need to install a newer version of libev_.
.. _libev: http://software.schmorp.de/pkg/libev.html
Usage
-----
@ -42,8 +53,8 @@ Usage
-w WORKERS, --workers=WORKERS
Number of workers to spawn. [1]
-a ARBITER, --arbiter=ARBITER
gunicorn arbiter entry point or module
[egg:gunicorn#main]
gunicorn arbiter entry point or module
[egg:gunicorn#main]
-p PIDFILE, --pid=PIDFILE
set the background PID FILE
-D, --daemon Run daemonized in the background.
@ -53,7 +64,7 @@ Usage
-g GROUP, --group=GROUP
Change worker group
-n APP_NAME, --name=APP_NAME
Application name
Application name
--log-level=LOGLEVEL Log level below which to silence messages. [info]
--log-file=LOGFILE Log to a file. - equals stdout. [-]
-d, --debug Debug mode. only 1 worker.
@ -61,7 +72,6 @@ Usage
-h, --help show this help message and exit
Example with test app::
$ cd examples

76
doc/htdocs/configuration.html
View File

@ -49,29 +49,29 @@
<div class="document" id="the-configuration-file">
<h1 class="title">The Configuration File</h1>
<p>Gunciorn 0.5 introduced the ability to use a Python configuration file. Gunicorn will look for <tt class="docutils literal">gunicorn.conf.py</tt> in the current working directory or what ever path is specified on the command line with the <tt class="docutils literal"><span class="pre">-c</span></tt> option.</p>
<p>Gunciorn 0.5 introduced the ability to use a Python configuration file. Gunicorn will look for <tt class="docutils literal"><span class="pre">gunicorn.conf.py</span></tt> in the current working directory or what ever path is specified on the command line with the <tt class="docutils literal"><span class="pre">-c</span></tt> option.</p>
<div class="section" id="example-gunicorn-conf-py">
<h1>Example gunicorn.conf.py</h1>
<pre class="literal-block">
arbiter = &quot;egg:gunicorn&quot; # Or &quot;egg:gunicorn#eventlet&quot; (eventlet or gevent)
backlog = 2048
bind = &quot;127.0.0.1:8000&quot; # Or &quot;unix:/tmp/gunicorn.sock&quot;
daemon = False # Whether work in the background
debug = False # Some extra logging
keepalive = 2 # Time we wait for next connection (in ms)
logfile = &quot;-&quot; # Name of the log file
loglevel = &quot;info&quot; # The level at which to log
pidfile = None # Path to a PID file
workers = 1 # Number of workers to initialize
umask = 0 # Umask to set when daemonizing
user = None # Change process owner to user
group = None # Change process group to group
proc_name = None # Change the process name
tmp_upload_dir = None # Set path used to store temporary uploads
worker_connections=1000 # Number of connections accepted by a worker
arbiter = &quot;egg:gunicorn&quot; # The arbiter to use for worker management
backlog = 2048 # The listen queue size for the server socket
bind = &quot;127.0.0.1:8000&quot; # Or &quot;unix:/tmp/gunicorn.sock&quot;
daemon = False # Whether work in the background
debug = False # Some extra logging
keepalive = 2 # Time we wait for next connection (in seconds)
logfile = &quot;-&quot; # Name of the log file
loglevel = &quot;info&quot; # The level at which to log
pidfile = None # Path to a PID file
workers = 1 # Number of workers to initialize
umask = 0 # Umask to set when daemonizing
user = None # Change process owner to user
group = None # Change process group to group
proc_name = None # Change the process name
tmp_upload_dir = None # Set path used to store temporary uploads
worker_connections=1000 # Maximum number of simultaneous connections
after_fork=lambda server, worker: server.log.info(
&quot;Worker spawned (pid: %s)&quot; % worker.pid),
&quot;Worker spawned (pid: %s)&quot; % worker.pid)
before_fork=lambda server, worker: True
@ -84,37 +84,57 @@ before_exec=lambda server: server.log.info(&quot;Forked child, reexecuting&quot;
<dt>after_fork(server, worker):</dt>
<dd>This is called by the worker after initialization.</dd>
<dt>arbiter:</dt>
<dd>The arbiter you want to use. An arbiter maintain the workers processes alive. It launches or kills them if needed. It also manages application reloading via SIGHUP/USR2. By default it's <cite>egg:gunicorn#main</cite>. This arbiter only support fast clients connections. If you need to create a sleepy application or handling keepalive set it to <cite>egg:gunicorn#eventlet</cite> to use it with <a class="reference external" href="http://eventlet.net">Eventlet</a> or <cite>egg:gunicorn#gevent</cite> with <a class="reference external" href="http://gevent.org">Gevent</a>. Eventlet arbiter can also be used with <a class="reference external" href="http://twistedmatrix.com">Twisted</a> by using its <a class="reference external" href="http://bitbucket.org/which_linden/eventlet/src/tip/README.twisted">helper</a>.</dd>
<dd><p class="first">The arbiter manages the worker processes that actually serve clients. It
handles launching new workers and killing misbehaving workers among
other things. By default the arbiter is <cite>egg:gunicorn#main</cite>. This arbiter
only supports fast request handling requiring a buffering HTTP proxy.</p>
<p class="last">If your application requires the ability to handle prolonged requests to
provide long polling, comet, or calling an external web service you'll
need to use an async arbiter. Gunicorn has two async arbiters built in
using <a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a>. You can also use the Evenlet arbiter with
the <a class="reference external" href="http://twistedmatrix.com">Twisted</a> helper.</p>
</dd>
<dt>backlog:</dt>
<dd>The backlog parameter defines the maximum length for the queue of pending connections see listen(2) for more information. The default is 2048.</dd>
<dd>The backlog parameter defines the maximum length for the queue of pending
connections. The default is 2048. See listen(2) for more information</dd>
<dt>before_fork(server, worker):</dt>
<dd>This is called by the worker just before forking.</dd>
<dt>before_exec(server):</dt>
<dd>This function is called before relaunching the master. This happens when the master receives a HUP or USR2 signal.</dd>
<dd>This function is called before relaunching the master. This happens when
the master receives a HUP or USR2 signal.</dd>
<dt>bind:</dt>
<dd>The address on which workers are listening. It can be a TCP address with a format of <tt class="docutils literal">IP:PORT</tt> or a Unix socket address like <tt class="docutils literal"><span class="pre">unix:/path/to/socketfile</span></tt>.</dd>
<dd>The address on which workers are listening. It can be a TCP address with a
format of <tt class="docutils literal"><span class="pre">IP:PORT</span></tt> or a Unix socket address like
<tt class="docutils literal"><span class="pre">unix:/path/to/socketfile</span></tt>.</dd>
<dt>daemon:</dt>
<dd>Whether or not to detach the server from the controlling terminal.</dd>
<dt>debug:</dt>
<dd>If <tt class="docutils literal">True</tt>, only one worker will be launch and the variable <tt class="docutils literal">wsgi.multiprocess</tt> will be set to False.</dd>
<dd>If <tt class="docutils literal"><span class="pre">True</span></tt>, only one worker will be launch and the variable
<tt class="docutils literal"><span class="pre">wsgi.multiprocess</span></tt> will be set to False.</dd>
<dt>group:</dt>
<dd>The group in which worker processes will be launched.</dd>
<dt>keepalive:</dt>
<dd>Keepalive timeout. The default is 2 seconds, which should be enough under most conditions for browsers to render the page and start retrieving extra elements for. Increasing this beyond 5 seconds is not recommended. Zero disables keepalive entirely.</dd>
<dd>KeepAlive timeout. The default is 2 seconds, which should be enough under
most conditions for browsers to render the page and start retrieving extra
elements for. Increasing this beyond 5 seconds is not recommended. Zero
disables KeepAlive entirely.</dd>
<dt>logfile:</dt>
<dd>The path to the log file <tt class="docutils literal">-</tt> (stdout) by default.</dd>
<dd>The path to the log file <tt class="docutils literal"><span class="pre">-</span></tt> (stdout) by default.</dd>
<dt>loglevel:</dt>
<dd>The level at which to log. <tt class="docutils literal">info</tt>, <tt class="docutils literal">debug</tt>, or <tt class="docutils literal">error</tt> for instance. Only log messages of equal or greater severity are logged.</dd>
<dd>The level at which to log. <tt class="docutils literal"><span class="pre">info</span></tt>, <tt class="docutils literal"><span class="pre">debug</span></tt>, or <tt class="docutils literal"><span class="pre">error</span></tt> for instance.
Only log messages of equal or greater severity are logged.</dd>
<dt>pidfile:</dt>
<dd>A file to store the master's PID.</dd>
<dt>proc_name:</dt>
<dd>If <a class="reference external" href="http://pypi.python.org/pypi/setproctitle">setproctitle</a> is installed, it allows you to set the process name for this Gunicorn instance.</dd>
<dd>A name for the master process. Only takes effect if <a class="reference external" href="http://pypi.python.org/pypi/setproctitle">setproctitle</a> is
installed. This alters the process names listed by commands like <tt class="docutils literal"><span class="pre">ps</span></tt>.</dd>
<dt>umask:</dt>
<dd>Used to set the umask when daemonizing.</dd>
<dt>user:</dt>
<dd>The user as which worker processes will by launched.</dd>
<dt>worker_connections:</dt>
<dd>Number of connections a worker can handle when used with Eventlet or Gevent arbiter. The default is 1000.</dd>
<dd>Number of simultaneous connections a worker can handle when used with
Eventlet or Gevent arbiter. The default is 1000.</dd>
<dt>tmp_upload_dir:</dt>
<dd>Set the path used to store temporarily the body of the request.</dd>
</dl>

38
doc/htdocs/deployment.html
View File

@ -49,10 +49,38 @@
<div class="document" id="production-setup">
<h1 class="title">Production Setup</h1>
<p>Although there are many HTTP proxies available, we strongly advise that you use <a class="reference external" href="http://www.nginx.org">Nginx</a>. If you choose another proxy server you need to make sure that it buffers slow clients when you use default Gunicorn arbiter. Without this buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.</p>
<p>There are two general classes of configuration for Gunicorn. For the time
being these will are referred to as &quot;fast clients&quot; and &quot;sleepy applications&quot;.</p>
<div class="section" id="fast-clients">
<h1>Fast Clients</h1>
<p>Generally speaking when we say &quot;fast clients&quot; what we really mean is that the
time taken to process a client from the time a socket is accepted until
the time the socket is closed is well defined to be short. This means that
clients are buffered by an upstream proxy (otherwise clients can send or
receive data slowly) and that your application code does not have major
blocking sections (a web request to the internet might occasionally take a
non trivial amount of time).</p>
<p>Traditional webapps are generally fine for fast client configurations.
Deployments should generally default to this type of configuration unless it is
known that the application code wants to do long-polling, comet, web sockets or
has other potentially long operations (on the order of seconds).</p>
</div>
<div class="section" id="sleepy-applications">
<h1>Sleepy Applications</h1>
<p>Any application that requires an undefined amount of time for client processing
is considered a sleepy application. If you are wanting a platform that is
capable of handling comet connections, long polling, or potentially long
blocking operations (requests to external web services, ie Facebook Connect)
then you'll want to use an async arbiter.</p>
</div>
<div class="section" id="nginx-config-for-fast-clients-handling">
<h1>Nginx Config for fast clients handling</h1>
<p>An <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf">example configuration</a> file for use with <a class="reference external" href="http://www.nginx.org">Nginx</a>:</p>
<p>Although there are many HTTP proxies available, we strongly advise that you
use <a class="reference external" href="http://www.nginx.org">Nginx</a>. If you choose another proxy server you need to make sure that it
buffers slow clients when you use default Gunicorn arbiter. Without this
buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
You can use <a class="reference external" href="http://ha.ckers.org/slowloris/">slowloris</a> to check if your proxy is behaving properly.</p>
<p>An <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf">example configuration</a> file for fast clients with <a class="reference external" href="http://www.nginx.org">Nginx</a>:</p>
<pre class="literal-block">
worker_processes 1;
@ -105,7 +133,8 @@ http {
}
}
</pre>
<p>To handle sleepy applications, just add the line <cite>proxy_buffering off;</cite> under the proxy_redirect directive:</p>
<p>To handle sleepy applications, just add the line <cite>proxy_buffering off;</cite> under
the proxy_redirect directive:</p>
<pre class="literal-block">
...
location / {
@ -124,7 +153,8 @@ location / {
</div>
<div class="section" id="daemon-monitoring">
<h1>Daemon Monitoring</h1>
<p>A popular method for deploying Gunicorn is to have it monitored by <a class="reference external" href="http://smarden.org/runit/">runit</a>. An <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc">example service</a> definition:</p>
<p>A popular method for deploying Gunicorn is to have it monitored by <a class="reference external" href="http://smarden.org/runit/">runit</a>.
An <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc">example service</a> definition:</p>
<pre class="literal-block">
#!/bin sh

17
doc/htdocs/faq.html
View File

@ -50,18 +50,19 @@
<div class="document" id="faq">
<h1 class="title">FAQ</h1>
<dl class="docutils">
<dt>What is a slow client?</dt>
<dd>A slow client is defined as a request that can take an arbitrary amount of
time to send or read a request. Sometimes due to network performance or
because it is a malicious client attempting to cause problems. Check out
the <a class="reference external" href="http://ha.ckers.org/slowloris/">slowloris</a> script to generate slow client traffic.</dd>
<dt>What is a fast client?</dt>
<dd>Generally speaking a fast client is something that is being served over the
local network or from the same machine. This generally would refer to requests
forwarded from an upstream proxy. Also see the above FAQ for what a fast
client is not.</dd>
<dt>What is a slow client?</dt>
<dd>A slow client is defined as a request that can take an arbitrary amount of
time to send a request or read a response. Sometimes due to network
performance or because it is a malicious client attempting to cause problems.
Check out the <a class="reference external" href="http://ha.ckers.org/slowloris/">slowloris</a> script to generate slow client traffic.</dd>
<dt>What are sleepy applications?</dt>
<dd>Applications that expect long request/response times and/or slow clients. Gunicorn use <a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a> to manage concurrency.</dd>
<dd>Applications that expect long request/response times and/or slow clients.
Gunicorn use <a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a> to manage concurrency.</dd>
<dt>How might I test a proxy configuration?</dt>
<dd>Check out <a class="reference external" href="http://ha.ckers.org/slowloris/">slowloris</a> for a script that will generate significant slow
traffic. If your application remains responsive through out that test you
@ -83,8 +84,8 @@ $ kill -TTOU $masterpid
</pre>
</dd>
<dt>How do I set SCRIPT_NAME?</dt>
<dd>By default <tt class="docutils literal">SCRIPT_NAME</tt> is an empy string. The value could be set by
setting <tt class="docutils literal">SCRIPT_NAME</tt> in the environment or as an HTTP header.</dd>
<dd>By default <tt class="docutils literal"><span class="pre">SCRIPT_NAME</span></tt> is an empy string. The value could be set by
setting <tt class="docutils literal"><span class="pre">SCRIPT_NAME</span></tt> in the environment or as an HTTP header.</dd>
<dt>How to name processes?</dt>
<dd>You need to install the Python package <a class="reference external" href="http://pypi.python.org/pypi/setproctitle">setproctitle</a>. Then you can name
your process with <cite>-n</cite> or just let the default. If you use a configuration

19
doc/htdocs/index.html
View File

@ -47,22 +47,25 @@
<div class="document" id="green-unicorn">
<h1 class="title">Green Unicorn</h1>
<p>Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve <a class="reference external" href="faq.html">fast clients</a> or <a class="reference external" href="faq.html">sleepy applications</a>.</p>
<p>This is a port of <a class="reference external" href="http://unicorn.bogomips.org/">Unicorn</a> in Python. Meet us on the <a class="reference external" href="http://webchat.freenode.net/?channels=gunicorn">#gunicorn IRC channel</a> on <a class="reference external" href="http://freenode.net">Freenode</a>.</p>
<p>Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve
<a class="reference external" href="faq.html">fast clients</a> or <a class="reference external" href="faq.html">sleepy applications</a>.</p>
<p>This is a port of <a class="reference external" href="http://unicorn.bogomips.org/">Unicorn</a> in Python. Meet us on the <a class="reference external" href="http://webchat.freenode.net/?channels=gunicorn">#gunicorn IRC channel</a>
on <a class="reference external" href="http://freenode.net">Freenode</a>.</p>
<p>Gunicorn is released under the MIT License. See the <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/LICENSE">LICENSE</a> for more details.</p>
<div class="section" id="features">
<h1>Features</h1>
<ul class="simple">
<li>Designed for Unix, <a class="reference external" href="http://www.python.org/dev/peps/pep-0333/">WSGI</a>, fast clients and sleepy applications.</li>
<li>Compatible with Python 2.x (&gt;= 2.5)</li>
<li>Easy integration with <a class="reference external" href="http://djangoproject.com">Django</a> and <a class="reference external" href="http://pythonpaste.org/">Paster</a> compatible applications (<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...)</li>
<li>Easy integration with <a class="reference external" href="http://djangoproject.com">Django</a> and <a class="reference external" href="http://pythonpaste.org/">Paster</a> compatible applications
(<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...)</li>
<li>Process management: <a class="reference external" href="http://gunicorn.org">Gunicorn</a> reaps and restarts workers that die.</li>
<li>Load balancing via pre-fork and a shared socket</li>
<li>Graceful worker process restarts</li>
<li>Upgrade &quot;àla nginx&quot; without losing connections</li>
<li>Simple and easy Python configuration</li>
<li>Decode chunked transfers on-the-fly, allowing upload progress notifications or
stream-based protocols over HTTP</li>
<li>Decode chunked transfers on-the-fly, allowing upload progress notifications
or stream-based protocols over HTTP</li>
<li>Support for <a class="reference external" href="http://eventlet.net">Eventlet</a> and <a class="reference external" href="http://gevent.org">Gevent</a> .</li>
<li>Post- and pre-fork hooks</li>
</ul>
@ -70,12 +73,12 @@ stream-based protocols over HTTP</li>
<div class="section" id="applications">
<h1>Applications</h1>
<ul class="simple">
<li>Any <a class="reference external" href="http://www.python.org/dev/peps/pep-0333/">WSGI</a>, <a class="reference external" href="http://djangoproject.com">Django</a> and <a class="reference external" href="http://pythonpaste.org/">Paster</a> compatible applications (<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...)</li>
<li>Websockets (see <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py">example</a>)</li>
<li>Any <a class="reference external" href="http://www.python.org/dev/peps/pep-0333/">WSGI</a>, <a class="reference external" href="http://djangoproject.com">Django</a> and <a class="reference external" href="http://pythonpaste.org/">Paster</a> compatible applications
(<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...)</li>
<li>Websockets (see the <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py">example</a>)</li>
<li>Reverse proxy implementation (with <a class="reference external" href="http://benoitc.github.com/restkit/wsgi_proxy.html">Restkit WSGI proxy</a>)</li>
<li>Comet</li>
<li>Long Polling</li>
<li>...</li>
</ul>
</div>
</div>

37
doc/htdocs/installation.html
View File

@ -59,7 +59,8 @@
</div>
<div class="section" id="installing-with-easy-install">
<h1>Installing with easy_install</h1>
<p>If you don't already have <tt class="docutils literal">easy_install</tt> available you'll want to download and run the <tt class="docutils literal">ez_setup.py</tt> script:</p>
<p>If you don't already have <tt class="docutils literal"><span class="pre">easy_install</span></tt> available you'll want to download
and run the <tt class="docutils literal"><span class="pre">ez_setup.py</span></tt> script:</p>
<pre class="literal-block">
$ curl -O http://peak.telecommunity.com/dist/ez_setup.py
$ sudo python ez_setup.py -U setuptools
@ -71,10 +72,13 @@ $ sudo easy_install -U gunicorn
</div>
<div class="section" id="installing-from-source">
<h1>Installing from source</h1>
<p>You can install Gunicorn from source as simply as you would install any other Python package. Gunicorn uses setuptools which will automatically fetch all dependencies (including setuptools itself).</p>
<p>You can install Gunicorn from source as simply as you would install any other
Python package. Gunicorn uses setuptools which will automatically fetch all
dependencies (including setuptools itself).</p>
<div class="section" id="get-a-copy">
<h2>Get a Copy</h2>
<p>You can download a tarball of the latest sources from <a class="reference external" href="http://github.com/benoitc/gunicorn/downloads">GitHub Downloads</a> or fetch them with <a class="reference external" href="http://git-scm.com/">git</a>:</p>
<p>You can download a tarball of the latest sources from <a class="reference external" href="http://github.com/benoitc/gunicorn/downloads">GitHub Downloads</a> or
fetch them with <a class="reference external" href="http://git-scm.com/">git</a>:</p>
<pre class="literal-block">
$ git clone git://github.com/benoitc/gunicorn.git
</pre>
@ -84,7 +88,10 @@ $ git clone git://github.com/benoitc/gunicorn.git
<pre class="literal-block">
$ python setup.py install
</pre>
<p>If you've cloned the git repository, its highly recommended that you use the <tt class="docutils literal">develop</tt> command which will allow you to use Gunicorn from the source directory. This will allow you to keep up to date with development on GitHub as well as make changes to the source:</p>
<p>If you've cloned the git repository, its highly recommended that you use the
<tt class="docutils literal"><span class="pre">develop</span></tt> command which will allow you to use Gunicorn from the source
directory. This will allow you to keep up to date with development on GitHub as
well as make changes to the source:</p>
<pre class="literal-block">
$ python setup.py develop
</pre>
@ -92,18 +99,30 @@ $ python setup.py develop
</div>
<div class="section" id="installation-requirements-for-sleepy-application-handling">
<h1>Installation requirements for sleepy application handling</h1>
<p>If you want to handle <a class="reference external" href="faq.html">sleepy application</a> you will need to install <a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a>.</p>
<p>If you want to handle <a class="reference external" href="faq.html">sleepy application</a> you will need to install
<a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a>.</p>
<p>To install eventlet:</p>
<pre class="literal-block">
$ easy_install -U eventlet
</pre>
<p>Replace <cite>eventlet</cite> by <strong>gevent</strong> if you want to use <cite>gevent</cite>.</p>
<p>You can now launch gunicorn with Eventlet or Gevent arbiter, see <a class="reference external" href="usage.html">usage</a> for more information.</p>
<p>Replace <tt class="docutils literal"><span class="pre">eventlet</span></tt> with <tt class="docutils literal"><span class="pre">gevent</span></tt> if you want to use the <tt class="docutils literal"><span class="pre">gevent</span></tt>
arbiter.</p>
<p>You can now launch gunicorn with Eventlet or Gevent arbiter, see
<a class="reference external" href="usage.html">usage</a> for more information.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">If <tt class="docutils literal"><span class="pre">eventlet</span></tt> or <tt class="docutils literal"><span class="pre">gevent</span></tt> fails to install for you, its most likely
due to an out of date <a class="reference external" href="http://software.schmorp.de/pkg/libev.html">libev</a> library. You'll need to download and install
a newer version for either of those to modules to work properly.</p>
</div>
</div>
<div class="section" id="installing-on-ubuntu-debian-systems">
<h1>Installing on Ubuntu/Debian systems</h1>
<p>If you use <a class="reference external" href="http://www.ubuntu.com/">ubuntu</a> karmic, you can update your system with packages from our <a class="reference external" href="https://launchpad.net/~bchesneau/+archive/gunicorn">PPA</a> by adding ppa:bchesneau/gunicorn to your system's Software Sources.</p>
<p>Or this PPA can be added to your system manually by copying the lines below and adding them to your system's software sources:</p>
<p>If you use <a class="reference external" href="http://www.ubuntu.com/">Ubuntu</a> karmic, you can update your
system with packages from our <a class="reference external" href="https://launchpad.net/~bchesneau/+archive/gunicorn">PPA</a> by adding <tt class="docutils literal"><span class="pre">ppa:bchesneau/gunicorn</span></tt>
to your system's Software Sources.</p>
<p>Or this PPA can be added to your system manually by copying the lines below
and adding them to your system's software sources:</p>
<pre class="literal-block">
deb http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
deb-src http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main

27
doc/htdocs/usage.html
View File

@ -61,17 +61,19 @@
$ cd /path/to/gunicorn/examples/
$ gunicorn --workers=2 test:app
</pre>
<p>The module <tt class="docutils literal">test:app</tt> specifies the complete module name and WSGI callable. You can replace it with anything that is available on your <tt class="docutils literal">PYTHONPATH</tt> like such:</p>
<p>The module <tt class="docutils literal"><span class="pre">test:app</span></tt> specifies the complete module name and WSGI callable.
You can replace it with anything that is available on your <tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt> like
such:</p>
<pre class="literal-block">
$ cd ~/
$ gunicorn --workers=12 awesomeproject.wsgi.main:main_app
</pre>
<p>To launch the <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py">websocket example application</a> using <a class="reference external" href="http://eventlet.net">Eventlet</a>:</p>
<p>To launch the <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py">websocket example</a> application using <a class="reference external" href="http://eventlet.net">Eventlet</a>:</p>
<pre class="literal-block">
$ cd /path/to/gunicorn/examples/
$ gunicorn -w 12 -a &quot;egg:gunicorn#eventlet&quot; websocket:app
</pre>
<p>and then go on <cite>http://localhost:8000</cite> to see the result.</p>
<p>You should then be able to visit <tt class="docutils literal"><span class="pre">http://localhost:8000</span></tt> to see output.</p>
<div class="section" id="full-command-line-usage">
<h2>Full command line usage</h2>
<pre class="literal-block">
@ -86,8 +88,8 @@ Options:
-w WORKERS, --workers=WORKERS
Number of workers to spawn. [1]
-a ARBITER, --arbiter=ARBITER
gunicorn arbiter entry point or module
[egg:gunicorn#main]
gunicorn arbiter entry point or module
[egg:gunicorn#main]
-p PIDFILE, --pid=PIDFILE
set the background PID FILE
-D, --daemon Run daemonized in the background.
@ -97,7 +99,7 @@ Options:
-g GROUP, --group=GROUP
Change worker group
-n APP_NAME, --name=APP_NAME
Application name
Application name
--log-level=LOGLEVEL Log level below which to silence messages. [info]
--log-file=LOGFILE Log to a file. - equals stdout. [-]
-d, --debug Debug mode. only 1 worker.
@ -108,13 +110,15 @@ Options:
</div>
<div class="section" id="django-projects">
<h1>Django Projects</h1>
<p><a class="reference external" href="http://djangoproject.com">Django</a> projects can be handled easily by Gunicorn using the <tt class="docutils literal">gunicorn_django</tt> command:</p>
<p><a class="reference external" href="http://djangoproject.com">Django</a> projects can be handled easily by Gunicorn using the
<tt class="docutils literal"><span class="pre">gunicorn_django</span></tt> command:</p>
<pre class="literal-block">
$ cd $yourdjangoproject
$ gunicorn_django --workers=2
</pre>
<p>But you can also use the <tt class="docutils literal">run_gunicorn</tt> <a class="reference external" href="http://docs.djangoproject.com/en/dev/howto/custom-management-commands/">admin command</a> like the other <tt class="docutils literal">management.py</tt> commands.</p>
<p>Add <tt class="docutils literal">&quot;gunicorn&quot;</tt> to INSTALLED_APPS in your settings file:</p>
<p>But you can also use the <tt class="docutils literal"><span class="pre">run_gunicorn</span></tt> <a class="reference external" href="http://docs.djangoproject.com/en/dev/howto/custom-management-commands/">admin command</a> like the other
<tt class="docutils literal"><span class="pre">management.py</span></tt> commands.</p>
<p>Add <tt class="docutils literal"><span class="pre">&quot;gunicorn&quot;</span></tt> to INSTALLED_APPS in your settings file:</p>
<pre class="literal-block">
INSTALLED_APPS = (
...
@ -128,12 +132,13 @@ python manage.py run_gunicorn
</div>
<div class="section" id="paste-compatible-projects">
<h1>Paste-compatible projects</h1>
<p>For <a class="reference external" href="http://pythonpaste.org/script/">Paste</a> compatible projects (<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...) use the <tt class="docutils literal">gunicorn_paste</tt> command:</p>
<p>For <a class="reference external" href="http://pythonpaste.org/script/">Paste</a> compatible projects (<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...) use the
<tt class="docutils literal"><span class="pre">gunicorn_paste</span></tt> command:</p>
<pre class="literal-block">
$ cd $yourpasteproject
$ gunicorn_paste --workers=2 development.ini
</pre>
<p>To use the <tt class="docutils literal">paster</tt> command add a sever section for Gunicorn:</p>
<p>To use the <tt class="docutils literal"><span class="pre">paster</span></tt> command add a sever section for Gunicorn:</p>
<pre class="literal-block">
[server:main]
use = egg:gunicorn#main

77
doc/site/configuration.rst
View File

@ -10,25 +10,25 @@ Example gunicorn.conf.py
------------------------
::
arbiter = "egg:gunicorn" # Or "egg:gunicorn#eventlet" (eventlet or gevent)
backlog = 2048
bind = "127.0.0.1:8000" # Or "unix:/tmp/gunicorn.sock"
daemon = False # Whether work in the background
debug = False # Some extra logging
keepalive = 2 # Time we wait for next connection (in ms)
logfile = "-" # Name of the log file
loglevel = "info" # The level at which to log
pidfile = None # Path to a PID file
workers = 1 # Number of workers to initialize
umask = 0 # Umask to set when daemonizing
user = None # Change process owner to user
group = None # Change process group to group
proc_name = None # Change the process name
tmp_upload_dir = None # Set path used to store temporary uploads
worker_connections=1000 # Number of connections accepted by a worker
arbiter = "egg:gunicorn" # The arbiter to use for worker management
backlog = 2048 # The listen queue size for the server socket
bind = "127.0.0.1:8000" # Or "unix:/tmp/gunicorn.sock"
daemon = False # Whether work in the background
debug = False # Some extra logging
keepalive = 2 # Time we wait for next connection (in seconds)
logfile = "-" # Name of the log file
loglevel = "info" # The level at which to log
pidfile = None # Path to a PID file
workers = 1 # Number of workers to initialize
umask = 0 # Umask to set when daemonizing
user = None # Change process owner to user
group = None # Change process group to group
proc_name = None # Change the process name
tmp_upload_dir = None # Set path used to store temporary uploads
worker_connections=1000 # Maximum number of simultaneous connections
after_fork=lambda server, worker: server.log.info(
"Worker spawned (pid: %s)" % worker.pid),
"Worker spawned (pid: %s)" % worker.pid)
before_fork=lambda server, worker: True
@ -41,44 +41,63 @@ after_fork(server, worker):
This is called by the worker after initialization.
arbiter:
The arbiter you want to use. An arbiter maintain the workers processes alive. It launches or kills them if needed. It also manages application reloading via SIGHUP/USR2. By default it's `egg:gunicorn#main`. This arbiter only support fast clients connections. If you need to create a sleepy application or handling keepalive set it to `egg:gunicorn#eventlet` to use it with `Eventlet`_ or `egg:gunicorn#gevent` with `Gevent`_. Eventlet arbiter can also be used with `Twisted`_ by using its `helper <http://bitbucket.org/which_linden/eventlet/src/tip/README.twisted>`_.
The arbiter manages the worker processes that actually serve clients. It
handles launching new workers and killing misbehaving workers among
other things. By default the arbiter is `egg:gunicorn#main`. This arbiter
only supports fast request handling requiring a buffering HTTP proxy.
If your application requires the ability to handle prolonged requests to
provide long polling, comet, or calling an external web service you'll
need to use an async arbiter. Gunicorn has two async arbiters built in
using `Eventlet`_ or `Gevent`_. You can also use the Evenlet arbiter with
the `Twisted`_ helper.
backlog:
The backlog parameter defines the maximum length for the queue of pending connections see listen(2) for more information. The default is 2048.
The backlog parameter defines the maximum length for the queue of pending
connections. The default is 2048. See listen(2) for more information
before_fork(server, worker):
This is called by the worker just before forking.
before_exec(server):
This function is called before relaunching the master. This happens when the master receives a HUP or USR2 signal.
This function is called before relaunching the master. This happens when
the master receives a HUP or USR2 signal.
bind:
The address on which workers are listening. It can be a TCP address with a format of ``IP:PORT`` or a Unix socket address like ``unix:/path/to/socketfile``.
The address on which workers are listening. It can be a TCP address with a
format of ``IP:PORT`` or a Unix socket address like
``unix:/path/to/socketfile``.
daemon:
Whether or not to detach the server from the controlling terminal.
debug:
If ``True``, only one worker will be launch and the variable ``wsgi.multiprocess`` will be set to False.
If ``True``, only one worker will be launch and the variable
``wsgi.multiprocess`` will be set to False.
group:
The group in which worker processes will be launched.
keepalive:
Keepalive timeout. The default is 2 seconds, which should be enough under most conditions for browsers to render the page and start retrieving extra elements for. Increasing this beyond 5 seconds is not recommended. Zero disables keepalive entirely.
KeepAlive timeout. The default is 2 seconds, which should be enough under
most conditions for browsers to render the page and start retrieving extra
elements for. Increasing this beyond 5 seconds is not recommended. Zero
disables KeepAlive entirely.
logfile:
The path to the log file ``-`` (stdout) by default.
loglevel:
The level at which to log. ``info``, ``debug``, or ``error`` for instance. Only log messages of equal or greater severity are logged.
The level at which to log. ``info``, ``debug``, or ``error`` for instance.
Only log messages of equal or greater severity are logged.
pidfile:
A file to store the master's PID.
proc_name:
If `setproctitle <http://pypi.python.org/pypi/setproctitle>`_ is installed, it allows you to set the process name for this Gunicorn instance.
A name for the master process. Only takes effect if setproctitle_ is
installed. This alters the process names listed by commands like ``ps``.
umask:
Used to set the umask when daemonizing.
@ -86,12 +105,14 @@ user:
The user as which worker processes will by launched.
worker_connections:
Number of connections a worker can handle when used with Eventlet or Gevent arbiter. The default is 1000.
Number of simultaneous connections a worker can handle when used with
Eventlet or Gevent arbiter. The default is 1000.
tmp_upload_dir:
Set the path used to store temporarily the body of the request.
.. _helper: http://bitbucket.org/which_linden/eventlet/src/tip/README.twisted
.. _Eventlet: http://eventlet.net
.. _Gevent: http://gevent.org
.. _Twisted: http://twistedmatrix.com
.. _setproctitle: http://pypi.python.org/pypi/setproctitle

46
doc/site/deployment.rst
View File

@ -4,12 +4,45 @@ title: Deployment
Production Setup
================
Although there are many HTTP proxies available, we strongly advise that you use Nginx_. If you choose another proxy server you need to make sure that it buffers slow clients when you use default Gunicorn arbiter. Without this buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
There are two general classes of configuration for Gunicorn. For the time
being these will are referred to as "fast clients" and "sleepy applications".
Fast Clients
------------
Generally speaking when we say "fast clients" what we really mean is that the
time taken to process a client from the time a socket is accepted until
the time the socket is closed is well defined to be short. This means that
clients are buffered by an upstream proxy (otherwise clients can send or
receive data slowly) and that your application code does not have major
blocking sections (a web request to the internet might occasionally take a
non trivial amount of time).
Traditional webapps are generally fine for fast client configurations.
Deployments should generally default to this type of configuration unless it is
known that the application code wants to do long-polling, comet, web sockets or
has other potentially long operations (on the order of seconds).
Sleepy Applications
-------------------
Any application that requires an undefined amount of time for client processing
is considered a sleepy application. If you are wanting a platform that is
capable of handling comet connections, long polling, or potentially long
blocking operations (requests to external web services, ie Facebook Connect)
then you'll want to use an async arbiter.
Nginx Config for fast clients handling
--------------------------------------
An `example configuration`_ file for use with Nginx_::
Although there are many HTTP proxies available, we strongly advise that you
use Nginx_. If you choose another proxy server you need to make sure that it
buffers slow clients when you use default Gunicorn arbiter. Without this
buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
You can use slowloris_ to check if your proxy is behaving properly.
An `example configuration`_ file for fast clients with Nginx_::
worker_processes 1;
@ -61,8 +94,9 @@ An `example configuration`_ file for use with Nginx_::
}
}
}
To handle sleepy applications, just add the line `proxy_buffering off;` under the proxy_redirect directive::
To handle sleepy applications, just add the line `proxy_buffering off;` under
the proxy_redirect directive::
...
location / {
@ -81,7 +115,8 @@ To handle sleepy applications, just add the line `proxy_buffering off;` under th
Daemon Monitoring
-----------------
A popular method for deploying Gunicorn is to have it monitored by runit_. An `example service`_ definition::
A popular method for deploying Gunicorn is to have it monitored by runit_.
An `example service`_ definition::
#!/bin sh
@ -108,6 +143,7 @@ Another useful tool to monitor and control Gunicorn is Supervisor_. A
redirect_stderr=True
.. _Nginx: http://www.nginx.org
.. _slowloris: http://ha.ckers.org/slowloris/
.. _`example configuration`: http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf
.. _runit: http://smarden.org/runit/
.. _`example service`: http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc

17
doc/site/faq.rst
View File

@ -4,20 +4,21 @@ title: FAQ
FAQ
===
What is a slow client?
A slow client is defined as a request that can take an arbitrary amount of
time to send or read a request. Sometimes due to network performance or
because it is a malicious client attempting to cause problems. Check out
the slowloris_ script to generate slow client traffic.
What is a fast client?
Generally speaking a fast client is something that is being served over the
local network or from the same machine. This generally would refer to requests
forwarded from an upstream proxy. Also see the above FAQ for what a fast
client is not.
What is a slow client?
A slow client is defined as a request that can take an arbitrary amount of
time to send a request or read a response. Sometimes due to network
performance or because it is a malicious client attempting to cause problems.
Check out the slowloris_ script to generate slow client traffic.
What are sleepy applications?
Applications that expect long request/response times and/or slow clients. Gunicorn use `Eventlet`_ or `Gevent`_ to manage concurrency.
Applications that expect long request/response times and/or slow clients.
Gunicorn use `Eventlet`_ or `Gevent`_ to manage concurrency.
How might I test a proxy configuration?
Check out slowloris_ for a script that will generate significant slow

25
doc/site/index.rst
View File

@ -3,9 +3,11 @@ template: index.html
Green Unicorn
=============
Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve `fast clients`_ or `sleepy applications`_.
Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve
`fast clients`_ or `sleepy applications`_.
This is a port of Unicorn_ in Python. Meet us on the `#gunicorn IRC channel`_ on Freenode_.
This is a port of Unicorn_ in Python. Meet us on the `#gunicorn IRC channel`_
on Freenode_.
Gunicorn is released under the MIT License. See the LICENSE_ for more details.
@ -14,26 +16,27 @@ Features
- Designed for Unix, WSGI_, fast clients and sleepy applications.
- Compatible with Python 2.x (>= 2.5)
- Easy integration with Django_ and Paster_ compatible applications (`Pylons`_, `TurboGears 2`_, ...)
- Easy integration with Django_ and Paster_ compatible applications
(`Pylons`_, `TurboGears 2`_, ...)
- Process management: Gunicorn_ reaps and restarts workers that die.
- Load balancing via pre-fork and a shared socket
- Graceful worker process restarts
- Upgrade "àla nginx" without losing connections
- Simple and easy Python configuration
- Decode chunked transfers on-the-fly, allowing upload progress notifications or
stream-based protocols over HTTP
- Decode chunked transfers on-the-fly, allowing upload progress notifications
or stream-based protocols over HTTP
- Support for `Eventlet`_ and `Gevent`_ .
- Post- and pre-fork hooks
Applications
------------
* Any WSGI_, Django_ and Paster_ compatible applications (`Pylons`_, `TurboGears 2`_, ...)
* Websockets (see `example <http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py>`_)
* Reverse proxy implementation (with `Restkit WSGI proxy <http://benoitc.github.com/restkit/wsgi_proxy.html>`_)
* Any WSGI_, Django_ and Paster_ compatible applications
(`Pylons`_, `TurboGears 2`_, ...)
* Websockets (see the example_)
* Reverse proxy implementation (with `Restkit WSGI proxy`_)
* Comet
* Long Polling
* ...
.. _WSGI: http://www.python.org/dev/peps/pep-0333/
.. _`fast clients`: faq.html
@ -48,4 +51,6 @@ Applications
.. _Eventlet: http://eventlet.net
.. _Gevent: http://gevent.org
.. _Pylons: http://pylonshq.com/
.. _Turbogears 2: http://turbogears.org/2.0/
.. _Turbogears 2: http://turbogears.org/2.0/
.. _example: http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py
.. _`Restkit WSGI proxy`: http://benoitc.github.com/restkit/wsgi_proxy.html

40
doc/site/installation.rst
View File

@ -14,7 +14,8 @@ Requirements
Installing with easy_install
----------------------------
If you don't already have ``easy_install`` available you'll want to download and run the ``ez_setup.py`` script::
If you don't already have ``easy_install`` available you'll want to download
and run the ``ez_setup.py`` script::
$ curl -O http://peak.telecommunity.com/dist/ez_setup.py
$ sudo python ez_setup.py -U setuptools
@ -26,12 +27,15 @@ To install or upgrade to the latest released version of Gunicorn::
Installing from source
----------------------
You can install Gunicorn from source as simply as you would install any other Python package. Gunicorn uses setuptools which will automatically fetch all dependencies (including setuptools itself).
You can install Gunicorn from source as simply as you would install any other
Python package. Gunicorn uses setuptools which will automatically fetch all
dependencies (including setuptools itself).
Get a Copy
++++++++++
You can download a tarball of the latest sources from `GitHub Downloads`_ or fetch them with git_::
You can download a tarball of the latest sources from `GitHub Downloads`_ or
fetch them with git_::
$ git clone git://github.com/benoitc/gunicorn.git
@ -45,29 +49,43 @@ Installation
$ python setup.py install
If you've cloned the git repository, its highly recommended that you use the ``develop`` command which will allow you to use Gunicorn from the source directory. This will allow you to keep up to date with development on GitHub as well as make changes to the source::
If you've cloned the git repository, its highly recommended that you use the
``develop`` command which will allow you to use Gunicorn from the source
directory. This will allow you to keep up to date with development on GitHub as
well as make changes to the source::
$ python setup.py develop
Installation requirements for sleepy application handling
---------------------------------------------------------
If you want to handle `sleepy application <faq.html>`_ you will need to install `Eventlet`_ or `Gevent`_.
If you want to handle `sleepy application <faq.html>`_ you will need to install
`Eventlet`_ or `Gevent`_.
To install eventlet::
$ easy_install -U eventlet
Replace `eventlet` by **gevent** if you want to use `gevent`.
Replace ``eventlet`` with ``gevent`` if you want to use the ``gevent``
arbiter.
You can now launch gunicorn with Eventlet or Gevent arbiter, see `usage <usage.html>`_ for more information.
You can now launch gunicorn with Eventlet or Gevent arbiter, see
`usage <usage.html>`_ for more information.
.. note::
If ``eventlet`` or ``gevent`` fails to install for you, its most likely
due to an out of date libev_ library. You'll need to download and install
a newer version for either of those to modules to work properly.
Installing on Ubuntu/Debian systems
-----------------------------------
If you use `ubuntu <http://www.ubuntu.com/>`_ karmic, you can update your system with packages from our `PPA <https://launchpad.net/~bchesneau/+archive/gunicorn>`_ by adding ppa:bchesneau/gunicorn to your system's Software Sources.
If you use `Ubuntu <http://www.ubuntu.com/>`_ karmic, you can update your
system with packages from our PPA_ by adding ``ppa:bchesneau/gunicorn``
to your system's Software Sources.
Or this PPA can be added to your system manually by copying the lines below and adding them to your system's software sources::
Or this PPA can be added to your system manually by copying the lines below
and adding them to your system's software sources::
deb http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
deb-src http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
@ -81,4 +99,6 @@ Fingerprint::
49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06
.. _Eventlet: http://eventlet.net
.. _Gevent: http://gevent.org
.. _Gevent: http://gevent.org
.. _libev: http://software.schmorp.de/pkg/libev.html
.. _PPA: https://launchpad.net/~bchesneau/+archive/gunicorn

24
doc/site/usage.rst
View File

@ -16,17 +16,19 @@ To launch the `example application`_ packaged with Gunicorn::
$ cd /path/to/gunicorn/examples/
$ gunicorn --workers=2 test:app
The module ``test:app`` specifies the complete module name and WSGI callable. You can replace it with anything that is available on your ``PYTHONPATH`` like such::
The module ``test:app`` specifies the complete module name and WSGI callable.
You can replace it with anything that is available on your ``PYTHONPATH`` like
such::
$ cd ~/
$ gunicorn --workers=12 awesomeproject.wsgi.main:main_app
To launch the `websocket example application <http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py>`_ using `Eventlet`_::
To launch the `websocket example`_ application using `Eventlet`_::
$ cd /path/to/gunicorn/examples/
$ gunicorn -w 12 -a "egg:gunicorn#eventlet" websocket:app
and then go on `http://localhost:8000` to see the result.
You should then be able to visit ``http://localhost:8000`` to see output.
Full command line usage
+++++++++++++++++++++++
@ -44,8 +46,8 @@ Full command line usage
-w WORKERS, --workers=WORKERS
Number of workers to spawn. [1]
-a ARBITER, --arbiter=ARBITER
gunicorn arbiter entry point or module
[egg:gunicorn#main]
gunicorn arbiter entry point or module
[egg:gunicorn#main]
-p PIDFILE, --pid=PIDFILE
set the background PID FILE
-D, --daemon Run daemonized in the background.
@ -55,7 +57,7 @@ Full command line usage
-g GROUP, --group=GROUP
Change worker group
-n APP_NAME, --name=APP_NAME
Application name
Application name
--log-level=LOGLEVEL Log level below which to silence messages. [info]
--log-file=LOGFILE Log to a file. - equals stdout. [-]
-d, --debug Debug mode. only 1 worker.
@ -65,12 +67,14 @@ Full command line usage
Django Projects
---------------
`Django`_ projects can be handled easily by Gunicorn using the ``gunicorn_django`` command::
`Django`_ projects can be handled easily by Gunicorn using the
``gunicorn_django`` command::
$ cd $yourdjangoproject
$ gunicorn_django --workers=2
But you can also use the ``run_gunicorn`` `admin command`_ like the other ``management.py`` commands.
But you can also use the ``run_gunicorn`` `admin command`_ like the other
``management.py`` commands.
Add ``"gunicorn"`` to INSTALLED_APPS in your settings file::
@ -87,7 +91,8 @@ Then run::
Paste-compatible projects
-------------------------
For `Paste`_ compatible projects (`Pylons`_, `TurboGears 2`_, ...) use the ``gunicorn_paste`` command::
For `Paste`_ compatible projects (`Pylons`_, `TurboGears 2`_, ...) use the
``gunicorn_paste`` command::
$ cd $yourpasteproject
$ gunicorn_paste --workers=2 development.ini
@ -105,6 +110,7 @@ And then all you need to do is::
$ paster serve development.ini workers=2
.. _`example application`: http://github.com/benoitc/gunicorn/blob/master/examples/test.py
.. _`websocket example`: http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py
.. _Django: http://djangoproject.com
.. _`admin command`: http://docs.djangoproject.com/en/dev/howto/custom-management-commands/
.. _Paste: http://pythonpaste.org/script/