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

Final edits to docs.

Browse Source
This commit is contained in:
Paul J. Davis 2010-02-20 14:47:25 -05:00
parent b202c879bd
commit 2f2bbd20b1
18 changed files with 309 additions and 260 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/buildweb.py
View File

@ -108,7 +108,7 @@ class Page(object):
if not tmpl_name:
return self.body
kwargs = {"conf": conf, "stuff": self.body, "url": self.url()}
kwargs = {"conf": conf, "body": self.body, "url": self.url()}
kwargs.update(self.headers)
return self.site.get_template(tmpl_name).render(kwargs)

20
doc/htdocs/configuration.html
View File

@ -2,7 +2,7 @@
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - Configuration</title>
<title>Green Unicorn - The Configuration File</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<!--[if IE]>
@ -38,6 +38,7 @@
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</a></li>
<li><a href="faq.html">FAQ</a></li>
@ -45,11 +46,11 @@
</ul>
</div>
<div class="document">
<div class="section" id="the-configuration-file">
<h1>The Configuration File</h1>
<div class="document" id="the-configuration-file">
<h1 class="title">The Configuration File</h1>
<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>A configuration file with default settings would look like this:</p>
<div class="section" id="example-gunicorn-conf-py">
<h1>Example gunicorn.conf.py</h1>
<pre class="literal-block">
bind = &quot;127.0.0.1:8000&quot; # Or &quot;unix:/tmp/gunicorn.sock&quot;
daemon = False # Whether work in the background
@ -73,6 +74,9 @@ def before_fork(server, worker):
def before_exec(server):
serer.log.info(&quot;Forked child, reexecuting.&quot;)
</pre>
</div>
<div class="section" id="parameter-descriptions">
<h1>Parameter Descriptions</h1>
<dl class="docutils">
<dt>after_fork(server, worker):</dt>
<dd>This is called by the worker after initialization.</dd>
@ -100,12 +104,6 @@ def before_exec(server):
<dd>The user as which worker processes will by launched.</dd>
</dl>
</div>
<div class="section" id="production-setup">
<h1>Production setup</h1>
<p>While some others HTTP proxies can be used we strongly advice you to use <a class="reference external" href="http://www/nginx.org">NGINX</a>. If you choose another proxy server, make sure it can do buffering to handle slow clients.</p>
<p>An example config file for use with nginx is available at <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf">github.com/benoitc/gunicorn/blob/master/examples/nginx.conf</a>.</p>
<p>You may want to monitor <a class="reference external" href="http://gunicorn.org">Gunicorn</a> service instead of launching it as daemon. You could for example use <a class="reference external" href="http://smarden.org/runit/">runit</a> for that purpose. An example config file for use with runit is available at <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc">github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc</a>.</p>
</div>
</div>

138
doc/htdocs/deployment.html Normal file
View File

@ -0,0 +1,138 @@
<!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" />
<!--[if IE]>
<script>
document.createElement('section');
document.createElement('article');
document.createElement('aside');
document.createElement('footer');
document.createElement('header');
document.createElement('nav');
document.createElement('time');
</script>
<![endif]-->
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen">
</head>
<body>
<div class="container">
<div id="header">
<h1 class="logo"><a href="http://gunicorn.org">gunicorn</a></h1>
<div id="links">
get the source in
<a href="http://github.com/benoitc/gunicorn">git</a> then
<a href="http://github.com/benoitc/gunicorn/issues">send feedback</a>
</div>
</div>
<div id="menu">
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</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>
<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. Without this buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.</p>
<div class="section" id="nginx-config">
<h1>Nginx Config</h1>
<p>An <a class="reference external" href="http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf">example configuration</a> file for use 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>
</div>
<div class="section" id="daemon-monitoring">
<h1>Daemon Monitoring</h1>
<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>
</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>
</body>
</html>

20
doc/htdocs/faq.html
View File

@ -38,6 +38,7 @@
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</a></li>
<li><a href="faq.html">FAQ</a></li>
@ -48,22 +49,25 @@
<div class="document" id="faq">
<h1 class="title">FAQ</h1>
<dl class="docutils">
<dt>How to reload my application in Gunicorn ?</dt>
<dt>How do I reload my application in Gunicorn?</dt>
<dd><p class="first">You can gracefully reload by sending HUP signal to gunicorn:</p>
<pre class="last literal-block">
$ kill -HUP masterpid
</pre>
</dd>
<dt>How to increase/decrease number of running workers ?</dt>
<dd><p class="first">send TTIN/TTOUT signals to do it:</p>
<dt>How do I increase or decrease the number of running workers dynamically?</dt>
<dd><p class="first">To increase the worker count by one:</p>
<pre class="literal-block">
$ kill -TTIN masterpid
$ kill -TTIN $masterpid
</pre>
<p>To decrease the worker count by one:</p>
<pre class="last literal-block">
$ kill -TTOUT $masterpid
</pre>
<p class="last">will increase the number from one worker</p>
</dd>
<dt>How to set SCRIPT_NAME ?</dt>
<dd>By default SCRIPT_name is an empy string. Value could be changed by passing
<cite>SCRIPT_NAME</cite> in environment (apache way) or as an HTTP header (nginx way).</dd>
<dt>How do I set SCRIPT_NAME?</dt>
<dd>By default <tt class="docutils literal">SCRIPT_NAME</tt> is an empy string. The value could be set by
setting <tt class="docutils literal">SCRIPT_NAME</tt> in the environment or as an HTTP header.</dd>
</dl>
</div>

1
doc/htdocs/index.html
View File

@ -59,6 +59,7 @@ stream-based protocols over HTTP</li>
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</a></li>
<li><a href="faq.html">FAQ</a></li>

1
doc/htdocs/installation.html
View File

@ -38,6 +38,7 @@
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</a></li>
<li><a href="faq.html">FAQ</a></li>

1
doc/htdocs/news.html
View File

@ -38,6 +38,7 @@
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</a></li>
<li><a href="faq.html">FAQ</a></li>

84
doc/htdocs/tune.html
View File

@ -1,84 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - </title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<!--[if IE]>
<script>
document.createElement('section');
document.createElement('article');
document.createElement('aside');
document.createElement('footer');
document.createElement('header');
document.createElement('nav');
document.createElement('time');
</script>
<![endif]-->
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen">
</head>
<body>
<div class="container">
<div id="header">
<h1 class="logo"><a href="http://gunicorn.org">gunicorn</a></h1>
<div id="links">
get the source in
<a href="http://github.com/benoitc/gunicorn">git</a> then
<a href="http://github.com/benoitc/gunicorn/issues">send feedback</a>
</div>
</div>
<div id="menu">
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tune.html">Tune</a></li>
<li><a href="faq.html">FAQ</a></li>
</ul>
</div>
<div class="document" id="kernel-parameters">
<h1 class="title">Kernel Parameters</h1>
<p>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.</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="increasing-the-file-descriptor-limit">
<h1>Increasing the File Descriptor Limit</h1>
<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 1024
</pre>
</div>
<div class="section" id="increasing-the-listen-queue-size">
<h1>Increasing the Listen Queue Size</h1>
<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;1024&quot;
</pre>
</div>
<div class="section" id="widening-the-ephemeral-port-range">
<h1>Widening the Ephemeral Port Range</h1>
<p>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.</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 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>
</div>
</div>
</body>
</html>

33
doc/htdocs/tuning.html
View File

@ -38,6 +38,7 @@
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</a></li>
<li><a href="faq.html">FAQ</a></li>
@ -45,36 +46,34 @@
</ul>
</div>
<div class="document">
<p>Gunicorn performances are good enough for most cases. Most often performances can be improved in your application.</p>
<div class="document" id="tuning">
<h1 class="title">Tuning</h1>
<div class="section" id="unicorn-configuration">
<h1>Unicorn configuration</h1>
<p>See <a class="reference external" href="configuration.html">Configuration</a> for more informations.</p>
<ul class="simple">
<li>worker_processes should be scaled to the number of processes your backend system(s) can support. DO NOT scale it to the number of external network clients your application expects to be serving. Gunicorn is <strong>NOT</strong> for serving slow clients, that is the job of <a class="reference external" href="http://nginx.org/">nginx</a>.</li>
</ul>
<h1>Unicorn Configuration</h1>
<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">
<h1>Kernel Parameters</h1>
<p>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.</p>
<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="increasing-the-file-descriptor-limit">
<h2>Increasing the File Descriptor Limit</h2>
<div class="section" id="file-descriptor-limits">
<h2>File Descriptor Limits</h2>
<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 1024
$ sudo ulimit -n 2048
</pre>
</div>
<div class="section" id="increasing-the-listen-queue-size">
<h2>Increasing the Listen Queue Size</h2>
<div class="section" id="listen-queue-size">
<h2>Listen Queue Size</h2>
<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;1024&quot;
$ sudo sysctl -w kern.ipc.somaxconn=&quot;2048&quot;
</pre>
</div>
<div class="section" id="widening-the-ephemeral-port-range">
<h2>Widening the Ephemeral Port Range</h2>
<p>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.</p>
<div class="section" id="ephemeral-port-range">
<h2>Ephemeral Port Range</h2>
<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;

96
doc/htdocs/tunning.html
View File

@ -1,96 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - Tunning</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<!--[if IE]>
<script>
document.createElement('section');
document.createElement('article');
document.createElement('aside');
document.createElement('footer');
document.createElement('header');
document.createElement('nav');
document.createElement('time');
</script>
<![endif]-->
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen">
</head>
<body>
<div class="container">
<div id="header">
<h1 class="logo"><a href="http://gunicorn.org">gunicorn</a></h1>
<div id="links">
get the source in
<a href="http://github.com/benoitc/gunicorn">git</a> then
<a href="http://github.com/benoitc/gunicorn/issues">send feedback</a>
</div>
</div>
<div id="menu">
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tunning.html">Tunning</a></li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="news.html">NEWS</a></li>
</ul>
</div>
<div class="document">
<p>Gunicorn performances are good enough for most cases. Most often performances can be improved in your application.</p>
<div class="section" id="unicorn-configuration">
<h1>Unicorn configuration</h1>
<p>See <a class="reference external" href="configuration.html">Configuration</a> for more informations.</p>
<ul class="simple">
<li>worker_processes should be scaled to the number of processes your backend system(s) can support. DO NOT scale it to the number of external network clients your application expects to be serving. Gunicorn is <strong>NOT</strong> for serving slow clients, that is the job of <a class="reference external" href="http://nginx.org/">nginx</a>.</li>
</ul>
</div>
<div class="section" id="kernel-parameters">
<h1>Kernel Parameters</h1>
<p>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.</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="increasing-the-file-descriptor-limit">
<h2>Increasing the File Descriptor Limit</h2>
<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 1024
</pre>
</div>
<div class="section" id="increasing-the-listen-queue-size">
<h2>Increasing the Listen Queue Size</h2>
<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;1024&quot;
</pre>
</div>
<div class="section" id="widening-the-ephemeral-port-range">
<h2>Widening the Ephemeral Port Range</h2>
<p>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.</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 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>
</body>
</html>

1
doc/htdocs/usage.html
View File

@ -38,6 +38,7 @@
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</a></li>
<li><a href="faq.html">FAQ</a></li>

23
doc/site/configuration.rst
View File

@ -1,12 +1,14 @@
template: doc.html
title: Configuration
title: The Configuration File
The Configuration File
----------------------
======================
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.
A configuration file with default settings would look like this::
Example gunicorn.conf.py
------------------------
::
bind = "127.0.0.1:8000" # Or "unix:/tmp/gunicorn.sock"
daemon = False # Whether work in the background
@ -30,6 +32,9 @@ A configuration file with default settings would look like this::
def before_exec(server):
serer.log.info("Forked child, reexecuting.")
Parameter Descriptions
----------------------
after_fork(server, worker):
This is called by the worker after initialization.
@ -65,15 +70,3 @@ umask:
user:
The user as which worker processes will by launched.
Production setup
----------------
While some others HTTP proxies can be used we strongly advice you to use `NGINX <http://www/nginx.org>`_. If you choose another proxy server, make sure it can do buffering to handle slow clients.
An example config file for use with nginx is available at `github.com/benoitc/gunicorn/blob/master/examples/nginx.conf <http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf>`_.
You may want to monitor `Gunicorn`_ service instead of launching it as daemon. You could for example use `runit <http://smarden.org/runit/>`_ for that purpose. An example config file for use with runit is available at `github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc <http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc>`_.
.. _Gunicorn: http://gunicorn.org

86
doc/site/deployment.rst Normal file
View File

@ -0,0 +1,86 @@
template: doc.html
title: Deployment
Production Setup
================
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. Without this buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
Nginx Config
------------
An `example configuration`_ file for use with Nginx_::
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;
}
}
}
Daemon Monitoring
-----------------
A popular method for deploying Gunicorn is to have it monitored by runit_. An `example service`_ definition::
#!/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
.. _Nginx: http://www.nginx.org
.. _`example configuration`: http://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf
.. _runit: http://smarden.org/runit/
.. _`example service`: http://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc

23
doc/site/faq.rst
View File

@ -4,19 +4,22 @@ title: FAQ
FAQ
===
How to reload my application in Gunicorn ?
How do I reload my application in Gunicorn?
You can gracefully reload by sending HUP signal to gunicorn::
$ kill -HUP masterpid
How to increase/decrease number of running workers ?
send TTIN/TTOUT signals to do it::
$ kill -TTIN masterpid
will increase the number from one worker
How to set SCRIPT_NAME ?
By default SCRIPT_name is an empy string. Value could be changed by passing
`SCRIPT_NAME` in environment (apache way) or as an HTTP header (nginx way).
How do I increase or decrease the number of running workers dynamically?
To increase the worker count by one::
$ kill -TTIN $masterpid
To decrease the worker count by one::
$ kill -TTOUT $masterpid
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.

35
doc/site/tuning.rst
View File

@ -1,48 +1,51 @@
template: doc.html
title: Tuning
Tuning
======
Gunicorn performances are good enough for most cases. Most often performances can be improved in your application.
Unicorn Configuration
---------------------
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_.
See `Configuration <configuration.html>`_ for more informations.
See Configuration_ for a more thorough description of the available parameters.
- worker_processes should be scaled to the number of processes your backend system(s) can support. DO NOT scale it to the number of external network clients your application expects to be serving. Gunicorn is **NOT** for serving slow clients, that is the job of `nginx <http://nginx.org/>`_.
.. _Nginx: http://www.nginx.org
.. _Configuration: configuration.html
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.
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.
Increasing the File Descriptor Limit
++++++++++++++++++++++++++++++++++++
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.
::
$ sudo ulimit -n 1024
$ sudo ulimit -n 2048
Increasing the Listen Queue Size
++++++++++++++++++++++++++++++++
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"
$ sudo sysctl -w kern.ipc.somaxconn="2048"
Widening the Ephemeral Port Range
+++++++++++++++++++++++++++++++++
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.
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"
$ sudo sysctl -w net.inet.ip.portrange.first="8048"

2
doc/templates/doc.html vendored
View File

@ -8,6 +8,6 @@
{% include "menu.html" %}
</div>
{{ stuff }}
{{ body }}
{% endblock %}

2
doc/templates/index.html vendored
View File

@ -1,6 +1,6 @@
{% extends "base.html" %}
{% block body %}{{ stuff }}{% endblock %}
{% block body %}{{ body }}{% endblock %}
{% block extra %}
{% include "menu.html" %}

1
doc/templates/menu.html vendored
View File

@ -1,6 +1,7 @@
<ul id="actions">
<li><a href="installation.html">Installation</a></li>
<li><a href="usage.html">Usage</a></li>
<li><a href="deployment.html">Deployment</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="tuning.html">Tuning</a></li>
<li><a href="faq.html">FAQ</a></li>