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.
diff --git a/doc/htdocs/css/style.css b/doc/htdocs/css/style.css
index c6948613..003a6c04 100644
--- a/doc/htdocs/css/style.css
+++ b/doc/htdocs/css/style.css
@@ -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 {
diff --git a/doc/htdocs/deployment.html b/doc/htdocs/deployment.html
index 6bfa1949..250f83ee 100644
--- a/doc/htdocs/deployment.html
+++ b/doc/htdocs/deployment.html
@@ -49,35 +49,33 @@
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".
-
-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).
+
+Synchronous vs Asynchronous workers
+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.
+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).
+Example use-cases for asynchronous workers:
+
+
+- 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
+
+
-
-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
+
+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:
@@ -133,8 +131,12 @@ http {
}
}
-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 / {
@@ -148,7 +150,7 @@ location / {
break;
}
}
-....
+...
diff --git a/doc/htdocs/faq.html b/doc/htdocs/faq.html
index 8dfaf026..bc38c22e 100644
--- a/doc/htdocs/faq.html
+++ b/doc/htdocs/faq.html
@@ -50,19 +50,19 @@
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.
-- 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.
+- 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 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
traffic. If your application remains responsive through out that test you
@@ -83,13 +83,16 @@ $ kill -TTIN $masterpid
$ kill -TTOU $masterpid
+- How can I figure out the best number of worker processes?
+- Start gunicorn with an approximate number of worker processes. Then use the
+TTIN and/or TTOU signals to adjust the number of workers under load.
- How do I set SCRIPT_NAME?
- 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.
diff --git a/doc/htdocs/index.html b/doc/htdocs/index.html
index a2727b5a..cc0cf9a2 100644
--- a/doc/htdocs/index.html
+++ b/doc/htdocs/index.html
@@ -47,15 +47,16 @@
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.
+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.
+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, ...)
@@ -77,8 +78,8 @@ or stream-based protocols over HTTP
(Pylons, TurboGears 2, ...)
- Websockets (see the example or the screencast)
- Reverse proxy implementation (with Restkit WSGI proxy)
-- Comet
- Long Polling
+- Comet
diff --git a/doc/htdocs/installation.html b/doc/htdocs/installation.html
index 5de0269e..bad19e6f 100644
--- a/doc/htdocs/installation.html
+++ b/doc/htdocs/installation.html
@@ -52,7 +52,7 @@
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)
@@ -72,7 +72,7 @@ $ sudo easy_install -U 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).
@@ -97,30 +97,28 @@ $ 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.
+
+Enabling async workers
+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.
-You can now launch gunicorn with Eventlet or Gevent arbiter, see
-usage 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 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:
diff --git a/doc/htdocs/news.html b/doc/htdocs/news.html
index 4c8e1ecd..ffad827b 100644
--- a/doc/htdocs/news.html
+++ b/doc/htdocs/news.html
@@ -61,14 +61,15 @@
0.8.0 / 2010-04-22
-- Refactored Worker management for better async support. Now use the -k option to set the type of request processing to use
+- Refactored Worker management for better async support. Now use the -k option
+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
@@ -82,7 +83,7 @@
0.7.0 / 2010-03-26
-- Added support for sleepy applications using Eventlet or Gevent.
+- Added support for Eventlet and Gevent based workers.
- Added Websockets support
- Fix Chunked Encoding
- Fix SIGWINCH on OpenBSD
@@ -92,7 +93,7 @@
0.6.5 / 2010-03-11
-- Fix pidfile
+- Fix pidfile handling
- Fix Exception Error
@@ -107,7 +108,7 @@
0.6.3 / 2010-03-07
- Make HTTP parsing faster.
-- Some fixes (see logs)
+- Various bug fixes
@@ -115,7 +116,8 @@
- 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).
@@ -123,7 +125,7 @@
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.
@@ -131,15 +133,16 @@
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
@@ -153,7 +156,7 @@
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
diff --git a/doc/htdocs/tuning.html b/doc/htdocs/tuning.html
index 52bd95a3..83dbf3e5 100644
--- a/doc/htdocs/tuning.html
+++ b/doc/htdocs/tuning.html
@@ -51,31 +51,48 @@
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.
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.
-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.
+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.
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.
$ sudo ulimit -n 2048
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.
$ sudo sysctl -w kern.ipc.somaxconn="2048"
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.
-This setting is generally only required on machines that are being used to test a network server.
+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.
$ sudo sysctl -w net.inet.ip.portrange.first="8048"
diff --git a/doc/htdocs/usage.html b/doc/htdocs/usage.html
index 3541fd08..acaf82b1 100644
--- a/doc/htdocs/usage.html
+++ b/doc/htdocs/usage.html
@@ -47,49 +47,125 @@
-
-Command Line Usage
+
+Usage
+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.
+
+Commonly Used Arguments
+
-- WSGI applications
-- Django projects
-- Paste-compatible projects
+- -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).
-
-WSGI applications
-To launch the example application packaged with Gunicorn:
+
+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:
-$ cd /path/to/gunicorn/examples/
-$ gunicorn -w 2 test:app
+$ gunicorn -h
-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:
+
+
+gunicorn
+The first and most basic script is used to server 'bare' WSGI applications
+that don't require a translation layer. Basic usage:
-$ cd ~/
-$ gunicorn -w 12 awesomeproject.wsgi.main:main_app
+$ gunicorn [OPTIONS] APP_MODULE
-To launch the websocket example application using Eventlet:
+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 /path/to/gunicorn/examples/
-$ gunicorn -w 12 -k "egg:gunicorn#eventlet" websocket:app
+$ cd examples
+$ gunicorn --workers=2 test:app
-You should then be able to visit http://localhost:8000 to see output.
+
+
+gunicorn_django
+You might not have guessed it, but this script is used to server Django
+applications. Basic usage:
+
+$ gunicorn_django [OPTIONS] [SETTINGS_PATH]
+
+By default SETTINGS_PATH will look for settings.py in the current
+directory.
+Example with your Django project:
+
+$ cd path/to/yourdjangoproject
+$ gunicorn_django --workers=2
+
+Alternatively, you can install some Gunicorn magic directly into your Django
+project and use the provided command for running the server.
+First you'll need to add gunicorn to your INSTALLED_APPS in the settings
+file:
+
+INSTALLED_APPS = (
+ ...
+ "gunicorn",
+)
+
+Then you can run:
+
+python manage.py run_gunicorn
+
+
+
+gunicorn_paster
+Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We
+apologize for the lack of script name creativity. And some usage:
+
+$ gunicorn_paster [OPTIONS] paste_config.ini
+
+Simple example:
+
+$ cd yourpasteproject
+$ gunicorn_paste --workers=2 development.ini
+
+If you're wanting to keep on keeping on with the usual paster serve command,
+you can specify the Gunicorn server settings in your configuration file:
+
+[server:main]
+use = egg:gunicorn#main
+host = 127.0.0.1
+port = 5000
+
+And then as per usual:
+
+$ cd yourpasteproject
+$ paster serve development.ini workers=2
+
+
-Full command line usage
+Full Command Line Usage
-$ 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:
-
-Django Projects
-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:
-
-INSTALLED_APPS = (
- ...
- "gunicorn",
-)
-
-Then run:
-
-python manage.py run_gunicorn
-
-
-
-Paste-compatible projects
-For Paste compatible projects (Pylons, TurboGears 2, ...) use the
-gunicorn_paste command:
-
-$ cd $yourpasteproject
-$ gunicorn_paste --workers=2 development.ini
-
-To use the paster command add a sever section for Gunicorn:
-
-[server:main]
-use = egg:gunicorn#main
-host = 127.0.0.1
-port = 5000
-
-And then all you need to do is:
-
-$ cd $yourpasteproject
-$ paster serve development.ini workers=2
-
-
-
diff --git a/doc/site/configuration.rst b/doc/site/configuration.rst
index 3f5427cb..6a466464 100644
--- a/doc/site/configuration.rst
+++ b/doc/site/configuration.rst
@@ -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
------------------------
diff --git a/doc/site/deployment.rst b/doc/site/deployment.rst
index 526e86bf..67837d78 100644
--- a/doc/site/deployment.rst
+++ b/doc/site/deployment.rst
@@ -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
-----------------------
diff --git a/doc/site/faq.rst b/doc/site/faq.rst
index 0f884919..2e82754d 100644
--- a/doc/site/faq.rst
+++ b/doc/site/faq.rst
@@ -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
diff --git a/doc/site/index.rst b/doc/site/index.rst
index be635dea..9127f735 100644
--- a/doc/site/index.rst
+++ b/doc/site/index.rst
@@ -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
diff --git a/doc/site/installation.rst b/doc/site/installation.rst
index cc1f74c8..548375a8 100644
--- a/doc/site/installation.rst
+++ b/doc/site/installation.rst
@@ -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 `_ 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 `_ 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 `_ 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 `_)
+* 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
diff --git a/doc/site/tuning.rst b/doc/site/tuning.rst
index 1587628d..7c977030 100644
--- a/doc/site/tuning.rst
+++ b/doc/site/tuning.rst
@@ -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.
::
diff --git a/doc/site/usage.rst b/doc/site/usage.rst
index 2594a4fb..066815a5 100644
--- a/doc/site/usage.rst
+++ b/doc/site/usage.rst
@@ -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
\ No newline at end of file
+
+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/