diff --git a/doc/htdocs/configuration.html b/doc/htdocs/configuration.html index bf36c537..63577a82 100644 --- a/doc/htdocs/configuration.html +++ b/doc/htdocs/configuration.html @@ -2,133 +2,12 @@ - Green Unicorn - The Configuration File - - + + Green Unicorn - Configuration -
- - -
-

The Configuration File

-

Gunicorn 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.

-
-

Example gunicorn.conf.py

-
-backlog = 2048              # The listen queue size for the server socket
-bind = "127.0.0.1:8000"     # Or "unix:/tmp/gunicorn.sock"
-daemon = False              # Whether work in the background
-debug = False               # Some extra logging
-keepalive = 2               # Time we wait for next connection (in seconds)
-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
-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 = "egg:gunicorn#sync"    # The type of request processing to use
-worker_connections=1000     # Maximum number of simultaneous connections
-
-after_fork=lambda server, worker: server.log.info(
-        "Worker spawned (pid: %s)" % worker.pid)
-
-before_fork=lambda server, worker: True
-
-before_exec=lambda server: server.log.info("Forked child, reexecuting")
-
-    when_ready=lambda server: server.log.info("Gunicorn started.")
-
-
-
-

Parameter Descriptions

-
-
after_fork(server, worker):
-
This is called by the worker after initialization.
-
worker_class:
-

Define the type of worker to use. A worker process all the requests send by -the arbiter.By default the worker_class is egg:gunicorn#sync. This worker -only supports fast request handling requiring a buffering HTTP proxy.

-

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 Tornado, Eventlet or Gevent. You can also use the Evenlet -worker with the Twisted helper.

-
-
backlog:
-
The backlog parameter defines the maximum length for the queue of pending -connections. The default is 2048. See listen(2) for more information
-
before_fork(server, worker):
-
This is called by the worker just before forking.
-
before_exec(server):
-
This function is called before relaunching the master. This happens when -the master receives a HUP or USR2 signal.
-
bind:
-
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:
-
Whether or not to detach the server from the controlling terminal.
-
debug:
-
If True, only one worker will be launch and the variable -wsgi.multiprocess will be set to False.
-
group:
-
The group in which worker processes will be launched.
-
keepalive:
-
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.
-
logfile:
-
The path to the log file - (stdout) by default.
-
loglevel:
-
The level at which to log. info, debug, or error for instance. -Only log messages of equal or greater severity are logged.
-
pidfile:
-
A file to store the master's PID.
-
proc_name:
-
A name for the master process. Only takes effect if setproctitle is -installed. This alters the process names listed by commands like ps.
-
umask:
-
Used to set the umask when daemonizing.
-
user:
-
The user as which worker processes will by launched.
-
when_ready(server):
-
This is called by the arbiter just after Gunicorn started.
-
worker_connections:
-
Number of simultaneous connections a worker can handle when used with -Eventlet or Gevent arbiter. The default is 1000.
-
timeout:
-
Set worker timeout.
-
tmp_upload_dir:
-
Set the path used to store temporarily the body of the request.
-
-
-
- - -
+

+ Redirecting to here +

- \ No newline at end of file + diff --git a/doc/htdocs/deployment.html b/doc/htdocs/deployment.html index 08a96df2..65b90c65 100644 --- a/doc/htdocs/deployment.html +++ b/doc/htdocs/deployment.html @@ -1,194 +1,12 @@ - - Green Unicorn - Deployment - - + + Green Unicorn - Deploy -
- - -
-

Production Setup

-
-

Synchronous vs Asynchronous workers

-

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.

-

This CPU bound assumption is why the default configuration needs to use a -buffering HTTP proxy like Nginx 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).

-

Example use-cases for asynchronous workers:

-
-
    -
  • Applications making long blocking calls (Ie, to external web services)
    • -
  • Serving requests directly to the internet
    • -
  • Streaming requests and responses
    • -
  • Long polling
    • -
  • Web sockets
    • -
  • Comet
    • -
-
-
-
-

Basic Nginx Configuration

-

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 when you use default Gunicorn workers. Without this -buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks. -You can use slowloris to check if your proxy is behaving properly.

-

An example configuration file for fast clients 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;
-        }
-    }
-}
-
-

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. When you do this you must run with one of the async worker -classes.

-

To turn off buffering, you only need to add proxy_buffering off; to your -location 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;
-    }
-}
-...
-
-
-
-

Working with Virtualenv

-

To serve an app from a Virtualenv 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.

-

If you have Virtualenv installed, you should be able to do something like -this:

-
-$ mkdir ~/venvs/
-$ virtualenv ~/venvs/webapp
-$ source ~/venvs/webapp/bin/activate
-$ ~/venvs/webapp/bin/easy_install -U gunicorn
-$ deactivate
-
-

Then you just need to use one of the three Gunicorn scripts that was installed -into ~/venvs/webapp/bin.

-
-
-

Daemon Monitoring

-
-

Note

-

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.

-
-

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
-
-

Another useful tool to monitor and control Gunicorn is Supervisor. A -simple configuration is:

-
-[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
-
-
-
- - -
+

+ Redirecting to here +

- \ No newline at end of file + diff --git a/doc/htdocs/installation.html b/doc/htdocs/installation.html index 2d7d4ac6..ca935a15 100644 --- a/doc/htdocs/installation.html +++ b/doc/htdocs/installation.html @@ -1,127 +1,12 @@ - - Green Unicorn - Installing Gunicorn - - + + Green Unicorn - Install -
- - -
-

Installation

-
-

Requirements

-
    -
  • Python 2.x >= 2.5 (Python 3.x will be supported soon)
    • -
  • setuptools >= 0.6c6
    • -
  • nosetests (for the test suite only)
    • -
-
-
-

Installing with easy_install

-

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
-$ sudo python ez_setup.py -U setuptools
-
-

To install or upgrade to the latest released version of Gunicorn:

-
-$ sudo easy_install -U gunicorn
-
-
-
-

Installing from source

-

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).

-
-

Get a Copy

-

You can download a tarball of the latest sources from GitHub Downloads or -fetch them with git:

-
-$ git clone git://github.com/benoitc/gunicorn.git
-
-
-
-

Installation

-
-$ python setup.py install
-
-

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
-
-
-
-
-

Enabling async workers

-

You may also want to install Eventlet or Gevent if you expect that your -application code may need to pause for extended periods of time during -request processing. Check out the FAQ for more information on when you'll -want to consider one of the alternate worker types.

-

To install eventlet:

-
-$ easy_install -U greenlet  # Required for both
-$ easy_install -U eventlet  # For eventlet workers
-$ easy_install -U gevent    # For gevent workers
-
-
-

Note

-

If installing greenlet fails you probably need to install -the Python headers. These headers are available in most package -managers. On Ubuntu the package name for apt-get is -python-dev.

-

Gevent also requires that libevent 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 Gevent fails to build even with libevent -installed, this is the most likely reason.

-
-
-
-

Installing on Ubuntu/Debian systems

-

If you use Ubuntu karmic, you can update your system with packages from -our PPA by adding ppa:bchesneau/gunicorn to your system's Software -Sources.

-

Or this PPA can be added to your system manually by copying the lines below -and adding them to your system's software sources:

-
-deb http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
-deb-src http://ppa.launchpad.net/bchesneau/gunicorn/ubuntu karmic main
-
-

Signing key:

-
-1024R/15E5EB06
-
-

Fingerprint:

-
-49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06
-
-
-
- - -
+

+ Redirecting to here +

diff --git a/doc/htdocs/tuning.html b/doc/htdocs/tuning.html index a783eae0..8173fb3e 100644 --- a/doc/htdocs/tuning.html +++ b/doc/htdocs/tuning.html @@ -2,88 +2,12 @@ - Green Unicorn - Tuning - - + + Green Unicorn - FAQ -
- - -
-
-

Tuning

-
-

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 for a more thorough description of the available parameters.

-
-
-

Kernel Parameters

-

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.

-
-

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 2048
-
-
-
-

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="2048"
-
-
-
-

Ephemeral Port Range

-

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"
-
-
-
-
- -
- -
+

+ Redirecting to here +

- \ No newline at end of file + diff --git a/doc/htdocs/usage.html b/doc/htdocs/usage.html index 56e2f546..e72ca3ed 100644 --- a/doc/htdocs/usage.html +++ b/doc/htdocs/usage.html @@ -2,211 +2,12 @@ - Green Unicorn - Command Line Usage - - + + Green Unicorn - Run -
- - -
-

Usage

-

After installing Gunicorn you will have access to three command line scripts -that can be used for serving the various supported web frameworks: gunicorn, -gunicorn_django, and gunicorn_paster.

-
-

Commonly Used Arguments

-
-
-
-c CONFIG, --config=CONFIG
-
Specify the path to a config file
-
-b BIND, --bind=BIND
-
Specify a server socket to bind. Server sockets can be any of $(HOST), -$(HOST):$(PORT), or unix:$(PATH). An IP is a valid $(HOST).
-
-w WORKERS, --workers=WORKERS
-
The number of worker processes. This number should generally be between 2-4 -workers per core in the server. Check the FAQ for ideas on tuning this -parameter.
-
-k WORKERCLASS, --worker-class=WORKERCLASS
-
The type of worker process to run. You'll definitely want to read the -production page for the implications of this parameter. You can set this -to egg:gunicorn#$(NAME) where $(NAME) is one of sync, -eventlet, gevent, or tornado. sync is the default.
-
-n APP_NAME, --name=APP_NAME
-
If setproctitle is installed you can adjust the name of Gunicorn process as -they appear in the process system table (which affects tools like ps and -top).
-
-
-

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:

-
-$ gunicorn -h
-
-
-
-

gunicorn

-

The first and most basic script is used to server 'bare' WSGI applications -that don't require a translation layer. Basic usage:

-
-$ gunicorn [OPTIONS] APP_MODULE
-
-

Where APP_MODULE is of the pattern $(MODULE_NAME):$(VARIABLE_NAME). The -module name can be a full dotted path. The variable name refers to a WSGI -callable that should be found in the specified module.

-

Example with test app:

-
-$ cd examples
-$ gunicorn --workers=2 test:app
-
-
-
-

gunicorn_django

-

You might not have guessed it, but this script is used to server Django -applications. Basic usage:

-
-$ gunicorn_django [OPTIONS] [SETTINGS_PATH]
-
-

By default SETTINGS_PATH will look for settings.py in the current -directory.

-

Example with your Django project:

-
-$ cd path/to/yourdjangoproject
-$ gunicorn_django --workers=2
-
-

Alternatively, you can install some Gunicorn magic directly into your Django -project and use the provided command for running the server.

-

First you'll need to add gunicorn to your INSTALLED_APPS in the settings -file:

-
-INSTALLED_APPS = (
-    ...
-    "gunicorn",
-)
-
-

Then you can run:

-
-python manage.py run_gunicorn
-
-
-
-

gunicorn_paster

-

Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We -apologize for the lack of script name creativity. And some usage:

-
-$ gunicorn_paster [OPTIONS] paste_config.ini
-
-

Simple example:

-
-$ cd yourpasteproject
-$ gunicorn_paste --workers=2 development.ini
-
-

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:

-
-[server:main]
-use = egg:gunicorn#main
-host = 127.0.0.1
-port = 5000
-
-

And then as per usual:

-
-$ cd yourpasteproject
-$ paster serve development.ini workers=2
-
-
-
-

Full Command Line Usage

-
-$ 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
-
-
-
-

Framework Examples

-

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 issue tracker to have it included.

-
-

Itty

-

Itty comes with builtin Gunicorn support. The Itty "Hello, world!" looks -like such:

-
-from itty import *
-
-@get('/')
-def index(request):
-    return 'Hello World!'
-
-run_itty(server='gunicorn')
-
-
-
-

Flask

-

Flask applications are WSGI compatible. Given this Flask app in an importable -Python module "helloflask.py":

-
-from flask import Flask
-app = Flask(__name__)
-
-@app.route("/")
-def hello():
-    return "Hello World!"
-
-

Gunicorn can then be used to run it as such:

-
-$ gunicorn helloflask:app
-
-

Remember, if you're just trying to get things up and runnign that "importable" -can be as simple as "exists in the current directory".

-
-
-
- - -
+

+ Redirecting to here +

- \ No newline at end of file +