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

Setup redirects from old URLS.

Browse Source
This commit is contained in:
Paul J. Davis 2010-05-30 15:21:17 -04:00
parent d26afdacc1
commit 7056ab902b
5 changed files with 29 additions and 722 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
doc/htdocs/configuration.html
View File

@ -2,133 +2,12 @@
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - The Configuration File</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" />
<meta http-equiv="refresh" content="2;url=http://gunicorn.org/configure.html" />
<title>Green Unicorn - Configuration</title>
</head>
<body>
<div class="container">
<div id="header">
<a href="http://gunicorn.org">
<img src="/images/logo.png" alt="Gunicorn - Green Unicorn" />
</a>
</div>
<div id="menu">
<ul id="actions">
<li><a href="install.html">Install</a></li>
<li><a href="configure.html">Configure</a></li>
<li><a href="deploy.html">Deploy</a></li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="news.html">News</a></li>
</ul>
</div>
<div class="document" id="the-configuration-file">
<h1 class="title">The Configuration File</h1>
<p>Gunicorn 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>
<div class="section" id="example-gunicorn-conf-py">
<h2>Example gunicorn.conf.py</h2>
<pre class="literal-block">
backlog = 2048 # The listen queue size for the server socket
bind = &quot;127.0.0.1:8000&quot; # Or &quot;unix:/tmp/gunicorn.sock&quot;
daemon = False # Whether work in the background
debug = False # Some extra logging
keepalive = 2 # Time we wait for next connection (in seconds)
logfile = &quot;-&quot; # Name of the log file
loglevel = &quot;info&quot; # The level at which to log
pidfile = None # Path to a PID file
workers = 1 # Number of workers to initialize
umask = 0 # Umask to set when daemonizing
user = None # Change process owner to user
group = None # Change process group to group
proc_name = None # Change the process name
spew=False # Display trace
timeout=30 # Worker timeout
tmp_upload_dir = None # Set path used to store temporary uploads
worker_class = &quot;egg:gunicorn#sync&quot; # The type of request processing to use
worker_connections=1000 # Maximum number of simultaneous connections
after_fork=lambda server, worker: server.log.info(
&quot;Worker spawned (pid: %s)&quot; % worker.pid)
before_fork=lambda server, worker: True
before_exec=lambda server: server.log.info(&quot;Forked child, reexecuting&quot;)
when_ready=lambda server: server.log.info(&quot;Gunicorn started.&quot;)
</pre>
</div>
<div class="section" id="parameter-descriptions">
<h2>Parameter Descriptions</h2>
<dl class="docutils">
<dt>after_fork(server, worker):</dt>
<dd>This is called by the worker after initialization.</dd>
<dt>worker_class:</dt>
<dd><p class="first">Define the type of worker to use. A worker process all the requests send by
the arbiter.By default the worker_class is <cite>egg:gunicorn#sync</cite>. This worker
only supports fast request handling requiring a buffering HTTP proxy.</p>
<p class="last">If your application requires the ability to handle prolonged requests to
provide long polling, comet, or calling an external web service you'll
need to use an async worker. Gunicorn has three async workers built in
using <a class="reference external" href="http://www.tornadoweb.org/">Tornado</a>, <a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a>. You can also use the Evenlet
worker with the <a class="reference external" href="http://twistedmatrix.com">Twisted</a> helper.</p>
</dd>
<dt>backlog:</dt>
<dd>The backlog parameter defines the maximum length for the queue of pending
connections. The default is 2048. See listen(2) for more information</dd>
<dt>before_fork(server, worker):</dt>
<dd>This is called by the worker just before forking.</dd>
<dt>before_exec(server):</dt>
<dd>This function is called before relaunching the master. This happens when
the master receives a HUP or USR2 signal.</dd>
<dt>bind:</dt>
<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>
<dd>Whether or not to detach the server from the controlling terminal.</dd>
<dt>debug:</dt>
<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>
<dd>The group in which worker processes will be launched.</dd>
<dt>keepalive:</dt>
<dd>KeepAlive timeout. The default is 2 seconds, which should be enough under
most conditions for browsers to render the page and start retrieving extra
elements for. Increasing this beyond 5 seconds is not recommended. Zero
disables KeepAlive entirely.</dd>
<dt>logfile:</dt>
<dd>The path to the log file <tt class="docutils literal">-</tt> (stdout) by default.</dd>
<dt>loglevel:</dt>
<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>
<dd>A file to store the master's PID.</dd>
<dt>proc_name:</dt>
<dd>A name for the master process. Only takes effect if <a class="reference external" href="http://pypi.python.org/pypi/setproctitle">setproctitle</a> is
installed. This alters the process names listed by commands like <tt class="docutils literal">ps</tt>.</dd>
<dt>umask:</dt>
<dd>Used to set the umask when daemonizing.</dd>
<dt>user:</dt>
<dd>The user as which worker processes will by launched.</dd>
<dt>when_ready(server):</dt>
<dd>This is called by the arbiter just after Gunicorn started.</dd>
<dt>worker_connections:</dt>
<dd>Number of simultaneous connections a worker can handle when used with
Eventlet or Gevent arbiter. The default is 1000.</dd>
<dt>timeout:</dt>
<dd>Set worker timeout.</dd>
<dt>tmp_upload_dir:</dt>
<dd>Set the path used to store temporarily the body of the request.</dd>
</dl>
</div>
</div>
<div id="footer">
<p>This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>.</p>
<p>Hosted on <a href="http://github.com/">Github</a></p>
</div>
</div>
<h2>
Redirecting to <a href="http://gunicorn.org/configure.html">here</a>
</h2>
</body>
</html>
</html>

194
doc/htdocs/deployment.html
View File

@ -1,194 +1,12 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - Deployment</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" />
<meta http-equiv="refresh" content="2;url=http://gunicorn.org/deploy.html" />
<title>Green Unicorn - Deploy</title>
</head>
<body>
<div class="container">
<div id="header">
<a href="http://gunicorn.org">
<img src="/images/logo.png" alt="Gunicorn - Green Unicorn" />
</a>
</div>
<div id="menu">
<ul id="actions">
<li><a href="install.html">Install</a></li>
<li><a href="configure.html">Configure</a></li>
<li><a href="deploy.html">Deploy</a></li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="news.html">News</a></li>
</ul>
</div>
<div class="document" id="production-setup">
<h1 class="title">Production Setup</h1>
<div class="section" id="synchronous-vs-asynchronous-workers">
<h2>Synchronous vs Asynchronous workers</h2>
<p>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.</p>
<p>This CPU bound assumption is why the default configuration needs to use a
buffering HTTP proxy like <a class="reference external" href="http://www.nginx.org">Nginx</a> 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).</p>
<p>Example use-cases for asynchronous workers:</p>
<blockquote>
<ul class="simple">
<li>Applications making long blocking calls (Ie, to external web services)</li>
<li>Serving requests directly to the internet</li>
<li>Streaming requests and responses</li>
<li>Long polling</li>
<li>Web sockets</li>
<li>Comet</li>
</ul>
</blockquote>
</div>
<div class="section" id="basic-nginx-configuration">
<h2>Basic Nginx Configuration</h2>
<p>Although there are many HTTP proxies available, we strongly advise that you
use <a class="reference external" href="http://www.nginx.org">Nginx</a>. If you choose another proxy server you need to make sure that it
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 <a class="reference external" href="http://ha.ckers.org/slowloris/">slowloris</a> to check if your proxy is behaving properly.</p>
<p>An <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf">example configuration</a> file for fast clients with <a class="reference external" href="http://www.nginx.org">Nginx</a>:</p>
<pre class="literal-block">
worker_processes 1;
user nobody nogroup;
pid /tmp/nginx.pid;
error_log /tmp/nginx.error.log;
events {
worker_connections 1024;
accept_mutex off;
}
http {
include mime.types;
default_type application/octet-stream;
access_log /tmp/nginx.access.log combined;
sendfile on;
upstream app_server {
server unix:/tmp/gunicorn.sock fail_timeout=0;
# For a TCP configuration:
# server 192.168.0.7:8000 fail_timeout=0;
}
server {
listen 80 default;
client_max_body_size 4G;
server_name _;
keepalive_timeout 5;
# path for static files
root /path/to/app/current/public;
location / {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_redirect off;
if (!-f $request_filename) {
proxy_pass http://app_server;
break;
}
}
error_page 500 502 503 504 /500.html;
location = /500.html {
root /path/to/app/current/public;
}
}
}
</pre>
<p>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. <strong>When you do this</strong> you must run with one of the async worker
classes.</p>
<p>To turn off buffering, you only need to add <tt class="docutils literal">proxy_buffering off;</tt> to your
<tt class="docutils literal">location</tt> block:</p>
<pre class="literal-block">
...
location / {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_redirect off;
proxy_buffering off;
if (!-f $request_filename) {
proxy_pass http://app_server;
break;
}
}
...
</pre>
</div>
<div class="section" id="working-with-virtualenv">
<h2>Working with Virtualenv</h2>
<p>To serve an app from a <a class="reference external" href="http://pypi.python.org/pypi/virtualenv">Virtualenv</a> it is generally easiest to just install
Gunicorn directly into the Virtualenv. This will create a set of Gunicorn
scripts for that Virtualenv which can be used to run applications normally.</p>
<p>If you have Virtualenv installed, you should be able to do something like
this:</p>
<pre class="literal-block">
$ mkdir ~/venvs/
$ virtualenv ~/venvs/webapp
$ source ~/venvs/webapp/bin/activate
$ ~/venvs/webapp/bin/easy_install -U gunicorn
$ deactivate
</pre>
<p>Then you just need to use one of the three Gunicorn scripts that was installed
into <tt class="docutils literal">~/venvs/webapp/bin</tt>.</p>
</div>
<div class="section" id="daemon-monitoring">
<h2>Daemon Monitoring</h2>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Make sure that when using either of these service monitors you do not
enable the Gunicorn's daemon mode. These monitors expect that the process
they launch will be the process they need to monior. Daemonizing
will fork-exec which creates an unmonitored process and generally just
confuses the monitor services.</p>
</div>
<p>A popular method for deploying Gunicorn is to have it monitored by <a class="reference external" href="http://smarden.org/runit/">runit</a>.
An <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc">example service</a> definition:</p>
<pre class="literal-block">
#!/bin sh
GUNICORN=/usr/local/bin/gunicorn
ROOT=/path/to/project
PID=/var/run/gunicorn.pid
APP=main:application
if [ -f $PID ]; then rm $PID fi
cd $ROOT
exec $GUNICORN -C $ROOT/gunicorn.conf.py --pidfile=$PID $APP
</pre>
<p>Another useful tool to monitor and control Gunicorn is <a class="reference external" href="http://supervisord.org">Supervisor</a>. A
<a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/supervisor.conf">simple configuration</a> is:</p>
<pre class="literal-block">
[program:gunicorn]
command=/usr/local/bin/gunicorn main:application -c /path/to/project/gunicorn.conf.py
directory=/path/to/project
user=nobody
autostart=true
autorestart=true
redirect_stderr=True
</pre>
</div>
</div>
<div id="footer">
<p>This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>.</p>
<p>Hosted on <a href="http://github.com/">Github</a></p>
</div>
</div>
<h2>
Redirecting to <a href="http://gunicorn.org/deploy.html">here</a>
</h2>
</body>
</html>
</html>

125
doc/htdocs/installation.html
View File

@ -1,127 +1,12 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - Installing Gunicorn</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" />
<meta http-equiv="refresh" content="2;url=http://gunicorn.org/install.html" />
<title>Green Unicorn - Install</title>
</head>
<body>
<div class="container">
<div id="header">
<a href="http://gunicorn.org">
<img src="/images/logo.png" alt="Gunicorn - Green Unicorn" />
</a>
</div>
<div id="menu">
<ul id="actions">
<li><a href="install.html">Install</a></li>
<li><a href="configure.html">Configure</a></li>
<li><a href="deploy.html">Deploy</a></li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="news.html">News</a></li>
</ul>
</div>
<div class="document" id="installation">
<h1 class="title">Installation</h1>
<div class="section" id="requirements">
<h2>Requirements</h2>
<ul class="simple">
<li><strong>Python 2.x &gt;= 2.5</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">
<h1>Installing with easy_install</h1>
<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">
$ curl -O http://peak.telecommunity.com/dist/ez_setup.py
$ sudo python ez_setup.py -U setuptools
</pre>
<p>To install or upgrade to the latest released version of Gunicorn:</p>
<pre class="literal-block">
$ sudo easy_install -U gunicorn
</pre>
</div>
<div class="section" id="installing-from-source">
<h2>Installing from source</h2>
<p>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).</p>
<div class="section" id="get-a-copy">
<h3>Get a Copy</h3>
<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>
<pre class="literal-block">
$ git clone git://github.com/benoitc/gunicorn.git
</pre>
</div>
<div class="section" id="id1">
<h3>Installation</h3>
<pre class="literal-block">
$ python setup.py install
</pre>
<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">
$ python setup.py develop
</pre>
</div>
</div>
<div class="section" id="enabling-async-workers">
<h2>Enabling async workers</h2>
<p>You may also want to install <a class="reference external" href="http://eventlet.net">Eventlet</a> or <a class="reference external" href="http://gevent.org">Gevent</a> if you expect that your
application code may need to pause for extended periods of time during
request processing. Check out the <a class="reference external" href="faq.html">FAQ</a> for more information on when you'll
want to consider one of the alternate worker types.</p>
<p>To install eventlet:</p>
<pre class="literal-block">
$ easy_install -U greenlet # Required for both
$ easy_install -U eventlet # For eventlet workers
$ easy_install -U gevent # For gevent workers
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p>If installing <tt class="docutils literal">greenlet</tt> fails you probably need to install
the Python headers. These headers are available in most package
managers. On Ubuntu the package name for <tt class="docutils literal"><span class="pre">apt-get</span></tt> is
<tt class="docutils literal"><span class="pre">python-dev</span></tt>.</p>
<p class="last"><a class="reference external" href="http://gevent.org">Gevent</a> also requires that <tt class="docutils literal">libevent</tt> 1.4.x or 2.0.4 is installed.
This could be a more recent version than what is available in your
package manager. If <a class="reference external" href="http://gevent.org">Gevent</a> fails to build even with <tt class="docutils literal">libevent</tt>
installed, this is the most likely reason.</p>
</div>
</div>
<div class="section" id="installing-on-ubuntu-debian-systems">
<h2>Installing on Ubuntu/Debian systems</h2>
<p>If you use <a class="reference external" href="http://www.ubuntu.com/">Ubuntu</a> karmic, you can update your system with packages from
our <a class="reference external" href="https://launchpad.net/~bchesneau/+archive/gunicorn">PPA</a> by adding <tt class="docutils literal">ppa:bchesneau/gunicorn</tt> to your system's Software
Sources.</p>
<p>Or this PPA can be added to your system manually by copying the lines below
and adding them to your system's software sources:</p>
<pre class="literal-block">
deb http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
deb-src http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
</pre>
<p>Signing key:</p>
<pre class="literal-block">
1024R/15E5EB06
</pre>
<p>Fingerprint:</p>
<pre class="literal-block">
49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06
</pre>
</div>
</div>
<div id="footer">
<p>This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>.</p>
<p>Hosted on <a href="http://github.com/">Github</a></p>
</div>
</div>
<h2>
Redirecting to <a href="http://gunicorn.org/install.html">here</a>
</h2>
</body>
</html>

88
doc/htdocs/tuning.html
View File

@ -2,88 +2,12 @@
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - Tuning</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" />
<meta http-equiv="refresh" content="2;url=http://gunicorn.org/faq.html" />
<title>Green Unicorn - FAQ</title>
</head>
<body>
<div class="container">
<div id="header">
<a href="./">
<img src="images/logo.png" alt="Gunicorn - Green Unicorn" />
</a>
</div>
<div id="menu">
<ul id="actions">
<li><a href="install.html">Install</a></li>
<li><a href="run.html">Run</a></li>
<li><a href="configure.html">Configure</a></li>
<li><a href="deploy.html">Deploy</a></li>
<li><a href="design.html">Design</a><li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="news.html">News</a></li>
<li><a href="http://github.com/benoitc/gunicorn/">Code</a></li>
</ul>
</div>
<div id="content">
<div class="document" id="tuning">
<h1 class="title">Tuning</h1>
<div class="section" id="unicorn-configuration">
<h2>Unicorn Configuration</h2>
<p>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 <strong>NOT</strong> designed for serving slow
clients, that's the job of <a class="reference external" href="http://www.nginx.org">Nginx</a>.</p>
<p>See <a class="reference external" href="configuration.html">Configuration</a> for a more thorough description of the available parameters.</p>
</div>
<div class="section" id="kernel-parameters">
<h2>Kernel Parameters</h2>
<p>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.</p>
<p>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.</p>
<div class="section" id="file-descriptor-limits">
<h3>File Descriptor Limits</h3>
<p>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.</p>
<pre class="literal-block">
$ sudo ulimit -n 2048
</pre>
</div>
<div class="section" id="listen-queue-size">
<h3>Listen Queue Size</h3>
<p>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.</p>
<pre class="literal-block">
$ sudo sysctl -w kern.ipc.somaxconn=&quot;2048&quot;
</pre>
</div>
<div class="section" id="ephemeral-port-range">
<h3>Ephemeral Port Range</h3>
<p>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.</p>
<p>This setting is generally only required on machines that are being used to test
a network server.</p>
<pre class="literal-block">
$ sudo sysctl -w net.inet.ip.portrange.first=&quot;8048&quot;
</pre>
</div>
</div>
</div>
</div>
<div id="footer">
<p>This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>.</p>
<p>Hosted on <a href="http://github.com/">Github</a></p>
</div>
</div>
<h2>
Redirecting to <a href="http://gunicorn.org/faq.html">here</a>
</h2>
</body>
</html>
</html>

211
doc/htdocs/usage.html
View File

@ -2,211 +2,12 @@
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - Command Line Usage</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" />
<meta http-equiv="refresh" content="2;url=http://gunicorn.org/run.html" />
<title>Green Unicorn - Run</title>
</head>
<body>
<div class="container">
<div id="header">
<a href="http://gunicorn.org">
<img src="/images/logo.png" alt="Gunicorn - Green Unicorn" />
</a>
</div>
<div id="menu">
<ul id="actions">
<li><a href="install.html">Install</a></li>
<li><a href="configure.html">Configure</a></li>
<li><a href="deploy.html">Deploy</a></li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="news.html">News</a></li>
</ul>
</div>
<div class="document" id="usage">
<h1 class="title">Usage</h1>
<p>After installing Gunicorn you will have access to three command line scripts
that can be used for serving the various supported web frameworks: <tt class="docutils literal">gunicorn</tt>,
<tt class="docutils literal">gunicorn_django</tt>, and <tt class="docutils literal">gunicorn_paster</tt>.</p>
<div class="section" id="commonly-used-arguments">
<h2>Commonly Used Arguments</h2>
<blockquote>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">-c</span> CONFIG, <span class="pre">--config=CONFIG</span></tt></dt>
<dd>Specify the path to a <a class="reference external" href="configuration.html">config file</a></dd>
<dt><tt class="docutils literal"><span class="pre">-b</span> BIND, <span class="pre">--bind=BIND</span></tt></dt>
<dd>Specify a server socket to bind. Server sockets can be any of <tt class="docutils literal">$(HOST)</tt>,
<tt class="docutils literal"><span class="pre">$(HOST):$(PORT)</span></tt>, or <tt class="docutils literal"><span class="pre">unix:$(PATH)</span></tt>. An IP is a valid <tt class="docutils literal">$(HOST)</tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-w</span> WORKERS, <span class="pre">--workers=WORKERS</span></tt></dt>
<dd>The number of worker processes. This number should generally be between 2-4
workers per core in the server. Check the <a class="reference external" href="faq.html">FAQ</a> for ideas on tuning this
parameter.</dd>
<dt><tt class="docutils literal"><span class="pre">-k</span> WORKERCLASS, <span class="pre">--worker-class=WORKERCLASS</span></tt></dt>
<dd>The type of worker process to run. You'll definitely want to read the
<a class="reference external" href="deployment.html">production page</a> for the implications of this parameter. You can set this
to <tt class="docutils literal"><span class="pre">egg:gunicorn#$(NAME)</span></tt> where <tt class="docutils literal">$(NAME)</tt> is one of <tt class="docutils literal">sync</tt>,
<tt class="docutils literal">eventlet</tt>, <tt class="docutils literal">gevent</tt>, or <tt class="docutils literal">tornado</tt>. <tt class="docutils literal">sync</tt> is the default.</dd>
<dt><tt class="docutils literal"><span class="pre">-n</span> APP_NAME, <span class="pre">--name=APP_NAME</span></tt></dt>
<dd>If <a class="reference external" href="http://pypi.python.org/pypi/setproctitle/">setproctitle</a> is installed you can adjust the name of Gunicorn process as
they appear in the process system table (which affects tools like <tt class="docutils literal">ps</tt> and
<tt class="docutils literal">top</tt>).</dd>
</dl>
</blockquote>
<p>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:</p>
<pre class="literal-block">
$ gunicorn -h
</pre>
</div>
<div class="section" id="gunicorn">
<h2>gunicorn</h2>
<p>The first and most basic script is used to server 'bare' WSGI applications
that don't require a translation layer. Basic usage:</p>
<pre class="literal-block">
$ gunicorn [OPTIONS] APP_MODULE
</pre>
<p>Where <tt class="docutils literal">APP_MODULE</tt> is of the pattern <tt class="docutils literal"><span class="pre">$(MODULE_NAME):$(VARIABLE_NAME)</span></tt>. 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.</p>
<p>Example with test app:</p>
<pre class="literal-block">
$ cd examples
$ gunicorn --workers=2 test:app
</pre>
</div>
<div class="section" id="gunicorn-django">
<h2>gunicorn_django</h2>
<p>You might not have guessed it, but this script is used to server Django
applications. Basic usage:</p>
<pre class="literal-block">
$ gunicorn_django [OPTIONS] [SETTINGS_PATH]
</pre>
<p>By default <tt class="docutils literal">SETTINGS_PATH</tt> will look for <tt class="docutils literal">settings.py</tt> in the current
directory.</p>
<p>Example with your Django project:</p>
<pre class="literal-block">
$ cd path/to/yourdjangoproject
$ gunicorn_django --workers=2
</pre>
<p>Alternatively, you can install some Gunicorn magic directly into your Django
project and use the provided command for running the server.</p>
<p>First you'll need to add <tt class="docutils literal">gunicorn</tt> to your <tt class="docutils literal">INSTALLED_APPS</tt> in the settings
file:</p>
<pre class="literal-block">
INSTALLED_APPS = (
...
&quot;gunicorn&quot;,
)
</pre>
<p>Then you can run:</p>
<pre class="literal-block">
python manage.py run_gunicorn
</pre>
</div>
<div class="section" id="gunicorn-paster">
<h2>gunicorn_paster</h2>
<p>Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We
apologize for the lack of script name creativity. And some usage:</p>
<pre class="literal-block">
$ gunicorn_paster [OPTIONS] paste_config.ini
</pre>
<p>Simple example:</p>
<pre class="literal-block">
$ cd yourpasteproject
$ gunicorn_paste --workers=2 development.ini
</pre>
<p>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:</p>
<pre class="literal-block">
[server:main]
use = egg:gunicorn#main
host = 127.0.0.1
port = 5000
</pre>
<p>And then as per usual:</p>
<pre class="literal-block">
$ cd yourpasteproject
$ paster serve development.ini workers=2
</pre>
</div>
<div class="section" id="full-command-line-usage">
<h2>Full Command Line Usage</h2>
<pre class="literal-block">
$ 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. [-]
--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
</pre>
</div>
<div class="section" id="framework-examples">
<h2>Framework Examples</h2>
<p>This is an incomplete list of examples of using Gunicorn with various
Python web frameworks. If you have an example to add you're very much
invited to submit a ticket to the <a class="reference external" href="http://github.com/benoitc/gunicorn/issues">issue tracker</a> to have it included.</p>
<div class="section" id="itty">
<h3>Itty</h3>
<p>Itty comes with builtin Gunicorn support. The Itty &quot;Hello, world!&quot; looks
like such:</p>
<pre class="literal-block">
from itty import *
&#64;get('/')
def index(request):
return 'Hello World!'
run_itty(server='gunicorn')
</pre>
</div>
<div class="section" id="flask">
<h3>Flask</h3>
<p>Flask applications are WSGI compatible. Given this Flask app in an importable
Python module &quot;helloflask.py&quot;:</p>
<pre class="literal-block">
from flask import Flask
app = Flask(__name__)
&#64;app.route(&quot;/&quot;)
def hello():
return &quot;Hello World!&quot;
</pre>
<p>Gunicorn can then be used to run it as such:</p>
<pre class="literal-block">
$ gunicorn helloflask:app
</pre>
<p>Remember, if you're just trying to get things up and runnign that &quot;importable&quot;
can be as simple as &quot;exists in the current directory&quot;.</p>
</div>
</div>
</div>
<div id="footer">
<p>This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>.</p>
<p>Hosted on <a href="http://github.com/">Github</a></p>
</div>
</div>
<h2>
Redirecting to <a href="http://gunicorn.org/run.html">here</a>
</h2>
</body>
</html>
</html>