From 4dbde5c2eff188282b86cd93fba5a525184e9358 Mon Sep 17 00:00:00 2001 From: "Paul J. Davis" Date: Fri, 26 Mar 2010 14:50:00 -0400 Subject: [PATCH] Some edits to the new docs. --- README.rst | 26 ++++++++---- doc/htdocs/configuration.html | 76 +++++++++++++++++++++------------- doc/htdocs/deployment.html | 38 +++++++++++++++-- doc/htdocs/faq.html | 17 ++++---- doc/htdocs/index.html | 19 +++++---- doc/htdocs/installation.html | 37 +++++++++++++---- doc/htdocs/usage.html | 27 +++++++----- doc/site/configuration.rst | 77 ++++++++++++++++++++++------------- doc/site/deployment.rst | 46 ++++++++++++++++++--- doc/site/faq.rst | 17 ++++---- doc/site/index.rst | 25 +++++++----- doc/site/installation.rst | 40 +++++++++++++----- doc/site/usage.rst | 24 +++++++---- 13 files changed, 323 insertions(+), 146 deletions(-) diff --git a/README.rst b/README.rst index a7d2c95c9..3adcf3b9c 100644 --- a/README.rst +++ b/README.rst @@ -1,9 +1,12 @@ About ----- -gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX handle fast clients **and** sleepy application. +gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX handle fast clients +**and** sleepy application. -This is a port of Unicorn (http://unicorn.bogomips.org/) in Python. Meet us on `#gunicorn irc channel `_ on `Freenode`_. +This is a port of Unicorn (http://unicorn.bogomips.org/) in Python. Meet us +on `#gunicorn irc channel `_ +on `Freenode`_. Installation ------------ @@ -18,13 +21,21 @@ Or from Pypi:: $ easy_install -U gunicorn -If you want to handle `sleepy application `_ you will need to install `Eventlet`_ or `Gevent`_. +If you want to handle `sleepy applications `_ +you will need to install `Eventlet`_ or `Gevent`_. To install eventlet:: $ easy_install -U eventlet -Replace `eventlet` by **gevent** if you want to use `gevent`. You can now launch gunicorn with Eventlet or Gevent arbiter, see `Gunicorn usage `_ for more information. +Replace `eventlet` by **gevent** if you want to use `gevent`. You can now +launch gunicorn with Eventlet or Gevent arbiter, see `Gunicorn usage +`_ for more information. + +If you encounter errors when compiling the extensions for `gevent` or +`eventlet` you probably need to install a newer version of libev_. + +.. _libev: http://software.schmorp.de/pkg/libev.html Usage ----- @@ -42,8 +53,8 @@ Usage -w WORKERS, --workers=WORKERS Number of workers to spawn. [1] -a ARBITER, --arbiter=ARBITER - gunicorn arbiter entry point or module - [egg:gunicorn#main] + gunicorn arbiter entry point or module + [egg:gunicorn#main] -p PIDFILE, --pid=PIDFILE set the background PID FILE -D, --daemon Run daemonized in the background. @@ -53,7 +64,7 @@ Usage -g GROUP, --group=GROUP Change worker group -n APP_NAME, --name=APP_NAME - Application name + Application name --log-level=LOGLEVEL Log level below which to silence messages. [info] --log-file=LOGFILE Log to a file. - equals stdout. [-] -d, --debug Debug mode. only 1 worker. @@ -61,7 +72,6 @@ Usage -h, --help show this help message and exit - Example with test app:: $ cd examples diff --git a/doc/htdocs/configuration.html b/doc/htdocs/configuration.html index e207810a7..2f72bf269 100644 --- a/doc/htdocs/configuration.html +++ b/doc/htdocs/configuration.html @@ -49,29 +49,29 @@

gunicorn

The Configuration File

-

Gunciorn 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.

+

Gunciorn 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

-arbiter = "egg:gunicorn"  # Or "egg:gunicorn#eventlet" (eventlet or gevent)
-backlog = 2048
-bind = "127.0.0.1:8000" # Or "unix:/tmp/gunicorn.sock"
-daemon = False          # Whether work in the background
-debug = False           # Some extra logging
-keepalive = 2           # Time we wait for next connection (in ms)
-logfile = "-"           # Name of the log file
-loglevel = "info"       # The level at which to log
-pidfile = None          # Path to a PID file
-workers = 1             # Number of workers to initialize
-umask = 0               # Umask to set when daemonizing
-user = None             # Change process owner to user
-group = None            # Change process group to group
-proc_name = None        # Change the process name
-tmp_upload_dir = None   # Set path used to store temporary uploads
-worker_connections=1000 # Number of connections accepted by a worker
+arbiter = "egg:gunicorn"    # The arbiter to use for worker management
+backlog = 2048              # The listen queue size for the server socket
+bind = "127.0.0.1:8000"     # Or "unix:/tmp/gunicorn.sock"
+daemon = False              # Whether work in the background
+debug = False               # Some extra logging
+keepalive = 2               # Time we wait for next connection (in seconds)
+logfile = "-"               # Name of the log file
+loglevel = "info"           # The level at which to log
+pidfile = None              # Path to a PID file
+workers = 1                 # Number of workers to initialize
+umask = 0                   # Umask to set when daemonizing
+user = None                 # Change process owner to user
+group = None                # Change process group to group
+proc_name = None            # Change the process name
+tmp_upload_dir = None       # Set path used to store temporary uploads
+worker_connections=1000     # Maximum number of simultaneous connections
 
 after_fork=lambda server, worker: server.log.info(
-        "Worker spawned (pid: %s)" % worker.pid),
+        "Worker spawned (pid: %s)" % worker.pid)
 
 before_fork=lambda server, worker: True
 
@@ -84,37 +84,57 @@ 
Parameter Descriptions

 
after_fork(server, worker):

 
This is called by the worker after initialization.

 
arbiter:

-
The arbiter you want to use.  An arbiter maintain the workers processes alive. It launches or kills them if needed. It also manages application reloading  via SIGHUP/USR2. By default it's egg:gunicorn#main. This arbiter only support fast clients connections. If you need to create a sleepy application or handling keepalive set it to egg:gunicorn#eventlet to use it with Eventlet or egg:gunicorn#gevent with Gevent. Eventlet arbiter can also be used with Twisted by using its helper.

+
The arbiter manages the worker processes that actually serve clients. It
+handles launching new workers and killing misbehaving workers among
+other things. By default the arbiter is egg:gunicorn#main. This arbiter
+only supports fast request handling requiring a buffering HTTP proxy.

+
If your application requires the ability to handle prolonged requests to
+provide long polling, comet, or calling an external web service you'll
+need to use an async arbiter. Gunicorn has two async arbiters built in
+using Eventlet or Gevent. You can also use the Evenlet arbiter with
+the Twisted helper.

+

 
backlog:

-
The backlog parameter defines the maximum length for the queue of pending connections see listen(2) for more information. The default is 2048.

+
The backlog parameter defines the maximum length for the queue of pending
+connections. The default is 2048. See listen(2) for more information

 
before_fork(server, worker):

 
This is called by the worker just before forking.

 
before_exec(server):

-
This function is called before relaunching the master. This happens when the master receives a HUP or USR2 signal.

+
This function is called before relaunching the master. This happens when
+the master receives a HUP or USR2 signal.

 
bind:

-
The address on which workers are listening. It can be a TCP address with a format of IP:PORT or a Unix socket address like unix:/path/to/socketfile.

+
The address on which workers are listening. It can be a TCP address with a
+format of IP:PORT or a Unix socket address like
+unix:/path/to/socketfile.

 
daemon:

 
Whether or not to detach the server from the controlling terminal.

 
debug:

-
If True, only one worker will be launch and the variable wsgi.multiprocess will be set to False.

+
If True, only one worker will be launch and the variable
+wsgi.multiprocess will be set to False.

 
group:

 
The group in which worker processes will be launched.

 
keepalive:

-
Keepalive timeout. The default is 2 seconds, which should be enough under most conditions for browsers to render the page and start retrieving extra elements for. Increasing this beyond 5 seconds is not recommended. Zero disables keepalive entirely.

+
KeepAlive timeout. The default is 2 seconds, which should be enough under
+most conditions for browsers to render the page and start retrieving extra
+elements for. Increasing this beyond 5 seconds is not recommended. Zero
+disables KeepAlive entirely.

 
logfile:

-
The path to the log file - (stdout) by default.

+
The path to the log file - (stdout) by default.

 
loglevel:

-
The level at which to log. info, debug, or error for instance. Only log messages of equal or greater severity are logged.

+
The level at which to log. info, debug, or error for instance.
+Only log messages of equal or greater severity are logged.

 
pidfile:

 
A file to store the master's PID.

 
proc_name:

-
If setproctitle is installed, it allows you to set the process name for this Gunicorn instance.

+
A name for the master process. Only takes effect if setproctitle is
+installed. This alters the process names listed by commands like ps.

 
umask:

 
Used to set the umask when daemonizing.

 
user:

 
The user as which worker processes will by launched.

 
worker_connections:

-
Number of connections a worker can handle when used with Eventlet or Gevent arbiter. The default is 1000.

+
Number of simultaneous connections a worker can handle when used with
+Eventlet or Gevent arbiter. The default is 1000.

 
tmp_upload_dir:

 
Set the path used to store temporarily the body of the request.

 
diff --git a/doc/htdocs/deployment.html b/doc/htdocs/deployment.html
index 83abc2165..eeb833a75 100644
--- a/doc/htdocs/deployment.html
+++ b/doc/htdocs/deployment.html
@@ -49,10 +49,38 @@ 
gunicorn

 
   

 
Production Setup

-
Although there are many HTTP proxies available, we strongly advise that you use Nginx. If you choose another proxy server you need to make sure that it buffers slow clients when you use default Gunicorn arbiter. Without this buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.

+
There are two general classes of configuration for Gunicorn. For the time
+being these will are referred to as "fast clients" and "sleepy applications".

+

+
Fast Clients

+
Generally speaking when we say "fast clients" what we really mean is that the
+time taken to process a client from the time a socket is accepted until
+the time the socket is closed is well defined to be short. This means that
+clients are buffered by an upstream proxy (otherwise clients can send or
+receive data slowly) and that your application code does not have major
+blocking sections (a web request to the internet might occasionally take a
+non trivial amount of time).

+
Traditional webapps are generally fine for fast client configurations.
+Deployments should generally default to this type of configuration unless it is
+known that the application code wants to do long-polling, comet, web sockets or
+has other potentially long operations (on the order of seconds).

+

+

+
Sleepy Applications

+
Any application that requires an undefined amount of time for client processing
+is considered a sleepy application. If you are wanting a platform that is
+capable of handling comet connections, long polling, or potentially long
+blocking operations (requests to external web services, ie Facebook Connect)
+then you'll want to use an async arbiter.

+

 

 
Nginx Config for fast clients handling

-
An example configuration file for use with Nginx:

+
Although there are many HTTP proxies available, we strongly advise that you
+use Nginx. If you choose another proxy server you need to make sure that it
+buffers slow clients when you use default Gunicorn arbiter. Without this
+buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
+You can use slowloris to check if your proxy is behaving properly.

+
An example configuration file for fast clients with Nginx:

 
 worker_processes 1;
 
@@ -105,7 +133,8 @@ 
Nginx Config for fast clients handling

     }
 }
 

-
To handle sleepy applications, just add the line proxy_buffering off; under the proxy_redirect directive:

+
To handle sleepy applications, just add the line proxy_buffering off; under
+the proxy_redirect directive:

 
 ...
 location / {
@@ -124,7 +153,8 @@ 
Nginx Config for fast clients handling

 

 

 
Daemon Monitoring

-
A popular method for deploying Gunicorn is to have it monitored by runit. An example service definition:

+
A popular method for deploying Gunicorn is to have it monitored by runit.
+An example service definition:

 
 #!/bin sh
 
diff --git a/doc/htdocs/faq.html b/doc/htdocs/faq.html
index dccc9b27f..e1f51600b 100644
--- a/doc/htdocs/faq.html
+++ b/doc/htdocs/faq.html
@@ -50,18 +50,19 @@ 
gunicorn

   

 
FAQ

 

-
What is a slow client?

-
A slow client is defined as a request that can take an arbitrary amount of
-time to send or read a request. Sometimes due to network performance or
-because it is a malicious client attempting to cause problems. Check out
-the slowloris script to generate slow client traffic.

 
What is a fast client?

 
Generally speaking a fast client is something that is being served over the
 local network or from the same machine. This generally would refer to requests
 forwarded from an upstream proxy. Also see the above FAQ for what a fast
 client is not.

+
What is a slow client?

+
A slow client is defined as a request that can take an arbitrary amount of
+time to send a request or read a response. Sometimes due to network
+performance or because it is a malicious client attempting to cause problems.
+Check out the slowloris script to generate slow client traffic.

 
What are sleepy applications?

-
Applications that expect long request/response times and/or slow clients. Gunicorn use Eventlet or Gevent to manage concurrency.

+
Applications that expect long request/response times and/or slow clients.
+Gunicorn use Eventlet or Gevent to manage concurrency.

 
How might I test a proxy configuration?

 
Check out slowloris for a script that will generate significant slow
 traffic. If your application remains responsive through out that test you
@@ -83,8 +84,8 @@ 
FAQ

 

 
 
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.

+
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
diff --git a/doc/htdocs/index.html b/doc/htdocs/index.html
index 3d2619ad9..b0363c442 100644
--- a/doc/htdocs/index.html
+++ b/doc/htdocs/index.html
@@ -47,22 +47,25 @@ 
gunicorn

 
     	

 
Green Unicorn

-
Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve fast clients or sleepy applications.

-
This is a port of Unicorn in Python. Meet us on the #gunicorn IRC channel  on Freenode.

+
Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve
+fast clients or sleepy applications.

+
This is a port of Unicorn in Python. Meet us on the #gunicorn IRC channel
+on Freenode.

 
Gunicorn is released under the MIT License. See the LICENSE for more details.

 

 
Features

 
    
 
  • Designed for Unix, WSGI, fast clients and sleepy applications.
    • 
 
  • Compatible with Python 2.x (>= 2.5)
    • 
-
  • Easy integration with Django and Paster compatible applications (Pylons, TurboGears 2, ...)
    • 
+
  • Easy integration with Django and Paster compatible applications
+(Pylons, TurboGears 2, ...)
    • 
 
  • Process management: Gunicorn reaps and restarts workers that die.
    • 
 
  • Load balancing via pre-fork and a shared socket
    • 
 
  • Graceful worker process restarts
    • 
 
  • Upgrade "àla nginx" without losing connections
    • 
 
  • Simple and easy Python configuration
    • 
-
  • Decode chunked transfers on-the-fly, allowing upload progress notifications or
-stream-based protocols over HTTP
    • 
+
  • Decode chunked transfers on-the-fly, allowing upload progress notifications
+or stream-based protocols over HTTP
    • 
 
  • Support for Eventlet and Gevent .
    • 
 
  • Post- and pre-fork hooks
    • 
 

@@ -70,12 +73,12 @@ 
Features

 

 
Applications

 
 

 

diff --git a/doc/htdocs/installation.html b/doc/htdocs/installation.html
index 590e5bba1..c185b4cad 100644
--- a/doc/htdocs/installation.html
+++ b/doc/htdocs/installation.html
@@ -59,7 +59,8 @@ 
Requirements

 

 

 
Installing with easy_install

-
If you don't already have easy_install available you'll want to download and run the ez_setup.py script:

+
If you don't already have easy_install available you'll want to download
+and run the ez_setup.py script:

 
 $ curl -O http://peak.telecommunity.com/dist/ez_setup.py
 $ sudo python ez_setup.py -U setuptools
@@ -71,10 +72,13 @@ 
Installing with easy_install

 

 

 
Installing from source

-
You can install Gunicorn from source as simply as you would install any other Python package. Gunicorn uses setuptools which will automatically fetch all dependencies (including setuptools itself).

+
You can install Gunicorn from source as simply as you would install any other
+Python package. Gunicorn uses setuptools which will automatically fetch all
+dependencies (including setuptools itself).

 

 
Get a Copy

-
You can download a tarball of the latest sources from GitHub Downloads or fetch them with git:

+
You can download a tarball of the latest sources from GitHub Downloads or
+fetch them with git:

 
 $ git clone git://github.com/benoitc/gunicorn.git
 

@@ -84,7 +88,10 @@ 
Installation

 
 $ python setup.py install
 

-
If you've cloned the git repository, its highly recommended that you use the develop command which will allow you to use Gunicorn from the source directory. This will allow you to keep up to date with development on GitHub as well as make changes to the source:

+
If you've cloned the git repository, its highly recommended that you use the
+develop command which will allow you to use Gunicorn from the source
+directory. This will allow you to keep up to date with development on GitHub as
+well as make changes to the source:

 
 $ python setup.py develop
 

@@ -92,18 +99,30 @@ 
Installation

 

 

 
Installation requirements for sleepy application handling

-
If you want to handle sleepy application you will need to install Eventlet or Gevent.

+
If you want to handle sleepy application you will need to install
+Eventlet or Gevent.

 
To install eventlet:

 
 $ easy_install -U eventlet
 

-
Replace eventlet by gevent if you want to use gevent.

-
You can now launch gunicorn with Eventlet or Gevent arbiter, see usage for more information.

+
Replace eventlet with gevent if you want to use the gevent
+arbiter.

+
You can now launch gunicorn with Eventlet or Gevent arbiter, see
+usage for more information.

+

+
Note

+
If eventlet or gevent fails to install for you, its most likely
+due to an out of date libev library. You'll need to download and install
+a newer version for either of those to modules to work properly.

+

 

 

 
Installing on Ubuntu/Debian systems

-
If you use ubuntu 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:

+
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:

 
 deb http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
 deb-src http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
diff --git a/doc/htdocs/usage.html b/doc/htdocs/usage.html
index 52c6c1c39..aa5304106 100644
--- a/doc/htdocs/usage.html
+++ b/doc/htdocs/usage.html
@@ -61,17 +61,19 @@ 
WSGI applications

 $ cd /path/to/gunicorn/examples/
 $ gunicorn --workers=2 test:app
 

-
The module test:app specifies the complete module name and WSGI callable. You can replace it with anything that is available on your PYTHONPATH like such:

+
The module test:app specifies the complete module name and WSGI callable.
+You can replace it with anything that is available on your PYTHONPATH like
+such:

 
 $ cd ~/
 $ gunicorn --workers=12 awesomeproject.wsgi.main:main_app
 

-
To launch the websocket example application using Eventlet:

+
To launch the websocket example application using Eventlet:

 
 $ cd /path/to/gunicorn/examples/
 $ gunicorn -w 12 -a "egg:gunicorn#eventlet" websocket:app
 

-
and then go on http://localhost:8000 to see the result.

+
You should then be able to visit http://localhost:8000 to see output.

 

 
Full command line usage

 
@@ -86,8 +88,8 @@ 
Full command line usage

   -w WORKERS, --workers=WORKERS
                         Number of workers to spawn. [1]
   -a ARBITER, --arbiter=ARBITER
-                          gunicorn arbiter entry point or module
-                          [egg:gunicorn#main]
+                        gunicorn arbiter entry point or module
+                        [egg:gunicorn#main]
   -p PIDFILE, --pid=PIDFILE
                         set the background PID FILE
   -D, --daemon          Run daemonized in the background.
@@ -97,7 +99,7 @@ 
Full command line usage

   -g GROUP, --group=GROUP
                         Change worker group
   -n APP_NAME, --name=APP_NAME
-                          Application name
+                        Application name
   --log-level=LOGLEVEL  Log level below which to silence messages. [info]
   --log-file=LOGFILE    Log to a file. - equals stdout. [-]
   -d, --debug           Debug mode. only 1 worker.
@@ -108,13 +110,15 @@ 
Full command line usage

 

 

 
Django Projects

-
Django projects can be handled easily by Gunicorn using the gunicorn_django command:

+
Django projects can be handled easily by Gunicorn using the
+gunicorn_django command:

 
 $ cd $yourdjangoproject
 $ gunicorn_django --workers=2
 

-
But you can also use the run_gunicorn admin command like the other management.py commands.

-
Add "gunicorn" to INSTALLED_APPS in your settings file:

+
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 = (
     ...
@@ -128,12 +132,13 @@ 
Django Projects

 

 

 
Paste-compatible projects

-
For Paste compatible projects (Pylons, TurboGears 2, ...) use the gunicorn_paste command:

+
For Paste compatible projects (Pylons, TurboGears 2, ...) use the
+gunicorn_paste command:

 
 $ cd $yourpasteproject
 $ gunicorn_paste --workers=2 development.ini
 

-
To use the paster command add a sever section for Gunicorn:

+
To use the paster command add a sever section for Gunicorn:

 
 [server:main]
 use = egg:gunicorn#main
diff --git a/doc/site/configuration.rst b/doc/site/configuration.rst
index 4ba0ecd69..97fb34c9e 100644
--- a/doc/site/configuration.rst
+++ b/doc/site/configuration.rst
@@ -10,25 +10,25 @@ Example gunicorn.conf.py
 ------------------------
 ::
 
-    arbiter = "egg:gunicorn"  # Or "egg:gunicorn#eventlet" (eventlet or gevent)
-    backlog = 2048
-    bind = "127.0.0.1:8000" # Or "unix:/tmp/gunicorn.sock"
-    daemon = False          # Whether work in the background
-    debug = False           # Some extra logging
-    keepalive = 2           # Time we wait for next connection (in ms)
-    logfile = "-"           # Name of the log file
-    loglevel = "info"       # The level at which to log
-    pidfile = None          # Path to a PID file
-    workers = 1             # Number of workers to initialize
-    umask = 0               # Umask to set when daemonizing
-    user = None             # Change process owner to user
-    group = None            # Change process group to group
-    proc_name = None        # Change the process name
-    tmp_upload_dir = None   # Set path used to store temporary uploads
-    worker_connections=1000 # Number of connections accepted by a worker
+    arbiter = "egg:gunicorn"    # The arbiter to use for worker management
+    backlog = 2048              # The listen queue size for the server socket
+    bind = "127.0.0.1:8000"     # Or "unix:/tmp/gunicorn.sock"
+    daemon = False              # Whether work in the background
+    debug = False               # Some extra logging
+    keepalive = 2               # Time we wait for next connection (in seconds)
+    logfile = "-"               # Name of the log file
+    loglevel = "info"           # The level at which to log
+    pidfile = None              # Path to a PID file
+    workers = 1                 # Number of workers to initialize
+    umask = 0                   # Umask to set when daemonizing
+    user = None                 # Change process owner to user
+    group = None                # Change process group to group
+    proc_name = None            # Change the process name
+    tmp_upload_dir = None       # Set path used to store temporary uploads
+    worker_connections=1000     # Maximum number of simultaneous connections
     
     after_fork=lambda server, worker: server.log.info(
-            "Worker spawned (pid: %s)" % worker.pid),
+            "Worker spawned (pid: %s)" % worker.pid)
         
     before_fork=lambda server, worker: True
 
@@ -41,44 +41,63 @@ after_fork(server, worker):
     This is called by the worker after initialization.
     
 arbiter:
-    The arbiter you want to use.  An arbiter maintain the workers processes alive. It launches or kills them if needed. It also manages application reloading  via SIGHUP/USR2. By default it's `egg:gunicorn#main`. This arbiter only support fast clients connections. If you need to create a sleepy application or handling keepalive set it to `egg:gunicorn#eventlet` to use it with `Eventlet`_ or `egg:gunicorn#gevent` with `Gevent`_. Eventlet arbiter can also be used with `Twisted`_ by using its `helper `_.
+    The arbiter manages the worker processes that actually serve clients. It
+    handles launching new workers and killing misbehaving workers among
+    other things. By default the arbiter is `egg:gunicorn#main`. This arbiter
+    only supports fast request handling requiring a buffering HTTP proxy.
+    
+    If your application requires the ability to handle prolonged requests to
+    provide long polling, comet, or calling an external web service you'll
+    need to use an async arbiter. Gunicorn has two async arbiters built in
+    using `Eventlet`_ or `Gevent`_. You can also use the Evenlet arbiter with
+    the `Twisted`_ helper.
     
 backlog:
-    The backlog parameter defines the maximum length for the queue of pending connections see listen(2) for more information. The default is 2048.
+    The backlog parameter defines the maximum length for the queue of pending
+    connections. The default is 2048. See listen(2) for more information
   
 before_fork(server, worker):
     This is called by the worker just before forking.
   
 before_exec(server):
-    This function is called before relaunching the master. This happens when the master receives a HUP or USR2 signal.
+    This function is called before relaunching the master. This happens when
+    the master receives a HUP or USR2 signal.
   
 bind:
-    The address on which workers are listening. It can be a TCP address with a format of ``IP:PORT`` or a Unix socket address like ``unix:/path/to/socketfile``.
+    The address on which workers are listening. It can be a TCP address with a
+    format of ``IP:PORT`` or a Unix socket address like
+    ``unix:/path/to/socketfile``.
 
 daemon:
     Whether or not to detach the server from the controlling terminal.
   
 debug:
-    If ``True``, only one worker will be launch and the variable ``wsgi.multiprocess`` will be set to False.
+    If ``True``, only one worker will be launch and the variable
+    ``wsgi.multiprocess`` will be set to False.
   
 group:
     The group in which worker processes will be launched.
     
 keepalive:
-    Keepalive timeout. The default is 2 seconds, which should be enough under most conditions for browsers to render the page and start retrieving extra elements for. Increasing this beyond 5 seconds is not recommended. Zero disables keepalive entirely.
+    KeepAlive timeout. The default is 2 seconds, which should be enough under
+    most conditions for browsers to render the page and start retrieving extra
+    elements for. Increasing this beyond 5 seconds is not recommended. Zero
+    disables KeepAlive entirely.
   
 logfile:
     The path to the log file ``-`` (stdout) by default.
   
 loglevel:
-    The level at which to log. ``info``, ``debug``, or ``error`` for instance. Only log messages of equal or greater severity are logged.
+    The level at which to log. ``info``, ``debug``, or ``error`` for instance.
+    Only log messages of equal or greater severity are logged.
   
 pidfile:
     A file to store the master's PID.
     
 proc_name:
-    If `setproctitle `_ is installed, it allows you to set the process name for this Gunicorn instance.
-  
+    A name for the master process. Only takes effect if setproctitle_ is
+    installed. This alters the process names listed by commands like ``ps``.
+    
 umask:
     Used to set the umask when daemonizing.
 
@@ -86,12 +105,14 @@ user:
     The user as which worker processes will by launched.
     
 worker_connections:
-    Number of connections a worker can handle when used with Eventlet or Gevent arbiter. The default is 1000.
+    Number of simultaneous connections a worker can handle when used with
+    Eventlet or Gevent arbiter. The default is 1000.
 
 tmp_upload_dir:
     Set the path used to store temporarily the body of the request.
     
-    
+.. _helper: http://bitbucket.org/which_linden/eventlet/src/tip/README.twisted
 .. _Eventlet: http://eventlet.net
 .. _Gevent: http://gevent.org
 .. _Twisted: http://twistedmatrix.com
+.. _setproctitle: http://pypi.python.org/pypi/setproctitle
\ No newline at end of file
diff --git a/doc/site/deployment.rst b/doc/site/deployment.rst
index d449184da..5c8ef95b9 100644
--- a/doc/site/deployment.rst
+++ b/doc/site/deployment.rst
@@ -4,12 +4,45 @@ title: Deployment
 Production Setup
 ================
 
-Although there are many HTTP proxies available, we strongly advise that you use Nginx_. If you choose another proxy server you need to make sure that it buffers slow clients when you use default Gunicorn arbiter. Without this buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
+There are two general classes of configuration for Gunicorn. For the time
+being these will are referred to as "fast clients" and "sleepy applications".
+
+Fast Clients
+------------
+
+Generally speaking when we say "fast clients" what we really mean is that the
+time taken to process a client from the time a socket is accepted until
+the time the socket is closed is well defined to be short. This means that
+clients are buffered by an upstream proxy (otherwise clients can send or
+receive data slowly) and that your application code does not have major
+blocking sections (a web request to the internet might occasionally take a
+non trivial amount of time).
+
+Traditional webapps are generally fine for fast client configurations.
+Deployments should generally default to this type of configuration unless it is
+known that the application code wants to do long-polling, comet, web sockets or
+has other potentially long operations (on the order of seconds).
+
+Sleepy Applications
+-------------------
+
+Any application that requires an undefined amount of time for client processing
+is considered a sleepy application. If you are wanting a platform that is
+capable of handling comet connections, long polling, or potentially long
+blocking operations (requests to external web services, ie Facebook Connect)
+then you'll want to use an async arbiter.
 
 Nginx Config for fast clients handling
 --------------------------------------
 
-An `example configuration`_ file for use with Nginx_::
+Although there are many HTTP proxies available, we strongly advise that you
+use Nginx_. If you choose another proxy server you need to make sure that it
+buffers slow clients when you use default Gunicorn arbiter. Without this
+buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
+You can use slowloris_ to check if your proxy is behaving properly.
+
+
+An `example configuration`_ file for fast clients with Nginx_::
 
     worker_processes 1;
  
@@ -61,8 +94,9 @@ An `example configuration`_ file for use with Nginx_::
             }
         }
     }
-    
-To handle sleepy applications, just add the line `proxy_buffering off;` under the proxy_redirect directive::
+
+To handle sleepy applications, just add the line `proxy_buffering off;` under
+the proxy_redirect directive::
 
   ...
   location / {
@@ -81,7 +115,8 @@ To handle sleepy applications, just add the line `proxy_buffering off;` under th
 Daemon Monitoring
 -----------------
 
-A popular method for deploying Gunicorn is to have it monitored by runit_. An `example service`_ definition::
+A popular method for deploying Gunicorn is to have it monitored by runit_.
+An `example service`_ definition::
 
     #!/bin sh
     
@@ -108,6 +143,7 @@ Another useful tool to monitor and control Gunicorn is Supervisor_. A
     redirect_stderr=True
 
 .. _Nginx: http://www.nginx.org
+.. _slowloris: http://ha.ckers.org/slowloris/
 .. _`example configuration`: http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf
 .. _runit: http://smarden.org/runit/
 .. _`example service`: http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc
diff --git a/doc/site/faq.rst b/doc/site/faq.rst
index 0dbccc15d..0f8849198 100644
--- a/doc/site/faq.rst
+++ b/doc/site/faq.rst
@@ -4,20 +4,21 @@ title: FAQ
 FAQ
 ===
 
-What is a slow client?
-  A slow client is defined as a request that can take an arbitrary amount of
-  time to send or read a request. Sometimes due to network performance or
-  because it is a malicious client attempting to cause problems. Check out
-  the slowloris_ script to generate slow client traffic.
-
 What is a fast client?
   Generally speaking a fast client is something that is being served over the
   local network or from the same machine. This generally would refer to requests
   forwarded from an upstream proxy. Also see the above FAQ for what a fast
   client is not.
- 
+
+What is a slow client?
+  A slow client is defined as a request that can take an arbitrary amount of
+  time to send a request or read a response. Sometimes due to network
+  performance or because it is a malicious client attempting to cause problems.
+  Check out the slowloris_ script to generate slow client traffic.
+
 What are sleepy applications?
-  Applications that expect long request/response times and/or slow clients. Gunicorn use `Eventlet`_ or `Gevent`_ to manage concurrency.
+  Applications that expect long request/response times and/or slow clients.
+  Gunicorn use `Eventlet`_ or `Gevent`_ to manage concurrency.
 
 How might I test a proxy configuration?
   Check out slowloris_ for a script that will generate significant slow
diff --git a/doc/site/index.rst b/doc/site/index.rst
index e80b9fc45..0536115cb 100644
--- a/doc/site/index.rst
+++ b/doc/site/index.rst
@@ -3,9 +3,11 @@ template: index.html
 Green Unicorn
 =============
 
-Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve `fast clients`_ or `sleepy applications`_.
+Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve
+`fast clients`_ or `sleepy applications`_.
 
-This is a port of Unicorn_ in Python. Meet us on the `#gunicorn IRC channel`_  on Freenode_.
+This is a port of Unicorn_ in Python. Meet us on the `#gunicorn IRC channel`_
+on Freenode_.
 
 Gunicorn is released under the MIT License. See the LICENSE_ for more details.
 
@@ -14,26 +16,27 @@ Features
 
 - Designed for Unix, WSGI_, fast clients and sleepy applications.
 - Compatible with Python 2.x (>= 2.5)
-- Easy integration with Django_ and Paster_ compatible applications (`Pylons`_, `TurboGears 2`_, ...)
+- Easy integration with Django_ and Paster_ compatible applications
+  (`Pylons`_, `TurboGears 2`_, ...)
 - Process management: Gunicorn_ reaps and restarts workers that die.
 - Load balancing via pre-fork and a shared socket
 - Graceful worker process restarts
 - Upgrade "àla nginx" without losing connections
 - Simple and easy Python configuration
-- Decode chunked transfers on-the-fly, allowing upload progress notifications or
-  stream-based protocols over HTTP
+- Decode chunked transfers on-the-fly, allowing upload progress notifications
+  or stream-based protocols over HTTP
 - Support for `Eventlet`_ and `Gevent`_ .
 - Post- and pre-fork hooks
 
 Applications
 ------------
 
-* Any WSGI_, Django_ and Paster_ compatible applications (`Pylons`_, `TurboGears 2`_, ...)
-* Websockets (see `example `_)
-* Reverse proxy implementation (with `Restkit WSGI proxy `_)
+* Any WSGI_, Django_ and Paster_ compatible applications
+  (`Pylons`_, `TurboGears 2`_, ...)
+* Websockets (see the example_)
+* Reverse proxy implementation (with `Restkit WSGI proxy`_)
 * Comet
 * Long Polling
-* ...
 
 .. _WSGI:  http://www.python.org/dev/peps/pep-0333/
 .. _`fast clients`: faq.html
@@ -48,4 +51,6 @@ Applications
 .. _Eventlet: http://eventlet.net
 .. _Gevent: http://gevent.org
 .. _Pylons: http://pylonshq.com/
-.. _Turbogears 2: http://turbogears.org/2.0/
\ No newline at end of file
+.. _Turbogears 2: http://turbogears.org/2.0/
+.. _example: http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py
+.. _`Restkit WSGI proxy`: http://benoitc.github.com/restkit/wsgi_proxy.html
\ No newline at end of file
diff --git a/doc/site/installation.rst b/doc/site/installation.rst
index 9bafe1d6a..cc1f74c8d 100644
--- a/doc/site/installation.rst
+++ b/doc/site/installation.rst
@@ -14,7 +14,8 @@ Requirements
 Installing with easy_install
 ----------------------------
 
-If you don't already have ``easy_install`` available you'll want to download and run the ``ez_setup.py`` script::
+If you don't already have ``easy_install`` available you'll want to download
+and run the ``ez_setup.py`` script::
 
   $ curl -O http://peak.telecommunity.com/dist/ez_setup.py
   $ sudo python ez_setup.py -U setuptools
@@ -26,12 +27,15 @@ To install or upgrade to the latest released version of Gunicorn::
 Installing from source
 ----------------------
 
-You can install Gunicorn from source as simply as you would install any other Python package. Gunicorn uses setuptools which will automatically fetch all dependencies (including setuptools itself).
+You can install Gunicorn from source as simply as you would install any other
+Python package. Gunicorn uses setuptools which will automatically fetch all
+dependencies (including setuptools itself).
 
 Get a Copy
 ++++++++++
 
-You can download a tarball of the latest sources from `GitHub Downloads`_ or fetch them with git_::
+You can download a tarball of the latest sources from `GitHub Downloads`_ or
+fetch them with git_::
 
     $ git clone git://github.com/benoitc/gunicorn.git
 
@@ -45,29 +49,43 @@ Installation
 
   $ python setup.py install
 
-If you've cloned the git repository, its highly recommended that you use the ``develop`` command which will allow you to use Gunicorn from the source directory. This will allow you to keep up to date with development on GitHub as well as make changes to the source::
+If you've cloned the git repository, its highly recommended that you use the
+``develop`` command which will allow you to use Gunicorn from the source
+directory. This will allow you to keep up to date with development on GitHub as
+well as make changes to the source::
 
   $ python setup.py develop
   
 Installation requirements for sleepy application handling
 ---------------------------------------------------------
 
-If you want to handle `sleepy application `_ you will need to install `Eventlet`_ or `Gevent`_.
+If you want to handle `sleepy application `_ you will need to install
+`Eventlet`_ or `Gevent`_.
 
 To install eventlet::
 
   $ easy_install -U eventlet
   
-Replace `eventlet` by **gevent** if you want to use `gevent`. 
+Replace ``eventlet`` with ``gevent`` if you want to use the ``gevent``
+arbiter.
 
-You can now launch gunicorn with Eventlet or Gevent arbiter, see `usage `_ for more information.
+You can now launch gunicorn with Eventlet or Gevent arbiter, see
+`usage `_ for more information.
+
+.. note::
+    If ``eventlet`` or ``gevent`` fails to install for you, its most likely
+    due to an out of date libev_ library. You'll need to download and install
+    a newer version for either of those to modules to work properly.
   
 Installing on Ubuntu/Debian systems
 -----------------------------------
 
-If you use `ubuntu `_ 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::
+Or this PPA can be added to your system manually by copying the lines below
+and adding them to your system's software sources::
 
   deb http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main 
   deb-src http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
@@ -81,4 +99,6 @@ Fingerprint::
   49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06
 
 .. _Eventlet: http://eventlet.net
-.. _Gevent: http://gevent.org
\ No newline at end of file
+.. _Gevent: http://gevent.org
+.. _libev: http://software.schmorp.de/pkg/libev.html
+.. _PPA: https://launchpad.net/~bchesneau/+archive/gunicorn
\ No newline at end of file
diff --git a/doc/site/usage.rst b/doc/site/usage.rst
index 2ee17f536..98df475a3 100644
--- a/doc/site/usage.rst
+++ b/doc/site/usage.rst
@@ -16,17 +16,19 @@ To launch the `example application`_ packaged with Gunicorn::
     $ cd /path/to/gunicorn/examples/
     $ gunicorn --workers=2 test:app
 
-The module ``test:app`` specifies the complete module name and WSGI callable. You can replace it with anything that is available on your ``PYTHONPATH`` like such::
+The module ``test:app`` specifies the complete module name and WSGI callable.
+You can replace it with anything that is available on your ``PYTHONPATH`` like
+such::
 
     $ cd ~/
     $ gunicorn --workers=12 awesomeproject.wsgi.main:main_app
     
-To launch the `websocket example application `_ using `Eventlet`_::
+To launch the `websocket example`_ application using `Eventlet`_::
 
         $ cd /path/to/gunicorn/examples/
         $ gunicorn -w 12 -a "egg:gunicorn#eventlet" websocket:app
 
-and then go on `http://localhost:8000` to see the result.
+You should then be able to visit ``http://localhost:8000`` to see output.
 
 Full command line usage
 +++++++++++++++++++++++
@@ -44,8 +46,8 @@ Full command line usage
     -w WORKERS, --workers=WORKERS
                           Number of workers to spawn. [1]
     -a ARBITER, --arbiter=ARBITER
-                            gunicorn arbiter entry point or module
-                            [egg:gunicorn#main]
+                          gunicorn arbiter entry point or module
+                          [egg:gunicorn#main]
     -p PIDFILE, --pid=PIDFILE
                           set the background PID FILE
     -D, --daemon          Run daemonized in the background.
@@ -55,7 +57,7 @@ Full command line usage
     -g GROUP, --group=GROUP
                           Change worker group
     -n APP_NAME, --name=APP_NAME
-                            Application name
+                          Application name
     --log-level=LOGLEVEL  Log level below which to silence messages. [info]
     --log-file=LOGFILE    Log to a file. - equals stdout. [-]
     -d, --debug           Debug mode. only 1 worker.
@@ -65,12 +67,14 @@ Full command line usage
 Django Projects
 ---------------
 
-`Django`_ projects can be handled easily by Gunicorn using the ``gunicorn_django`` command::
+`Django`_ projects can be handled easily by Gunicorn using the
+``gunicorn_django`` command::
 
     $ cd $yourdjangoproject
     $ gunicorn_django --workers=2
 
-But you can also use the ``run_gunicorn`` `admin command`_ like the other ``management.py`` commands.
+But you can also use the ``run_gunicorn`` `admin command`_ like the other
+``management.py`` commands.
 
 Add ``"gunicorn"`` to INSTALLED_APPS in your settings file::
 
@@ -87,7 +91,8 @@ Then run::
 Paste-compatible projects
 -------------------------
 
-For `Paste`_ compatible projects (`Pylons`_, `TurboGears 2`_, ...) use the ``gunicorn_paste`` command::
+For `Paste`_ compatible projects (`Pylons`_, `TurboGears 2`_, ...) use the
+``gunicorn_paste`` command::
 
     $ cd $yourpasteproject
     $ gunicorn_paste --workers=2 development.ini
@@ -105,6 +110,7 @@ And then all you need to do is::
     $ paster serve development.ini workers=2
  
 .. _`example application`: http://github.com/benoitc/gunicorn/blob/master/examples/test.py
+.. _`websocket example`: http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py
 .. _Django: http://djangoproject.com
 .. _`admin command`: http://docs.djangoproject.com/en/dev/howto/custom-management-commands/
 .. _Paste: http://pythonpaste.org/script/