Skip to content

Commit

Permalink
Updating webpage docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@davisp
davisp committed May 7, 2010
1 parent c2af49c commit 8382dfe
Show file tree
Hide file tree
Showing 17 changed files with 454 additions and 344 deletions.
4 changes: 3 additions & 1 deletion doc/htdocs/configuration.html
View file
Expand Up @@ -49,7 +49,9 @@ <h1 class="logo"><a href="http://gunicorn.org">gunicorn</a></h1>

<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">
Expand Down
11 changes: 8 additions & 3 deletions doc/htdocs/css/style.css
View file
Expand Up @@ -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 {
Expand Down
60 changes: 31 additions & 29 deletions doc/htdocs/deployment.html
View file
Expand Up @@ -49,35 +49,33 @@ <h1 class="logo"><a href="http://gunicorn.org">gunicorn</a></h1>

<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>
Expand Down Expand Up @@ -133,8 +131,12 @@ <h1>Nginx Config for fast clients handling</h1>
}
}
</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 / {
Expand All @@ -148,7 +150,7 @@ <h1>Nginx Config for fast clients handling</h1>
break;
}
}
....
...
</pre>
</div>
<div class="section" id="working-with-virtualenv">
Expand Down
37 changes: 20 additions & 17 deletions doc/htdocs/faq.html
View file
Expand Up @@ -50,19 +50,19 @@ <h1 class="logo"><a href="http://gunicorn.org">gunicorn</a></h1>
<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
Expand All @@ -83,13 +83,16 @@ <h1 class="title">FAQ</h1>
$ 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>

Expand Down
13 changes: 7 additions & 6 deletions doc/htdocs/index.html
View file
Expand Up @@ -47,15 +47,16 @@ <h1 class="logo"><a href="http://gunicorn.org">gunicorn</a></h1>

<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>
Expand All @@ -77,8 +78,8 @@ <h1>Applications</h1>
(<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>
Expand Down
30 changes: 14 additions & 16 deletions doc/htdocs/installation.html
View file
Expand Up @@ -52,7 +52,7 @@ <h1 class="title">Installation</h1>
<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>
Expand All @@ -72,7 +72,7 @@ <h1>Installing with easy_install</h1>
</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">
Expand All @@ -97,30 +97,28 @@ <h2>Installation</h2>
</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">
Expand Down

0 comments on commit 8382dfe

Please sign in to comment.