jingrow/gunicorn
1
0
Fork 0
mirror of https://github.com/frappe/gunicorn.git synced 2026-01-14 11:09:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updating the README

Browse Source
This commit is contained in:
Paul J. Davis 2010-05-06 19:28:43 -04:00
parent 4bf5d8e4bd
commit dc7544050b
1 changed files with 96 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

208
README.rst
View File

@ -1,17 +1,17 @@
About About
----- -----
gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX handle fast clients Gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX. It's a pre-fork
**and** sleepy application. 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 (http://unicorn.bogomips.org/) in Python. Meet us Feel free to join us in #gunicorn_ on freenode_.
on `#gunicorn irc channel <http://webchat.freenode.net/?channels=gunicorn>`_
on `Freenode`_.
Installation Installation
------------ ------------
Gunicorn requires **Python 2.5 or newer** (Python 3.x will be supported soon). Gunicorn requires **Python 2.x >= 2.5**. Python 3.x support is planned.
Install from sources:: Install from sources::
@ -20,145 +20,129 @@ Install from sources::
Or from Pypi:: Or from Pypi::
$ easy_install -U gunicorn $ easy_install -U gunicorn
If you want to handle `sleepy applications <http://gunicorn.org/faq.html>`_ .. note:
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:: To install eventlet::
$ easy_install -U eventlet $ easy_install -U eventlet
Replace `eventlet` by **gevent** if you want to use `gevent`. You can now .. note:
launch gunicorn with Eventlet or Gevent arbiter, see `Gunicorn usage If you encounter errors when compiling the extensions for Eventlet_ or
<http://gunicorn.org/usage.html>`_ for more information. Gevent_ you most likely need to install a newer version of libev_.
If you encounter errors when compiling the extensions for `gevent` or Basic Usage
`eventlet` you probably need to install a newer version of libev_. -----------
.. _libev: http://software.schmorp.de/pkg/libev.html 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``.
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) where $(HOST) can
also be an IP.
* ``-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 FAQ_ for the implications of
this parameter.
* ``-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 There are various other parameters that affect user privileges, logging, etc.
Usage: gunicorn [OPTIONS] [APP_MODULE] You can see the complete list with the expected::
Options: $ gunicorn -h
-c CONFIG, --config=CONFIG
Config file. [none] gunicorn
-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 first and most basic script is used to server 'bare' WSGI applications
The type of request processing to use that don't require a translation layer. Basic usage::
[egg:gunicorn#sync]
-w WORKERS, --workers=WORKERS $ gunicorn [OPTIONS] APP_MODULE
Number of workers to spawn. [1]
-p PIDFILE, --pid=PIDFILE Where APP_MODULE is of the pattern $(MODULE_NAME):$(VARIABLE_NAME). The module
set the background PID FILE name can be a full dotted path. The variable name refers to a WSGI callable
-D, --daemon Run daemonized in the background. that should be found in the specified module.
-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
Example with test app:: Example with test app::
$ cd examples $ cd examples
$ gunicorn --workers=2 test:app $ gunicorn --workers=2 test:app
Django projects gunicorn_django
+++++++++++++++ +++++++++++++++
For django projects use the `gunicorn_django` command:: You might not have guessed it, but this script is used to server Django
applications. Basic usage::
$ cd yourdjangoproject $ 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 $ gunicorn_django --workers=2
or use `run_gunicorn` command. 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 the settings file:: First you'll need to add ``gunicorn`` to your INSTALLED_APPS in the settings
file::
INSTALLED_APPS = ( INSTALLED_APPS = (
... ...
"gunicorn", "gunicorn",
) )
Then run:: Then you can run::
python manage.py run_gunicorn python manage.py run_gunicorn
Paste-compatible projects gunicorn_paster
+++++++++++++++++++++++++ +++++++++++++++
For paste-compatible projects (like 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::
$ gunicorn_paster [OPTIONS] paste_config.ini
Simple example::
$ cd your pasteproject $ cd your pasteproject
$ gunicorn_paste --workers=2 development.ini $ gunicorn_paste --workers=2 development.ini
or usual paster command:: 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::
$ cd your pasteproject [server:main]
$ paster serve development.ini workers=2 use = egg:gunicorn#main
host = 127.0.0.1
In last case don't forget to add a server section for gunicorn. Here is an example that use port = 5000
gunicorn as main server::
[server:main] And then as per usual::
use = egg:gunicorn#main
host = 127.0.0.1
port = 5000
Kernel Parameters
-----------------
There are various kernel parameters that you might want to tune in order to deal with a large number of simultaneous connections. Generally these should only affect sites with a large number of concurrent requests and apply to any sort of network server you may be running. They're listed here for ease of reference. $ cd your pasteproject
$ paster serve development.ini workers=2
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. .. _Unicorn: http://unicorn.bogomips.org/
.. _#gunicorn: http://webchat.freenode.net/?channels=gunicorn
Increasing the File Descriptor Limit
++++++++++++++++++++++++++++++++++++
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 1024
Increasing the 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.
::
$ sudo sysctl -w kern.ipc.somaxconn="1024"
Widening the Ephemeral Port Range
+++++++++++++++++++++++++++++++++
After a socket is closed it eventually enters the TIME_WAIT state. This can become an issue after a prolonged burst of client activity. Eventually the ephemeral port range is used up 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"
Check `this article`_ for more information on ephemeral ports.
.. _this article: http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html
.. _freenode: http://freenode.net .. _freenode: http://freenode.net
.. _Eventlet: http://eventlet.net .. _Eventlet: http://eventlet.net
.. _Gevent: http://gevent.org .. _Gevent: http://gevent.org
.. _FAQ: http://gunicorn.org/faq.html
.. _libev: http://software.schmorp.de/pkg/libev.html
.. _`config file`: http://gunicorn.org/configuration.html