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

Updating webpage docs.

Browse Source
This commit is contained in:
Paul J. Davis 2010-05-06 20:55:38 -04:00
parent c2af49cb12
commit 8382dfea5e
17 changed files with 459 additions and 349 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/htdocs/configuration.html
View File

@ -49,7 +49,9 @@
<div class="document" id="the-configuration-file"> <div class="document" id="the-configuration-file">
<h1 class="title">The Configuration File</h1> <h1 class="title">The Configuration File</h1>
<p>Gunicorn 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>Gunicorn 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>
<div class="section" id="example-gunicorn-conf-py"> <div class="section" id="example-gunicorn-conf-py">
<h1>Example gunicorn.conf.py</h1> <h1>Example gunicorn.conf.py</h1>
<pre class="literal-block"> <pre class="literal-block">

11
doc/htdocs/css/style.css
View File

@ -23,10 +23,15 @@ ul {
padding-left: 1em; padding-left: 1em;
} }
dt {
border-top: 1px solid #BBB;
padding-top: 0.5em;
}
dd { dd {
border-bottom: 1px solid #eee; margin: 0px;
margin: 0 0 .5em; margin-bottom: 0.5em;
padding: 0 0 .5em; padding: 0px;
} }
pre { pre {

60
doc/htdocs/deployment.html
View File

@ -49,35 +49,33 @@
<div class="document" id="production-setup"> <div class="document" id="production-setup">
<h1 class="title">Production Setup</h1> <h1 class="title">Production Setup</h1>
<p>There are two general classes of configuration for Gunicorn. For the time <div class="section" id="synchronous-vs-asynchronous-workers">
being these will are referred to as &quot;fast clients&quot; and &quot;sleepy applications&quot;.</p> <h1>Synchronous vs Asynchronous workers</h1>
<div class="section" id="fast-clients"> <p>The default configuration of Gunicorn assumes that your application code is
<h1>Fast Clients</h1> mostly CPU bound. The default worker class is a simple single threaded loop that
<p>Generally speaking when we say &quot;fast clients&quot; what we really mean is that the just processes requests as they are received. In general, most applications will
time taken to process a client from the time a socket is accepted until do just fine with this sort of configuration.</p>
the time the socket is closed is well defined to be short. This means that <p>This CPU bound assumption is why the default configuration needs to use a
clients are buffered by an upstream proxy (otherwise clients can send or buffering HTTP proxy like <a class="reference external" href="http://www.nginx.org">Nginx</a> to protect the Gunicorn server. If we allowed
receive data slowly) and that your application code does not have major direct connections a client could send a request slowly thus starving the server
blocking sections (a web request to the internet might occasionally take a of free worker processes (because they're all stuck waiting for data).</p>
non trivial amount of time).</p> <p>Example use-cases for asynchronous workers:</p>
<p>Traditional webapps are generally fine for fast client configurations. <blockquote>
Deployments should generally default to this type of configuration unless it is <ul class="simple">
known that the application code wants to do long-polling, comet, web sockets or <li>Applications making long blocking calls (Ie, to external web services)</li>
has other potentially long operations (on the order of seconds).</p> <li>Serving requests directly to the internet</li>
<li>Streaming requests and responses</li>
<li>Long polling</li>
<li>Web sockets</li>
<li>Comet</li>
</ul>
</blockquote>
</div> </div>
<div class="section" id="sleepy-applications"> <div class="section" id="basic-nginx-configuration">
<h1>Sleepy Applications</h1> <h1>Basic Nginx Configuration</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>Although there are many HTTP proxies available, we strongly advise that you <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 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 buffers slow clients when you use default Gunicorn workers. Without this
buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks. 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> 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> <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>
@ -133,8 +131,12 @@ http {
} }
} }
</pre> </pre>
<p>To handle sleepy applications, just add the line <cite>proxy_buffering off;</cite> under <p>If you want to be able to handle streaming request/responses or other fancy
the proxy_redirect directive:</p> features like Comet, Long polling, or Web sockets, you need to turn off the
proxy buffering. <strong>When you do this</strong> you must run with one of the async worker
classes.</p>
<p>To turn off buffering, you only need to add <tt class="docutils literal">proxy_buffering off;</tt> to your
<tt class="docutils literal">location</tt> block:</p>
<pre class="literal-block"> <pre class="literal-block">
... ...
location / { location / {
@ -148,7 +150,7 @@ location / {
break; break;
} }
} }
.... ...
</pre> </pre>
</div> </div>
<div class="section" id="working-with-virtualenv"> <div class="section" id="working-with-virtualenv">

37
doc/htdocs/faq.html
View File

@ -50,19 +50,19 @@
<div class="document" id="faq"> <div class="document" id="faq">
<h1 class="title">FAQ</h1> <h1 class="title">FAQ</h1>
<dl class="docutils"> <dl class="docutils">
<dt>What is a fast client?</dt> <dt>How do I know which type of worker to use?</dt>
<dd>Generally speaking a fast client is something that is being served over the <dd>Test. Read the &quot;Synchronous vs Asynchronous workers&quot; section on the
local network or from the same machine. This generally would refer to requests <a class="reference external" href="http://gunicorn.org/deployment.html">deployment</a> page. Test some more.</dd>
forwarded from an upstream proxy. Also see the above FAQ for what a fast <dt>What types of workers are there?</dt>
client is not.</dd> <dd><p class="first">These can all be used with the <tt class="docutils literal"><span class="pre">-k</span></tt> option and specifying them
<dt>What is a slow client?</dt> as <tt class="docutils literal"><span class="pre">egg:gunicorn#$(NAME)</span></tt> where <tt class="docutils literal">$(NAME)</tt> is chosen from this list.</p>
<dd>A slow client is defined as a request that can take an arbitrary amount of <ul class="last simple">
time to send a request or read a response. Sometimes due to network <li><tt class="docutils literal">sync</tt> - The default synchronous worker</li>
performance or because it is a malicious client attempting to cause problems. <li><tt class="docutils literal">eventlet</tt> - Asynchronous workers based on Greenlets</li>
Check out the <a class="reference external" href="http://ha.ckers.org/slowloris/">slowloris</a> script to generate slow client traffic.</dd> <li><tt class="docutils literal">gevent</tt> - Asynchronous workers based on Greenlets</li>
<dt>What are sleepy applications?</dt> <li><tt class="docutils literal">tornado</tt> - Asynchronous workers based on FriendFeed's Tornado server.</li>
<dd>Applications that expect long request/response times and/or slow clients. </ul>
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>
<dt>How might I test a proxy configuration?</dt> <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 <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 traffic. If your application remains responsive through out that test you
@ -83,13 +83,16 @@ $ kill -TTIN $masterpid
$ kill -TTOU $masterpid $ kill -TTOU $masterpid
</pre> </pre>
</dd> </dd>
<dt>How can I figure out the best number of worker processes?</dt>
<dd>Start gunicorn with an approximate number of worker processes. Then use the
TTIN and/or TTOU signals to adjust the number of workers under load.</dd>
<dt>How do I set SCRIPT_NAME?</dt> <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 <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> setting <tt class="docutils literal">SCRIPT_NAME</tt> in the environment or as an HTTP header.</dd>
<dt>How to name processes?</dt> <dt>How can I 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 <dd>You need to install the Python package <a class="reference external" href="http://pypi.python.org/pypi/setproctitle">setproctitle</a>. Then you can specify
your process with <cite>-n</cite> or just let the default. If you use a configuration a base process name on the command line (<tt class="docutils literal"><span class="pre">-n</span></tt>) or in the configuration
file you can set the process name with the proc_name option.</dd> file.</dd>
</dl> </dl>
</div> </div>

13
doc/htdocs/index.html
View File

@ -47,15 +47,16 @@
<div class="document" id="green-unicorn"> <div class="document" id="green-unicorn">
<h1 class="title">Green Unicorn</h1> <h1 class="title">Green Unicorn</h1>
<p>Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve <p>Gunicorn 'Green Unicorn' is a <a class="reference external" href="http://www.python.org/dev/peps/pep-0333/">WSGI</a> HTTP Server for UNIX. It's a pre-fork
<a class="reference external" href="faq.html">fast clients</a> or <a class="reference external" href="faq.html">sleepy applications</a>.</p> worker model ported from Ruby's <a class="reference external" href="http://unicorn.bogomips.org/">Unicorn</a> project. The Gunicorn server is
<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> broadly compatible with various web frameworks, simply implemented, light
on <a class="reference external" href="http://freenode.net">Freenode</a>.</p> on server resource usage, and fairly speedy.</p>
<p>Feel free to join us in <a class="reference external" href="http://webchat.freenode.net/?channels=gunicorn">#gunicorn</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> <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"> <div class="section" id="features">
<h1>Features</h1> <h1>Features</h1>
<ul class="simple"> <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>Designed for Unix.</li>
<li>Compatible with Python 2.x (&gt;= 2.5)</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 <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> (<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...)</li>
@ -77,8 +78,8 @@ or stream-based protocols over HTTP</li>
(<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...)</li> (<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> or the <a class="reference external" href="http://vimeo.com/10461162">screencast</a>)</li> <li>Websockets (see the <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py">example</a> or the <a class="reference external" href="http://vimeo.com/10461162">screencast</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>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>Long Polling</li>
<li>Comet</li>
</ul> </ul>
</div> </div>
</div> </div>

30
doc/htdocs/installation.html
View File

@ -52,7 +52,7 @@
<div class="section" id="requirements"> <div class="section" id="requirements">
<h1>Requirements</h1> <h1>Requirements</h1>
<ul class="simple"> <ul class="simple">
<li><strong>Python 2.5 or newer</strong> (Python 3.x will be supported soon)</li> <li><strong>Python 2.x &gt;= 2.5</strong> (Python 3.x will be supported soon)</li>
<li>setuptools &gt;= 0.6c6</li> <li>setuptools &gt;= 0.6c6</li>
<li>nosetests (for the test suite only)</li> <li>nosetests (for the test suite only)</li>
</ul> </ul>
@ -72,7 +72,7 @@ $ sudo easy_install -U gunicorn
</div> </div>
<div class="section" id="installing-from-source"> <div class="section" id="installing-from-source">
<h1>Installing from source</h1> <h1>Installing from source</h1>
<p>You can install Gunicorn from source as simply as you would install any other <p>You can install Gunicorn from source just as you would install any other
Python package. Gunicorn uses setuptools which will automatically fetch all Python package. Gunicorn uses setuptools which will automatically fetch all
dependencies (including setuptools itself).</p> dependencies (including setuptools itself).</p>
<div class="section" id="get-a-copy"> <div class="section" id="get-a-copy">
@ -97,30 +97,28 @@ $ python setup.py develop
</pre> </pre>
</div> </div>
</div> </div>
<div class="section" id="installation-requirements-for-sleepy-application-handling"> <div class="section" id="enabling-async-workers">
<h1>Installation requirements for sleepy application handling</h1> <h1>Enabling async workers</h1>
<p>If you want to handle <a class="reference external" href="faq.html">sleepy application</a> you will need to install <p>You may also want to install <a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a> if you expect that your
<a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a>.</p> application code may need to pause for extended periods of time during
request processing. Check out the <a class="reference external" href="faq.html">FAQ</a> for more information on when you'll
want to consider one of the alternate worker types.</p>
<p>To install eventlet:</p> <p>To install eventlet:</p>
<pre class="literal-block"> <pre class="literal-block">
$ easy_install -U eventlet $ easy_install -U eventlet
</pre> </pre>
<p>Replace <tt class="docutils literal">eventlet</tt> with <tt class="docutils literal">gevent</tt> if you want to use the <tt class="docutils literal">gevent</tt> <p>Replace <tt class="docutils literal">eventlet</tt> with <tt class="docutils literal">gevent</tt> to use to the <tt class="docutils literal">gevent</tt> based workers.</p>
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"> <div class="note">
<p class="first admonition-title">Note</p> <p class="first admonition-title">Note</p>
<p class="last">If <tt class="docutils literal">eventlet</tt> or <tt class="docutils literal">gevent</tt> fails to install for you, its most likely <p class="last">If you encounter errors when compiling the extensions for <a class="reference external" href="http://eventlet.net">Eventlet</a> or
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 class="reference external" href="http://gevent.org">Gevent</a> you most likely need to install a newer version of <a class="reference external" href="http://software.schmorp.de/pkg/libev.html">libev</a>.</p>
a newer version for either of those to modules to work properly.</p>
</div> </div>
</div> </div>
<div class="section" id="installing-on-ubuntu-debian-systems"> <div class="section" id="installing-on-ubuntu-debian-systems">
<h1>Installing on Ubuntu/Debian systems</h1> <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 <p>If you use <a class="reference external" href="http://www.ubuntu.com/">Ubuntu</a> karmic, you can update your system with packages from
system with packages from our <a class="reference external" href="https://launchpad.net/~bchesneau/+archive/gunicorn">PPA</a> by adding <tt class="docutils literal">ppa:bchesneau/gunicorn</tt> our <a class="reference external" href="https://launchpad.net/~bchesneau/+archive/gunicorn">PPA</a> by adding <tt class="docutils literal">ppa:bchesneau/gunicorn</tt> to your system's Software
to your system's Software Sources.</p> Sources.</p>
<p>Or this PPA can be added to your system manually by copying the lines below <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> and adding them to your system's software sources:</p>
<pre class="literal-block"> <pre class="literal-block">

25
doc/htdocs/news.html
View File

@ -61,14 +61,15 @@
<div class="section" id="id2"> <div class="section" id="id2">
<h1>0.8.0 / 2010-04-22</h1> <h1>0.8.0 / 2010-04-22</h1>
<ul class="simple"> <ul class="simple">
<li>Refactored Worker management for better async support. Now use the -k option to set the type of request processing to use</li> <li>Refactored Worker management for better async support. Now use the -k option
to set the type of request processing to use</li>
<li>Added support for <a class="reference external" href="http://www.tornadoweb.org/">Tornado</a></li> <li>Added support for <a class="reference external" href="http://www.tornadoweb.org/">Tornado</a></li>
</ul> </ul>
</div> </div>
<div class="section" id="id3"> <div class="section" id="id3">
<h1>0.7.2 / 2010-04-15</h1> <h1>0.7.2 / 2010-04-15</h1>
<ul class="simple"> <ul class="simple">
<li>Added --spew option to help debugging (install a Trace hook)</li> <li>Added --spew option to help debugging (installs a system trace hook)</li>
<li>Some fixes in async arbiters</li> <li>Some fixes in async arbiters</li>
<li>Fix a bug in start_response on error</li> <li>Fix a bug in start_response on error</li>
</ul> </ul>
@ -82,7 +83,7 @@
<div class="section" id="id5"> <div class="section" id="id5">
<h1>0.7.0 / 2010-03-26</h1> <h1>0.7.0 / 2010-03-26</h1>
<ul class="simple"> <ul class="simple">
<li>Added support for <a class="reference external" href="faq.html">sleepy applications</a> using <a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a>.</li> <li>Added support for <a class="reference external" href="http://eventlet.net">Eventlet</a> and <a class="reference external" href="http://gevent.org">Gevent</a> based workers.</li>
<li>Added <a class="reference external" href="http://dev.w3.org/html5/websockets/">Websockets</a> support</li> <li>Added <a class="reference external" href="http://dev.w3.org/html5/websockets/">Websockets</a> support</li>
<li>Fix Chunked Encoding</li> <li>Fix Chunked Encoding</li>
<li>Fix SIGWINCH on <a class="reference external" href="http://openbsd.org">OpenBSD</a></li> <li>Fix SIGWINCH on <a class="reference external" href="http://openbsd.org">OpenBSD</a></li>
@ -92,7 +93,7 @@
<div class="section" id="id6"> <div class="section" id="id6">
<h1>0.6.5 / 2010-03-11</h1> <h1>0.6.5 / 2010-03-11</h1>
<ul class="simple"> <ul class="simple">
<li>Fix pidfile</li> <li>Fix pidfile handling</li>
<li>Fix Exception Error</li> <li>Fix Exception Error</li>
</ul> </ul>
</div> </div>
@ -107,7 +108,7 @@
<h1>0.6.3 / 2010-03-07</h1> <h1>0.6.3 / 2010-03-07</h1>
<ul class="simple"> <ul class="simple">
<li>Make HTTP parsing faster.</li> <li>Make HTTP parsing faster.</li>
<li>Some fixes (see <a class="reference external" href="http://github.com/benoitc/gunicorn/commits/master">logs</a>)</li> <li>Various bug fixes</li>
</ul> </ul>
</div> </div>
<div class="section" id="id9"> <div class="section" id="id9">
@ -115,7 +116,8 @@
<ul class="simple"> <ul class="simple">
<li>Added support for chunked response.</li> <li>Added support for chunked response.</li>
<li>Added proc_name option to the config file.</li> <li>Added proc_name option to the config file.</li>
<li>Improved the HTTP parser. It now uses buffers instead of strings to store temporary data.</li> <li>Improved the HTTP parser. It now uses buffers instead of strings to store
temporary data.</li>
<li>Improved performance when sending responses.</li> <li>Improved performance when sending responses.</li>
<li>Workers are now murdered by age (the oldest is killed first).</li> <li>Workers are now murdered by age (the oldest is killed first).</li>
</ul> </ul>
@ -123,7 +125,7 @@
<div class="section" id="id10"> <div class="section" id="id10">
<h1>0.6.1 / 2010-02-24</h1> <h1>0.6.1 / 2010-02-24</h1>
<ul class="simple"> <ul class="simple">
<li>Added gunicorn config file support for django admin command</li> <li>Added gunicorn config file support for Django admin command</li>
<li>Fix gunicorn config file. -c was broken.</li> <li>Fix gunicorn config file. -c was broken.</li>
<li>Removed TTIN/TTOU from workers which blocked other signals.</li> <li>Removed TTIN/TTOU from workers which blocked other signals.</li>
</ul> </ul>
@ -131,15 +133,16 @@
<div class="section" id="id11"> <div class="section" id="id11">
<h1>0.6 / 2010-02-22</h1> <h1>0.6 / 2010-02-22</h1>
<ul class="simple"> <ul class="simple">
<li>Added setproctitle</li> <li>Added setproctitle support</li>
<li>Change privilege switch behaviour. We now work like NGINX, master keeps the permissions, new uid/gid permissions are only set for workers.</li> <li>Change privilege switch behavior. We now work like NGINX, master keeps the
permissions, new uid/gid permissions are only set for workers.</li>
</ul> </ul>
</div> </div>
<div class="section" id="id12"> <div class="section" id="id12">
<h1>0.5.1 / 2010-02-22</h1> <h1>0.5.1 / 2010-02-22</h1>
<ul class="simple"> <ul class="simple">
<li>Fix umask</li> <li>Fix umask</li>
<li>Added debian packaging</li> <li>Added Debian packaging</li>
</ul> </ul>
</div> </div>
<div class="section" id="id13"> <div class="section" id="id13">
@ -153,7 +156,7 @@
<li>Added umask option</li> <li>Added umask option</li>
<li>Added SCRIPT_NAME support</li> <li>Added SCRIPT_NAME support</li>
<li>Better support of some exotic settings for Django projects</li> <li>Better support of some exotic settings for Django projects</li>
<li>Better support of Paste-compatible applicatins</li> <li>Better support of Paste-compatible applications</li>
<li>Some refactoring to make the code easier to hack</li> <li>Some refactoring to make the code easier to hack</li>
<li>Allow multiple keys in request and response headers</li> <li>Allow multiple keys in request and response headers</li>
</ul> </ul>

31
doc/htdocs/tuning.html
View File

@ -51,31 +51,48 @@
<h1 class="title">Tuning</h1> <h1 class="title">Tuning</h1>
<div class="section" id="unicorn-configuration"> <div class="section" id="unicorn-configuration">
<h1>Unicorn Configuration</h1> <h1>Unicorn Configuration</h1>
<p>DO NOT scale the number of workers to the number of clients you expect to have. Gunicorn should only need 4-12 worker processes to handle hundreds or thousands of simultaneous clients. Remember, Gunicorn is <strong>NOT</strong> designed for serving slow clients, that's the job of <a class="reference external" href="http://www.nginx.org">Nginx</a>.</p> <p>DO NOT scale the number of workers to the number of clients you expect to have.
Gunicorn should only need 4-12 worker processes to handle hundreds or thousands
of simultaneous clients. Remember, Gunicorn is <strong>NOT</strong> designed for serving slow
clients, that's the job of <a class="reference external" href="http://www.nginx.org">Nginx</a>.</p>
<p>See <a class="reference external" href="configuration.html">Configuration</a> for a more thorough description of the available parameters.</p> <p>See <a class="reference external" href="configuration.html">Configuration</a> for a more thorough description of the available parameters.</p>
</div> </div>
<div class="section" id="kernel-parameters"> <div class="section" id="kernel-parameters">
<h1>Kernel Parameters</h1> <h1>Kernel Parameters</h1>
<p>When dealing with large numbers of concurrent connections there are a handful of kernel parameters that you might need to adjust. Generally these should only affect sites with a very large concurrent load. These parameters are not specific to Gunicorn, they would apply to any sort of network server you may be running.</p> <p>When dealing with large numbers of concurrent connections there are a handful of
<p>The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use slightly different flags. Always reference the appropriate man pages if uncertain.</p> kernel parameters that you might need to adjust. Generally these should only
affect sites with a very large concurrent load. These parameters are not
specific to Gunicorn, they would apply to any sort of network server you may be
running.</p>
<p>The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use
slightly different flags. Always reference the appropriate man pages if
uncertain.</p>
<div class="section" id="file-descriptor-limits"> <div class="section" id="file-descriptor-limits">
<h2>File Descriptor Limits</h2> <h2>File Descriptor Limits</h2>
<p>One of the first settings that usually needs to be bumped is the maximum number of open file descriptors for a given process. For the confused out there, remember that Unices treat sockets as files.</p> <p>One of the first settings that usually needs to be bumped is the maximum number
of open file descriptors for a given process. For the confused out there,
remember that Unices treat sockets as files.</p>
<pre class="literal-block"> <pre class="literal-block">
$ sudo ulimit -n 2048 $ sudo ulimit -n 2048
</pre> </pre>
</div> </div>
<div class="section" id="listen-queue-size"> <div class="section" id="listen-queue-size">
<h2>Listen Queue Size</h2> <h2>Listen Queue Size</h2>
<p>Listening sockets have an associated queue of incoming connections that are waiting to be accepted. If you happen to have a stampede of clients that fill up this queue new connections will eventually start getting dropped.</p> <p>Listening sockets have an associated queue of incoming connections that are
waiting to be accepted. If you happen to have a stampede of clients that fill up
this queue new connections will eventually start getting dropped.</p>
<pre class="literal-block"> <pre class="literal-block">
$ sudo sysctl -w kern.ipc.somaxconn=&quot;2048&quot; $ sudo sysctl -w kern.ipc.somaxconn=&quot;2048&quot;
</pre> </pre>
</div> </div>
<div class="section" id="ephemeral-port-range"> <div class="section" id="ephemeral-port-range">
<h2>Ephemeral Port Range</h2> <h2>Ephemeral Port Range</h2>
<p>After a socket is closed it enters the TIME_WAIT state. This can become an issue after a prolonged burst of client activity. Eventually the ephemeral port range is exhausted which can cause new connections to stall while they wait for a valid port.</p> <p>After a socket is closed it enters the TIME_WAIT state. This can become an issue
<p>This setting is generally only required on machines that are being used to test a network server.</p> after a prolonged burst of client activity. Eventually the ephemeral port range
is exhausted which can cause new connections to stall while they wait for a
valid port.</p>
<p>This setting is generally only required on machines that are being used to test
a network server.</p>
<pre class="literal-block"> <pre class="literal-block">
$ sudo sysctl -w net.inet.ip.portrange.first=&quot;8048&quot; $ sudo sysctl -w net.inet.ip.portrange.first=&quot;8048&quot;
</pre> </pre>

174
doc/htdocs/usage.html
View File

@ -47,49 +47,125 @@
</ul> </ul>
</div> </div>
<div class="document" id="command-line-usage"> <div class="document" id="usage">
<h1 class="title">Command Line Usage</h1> <h1 class="title">Usage</h1>
<p>After installing Gunicorn you will have access to three command line scripts
that can be used for serving the various supported web frameworks: <tt class="docutils literal">gunicorn</tt>,
<tt class="docutils literal">gunicorn_django</tt>, and <tt class="docutils literal">gunicorn_paster</tt>.</p>
<div class="section" id="commonly-used-arguments">
<h1>Commonly Used Arguments</h1>
<blockquote>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#wsgi-applications">WSGI applications</a></li> <li><tt class="docutils literal"><span class="pre">-c</span> CONFIG, <span class="pre">--config=CONFIG</span></tt> - Specify the path to a <a class="reference external" href="configuration.html">config file</a></li>
<li><a class="reference internal" href="#django-projects">Django projects</a></li> <li><tt class="docutils literal"><span class="pre">-b</span> BIND, <span class="pre">--bind=BIND</span></tt> - Specify a server socket to bind. Server sockets
<li><a class="reference internal" href="#paste-compatible-projects">Paste-compatible projects</a></li> can be any of <tt class="docutils literal">$(HOST)</tt>, <tt class="docutils literal"><span class="pre">$(HOST):$(PORT)</span></tt>, or <tt class="docutils literal"><span class="pre">unix:$(PATH)</span></tt>.
An IP is a valid <tt class="docutils literal">$(HOST)</tt>.</li>
<li><tt class="docutils literal"><span class="pre">-w</span> WORKERS, <span class="pre">--workers=WORKERS</span></tt> - The number of worker processes. This
number should generally be between 2-4 workers per core in the server.
Check the <a class="reference external" href="faq.html">FAQ</a> for ideas on tuning this parameter.</li>
<li><tt class="docutils literal"><span class="pre">-k</span> WORKERCLASS, <span class="pre">--worker-class=WORKERCLASS</span></tt> - The type of worker process
to run. You'll definitely want to read the <a class="reference external" href="deployment.html">production page</a> for the
implications of this parameter. You can set this to <tt class="docutils literal"><span class="pre">egg:gunicorn#$(NAME)</span></tt>
where <tt class="docutils literal">$(NAME)</tt> is one of <tt class="docutils literal">sync</tt>, <tt class="docutils literal">eventlet</tt>, <tt class="docutils literal">gevent</tt>, or
<tt class="docutils literal">tornado</tt>. <tt class="docutils literal">sync</tt> is the default.</li>
<li><tt class="docutils literal"><span class="pre">-n</span> APP_NAME, <span class="pre">--name=APP_NAME</span></tt> - If <a class="reference external" href="http://pypi.python.org/pypi/setproctitle/">setproctitle</a> is installed you can
adjust the name of Gunicorn process as they appear in the process system
table (which affects tools like <tt class="docutils literal">ps</tt> and <tt class="docutils literal">top</tt>).</li>
</ul> </ul>
<div class="section" id="wsgi-applications"> </blockquote>
<h1>WSGI applications</h1> <p>There are various other parameters that affect user privileges, logging, etc.
<p>To launch the <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/test.py">example application</a> packaged with Gunicorn:</p> You can see the complete list at the bottom of this page or as expected with:</p>
<pre class="literal-block"> <pre class="literal-block">
$ cd /path/to/gunicorn/examples/ $ gunicorn -h
$ gunicorn -w 2 test:app
</pre> </pre>
<p>The module <tt class="docutils literal">test:app</tt> specifies the complete module name and WSGI callable. </div>
You can replace it with anything that is available on your <tt class="docutils literal">PYTHONPATH</tt> like <div class="section" id="gunicorn">
such:</p> <h1>gunicorn</h1>
<p>The first and most basic script is used to server 'bare' WSGI applications
that don't require a translation layer. Basic usage:</p>
<pre class="literal-block"> <pre class="literal-block">
$ cd ~/ $ gunicorn [OPTIONS] APP_MODULE
$ gunicorn -w 12 awesomeproject.wsgi.main:main_app
</pre> </pre>
<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> <p>Where <tt class="docutils literal">APP_MODULE</tt> is of the pattern <tt class="docutils literal"><span class="pre">$(MODULE_NAME):$(VARIABLE_NAME)</span></tt>. The
module name can be a full dotted path. The variable name refers to a WSGI
callable that should be found in the specified module.</p>
<p>Example with test app:</p>
<pre class="literal-block"> <pre class="literal-block">
$ cd /path/to/gunicorn/examples/ $ cd examples
$ gunicorn -w 12 -k &quot;egg:gunicorn#eventlet&quot; websocket:app $ gunicorn --workers=2 test:app
</pre> </pre>
<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>
<div class="section" id="gunicorn-django">
<h1>gunicorn_django</h1>
<p>You might not have guessed it, but this script is used to server Django
applications. Basic usage:</p>
<pre class="literal-block">
$ gunicorn_django [OPTIONS] [SETTINGS_PATH]
</pre>
<p>By default <tt class="docutils literal">SETTINGS_PATH</tt> will look for <tt class="docutils literal">settings.py</tt> in the current
directory.</p>
<p>Example with your Django project:</p>
<pre class="literal-block">
$ cd path/to/yourdjangoproject
$ gunicorn_django --workers=2
</pre>
<p>Alternatively, you can install some Gunicorn magic directly into your Django
project and use the provided command for running the server.</p>
<p>First you'll need to add <tt class="docutils literal">gunicorn</tt> to your <tt class="docutils literal">INSTALLED_APPS</tt> in the settings
file:</p>
<pre class="literal-block">
INSTALLED_APPS = (
...
&quot;gunicorn&quot;,
)
</pre>
<p>Then you can run:</p>
<pre class="literal-block">
python manage.py run_gunicorn
</pre>
</div>
<div class="section" id="gunicorn-paster">
<h1>gunicorn_paster</h1>
<p>Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We
apologize for the lack of script name creativity. And some usage:</p>
<pre class="literal-block">
$ gunicorn_paster [OPTIONS] paste_config.ini
</pre>
<p>Simple example:</p>
<pre class="literal-block">
$ cd yourpasteproject
$ gunicorn_paste --workers=2 development.ini
</pre>
<p>If you're wanting to keep on keeping on with the usual paster serve command,
you can specify the Gunicorn server settings in your configuration file:</p>
<pre class="literal-block">
[server:main]
use = egg:gunicorn#main
host = 127.0.0.1
port = 5000
</pre>
<p>And then as per usual:</p>
<pre class="literal-block">
$ cd yourpasteproject
$ paster serve development.ini workers=2
</pre>
</div>
<div class="section" id="full-command-line-usage"> <div class="section" id="full-command-line-usage">
<h2>Full command line usage</h2> <h1>Full Command Line Usage</h1>
<pre class="literal-block"> <pre class="literal-block">
$ gunicorn --help $ gunicorn -h
Usage: gunicorn [OPTIONS] [APP_MODULE] Usage: gunicorn [OPTIONS] APP_MODULE
Options: Options:
-c CONFIG, --config=CONFIG -c CONFIG, --config=CONFIG
Config file. [none] Config file. [none]
-b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or -b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or
unix:/tmp/gunicorn.sock unix:/tmp/gunicorn.sock
-k WORKERCLASS, --worker-class=WORKERCLASS
The type of request processing to use
[egg:gunicorn#sync]
-w WORKERS, --workers=WORKERS -w WORKERS, --workers=WORKERS
Number of workers to spawn. [1] Number of workers to spawn. [1]
-k WORKER_CLASS, --worker-class=WORKER_CLASS
The type of request processing to use
[egg:gunicorn#sync]
-p PIDFILE, --pid=PIDFILE -p PIDFILE, --pid=PIDFILE
set the background PID FILE set the background PID FILE
-D, --daemon Run daemonized in the background. -D, --daemon Run daemonized in the background.
@ -98,8 +174,8 @@ Options:
-u USER, --user=USER Change worker user -u USER, --user=USER Change worker user
-g GROUP, --group=GROUP -g GROUP, --group=GROUP
Change worker group Change worker group
-n APP_NAME, --name=APP_NAME -n PROC_NAME, --name=PROC_NAME
Application name Process name
--log-level=LOGLEVEL Log level below which to silence messages. [info] --log-level=LOGLEVEL Log level below which to silence messages. [info]
--log-file=LOGFILE Log to a file. - equals stdout. [-] --log-file=LOGFILE Log to a file. - equals stdout. [-]
-d, --debug Debug mode. only 1 worker. -d, --debug Debug mode. only 1 worker.
@ -109,50 +185,6 @@ Options:
</pre> </pre>
</div> </div>
</div> </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>
<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>
<pre class="literal-block">
INSTALLED_APPS = (
...
&quot;gunicorn&quot;,
)
</pre>
<p>Then run:</p>
<pre class="literal-block">
python manage.py run_gunicorn
</pre>
</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>
<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>
<pre class="literal-block">
[server:main]
use = egg:gunicorn#main
host = 127.0.0.1
port = 5000
</pre>
<p>And then all you need to do is:</p>
<pre class="literal-block">
$ cd $yourpasteproject
$ paster serve development.ini workers=2
</pre>
</div>
</div>

4
doc/site/configuration.rst
View File

@ -4,7 +4,9 @@ title: The Configuration File
The Configuration File The Configuration File
====================== ======================
Gunicorn 0.5 introduced the ability to use a Python configuration file. Gunicorn will look for ``gunicorn.conf.py`` in the current working directory or what ever path is specified on the command line with the ``-c`` option. Gunicorn 0.5 introduced the ability to use a Python configuration file. Gunicorn
will look for ``gunicorn.conf.py`` in the current working directory or what ever
path is specified on the command line with the ``-c`` option.
Example gunicorn.conf.py Example gunicorn.conf.py
------------------------ ------------------------

58
doc/site/deployment.rst
View File

@ -4,44 +4,37 @@ title: Deployment
Production Setup Production Setup
================ ================
There are two general classes of configuration for Gunicorn. For the time Synchronous vs Asynchronous workers
being these will are referred to as "fast clients" and "sleepy applications". -----------------------------------
Fast Clients The default configuration of Gunicorn assumes that your application code is
------------ mostly CPU bound. The default worker class is a simple single threaded loop that
just processes requests as they are received. In general, most applications will
do just fine with this sort of configuration.
Generally speaking when we say "fast clients" what we really mean is that the This CPU bound assumption is why the default configuration needs to use a
time taken to process a client from the time a socket is accepted until buffering HTTP proxy like Nginx_ to protect the Gunicorn server. If we allowed
the time the socket is closed is well defined to be short. This means that direct connections a client could send a request slowly thus starving the server
clients are buffered by an upstream proxy (otherwise clients can send or of free worker processes (because they're all stuck waiting for data).
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. Example use-cases for asynchronous workers:
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 * Applications making long blocking calls (Ie, to external web services)
------------------- * Serving requests directly to the internet
* Streaming requests and responses
* Long polling
* Web sockets
* Comet
Any application that requires an undefined amount of time for client processing Basic Nginx Configuration
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
--------------------------------------
Although there are many HTTP proxies available, we strongly advise that you 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 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 buffers slow clients when you use default Gunicorn workers. Without this
buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks. buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
You can use slowloris_ to check if your proxy is behaving properly. You can use slowloris_ to check if your proxy is behaving properly.
An `example configuration`_ file for fast clients with Nginx_:: An `example configuration`_ file for fast clients with Nginx_::
worker_processes 1; worker_processes 1;
@ -95,8 +88,13 @@ An `example configuration`_ file for fast clients with Nginx_::
} }
} }
To handle sleepy applications, just add the line `proxy_buffering off;` under If you want to be able to handle streaming request/responses or other fancy
the proxy_redirect directive:: features like Comet, Long polling, or Web sockets, you need to turn off the
proxy buffering. **When you do this** you must run with one of the async worker
classes.
To turn off buffering, you only need to add ``proxy_buffering off;`` to your
``location`` block::
... ...
location / { location / {
@ -110,7 +108,7 @@ the proxy_redirect directive::
break; break;
} }
} }
.... ...
Working with Virtualenv Working with Virtualenv
----------------------- -----------------------

36
doc/site/faq.rst
View File

@ -4,21 +4,18 @@ title: FAQ
FAQ FAQ
=== ===
What is a fast client? How do I know which type of worker to use?
Generally speaking a fast client is something that is being served over the Test. Read the "Synchronous vs Asynchronous workers" section on the
local network or from the same machine. This generally would refer to requests deployment_ page. Test some more.
forwarded from an upstream proxy. Also see the above FAQ for what a fast
client is not.
What is a slow client? What types of workers are there?
A slow client is defined as a request that can take an arbitrary amount of These can all be used with the ``-k`` option and specifying them
time to send a request or read a response. Sometimes due to network as ``egg:gunicorn#$(NAME)`` where ``$(NAME)`` is chosen from this list.
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? * ``sync`` - The default synchronous worker
Applications that expect long request/response times and/or slow clients. * ``eventlet`` - Asynchronous workers based on Greenlets
Gunicorn use `Eventlet`_ or `Gevent`_ to manage concurrency. * ``gevent`` - Asynchronous workers based on Greenlets
* ``tornado`` - Asynchronous workers based on FriendFeed's Tornado server.
How might I test a proxy configuration? How might I test a proxy configuration?
Check out slowloris_ for a script that will generate significant slow Check out slowloris_ for a script that will generate significant slow
@ -30,7 +27,6 @@ How do I reload my application in Gunicorn?
$ kill -HUP masterpid $ kill -HUP masterpid
How do I increase or decrease the number of running workers dynamically? How do I increase or decrease the number of running workers dynamically?
To increase the worker count by one:: To increase the worker count by one::
@ -40,16 +36,20 @@ How do I increase or decrease the number of running workers dynamically?
$ kill -TTOU $masterpid $ kill -TTOU $masterpid
How can I figure out the best number of worker processes?
Start gunicorn with an approximate number of worker processes. Then use the
TTIN and/or TTOU signals to adjust the number of workers under load.
How do I set SCRIPT_NAME? How do I set SCRIPT_NAME?
By default ``SCRIPT_NAME`` is an empy string. The value could be set by By default ``SCRIPT_NAME`` is an empy string. The value could be set by
setting ``SCRIPT_NAME`` in the environment or as an HTTP header. setting ``SCRIPT_NAME`` in the environment or as an HTTP header.
How to name processes? How can I name processes?
You need to install the Python package setproctitle_. Then you can name You need to install the Python package setproctitle_. Then you can specify
your process with `-n` or just let the default. If you use a configuration a base process name on the command line (``-n``) or in the configuration
file you can set the process name with the proc_name option. file.
.. _deployment: http://gunicorn.org/deployment.html
.. _slowloris: http://ha.ckers.org/slowloris/ .. _slowloris: http://ha.ckers.org/slowloris/
.. _setproctitle: http://pypi.python.org/pypi/setproctitle .. _setproctitle: http://pypi.python.org/pypi/setproctitle
.. _Eventlet: http://eventlet.net .. _Eventlet: http://eventlet.net

19
doc/site/index.rst
View File

@ -3,18 +3,19 @@ template: index.html
Green Unicorn Green Unicorn
============= =============
Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve Gunicorn 'Green Unicorn' is a WSGI_ HTTP Server for UNIX. It's a pre-fork
`fast clients`_ or `sleepy applications`_. worker model ported from Ruby's Unicorn_ project. The Gunicorn server is
broadly compatible with various web frameworks, simply implemented, light
on server resource usage, and fairly speedy.
This is a port of Unicorn_ in Python. Meet us on the `#gunicorn IRC channel`_ Feel free to join us in `#gunicorn`_ on freenode_.
on Freenode_.
Gunicorn is released under the MIT License. See the LICENSE_ for more details. Gunicorn is released under the MIT License. See the LICENSE_ for more details.
Features Features
-------- --------
- Designed for Unix, WSGI_, fast clients and sleepy applications. - Designed for Unix.
- Compatible with Python 2.x (>= 2.5) - Compatible with Python 2.x (>= 2.5)
- Easy integration with Django_ and Paster_ compatible applications - Easy integration with Django_ and Paster_ compatible applications
(`Pylons`_, `TurboGears 2`_, ...) (`Pylons`_, `TurboGears 2`_, ...)
@ -35,15 +36,13 @@ Applications
(`Pylons`_, `TurboGears 2`_, ...) (`Pylons`_, `TurboGears 2`_, ...)
* Websockets (see the example_ or the screencast_) * Websockets (see the example_ or the screencast_)
* Reverse proxy implementation (with `Restkit WSGI proxy`_) * Reverse proxy implementation (with `Restkit WSGI proxy`_)
* Comet
* Long Polling * Long Polling
* Comet
.. _WSGI: http://www.python.org/dev/peps/pep-0333/ .. _WSGI: http://www.python.org/dev/peps/pep-0333/
.. _`fast clients`: faq.html
.. _`sleepy applications`: faq.html
.. _Unicorn: http://unicorn.bogomips.org/ .. _Unicorn: http://unicorn.bogomips.org/
.. _`#gunicorn IRC channel`: http://webchat.freenode.net/?channels=gunicorn .. _`#gunicorn`: http://webchat.freenode.net/?channels=gunicorn
.. _Freenode: http://freenode.net .. _freenode: http://freenode.net
.. _LICENSE: http://github.com/benoitc/gunicorn/blob/master/LICENSE .. _LICENSE: http://github.com/benoitc/gunicorn/blob/master/LICENSE
.. _Gunicorn: http://gunicorn.org .. _Gunicorn: http://gunicorn.org
.. _Django: http://djangoproject.com .. _Django: http://djangoproject.com

40
doc/site/installation.rst
View File

@ -7,7 +7,7 @@ Installation
Requirements Requirements
------------ ------------
- **Python 2.5 or newer** (Python 3.x will be supported soon) - **Python 2.x >= 2.5** (Python 3.x will be supported soon)
- setuptools >= 0.6c6 - setuptools >= 0.6c6
- nosetests (for the test suite only) - nosetests (for the test suite only)
@ -27,7 +27,7 @@ To install or upgrade to the latest released version of Gunicorn::
Installing from source Installing from source
---------------------- ----------------------
You can install Gunicorn from source as simply as you would install any other You can install Gunicorn from source just as you would install any other
Python package. Gunicorn uses setuptools which will automatically fetch all Python package. Gunicorn uses setuptools which will automatically fetch all
dependencies (including setuptools itself). dependencies (including setuptools itself).
@ -39,11 +39,8 @@ fetch them with git_::
$ git clone git://github.com/benoitc/gunicorn.git $ git clone git://github.com/benoitc/gunicorn.git
.. _`GitHub Downloads`: http://github.com/benoitc/gunicorn/downloads
.. _git: http://git-scm.com/
Installation Installation
++++++++++++++++ ++++++++++++
:: ::
@ -56,33 +53,30 @@ well as make changes to the source::
$ python setup.py develop $ python setup.py develop
Installation requirements for sleepy application handling Enabling async workers
--------------------------------------------------------- ----------------------
If you want to handle `sleepy application <faq.html>`_ you will need to install You may also want to install Eventlet_ or Gevent_ if you expect that your
`Eventlet`_ or `Gevent`_. application code may need to pause for extended periods of time during
request processing. Check out the FAQ_ for more information on when you'll
want to consider one of the alternate worker types.
To install eventlet:: To install eventlet::
$ easy_install -U eventlet $ easy_install -U eventlet
Replace ``eventlet`` with ``gevent`` if you want to use the ``gevent`` Replace ``eventlet`` with ``gevent`` to use to the ``gevent`` based workers.
arbiter.
You can now launch gunicorn with Eventlet or Gevent arbiter, see
`usage <usage.html>`_ for more information.
.. note:: .. note::
If ``eventlet`` or ``gevent`` fails to install for you, its most likely If you encounter errors when compiling the extensions for Eventlet_ or
due to an out of date libev_ library. You'll need to download and install Gevent_ you most likely need to install a newer version of libev_.
a newer version for either of those to modules to work properly.
Installing on Ubuntu/Debian systems Installing on Ubuntu/Debian systems
----------------------------------- -----------------------------------
If you use `Ubuntu <http://www.ubuntu.com/>`_ karmic, you can update your If you use Ubuntu_ karmic, you can update your system with packages from
system with packages from our PPA_ by adding ``ppa:bchesneau/gunicorn`` our PPA_ by adding ``ppa:bchesneau/gunicorn`` to your system's Software
to your system's Software Sources. Sources.
Or this PPA can be added to your system manually by copying the lines below Or this PPA can be added to your system manually by copying the lines below
and adding them to your system's software sources:: and adding them to your system's software sources::
@ -98,7 +92,11 @@ Fingerprint::
49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06 49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06
.. _`GitHub Downloads`: http://github.com/benoitc/gunicorn/downloads
.. _FAQ: faq.html
.. _git: http://git-scm.com/
.. _Eventlet: http://eventlet.net .. _Eventlet: http://eventlet.net
.. _Gevent: http://gevent.org .. _Gevent: http://gevent.org
.. _libev: http://software.schmorp.de/pkg/libev.html .. _libev: http://software.schmorp.de/pkg/libev.html
.. _Ubuntu: http://www.ubuntu.com/
.. _PPA: https://launchpad.net/~bchesneau/+archive/gunicorn .. _PPA: https://launchpad.net/~bchesneau/+archive/gunicorn

31
doc/site/news.rst
View File

@ -15,14 +15,15 @@ News
0.8.0 / 2010-04-22 0.8.0 / 2010-04-22
------------------ ------------------
- Refactored Worker management for better async support. Now use the -k option to set the type of request processing to use - Refactored Worker management for better async support. Now use the -k option
- Added support for `Tornado <http://www.tornadoweb.org/>`_ to set the type of request processing to use
- Added support for Tornado_
0.7.2 / 2010-04-15 0.7.2 / 2010-04-15
------------------ ------------------
- Added --spew option to help debugging (install a Trace hook) - Added --spew option to help debugging (installs a system trace hook)
- Some fixes in async arbiters - Some fixes in async arbiters
- Fix a bug in start_response on error - Fix a bug in start_response on error
@ -34,16 +35,16 @@ News
0.7.0 / 2010-03-26 0.7.0 / 2010-03-26
------------------ ------------------
- Added support for `sleepy applications <faq.html>`_ using Eventlet_ or Gevent_. - Added support for Eventlet_ and Gevent_ based workers.
- Added Websockets_ support - Added Websockets_ support
- Fix Chunked Encoding - Fix Chunked Encoding
- Fix SIGWINCH on OpenBSD_ - Fix SIGWINCH on OpenBSD_
- Fix `PEP 333 <http://www.python.org/dev/peps/pep-0333/>`_ compliance for the write callable. - Fix `PEP 333`_ compliance for the write callable.
0.6.5 / 2010-03-11 0.6.5 / 2010-03-11
------------------ ------------------
- Fix pidfile - Fix pidfile handling
- Fix Exception Error - Fix Exception Error
0.6.4 / 2010-03-08 0.6.4 / 2010-03-08
@ -56,14 +57,15 @@ News
------------------ ------------------
* Make HTTP parsing faster. * Make HTTP parsing faster.
* Some fixes (see `logs <http://github.com/benoitc/gunicorn/commits/master>`_) * Various bug fixes
0.6.2 / 2010-03-01 0.6.2 / 2010-03-01
------------------ ------------------
* Added support for chunked response. * Added support for chunked response.
* Added proc_name option to the config file. * Added proc_name option to the config file.
* Improved the HTTP parser. It now uses buffers instead of strings to store temporary data. * Improved the HTTP parser. It now uses buffers instead of strings to store
temporary data.
* Improved performance when sending responses. * Improved performance when sending responses.
* Workers are now murdered by age (the oldest is killed first). * Workers are now murdered by age (the oldest is killed first).
@ -71,21 +73,22 @@ News
0.6.1 / 2010-02-24 0.6.1 / 2010-02-24
------------------ ------------------
* Added gunicorn config file support for django admin command * Added gunicorn config file support for Django admin command
* Fix gunicorn config file. -c was broken. * Fix gunicorn config file. -c was broken.
* Removed TTIN/TTOU from workers which blocked other signals. * Removed TTIN/TTOU from workers which blocked other signals.
0.6 / 2010-02-22 0.6 / 2010-02-22
------------------ ------------------
* Added setproctitle * Added setproctitle support
* Change privilege switch behaviour. We now work like NGINX, master keeps the permissions, new uid/gid permissions are only set for workers. * Change privilege switch behavior. We now work like NGINX, master keeps the
permissions, new uid/gid permissions are only set for workers.
0.5.1 / 2010-02-22 0.5.1 / 2010-02-22
------------------ ------------------
* Fix umask * Fix umask
* Added debian packaging * Added Debian packaging
0.5 / 2010-02-20 0.5 / 2010-02-20
---------------- ----------------
@ -98,10 +101,12 @@ News
* Added umask option * Added umask option
* Added SCRIPT_NAME support * Added SCRIPT_NAME support
* Better support of some exotic settings for Django projects * Better support of some exotic settings for Django projects
* Better support of Paste-compatible applicatins * Better support of Paste-compatible applications
* Some refactoring to make the code easier to hack * Some refactoring to make the code easier to hack
* Allow multiple keys in request and response headers * Allow multiple keys in request and response headers
.. _Tornado: http://www.tornadoweb.org/
.. _`PEP 333`: http://www.python.org/dev/peps/pep-0333/
.. _Eventlet: http://eventlet.net .. _Eventlet: http://eventlet.net
.. _Gevent: http://gevent.org .. _Gevent: http://gevent.org
.. _OpenBSD: http://openbsd.org .. _OpenBSD: http://openbsd.org

31
doc/site/tuning.rst
View File

@ -7,7 +7,10 @@ Tuning
Unicorn Configuration Unicorn Configuration
--------------------- ---------------------
DO NOT scale the number of workers to the number of clients you expect to have. Gunicorn should only need 4-12 worker processes to handle hundreds or thousands of simultaneous clients. Remember, Gunicorn is **NOT** designed for serving slow clients, that's the job of Nginx_. DO NOT scale the number of workers to the number of clients you expect to have.
Gunicorn should only need 4-12 worker processes to handle hundreds or thousands
of simultaneous clients. Remember, Gunicorn is **NOT** designed for serving slow
clients, that's the job of Nginx_.
See Configuration_ for a more thorough description of the available parameters. See Configuration_ for a more thorough description of the available parameters.
@ -17,14 +20,22 @@ See Configuration_ for a more thorough description of the available parameters.
Kernel Parameters Kernel Parameters
----------------- -----------------
When dealing with large numbers of concurrent connections there are a handful of kernel parameters that you might need to adjust. Generally these should only affect sites with a very large concurrent load. These parameters are not specific to Gunicorn, they would apply to any sort of network server you may be running. When dealing with large numbers of concurrent connections there are a handful of
kernel parameters that you might need to adjust. Generally these should only
affect sites with a very large concurrent load. These parameters are not
specific to Gunicorn, they would apply to any sort of network server you may be
running.
The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use slightly different flags. Always reference the appropriate man pages if uncertain. The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use
slightly different flags. Always reference the appropriate man pages if
uncertain.
File Descriptor Limits File Descriptor Limits
++++++++++++++++++++++ ++++++++++++++++++++++
One of the first settings that usually needs to be bumped is the maximum number of open file descriptors for a given process. For the confused out there, remember that Unices treat sockets as files. One of the first settings that usually needs to be bumped is the maximum number
of open file descriptors for a given process. For the confused out there,
remember that Unices treat sockets as files.
:: ::
@ -33,7 +44,9 @@ One of the first settings that usually needs to be bumped is the maximum number
Listen Queue Size Listen Queue Size
+++++++++++++++++ +++++++++++++++++
Listening sockets have an associated queue of incoming connections that are waiting to be accepted. If you happen to have a stampede of clients that fill up this queue new connections will eventually start getting dropped. Listening sockets have an associated queue of incoming connections that are
waiting to be accepted. If you happen to have a stampede of clients that fill up
this queue new connections will eventually start getting dropped.
:: ::
@ -42,9 +55,13 @@ Listening sockets have an associated queue of incoming connections that are wait
Ephemeral Port Range Ephemeral Port Range
++++++++++++++++++++ ++++++++++++++++++++
After a socket is closed it enters the TIME_WAIT state. This can become an issue after a prolonged burst of client activity. Eventually the ephemeral port range is exhausted which can cause new connections to stall while they wait for a valid port. After a socket is closed it enters the TIME_WAIT state. This can become an issue
after a prolonged burst of client activity. Eventually the ephemeral port range
is exhausted which can cause new connections to stall while they wait for a
valid port.
This setting is generally only required on machines that are being used to test a network server. This setting is generally only required on machines that are being used to test
a network server.
:: ::

186
doc/site/usage.rst
View File

@ -1,53 +1,129 @@
template: doc.html template: doc.html
title: Command Line Usage title: Command Line Usage
Command Line Usage Usage
================== =====
- `WSGI applications`_ After installing Gunicorn you will have access to three command line scripts
- `Django projects`_ that can be used for serving the various supported web frameworks: ``gunicorn``,
- `Paste-compatible projects`_ ``gunicorn_django``, and ``gunicorn_paster``.
WSGI applications Commonly Used Arguments
----------------- +++++++++++++++++++++++
To launch the `example application`_ packaged with Gunicorn:: * ``-c CONFIG, --config=CONFIG`` - Specify the path to a `config file`_
* ``-b BIND, --bind=BIND`` - Specify a server socket to bind. Server sockets
can be any of ``$(HOST)``, ``$(HOST):$(PORT)``, or ``unix:$(PATH)``.
An IP is a valid ``$(HOST)``.
* ``-w WORKERS, --workers=WORKERS`` - The number of worker processes. This
number should generally be between 2-4 workers per core in the server.
Check the FAQ_ for ideas on tuning this parameter.
* ``-k WORKERCLASS, --worker-class=WORKERCLASS`` - The type of worker process
to run. You'll definitely want to read the `production page`_ for the
implications of this parameter. You can set this to ``egg:gunicorn#$(NAME)``
where ``$(NAME)`` is one of ``sync``, ``eventlet``, ``gevent``, or
``tornado``. ``sync`` is the default.
* ``-n APP_NAME, --name=APP_NAME`` - If setproctitle_ is installed you can
adjust the name of Gunicorn process as they appear in the process system
table (which affects tools like ``ps`` and ``top``).
$ cd /path/to/gunicorn/examples/ There are various other parameters that affect user privileges, logging, etc.
$ gunicorn -w 2 test:app You can see the complete list at the bottom of this page or as expected with::
The module ``test:app`` specifies the complete module name and WSGI callable. $ gunicorn -h
You can replace it with anything that is available on your ``PYTHONPATH`` like
such::
$ cd ~/ gunicorn
$ gunicorn -w 12 awesomeproject.wsgi.main:main_app ++++++++
To launch the `websocket example`_ application using `Eventlet`_:: The first and most basic script is used to server 'bare' WSGI applications
that don't require a translation layer. Basic usage::
$ cd /path/to/gunicorn/examples/ $ gunicorn [OPTIONS] APP_MODULE
$ gunicorn -w 12 -k "egg:gunicorn#eventlet" websocket:app
You should then be able to visit ``http://localhost:8000`` to see output. Where ``APP_MODULE`` is of the pattern ``$(MODULE_NAME):$(VARIABLE_NAME)``. The
module name can be a full dotted path. The variable name refers to a WSGI
callable that should be found in the specified module.
Full command line usage Example with test app::
$ cd examples
$ gunicorn --workers=2 test:app
gunicorn_django
+++++++++++++++
You might not have guessed it, but this script is used to server Django
applications. Basic usage::
$ gunicorn_django [OPTIONS] [SETTINGS_PATH]
By default ``SETTINGS_PATH`` will look for ``settings.py`` in the current
directory.
Example with your Django project::
$ cd path/to/yourdjangoproject
$ gunicorn_django --workers=2
Alternatively, you can install some Gunicorn magic directly into your Django
project and use the provided command for running the server.
First you'll need to add ``gunicorn`` to your ``INSTALLED_APPS`` in the settings
file::
INSTALLED_APPS = (
...
"gunicorn",
)
Then you can run::
python manage.py run_gunicorn
gunicorn_paster
+++++++++++++++
Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We
apologize for the lack of script name creativity. And some usage::
$ gunicorn_paster [OPTIONS] paste_config.ini
Simple example::
$ cd yourpasteproject
$ gunicorn_paste --workers=2 development.ini
If you're wanting to keep on keeping on with the usual paster serve command,
you can specify the Gunicorn server settings in your configuration file::
[server:main]
use = egg:gunicorn#main
host = 127.0.0.1
port = 5000
And then as per usual::
$ cd yourpasteproject
$ paster serve development.ini workers=2
Full Command Line Usage
+++++++++++++++++++++++ +++++++++++++++++++++++
:: ::
$ gunicorn --help $ gunicorn -h
Usage: gunicorn [OPTIONS] [APP_MODULE] Usage: gunicorn [OPTIONS] APP_MODULE
Options: Options:
-c CONFIG, --config=CONFIG -c CONFIG, --config=CONFIG
Config file. [none] Config file. [none]
-b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or -b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or
unix:/tmp/gunicorn.sock unix:/tmp/gunicorn.sock
-k WORKERCLASS, --worker-class=WORKERCLASS
The type of request processing to use
[egg:gunicorn#sync]
-w WORKERS, --workers=WORKERS -w WORKERS, --workers=WORKERS
Number of workers to spawn. [1] Number of workers to spawn. [1]
-k WORKER_CLASS, --worker-class=WORKER_CLASS
The type of request processing to use
[egg:gunicorn#sync]
-p PIDFILE, --pid=PIDFILE -p PIDFILE, --pid=PIDFILE
set the background PID FILE set the background PID FILE
-D, --daemon Run daemonized in the background. -D, --daemon Run daemonized in the background.
@ -56,8 +132,8 @@ Full command line usage
-u USER, --user=USER Change worker user -u USER, --user=USER Change worker user
-g GROUP, --group=GROUP -g GROUP, --group=GROUP
Change worker group Change worker group
-n APP_NAME, --name=APP_NAME -n PROC_NAME, --name=PROC_NAME
Application name Process name
--log-level=LOGLEVEL Log level below which to silence messages. [info] --log-level=LOGLEVEL Log level below which to silence messages. [info]
--log-file=LOGFILE Log to a file. - equals stdout. [-] --log-file=LOGFILE Log to a file. - equals stdout. [-]
-d, --debug Debug mode. only 1 worker. -d, --debug Debug mode. only 1 worker.
@ -65,56 +141,8 @@ Full command line usage
--version show program's version number and exit --version show program's version number and exit
-h, --help show this help message and exit -h, --help show this help message and exit
Django Projects
---------------
`Django`_ projects can be handled easily by Gunicorn using the .. _FAQ: faq.html
``gunicorn_django`` command:: .. _`production page`: deployment.html
.. _`config file`: configuration.html
$ cd $yourdjangoproject .. _setproctitle: http://pypi.python.org/pypi/setproctitle/
$ gunicorn_django --workers=2
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::
INSTALLED_APPS = (
...
"gunicorn",
)
Then run::
python manage.py run_gunicorn
Paste-compatible projects
-------------------------
For `Paste`_ compatible projects (`Pylons`_, `TurboGears 2`_, ...) use the
``gunicorn_paste`` command::
$ cd $yourpasteproject
$ gunicorn_paste --workers=2 development.ini
To use the ``paster`` command add a sever section for Gunicorn::
[server:main]
use = egg:gunicorn#main
host = 127.0.0.1
port = 5000
And then all you need to do is::
$ cd $yourpasteproject
$ 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/
.. _Pylons: http://pylonshq.com/
.. _Turbogears 2: http://turbogears.org/2.0/
.. _Eventlet: http://eventlet.net