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

Editing the documentation.

Browse Source
This commit is contained in:
Paul J. Davis 2010-02-20 14:12:32 -05:00
parent 300d390f19
commit b202c879bd
8 changed files with 204 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
doc/htdocs/configuration.html
View File

@ -46,57 +46,58 @@
</div> </div>
<div class="document"> <div class="document">
<p>This manual to setup Gunicorn in production and use the configuration file.</p>
<div class="section" id="the-configuration-file"> <div class="section" id="the-configuration-file">
<h1>The configuration file</h1> <h1>The Configuration File</h1>
<p><a class="reference external" href="http://gunicorn.org">Gunicorn</a> 0.5 introduced the ability to read configuration from a file. Gunicorn will either look for &quot;gunicorn.conf.py&quot; in the current directory or a file referred through the -c flag.</p> <p>Gunciorn 0.5 introduced the ability to use a Python configuration file. Gunicorn will look for <tt class="docutils literal">gunicorn.conf.py</tt> in the current working directory or what ever path is specified on the command line with the <tt class="docutils literal"><span class="pre">-c</span></tt> option.</p>
<p>See <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn.conf.py.sample">github.com/benoitc/gunicorn/blob/master/examples/gunicorn.conf.py.sample</a> for an example of configuration file.</p> <p>A configuration file with default settings would look like this:</p>
<p>Default configuration settings are:</p>
<pre class="literal-block"> <pre class="literal-block">
bind='127.0.0.1:8000', bind = &quot;127.0.0.1:8000&quot; # Or &quot;unix:/tmp/gunicorn.sock&quot;
daemon=False, daemon = False # Whether work in the background
debug=False, debug = False # Some extra logging
logfile='-', logfile = &quot;-&quot; # Name of the log file
loglevel='info', loglevel = &quot;info&quot; # The level at which to log
pidfile=None, pidfile = None # Path to a PID file
workers=1, workers = 1 # Number of workers to initialize
umask=0, umask = 0 # Umask to set when daemonizing
user=None, user = None # Change process owner to user
group=None, group = None # Change process group to group
after_fork=lambda server, worker: server.log.info( def after_fork(server, worker):
&quot;worker=%s spawned pid=%s&quot; % (worker.id, str(worker.pid))), fmt = &quot;worker=%s spawned pid=%s&quot;
server.log.info(fmt % (worker.id, worker.pid))
before_fork=lambda server, worker: server.log.info( def before_fork(server, worker):
&quot;worker=%s spawning&quot; % worker.id), fmt = &quot;worker=%s spawning&quot;
server.log.info(fmt % worker.id)
before_exec=lambda server: server.log.info(&quot;forked child, reexecuting&quot;) def before_exec(server):
serer.log.info(&quot;Forked child, reexecuting.&quot;)
</pre> </pre>
<dl class="docutils"> <dl class="docutils">
<dt>after_fork:</dt> <dt>after_fork(server, worker):</dt>
<dd>this function is called by the worker after forking. Arguments are the master and worker instances.</dd> <dd>This is called by the worker after initialization.</dd>
<dt>before_fork:</dt> <dt>before_fork(server, worker):</dt>
<dd>this function is called by the worker before forking. Arguments are the master and worker instances.</dd> <dd>This is called by the worker just before forking.</dd>
<dt>before_exec:</dt> <dt>before_exec(server):</dt>
<dd>this function is called before relaunching the master. This happens when the master receive HUP or USR2 signals.</dd> <dd>This function is called before relaunching the master. This happens when the master receives a HUP or USR2 signal.</dd>
<dt>bind:</dt> <dt>bind:</dt>
<dd>address on which workers are listening. It could be a tcp address <cite>IP:PORT</cite> or a unix address <cite>unix:/path/to/sockfile</cite>.</dd> <dd>The address on which workers are listening. It can be a TCP address with a format of <tt class="docutils literal">IP:PORT</tt> or a Unix socket address like <tt class="docutils literal"><span class="pre">unix:/path/to/socketfile</span></tt>.</dd>
<dt>daemon:</dt> <dt>daemon:</dt>
<dd>Start in daemonized mode.</dd> <dd>Whether or not to detach the server from the controlling terminal.</dd>
<dt>debug:</dt> <dt>debug:</dt>
<dd>if set to <cite>True</cite>, only one worker will be launch and`the variable <cite>wsgi.multiprocess</cite> will be set to False.</dd> <dd>If <tt class="docutils literal">True</tt>, only one worker will be launch and the variable <tt class="docutils literal">wsgi.multiprocess</tt> will be set to False.</dd>
<dt>group:</dt> <dt>group:</dt>
<dd>the group on which workers processes will be launched.</dd> <dd>The group in which worker processes will be launched.</dd>
<dt>logfile:</dt> <dt>logfile:</dt>
<dd>path to the log file. <cite>-</cite> (stdout) by default.</dd> <dd>The path to the log file <tt class="docutils literal">-</tt> (stdout) by default.</dd>
<dt>loglevel:</dt> <dt>loglevel:</dt>
<dd>set debug level: info, debug, error</dd> <dd>The level at which to log. <tt class="docutils literal">info</tt>, <tt class="docutils literal">debug</tt>, or <tt class="docutils literal">error</tt> for instance. Only log messages of equal or greater severity are logged.</dd>
<dt>pidfile:</dt> <dt>pidfile:</dt>
<dd>file where master PID number will be saved</dd> <dd>A file to store the master's PID.</dd>
<dt>umask:</dt> <dt>umask:</dt>
<dd>in daemon mode, fix user mask of master.</dd> <dd>Used to set the umask when daemonizing.</dd>
<dt>user:</dt> <dt>user:</dt>
<dd>the user on which workers processes will be launched.</dd> <dd>The user as which worker processes will by launched.</dd>
</dl> </dl>
</div> </div>
<div class="section" id="production-setup"> <div class="section" id="production-setup">

24
doc/htdocs/index.html
View File

@ -34,23 +34,23 @@
</div> </div>
<div class="document" id="green-unicorn"> <div class="document" id="green-unicorn">
<h1 class="title">Green Unicorn</h1> <h1 class="title">Green Unicorn</h1>
<p>gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX, fast clients and nothing else.</p> <p>Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve fast clients and nothing else.</p>
<p>This is a port of Unicorn (<a class="reference external" href="http://unicorn.bogomips.org/">http://unicorn.bogomips.org/</a>) in Python. Meet us on <a class="reference external" href="http://webchat.freenode.net/?channels=gunicorn">#gunicorn irc channel</a> on <a class="reference external" href="http://freenode.net">Freenode</a>.</p> <p>This is a port of <a class="reference external" href="http://unicorn.bogomips.org/">Unicorn</a> in Python. Meet us on the <a class="reference external" href="http://webchat.freenode.net/?channels=gunicorn">#gunicorn IRC channel</a> on <a class="reference external" href="http://freenode.net">Freenode</a>.</p>
<p>Gunicorn is under MIT License. see <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/LICENSE">LICENSE</a> file for more details.</p> <p>Gunicorn is released under the MIT License. See the <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/LICENSE">LICENSE</a> for more details.</p>
<div class="section" id="features"> <div class="section" id="features">
<h1>Features</h1> <h1>Features</h1>
<ul class="simple"> <ul class="simple">
<li>Designed for WSGI, Unix and fast clients.</li> <li>Designed for Unix, WSGI, and fast clients</li>
<li>Compatible with Python 2.x superior to 2.5</li> <li>Compatible with Python 2.x (&gt;= 2.5)</li>
<li>Easy integration with <a class="reference external" href="http://djangoproject.com">Django</a> and <a class="reference external" href="http://pythonpaste.org/">Paster</a> compatible applications (Pylons, Turbogears 2, ...)</li> <li>Easy integration with <a class="reference external" href="http://djangoproject.com">Django</a> and <a class="reference external" href="http://pythonpaste.org/">Paster</a> compatible applications (Pylons, TurboGears 2, ...)</li>
<li>Process management: <a class="reference external" href="http://gunicorn.org">Gunicorn</a> reap and restart workers that die.</li> <li>Process management: <a class="reference external" href="http://gunicorn.org">Gunicorn</a> reaps and restarts workers that die.</li>
<li>Load balancing done by the os</li> <li>Load balancing via pre-fork and a shared socket</li>
<li>Graceful restart of workers</li> <li>Graceful worker process restarts</li>
<li>Upgrade &quot;àla nginx&quot; without losing connections</li> <li>Upgrade &quot;àla nginx&quot; without losing connections</li>
<li>Simple and easy Python DSL for configuration</li> <li>Simple and easy Python configuration</li>
<li>Decode chunked transfers on-the-fly, allowing upload progress notifications or <li>Decode chunked transfers on-the-fly, allowing upload progress notifications or
stream-based protocols over HTTP.</li> stream-based protocols over HTTP</li>
<li>post/pre fork hooks</li> <li>Post- and pre-fork hooks</li>
</ul> </ul>
</div> </div>
</div> </div>

39
doc/htdocs/installation.html
View File

@ -45,14 +45,19 @@
</ul> </ul>
</div> </div>
<div class="document"> <div class="document" id="installation">
<p>This is a manual for installing Gunicorn and its dependencies.</p> <h1 class="title">Installation</h1>
<div class="section" id="installing-gunicorn"> <div class="section" id="requirements">
<h1>Installing Gunicorn</h1> <h1>Requirements</h1>
<p>Gunicorn requires <strong>Python 2.x superior to 2.5</strong> to work. Python 3.x will be supported soon.</p> <ul class="simple">
<li><strong>Python 2.5 or newer</strong> (Python 3.x will be supported soon)</li>
<li>setuptools &gt;= 0.6c6</li>
<li>nosetests (for the test suite only)</li>
</ul>
</div>
<div class="section" id="installing-with-easy-install"> <div class="section" id="installing-with-easy-install">
<h2>Installing with easy_install</h2> <h1>Installing with easy_install</h1>
<p>To install Gunicorn using easy_install you must make sure you have a recent version of setuptools installed (as of this writing, 0.6c6 (0.6a9 on windows) or later):</p> <p>If you don't already have <tt class="docutils literal">easy_install</tt> available you'll want to download and run the <tt class="docutils literal">ez_setup.py</tt> script:</p>
<pre class="literal-block"> <pre class="literal-block">
$ curl -O http://peak.telecommunity.com/dist/ez_setup.py $ curl -O http://peak.telecommunity.com/dist/ez_setup.py
$ sudo python ez_setup.py -U setuptools $ sudo python ez_setup.py -U setuptools
@ -61,25 +66,23 @@ $ sudo python ez_setup.py -U setuptools
<pre class="literal-block"> <pre class="literal-block">
$ sudo easy_install -U gunicorn $ sudo easy_install -U gunicorn
</pre> </pre>
</div>
<div class="section" id="installing-from-source"> <div class="section" id="installing-from-source">
<h3>Installing from source</h3> <h1>Installing from source</h1>
<p>To install Gunicorn from source, simply use the normal procedure for installing any Python package. Since Gunicorn uses setuptools, all dependencies (including setuptools itself) will be automatically acquired and installed for you as appropriate.</p> <p>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).</p>
</div> <div class="section" id="get-a-copy">
</div> <h2>Get a Copy</h2>
<div class="section" id="fetch-sources"> <p>You can download a tarball of the latest sources from <a class="reference external" href="http://github.com/benoitc/gunicorn/downloads">GitHub Downloads</a> or fetch them with <a class="reference external" href="http://git-scm.com/">git</a>:</p>
<h2>Fetch sources</h2>
<p>You could download latest sources from <a class="reference external" href="http://github.com/benoitc/gunicorn/downloads">Github Downloads</a></p>
<p>Or fetch them with git. Therefore we have to <a class="reference external" href="http://git-scm.com/">install git</a> and then run:</p>
<pre class="literal-block"> <pre class="literal-block">
$ git clone git://github.com/benoitc/gunicorn.git $ git clone git://github.com/benoitc/gunicorn.git
</pre> </pre>
</div> </div>
<div class="section" id="install-gunicorn"> <div class="section" id="id1">
<h2>Install Gunicorn</h2> <h2>Installation</h2>
<pre class="literal-block"> <pre class="literal-block">
$ python setup.py install $ python setup.py install
</pre> </pre>
<p>If you're using a git clone, it's recommended to use the setuptools <cite>develop</cite> command, which will simply activate Gunicorn directly from your source directory. This way you can do a hg fetch or make changes to the source code without re-installing every time:</p> <p>If you've cloned the git repository, its highly recommended that you use the <tt class="docutils literal">develop</tt> 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:</p>
<pre class="literal-block"> <pre class="literal-block">
$ python setup.py develop $ python setup.py develop
</pre> </pre>

44
doc/htdocs/usage.html
View File

@ -2,7 +2,7 @@
<html lang="en"> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<title>Green Unicorn - Command line usage</title> <title>Green Unicorn - Command Line Usage</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" /> <link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<!--[if IE]> <!--[if IE]>
@ -46,8 +46,7 @@
</div> </div>
<div class="document" id="command-line-usage"> <div class="document" id="command-line-usage">
<h1 class="title">Command line usage</h1> <h1 class="title">Command Line Usage</h1>
<p><a class="reference external" href="http://gunicorn.org">Gunicorn</a> can easily be launched from the command line. This manual will show you how to use it with:</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#wsgi-applications">WSGI applications</a></li> <li><a class="reference internal" href="#wsgi-applications">WSGI applications</a></li>
<li><a class="reference internal" href="#django-projects">Django projects</a></li> <li><a class="reference internal" href="#django-projects">Django projects</a></li>
@ -55,11 +54,16 @@
</ul> </ul>
<div class="section" id="wsgi-applications"> <div class="section" id="wsgi-applications">
<h1>WSGI applications</h1> <h1>WSGI applications</h1>
<p>Here is how to launch your application in less than 30 seconds. Here is an example with our <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/test.py">test application</a>:</p> <p>Thirty seconds to launch the <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/test.py">example application</a> packaged with Gunicorn:</p>
<pre class="literal-block"> <pre class="literal-block">
$ cd examples $ cd /path/to/gunicorn/examples/
$ gunicorn --workers=2 test:application $ gunicorn --workers=2 test:application
</pre> </pre>
<p>The module <tt class="docutils literal">test:application</tt> specifies the complete module name and WSGI callable. You can replace it with anything that is available on your <tt class="docutils literal">PYTHONPATH</tt> like such:</p>
<pre class="literal-block">
$ cd ~/
$ gunicorn --workers=12 awesomeproject.wsgi.main:main_app
</pre>
<div class="section" id="full-command-line-usage"> <div class="section" id="full-command-line-usage">
<h2>Full command line usage</h2> <h2>Full command line usage</h2>
<pre class="literal-block"> <pre class="literal-block">
@ -90,18 +94,18 @@ Options:
</div> </div>
</div> </div>
<div class="section" id="django-projects"> <div class="section" id="django-projects">
<h1>Django projects</h1> <h1>Django Projects</h1>
<p><a class="reference external" href="http://djangoproject.com">Django</a> projects can be handled easily by <a class="reference external" href="http://gunicorn.org">Gunicorn</a> using the <cite>gunicorn_django</cite> command:</p> <p><a class="reference external" href="http://djangoproject.com">Django</a> projects can be handled easily by Gunicorn using the <tt class="docutils literal">gunicorn_django</tt> command:</p>
<pre class="literal-block"> <pre class="literal-block">
$ cd yourdjangoproject $ cd $yourdjangoproject
$ gunicorn_django --workers=2 $ gunicorn_django --workers=2
</pre> </pre>
<p>But you can also use <cite>run_gunicorn</cite> <a class="reference external" href="http://docs.djangoproject.com/en/dev/howto/custom-management-commands/">admin command</a> like all other commands.</p> <p>But you can also use the <tt class="docutils literal">run_gunicorn</tt> <a class="reference external" href="http://docs.djangoproject.com/en/dev/howto/custom-management-commands/">admin command</a> like the other <tt class="docutils literal">management.py</tt> commands.</p>
<p>add <cite>gunicorn</cite> to INSTALLED_APPS in the settings file:</p> <p>Add <tt class="docutils literal">&quot;gunicorn&quot;</tt> to INSTALLED_APPS in your settings file:</p>
<pre class="literal-block"> <pre class="literal-block">
INSTALLED_APPS = ( INSTALLED_APPS = (
... ...
&quot;gunicorn&quot;, &quot;gunicorn&quot;,
) )
</pre> </pre>
<p>Then run:</p> <p>Then run:</p>
@ -111,23 +115,23 @@ python manage.py run_gunicorn
</div> </div>
<div class="section" id="paste-compatible-projects"> <div class="section" id="paste-compatible-projects">
<h1>Paste-compatible projects</h1> <h1>Paste-compatible projects</h1>
<p>For <a class="reference external" href="http://pythonpaste.org/script/">Paste</a> compatible projects (like <a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...) use the <cite>gunicorn_paste</cite> command:</p> <p>For <a class="reference external" href="http://pythonpaste.org/script/">Paste</a> compatible projects (<a class="reference external" href="http://pylonshq.com/">Pylons</a>, <a class="reference external" href="http://turbogears.org/2.0/">TurboGears 2</a>, ...) use the <tt class="docutils literal">gunicorn_paste</tt> command:</p>
<pre class="literal-block"> <pre class="literal-block">
$ cd your pasteproject $ cd $yourpasteproject
$ gunicorn_paste --workers=2 development.ini $ gunicorn_paste --workers=2 development.ini
</pre> </pre>
<p>or usual <strong>paster</strong> command:</p> <p>To use the <tt class="docutils literal">paster</tt> command add a sever section for Gunicorn:</p>
<pre class="literal-block">
$ cd your pasteproject
$ paster serve development.ini workers=2
</pre>
<p>In this case don't forget to add a server section for <a class="reference external" href="http://gunicorn.org">Gunicorn</a>. Here is an example that use gunicorn as main server:</p>
<pre class="literal-block"> <pre class="literal-block">
[server:main] [server:main]
use = egg:gunicorn#main use = egg:gunicorn#main
host = 127.0.0.1 host = 127.0.0.1
port = 5000 port = 5000
</pre> </pre>
<p>And then all you need to do is:</p>
<pre class="literal-block">
$ cd $yourpasteproject
$ paster serve development.ini workers=2
</pre>
</div> </div>
</div> </div>

76
doc/site/configuration.rst
View File

@ -1,74 +1,70 @@
template: doc.html template: doc.html
title: Configuration title: Configuration
This manual to setup Gunicorn in production and use the configuration file. The Configuration File
The configuration file
---------------------- ----------------------
`Gunicorn`_ 0.5 introduced the ability to read configuration from a file. Gunicorn will either look for "gunicorn.conf.py" in the current directory or a file referred through the -c flag. 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.
See `github.com/benoitc/gunicorn/blob/master/examples/gunicorn.conf.py.sample <http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn.conf.py.sample>`_ for an example of configuration file. A configuration file with default settings would look like this::
Default configuration settings are:: bind = "127.0.0.1:8000" # Or "unix:/tmp/gunicorn.sock"
daemon = False # Whether work in the background
debug = False # Some extra logging
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
bind='127.0.0.1:8000', def after_fork(server, worker):
daemon=False, fmt = "worker=%s spawned pid=%s"
debug=False, server.log.info(fmt % (worker.id, worker.pid))
logfile='-',
loglevel='info',
pidfile=None,
workers=1,
umask=0,
user=None,
group=None,
after_fork=lambda server, worker: server.log.info( def before_fork(server, worker):
"worker=%s spawned pid=%s" % (worker.id, str(worker.pid))), fmt = "worker=%s spawning"
server.log.info(fmt % worker.id)
before_fork=lambda server, worker: server.log.info( def before_exec(server):
"worker=%s spawning" % worker.id), serer.log.info("Forked child, reexecuting.")
before_exec=lambda server: server.log.info("forked child, reexecuting") after_fork(server, worker):
This is called by the worker after initialization.
before_fork(server, worker):
This is called by the worker just before forking.
before_exec(server):
after_fork: This function is called before relaunching the master. This happens when the master receives a HUP or USR2 signal.
this function is called by the worker after forking. Arguments are the master and worker instances.
before_fork:
this function is called by the worker before forking. Arguments are the master and worker instances.
before_exec:
this function is called before relaunching the master. This happens when the master receive HUP or USR2 signals.
bind: bind:
address on which workers are listening. It could be a tcp address `IP:PORT` or a unix address `unix:/path/to/sockfile`. 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: daemon:
Start in daemonized mode. Whether or not to detach the server from the controlling terminal.
debug: debug:
if set to `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: group:
the group on which workers processes will be launched. The group in which worker processes will be launched.
logfile: logfile:
path to the log file. `-` (stdout) by default. The path to the log file ``-`` (stdout) by default.
loglevel: loglevel:
set debug level: info, debug, error The level at which to log. ``info``, ``debug``, or ``error`` for instance. Only log messages of equal or greater severity are logged.
pidfile: pidfile:
file where master PID number will be saved A file to store the master's PID.
umask: umask:
in daemon mode, fix user mask of master. Used to set the umask when daemonizing.
user: user:
the user on which workers processes will be launched. The user as which worker processes will by launched.
Production setup Production setup
---------------- ----------------

31
doc/site/index.rst
View File

@ -3,26 +3,31 @@ template: index.html
Green Unicorn Green Unicorn
============= =============
gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX, fast clients and nothing else. Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve fast clients and nothing else.
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`_. This is a port of Unicorn_ in Python. Meet us on the `#gunicorn IRC channel`_ on Freenode_.
Gunicorn is under MIT License. see `LICENSE <http://github.com/benoitc/gunicorn/blob/master/LICENSE>`_ file for more details. Gunicorn is released under the MIT License. See the LICENSE_ for more details.
Features Features
-------- --------
- Designed for WSGI, Unix and fast clients. - Designed for Unix, WSGI, and fast clients
- Compatible with Python 2.x superior to 2.5 - Compatible with Python 2.x (>= 2.5)
- Easy integration with `Django <http://djangoproject.com>`_ and `Paster <http://pythonpaste.org/>`_ compatible applications (Pylons, Turbogears 2, ...) - Easy integration with Django_ and Paster_ compatible applications (Pylons, TurboGears 2, ...)
- Process management: `Gunicorn`_ reap and restart workers that die. - Process management: Gunicorn_ reaps and restarts workers that die.
- Load balancing done by the os - Load balancing via pre-fork and a shared socket
- Graceful restart of workers - Graceful worker process restarts
- Upgrade "àla nginx" without losing connections - Upgrade "àla nginx" without losing connections
- Simple and easy Python DSL for configuration - Simple and easy Python configuration
- Decode chunked transfers on-the-fly, allowing upload progress notifications or - Decode chunked transfers on-the-fly, allowing upload progress notifications or
stream-based protocols over HTTP. stream-based protocols over HTTP
- post/pre fork hooks - Post- and pre-fork hooks
.. _freenode: http://freenode.net .. _Unicorn: http://unicorn.bogomips.org/
.. _`#gunicorn IRC channel`: http://webchat.freenode.net/?channels=gunicorn
.. _Freenode: http://freenode.net
.. _LICENSE: http://github.com/benoitc/gunicorn/blob/master/LICENSE
.. _Gunicorn: http://gunicorn.org .. _Gunicorn: http://gunicorn.org
.. _Django: http://djangoproject.com
.. _Paster: http://pythonpaste.org/

33
doc/site/installation.rst
View File

@ -1,18 +1,20 @@
template: doc.html template: doc.html
title: Installing Gunicorn title: Installing Gunicorn
Installation
============
This is a manual for installing Gunicorn and its dependencies. Requirements
------------
Installing Gunicorn - **Python 2.5 or newer** (Python 3.x will be supported soon)
===================== - setuptools >= 0.6c6
- nosetests (for the test suite only)
Gunicorn requires **Python 2.x superior to 2.5** to work. Python 3.x will be supported soon.
Installing with easy_install Installing with easy_install
++++++++++++++++++++++++++++ ----------------------------
To install Gunicorn using easy_install you must make sure you have a recent version of setuptools installed (as of this writing, 0.6c6 (0.6a9 on windows) or later):: 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 $ curl -O http://peak.telecommunity.com/dist/ez_setup.py
$ sudo python ez_setup.py -U setuptools $ sudo python ez_setup.py -U setuptools
@ -24,24 +26,25 @@ To install or upgrade to the latest released version of Gunicorn::
Installing from source Installing from source
---------------------- ----------------------
To install Gunicorn from source, simply use the normal procedure for installing any Python package. Since Gunicorn uses setuptools, all dependencies (including setuptools itself) will be automatically acquired and installed for you as appropriate. 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).
Fetch sources Get a Copy
+++++++++++++ ++++++++++
You could download latest sources from `Github Downloads <http://github.com/benoitc/gunicorn/downloads>`_ You can download a tarball of the latest sources from `GitHub Downloads`_ or fetch them with git_::
Or fetch them with git. Therefore we have to `install git <http://git-scm.com/>`_ and then run:: $ git clone git://github.com/benoitc/gunicorn.git
$ git clone git://github.com/benoitc/gunicorn.git .. _`GitHub Downloads`: http://github.com/benoitc/gunicorn/downloads
.. _git: http://git-scm.com/
Install Gunicorn Installation
++++++++++++++++ ++++++++++++++++
:: ::
$ python setup.py install $ python setup.py install
If you're using a git clone, it's recommended to use the setuptools `develop` command, which will simply activate Gunicorn directly from your source directory. This way you can do a hg fetch or make changes to the source code without re-installing every time:: 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 $ python setup.py develop

64
doc/site/usage.rst
View File

@ -1,11 +1,9 @@
template: doc.html template: doc.html
title: Command line usage title: Command Line Usage
Command line usage Command Line Usage
================== ==================
`Gunicorn`_ can easily be launched from the command line. This manual will show you how to use it with:
- `WSGI applications`_ - `WSGI applications`_
- `Django projects`_ - `Django projects`_
- `Paste-compatible projects`_ - `Paste-compatible projects`_
@ -13,10 +11,15 @@ Command line usage
WSGI applications WSGI applications
----------------- -----------------
Here is how to launch your application in less than 30 seconds. Here is an example with our `test application <http://github.com/benoitc/gunicorn/blob/master/examples/test.py>`_:: Thirty seconds to launch the `example application`_ packaged with Gunicorn::
$ cd examples $ cd /path/to/gunicorn/examples/
$ gunicorn --workers=2 test:application $ gunicorn --workers=2 test:application
The module ``test:application`` 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
Full command line usage Full command line usage
+++++++++++++++++++++++ +++++++++++++++++++++++
@ -47,52 +50,51 @@ Full command line usage
--version show program's version number and exit --version show program's version number and exit
-h, --help show this help message and exit -h, --help show this help message and exit
Django projects 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 $ cd $yourdjangoproject
$ gunicorn_django --workers=2 $ 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 `run_gunicorn` `admin command <http://docs.djangoproject.com/en/dev/howto/custom-management-commands/>`_ like all other commands. Add ``"gunicorn"`` to INSTALLED_APPS in your settings file::
add `gunicorn` to INSTALLED_APPS in the settings file:: INSTALLED_APPS = (
...
INSTALLED_APPS = ( "gunicorn",
... )
"gunicorn",
)
Then run:: Then run::
python manage.py run_gunicorn python manage.py run_gunicorn
Paste-compatible projects Paste-compatible projects
------------------------- -------------------------
For `Paste`_ compatible projects (like `Pylons`_, `TurboGears 2`_, ...) use the `gunicorn_paste` command:: For `Paste`_ compatible projects (`Pylons`_, `TurboGears 2`_, ...) use the ``gunicorn_paste`` command::
$ cd your pasteproject $ cd $yourpasteproject
$ gunicorn_paste --workers=2 development.ini $ gunicorn_paste --workers=2 development.ini
or usual **paster** command:: To use the ``paster`` command add a sever section for Gunicorn::
$ cd your pasteproject [server:main]
$ paster serve development.ini workers=2 use = egg:gunicorn#main
host = 127.0.0.1
port = 5000
In this case don't forget to add a server section for `Gunicorn`_. Here is an example that use gunicorn as main server:: And then all you need to do is::
[server:main] $ cd $yourpasteproject
use = egg:gunicorn#main $ paster serve development.ini workers=2
host = 127.0.0.1
port = 5000
.. _`example application`: http://github.com/benoitc/gunicorn/blob/master/examples/test.py
.. _Gunicorn: http://gunicorn.org
.. _Django: http://djangoproject.com .. _Django: http://djangoproject.com
.. _`admin command`: http://docs.djangoproject.com/en/dev/howto/custom-management-commands/
.. _Paste: http://pythonpaste.org/script/ .. _Paste: http://pythonpaste.org/script/
.. _Pylons: http://pylonshq.com/ .. _Pylons: http://pylonshq.com/
.. _Turbogears 2: http://turbogears.org/2.0/ .. _Turbogears 2: http://turbogears.org/2.0/