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">
<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">
<h1>Example gunicorn.conf.py</h1>
<pre class="literal-block">

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

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

60
doc/htdocs/deployment.html
View File

@ -49,35 +49,33 @@
<div class="document" id="production-setup">
<h1 class="title">Production Setup</h1>
<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 class="section" id="synchronous-vs-asynchronous-workers">
<h1>Synchronous vs Asynchronous workers</h1>
<p>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.</p>
<p>This CPU bound assumption is why the default configuration needs to use a
buffering HTTP proxy like <a class="reference external" href="http://www.nginx.org">Nginx</a> to protect the Gunicorn server. If we allowed
direct connections a client could send a request slowly thus starving the server
of free worker processes (because they're all stuck waiting for data).</p>
<p>Example use-cases for asynchronous workers:</p>
<blockquote>
<ul class="simple">
<li>Applications making long blocking calls (Ie, to external web services)</li>
<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 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>
<div class="section" id="basic-nginx-configuration">
<h1>Basic Nginx Configuration</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
buffers slow clients when you use default Gunicorn workers. 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>
@ -133,8 +131,12 @@ http {
}
}
</pre>
<p>To handle sleepy applications, just add the line <cite>proxy_buffering off;</cite> under
the proxy_redirect directive:</p>
<p>If you want to be able to handle streaming request/responses or other fancy
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">
...
location / {
@ -148,7 +150,7 @@ location / {
break;
}
}
....
...
</pre>
</div>
<div class="section" id="working-with-virtualenv">

37
doc/htdocs/faq.html
View File

@ -50,19 +50,19 @@
<div class="document" id="faq">
<h1 class="title">FAQ</h1>
<dl class="docutils">
<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>
<dt>How do I know which type of worker to use?</dt>
<dd>Test. Read the &quot;Synchronous vs Asynchronous workers&quot; section on the
<a class="reference external" href="http://gunicorn.org/deployment.html">deployment</a> page. Test some more.</dd>
<dt>What types of workers are there?</dt>
<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
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>
<ul class="last simple">
<li><tt class="docutils literal">sync</tt> - The default synchronous worker</li>
<li><tt class="docutils literal">eventlet</tt> - Asynchronous workers based on Greenlets</li>
<li><tt class="docutils literal">gevent</tt> - Asynchronous workers based on Greenlets</li>
<li><tt class="docutils literal">tornado</tt> - Asynchronous workers based on FriendFeed's Tornado server.</li>
</ul>
</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,13 +83,16 @@ $ kill -TTIN $masterpid
$ kill -TTOU $masterpid
</pre>
</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>
<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>
<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
file you can set the process name with the proc_name option.</dd>
<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 specify
a base process name on the command line (<tt class="docutils literal"><span class="pre">-n</span></tt>) or in the configuration
file.</dd>
</dl>
</div>

13
doc/htdocs/index.html
View File

@ -47,15 +47,16 @@
<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>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
worker model ported from Ruby's <a class="reference external" href="http://unicorn.bogomips.org/">Unicorn</a> project. The Gunicorn server is
broadly compatible with various web frameworks, simply implemented, light
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>
<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>Designed for Unix.</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>
@ -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>
<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>Comet</li>
<li>Long Polling</li>
<li>Comet</li>
</ul>
</div>
</div>

30
doc/htdocs/installation.html
View File

@ -52,7 +52,7 @@
<div class="section" id="requirements">
<h1>Requirements</h1>
<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>nosetests (for the test suite only)</li>
</ul>
@ -72,7 +72,7 @@ $ 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
<p>You can install Gunicorn from source just 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">
@ -97,30 +97,28 @@ $ python setup.py develop
</pre>
</div>
</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>
<div class="section" id="enabling-async-workers">
<h1>Enabling async workers</h1>
<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
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>
<pre class="literal-block">
$ easy_install -U eventlet
</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>
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>
<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>
<div class="note">
<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
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>
<p class="last">If you encounter errors when compiling the extensions for <a class="reference external" href="http://eventlet.net">Eventlet</a> or
<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>
</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 <tt class="docutils literal">ppa:bchesneau/gunicorn</tt>
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">ppa:bchesneau/gunicorn</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">

25
doc/htdocs/news.html
View File

@ -61,14 +61,15 @@
<div class="section" id="id2">
<h1>0.8.0 / 2010-04-22</h1>
<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>
</ul>
</div>
<div class="section" id="id3">
<h1>0.7.2 / 2010-04-15</h1>
<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>Fix a bug in start_response on error</li>
</ul>
@ -82,7 +83,7 @@
<div class="section" id="id5">
<h1>0.7.0 / 2010-03-26</h1>
<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>Fix Chunked Encoding</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">
<h1>0.6.5 / 2010-03-11</h1>
<ul class="simple">
<li>Fix pidfile</li>
<li>Fix pidfile handling</li>
<li>Fix Exception Error</li>
</ul>
</div>
@ -107,7 +108,7 @@
<h1>0.6.3 / 2010-03-07</h1>
<ul class="simple">
<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>
</div>
<div class="section" id="id9">
@ -115,7 +116,8 @@
<ul class="simple">
<li>Added support for chunked response.</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>Workers are now murdered by age (the oldest is killed first).</li>
</ul>
@ -123,7 +125,7 @@
<div class="section" id="id10">
<h1>0.6.1 / 2010-02-24</h1>
<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>Removed TTIN/TTOU from workers which blocked other signals.</li>
</ul>
@ -131,15 +133,16 @@
<div class="section" id="id11">
<h1>0.6 / 2010-02-22</h1>
<ul class="simple">
<li>Added setproctitle</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>Added setproctitle support</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>
</div>
<div class="section" id="id12">
<h1>0.5.1 / 2010-02-22</h1>
<ul class="simple">
<li>Fix umask</li>
<li>Added debian packaging</li>
<li>Added Debian packaging</li>
</ul>
</div>
<div class="section" id="id13">
@ -153,7 +156,7 @@
<li>Added umask option</li>
<li>Added SCRIPT_NAME support</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>Allow multiple keys in request and response headers</li>
</ul>

31
doc/htdocs/tuning.html
View File

@ -51,31 +51,48 @@
<h1 class="title">Tuning</h1>
<div class="section" id="unicorn-configuration">
<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>
</div>
<div class="section" id="kernel-parameters">
<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>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>
<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>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">
<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">
$ sudo ulimit -n 2048
</pre>
</div>
<div class="section" id="listen-queue-size">
<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">
$ sudo sysctl -w kern.ipc.somaxconn=&quot;2048&quot;
</pre>
</div>
<div class="section" id="ephemeral-port-range">
<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>This setting is generally only required on machines that are being used to test a network server.</p>
<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>This setting is generally only required on machines that are being used to test
a network server.</p>
<pre class="literal-block">
$ sudo sysctl -w net.inet.ip.portrange.first=&quot;8048&quot;
</pre>

174
doc/htdocs/usage.html
View File

@ -47,49 +47,125 @@
</ul>
</div>
<div class="document" id="command-line-usage">
<h1 class="title">Command Line Usage</h1>
<div class="document" id="usage">
<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">
<li><a class="reference internal" href="#wsgi-applications">WSGI applications</a></li>
<li><a class="reference internal" href="#django-projects">Django projects</a></li>
<li><a class="reference internal" href="#paste-compatible-projects">Paste-compatible projects</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><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
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>
<div class="section" id="wsgi-applications">
<h1>WSGI applications</h1>
<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>
</blockquote>
<p>There are various other parameters that affect user privileges, logging, etc.
You can see the complete list at the bottom of this page or as expected with:</p>
<pre class="literal-block">
$ cd /path/to/gunicorn/examples/
$ gunicorn -w 2 test:app
$ gunicorn -h
</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>
</div>
<div class="section" id="gunicorn">
<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">
$ cd ~/
$ gunicorn -w 12 awesomeproject.wsgi.main:main_app
$ gunicorn [OPTIONS] APP_MODULE
</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">
$ cd /path/to/gunicorn/examples/
$ gunicorn -w 12 -k &quot;egg:gunicorn#eventlet&quot; websocket:app
$ cd examples
$ gunicorn --workers=2 test:app
</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">
<h2>Full command line usage</h2>
<h1>Full Command Line Usage</h1>
<pre class="literal-block">
$ gunicorn --help
Usage: gunicorn [OPTIONS] [APP_MODULE]
$ gunicorn -h
Usage: gunicorn [OPTIONS] APP_MODULE
Options:
-c CONFIG, --config=CONFIG
Config file. [none]
-b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or
unix:/tmp/gunicorn.sock
-k WORKERCLASS, --worker-class=WORKERCLASS
The type of request processing to use
[egg:gunicorn#sync]
-w WORKERS, --workers=WORKERS
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
set the background PID FILE
-D, --daemon Run daemonized in the background.
@ -98,8 +174,8 @@ Options:
-u USER, --user=USER Change worker user
-g GROUP, --group=GROUP
Change worker group
-n APP_NAME, --name=APP_NAME
Application name
-n PROC_NAME, --name=PROC_NAME
Process 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.
@ -109,50 +185,6 @@ Options:
</pre>
</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
======================
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
------------------------

58
doc/site/deployment.rst
View File

@ -4,44 +4,37 @@ title: Deployment
Production Setup
================
There are two general classes of configuration for Gunicorn. For the time
being these will are referred to as "fast clients" and "sleepy applications".
Synchronous vs Asynchronous workers
-----------------------------------
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
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).
This CPU bound assumption is why the default configuration needs to use a
buffering HTTP proxy like Nginx_ to protect the Gunicorn server. If we allowed
direct connections a client could send a request slowly thus starving the server
of free worker processes (because they're all stuck waiting for data).
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).
Example use-cases for asynchronous workers:
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
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
--------------------------------------
Basic Nginx Configuration
-------------------------
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
buffers slow clients when you use default Gunicorn workers. 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;
@ -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
the proxy_redirect directive::
If you want to be able to handle streaming request/responses or other fancy
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 / {
@ -110,7 +108,7 @@ the proxy_redirect directive::
break;
}
}
....
...
Working with Virtualenv
-----------------------

40
doc/site/faq.rst
View File

@ -4,21 +4,18 @@ title: FAQ
FAQ
===
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.
How do I know which type of worker to use?
Test. Read the "Synchronous vs Asynchronous workers" section on the
deployment_ page. Test some more.
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.
What types of workers are there?
These can all be used with the ``-k`` option and specifying them
as ``egg:gunicorn#$(NAME)`` where ``$(NAME)`` is chosen from this list.
* ``sync`` - The default synchronous worker
* ``eventlet`` - Asynchronous workers based on Greenlets
* ``gevent`` - Asynchronous workers based on Greenlets
* ``tornado`` - Asynchronous workers based on FriendFeed's Tornado server.
How might I test a proxy configuration?
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
How do I increase or decrease the number of running workers dynamically?
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
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?
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.
How to name processes?
You need to install the Python package setproctitle_. Then you can name
your process with `-n` or just let the default. If you use a configuration
file you can set the process name with the proc_name option.
How can I name processes?
You need to install the Python package setproctitle_. Then you can specify
a base process name on the command line (``-n``) or in the configuration
file.
.. _deployment: http://gunicorn.org/deployment.html
.. _slowloris: http://ha.ckers.org/slowloris/
.. _setproctitle: http://pypi.python.org/pypi/setproctitle
.. _Eventlet: http://eventlet.net

19
doc/site/index.rst
View File

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

42
doc/site/installation.rst
View File

@ -7,7 +7,7 @@ Installation
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
- nosetests (for the test suite only)
@ -27,7 +27,7 @@ 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
You can install Gunicorn from source just as you would install any other
Python package. Gunicorn uses setuptools which will automatically fetch all
dependencies (including setuptools itself).
@ -39,11 +39,8 @@ fetch them with git_::
$ git clone git://github.com/benoitc/gunicorn.git
.. _`GitHub Downloads`: http://github.com/benoitc/gunicorn/downloads
.. _git: http://git-scm.com/
Installation
++++++++++++++++
++++++++++++
::
@ -56,33 +53,30 @@ well as make changes to the source::
$ 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
`Eventlet`_ or `Gevent`_.
You may also want to install Eventlet_ or Gevent_ if you expect that your
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::
$ easy_install -U eventlet
Replace ``eventlet`` with ``gevent`` if you want to use the ``gevent``
arbiter.
$ easy_install -U eventlet
You can now launch gunicorn with Eventlet or Gevent arbiter, see
`usage <usage.html>`_ for more information.
Replace ``eventlet`` with ``gevent`` to use to the ``gevent`` based workers.
.. 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.
If you encounter errors when compiling the extensions for Eventlet_ or
Gevent_ you most likely need to install a newer version of libev_.
Installing on Ubuntu/Debian systems
-----------------------------------
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.
If you use Ubuntu_ 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::
@ -98,7 +92,11 @@ Fingerprint::
49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06
.. _`GitHub Downloads`: http://github.com/benoitc/gunicorn/downloads
.. _FAQ: faq.html
.. _git: http://git-scm.com/
.. _Eventlet: http://eventlet.net
.. _Gevent: http://gevent.org
.. _libev: http://software.schmorp.de/pkg/libev.html
.. _Ubuntu: http://www.ubuntu.com/
.. _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
------------------
- Refactored Worker management for better async support. Now use the -k option to set the type of request processing to use
- Added support for `Tornado <http://www.tornadoweb.org/>`_
- Refactored Worker management for better async support. Now use the -k option
to set the type of request processing to use
- Added support for Tornado_
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
- Fix a bug in start_response on error
@ -34,16 +35,16 @@ News
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
- Fix Chunked Encoding
- 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
------------------
- Fix pidfile
- Fix pidfile handling
- Fix Exception Error
0.6.4 / 2010-03-08
@ -56,14 +57,15 @@ News
------------------
* Make HTTP parsing faster.
* Some fixes (see `logs <http://github.com/benoitc/gunicorn/commits/master>`_)
* Various bug fixes
0.6.2 / 2010-03-01
------------------
* Added support for chunked response.
* 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.
* Workers are now murdered by age (the oldest is killed first).
@ -71,21 +73,22 @@ News
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.
* Removed TTIN/TTOU from workers which blocked other signals.
0.6 / 2010-02-22
------------------
* Added setproctitle
* Change privilege switch behaviour. We now work like NGINX, master keeps the permissions, new uid/gid permissions are only set for workers.
* Added setproctitle support
* 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
------------------
* Fix umask
* Added debian packaging
* Added Debian packaging
0.5 / 2010-02-20
----------------
@ -98,10 +101,12 @@ News
* Added umask option
* Added SCRIPT_NAME support
* 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
* 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
.. _Gevent: http://gevent.org
.. _OpenBSD: http://openbsd.org

31
doc/site/tuning.rst
View File

@ -7,7 +7,10 @@ Tuning
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.
@ -17,14 +20,22 @@ See Configuration_ for a more thorough description of the available 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
++++++++++++++++++++++
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
+++++++++++++++++
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
++++++++++++++++++++
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.
::

198
doc/site/usage.rst
View File

@ -1,120 +1,148 @@
template: doc.html
title: Command Line Usage
Command Line Usage
==================
Usage
=====
- `WSGI applications`_
- `Django projects`_
- `Paste-compatible projects`_
After installing Gunicorn you will have access to three command line scripts
that can be used for serving the various supported web frameworks: ``gunicorn``,
``gunicorn_django``, and ``gunicorn_paster``.
WSGI applications
-----------------
To launch the `example application`_ packaged with Gunicorn::
$ cd /path/to/gunicorn/examples/
$ gunicorn -w 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::
$ cd ~/
$ gunicorn -w 12 awesomeproject.wsgi.main:main_app
To launch the `websocket example`_ application using `Eventlet`_::
$ cd /path/to/gunicorn/examples/
$ gunicorn -w 12 -k "egg:gunicorn#eventlet" websocket:app
You should then be able to visit ``http://localhost:8000`` to see output.
Full command line usage
Commonly Used Arguments
+++++++++++++++++++++++
::
* ``-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``).
$ gunicorn --help
Usage: gunicorn [OPTIONS] [APP_MODULE]
Options:
-c CONFIG, --config=CONFIG
Config file. [none]
-b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or
unix:/tmp/gunicorn.sock
-k WORKERCLASS, --worker-class=WORKERCLASS
The type of request processing to use
[egg:gunicorn#sync]
-w WORKERS, --workers=WORKERS
Number of workers to spawn. [1]
-p PIDFILE, --pid=PIDFILE
set the background PID FILE
-D, --daemon Run daemonized in the background.
-m UMASK, --umask=UMASK
Define umask of daemon process
-u USER, --user=USER Change worker user
-g GROUP, --group=GROUP
Change worker group
-n APP_NAME, --name=APP_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.
--spew Install a trace hook
--version show program's version number and exit
-h, --help show this help message and exit
There are various other parameters that affect user privileges, logging, etc.
You can see the complete list at the bottom of this page or as expected with::
Django Projects
---------------
$ gunicorn -h
`Django`_ projects can be handled easily by Gunicorn using the
``gunicorn_django`` command::
gunicorn
++++++++
$ cd $yourdjangoproject
The first and most basic script is used to server 'bare' WSGI applications
that don't require a translation layer. Basic usage::
$ gunicorn [OPTIONS] APP_MODULE
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.
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
But you can also use the ``run_gunicorn`` `admin command`_ like the other
``management.py`` commands.
Alternatively, you can install some Gunicorn magic directly into your Django
project and use the provided command for running the server.
Add ``"gunicorn"`` to INSTALLED_APPS in your settings file::
First you'll need to add ``gunicorn`` to your ``INSTALLED_APPS`` in the settings
file::
INSTALLED_APPS = (
...
"gunicorn",
)
Then run::
Then you can run::
python manage.py run_gunicorn
Paste-compatible projects
-------------------------
gunicorn_paster
+++++++++++++++
For `Paste`_ compatible projects (`Pylons`_, `TurboGears 2`_, ...) use the
``gunicorn_paste`` command::
Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We
apologize for the lack of script name creativity. And some usage::
$ cd $yourpasteproject
$ gunicorn_paster [OPTIONS] paste_config.ini
Simple example::
$ cd yourpasteproject
$ gunicorn_paste --workers=2 development.ini
To use the ``paster`` command add a sever section for Gunicorn::
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 all you need to do is::
And then as per usual::
$ cd $yourpasteproject
$ 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
Full Command Line Usage
+++++++++++++++++++++++
::
$ gunicorn -h
Usage: gunicorn [OPTIONS] APP_MODULE
Options:
-c CONFIG, --config=CONFIG
Config file. [none]
-b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or
unix:/tmp/gunicorn.sock
-w WORKERS, --workers=WORKERS
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
set the background PID FILE
-D, --daemon Run daemonized in the background.
-m UMASK, --umask=UMASK
Define umask of daemon process
-u USER, --user=USER Change worker user
-g GROUP, --group=GROUP
Change worker group
-n PROC_NAME, --name=PROC_NAME
Process 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.
--spew Install a trace hook
--version show program's version number and exit
-h, --help show this help message and exit
.. _FAQ: faq.html
.. _`production page`: deployment.html
.. _`config file`: configuration.html
.. _setproctitle: http://pypi.python.org/pypi/setproctitle/