mirror of
https://github.com/frappe/gunicorn.git
synced 2026-01-14 11:09:11 +08:00
Updating the README
This commit is contained in:
Paul J. Davis
parent
4bf5d8e4bd
commit
dc7544050b
208
README.rst
208
README.rst
@ -1,17 +1,17 @@
|
||||
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. 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 (http://unicorn.bogomips.org/) in Python. Meet us
|
||||
on `#gunicorn irc channel <http://webchat.freenode.net/?channels=gunicorn>`_
|
||||
on `Freenode`_.
|
||||
Feel free to join us in #gunicorn_ on freenode_.
|
||||
|
||||
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::
|
||||
|
||||
@ -20,145 +20,129 @@ Install from sources::
|
||||
Or from Pypi::
|
||||
|
||||
$ easy_install -U gunicorn
|
||||
|
||||
If you want to handle `sleepy applications <http://gunicorn.org/faq.html>`_
|
||||
you will need to install Eventlet_ or Gevent_.
|
||||
|
||||
.. note:
|
||||
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
|
||||
$ 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
|
||||
<http://gunicorn.org/usage.html>`_ for more information.
|
||||
.. note:
|
||||
If you encounter errors when compiling the extensions for Eventlet_ or
|
||||
Gevent_ you most likely need to install a newer version of libev_.
|
||||
|
||||
If you encounter errors when compiling the extensions for `gevent` or
|
||||
`eventlet` you probably need to install a newer version of libev_.
|
||||
Basic Usage
|
||||
-----------
|
||||
|
||||
.. _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
|
||||
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 with the expected::
|
||||
|
||||
$ gunicorn -h
|
||||
|
||||
gunicorn
|
||||
++++++++
|
||||
|
||||
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
|
||||
$ cd examples
|
||||
$ 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
|
||||
|
||||
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 = (
|
||||
...
|
||||
"gunicorn",
|
||||
)
|
||||
INSTALLED_APPS = (
|
||||
...
|
||||
"gunicorn",
|
||||
)
|
||||
|
||||
Then run::
|
||||
Then you can run::
|
||||
|
||||
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
|
||||
$ 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
|
||||
$ paster serve development.ini workers=2
|
||||
|
||||
In last case don't forget to add a server section for gunicorn. Here is an example that use
|
||||
gunicorn as main server::
|
||||
[server:main]
|
||||
use = egg:gunicorn#main
|
||||
host = 127.0.0.1
|
||||
port = 5000
|
||||
|
||||
[server:main]
|
||||
use = egg:gunicorn#main
|
||||
host = 127.0.0.1
|
||||
port = 5000
|
||||
|
||||
Kernel Parameters
|
||||
-----------------
|
||||
And then as per usual::
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
.. _Unicorn: http://unicorn.bogomips.org/
|
||||
.. _#gunicorn: http://webchat.freenode.net/?channels=gunicorn
|
||||
.. _freenode: http://freenode.net
|
||||
.. _Eventlet: http://eventlet.net
|
||||
.. _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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user