diff --git a/README.rst b/README.rst index e40b0e82..778a5d57 100644 --- a/README.rst +++ b/README.rst @@ -1,17 +1,17 @@ About ----- -gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX handle fast clients -**and** sleepy application. +Gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX. It's a pre-fork +worker model ported from Ruby's Unicorn_ project. The Gunicorn server is +broadly compatible with various web frameworks, simply implemented, light +on server resource usage, and fairly speedy. -This is a port of Unicorn (http://unicorn.bogomips.org/) in Python. Meet us -on `#gunicorn irc channel `_ -on `Freenode`_. +Feel free to join us in #gunicorn_ on freenode_. Installation ------------ -Gunicorn requires **Python 2.5 or newer** (Python 3.x will be supported soon). +Gunicorn requires **Python 2.x >= 2.5**. Python 3.x support is planned. Install from sources:: @@ -20,145 +20,129 @@ Install from sources:: Or from Pypi:: $ easy_install -U gunicorn - -If you want to handle `sleepy applications `_ -you will need to install Eventlet_ or Gevent_. + +.. note: + You may also want to install Eventlet_ or Gevent_ if you expect that your + application code may need to pause for extended periods of time during + request processing. Check out the FAQ_ for more information on when you'll + want to consider one of the alternate worker types. To install eventlet:: - $ easy_install -U eventlet + $ easy_install -U eventlet -Replace `eventlet` by **gevent** if you want to use `gevent`. You can now -launch gunicorn with Eventlet or Gevent arbiter, see `Gunicorn usage -`_ for more information. +.. note: + If you encounter errors when compiling the extensions for Eventlet_ or + Gevent_ you most likely need to install a newer version of libev_. -If you encounter errors when compiling the extensions for `gevent` or -`eventlet` you probably need to install a newer version of libev_. +Basic Usage +----------- -.. _libev: http://software.schmorp.de/pkg/libev.html +After installing Gunicorn you will have access to three command line scripts +that can be used for serving the various supported web frameworks: ``gunicorn``, +``gunicorn_django``, and ``gunicorn_paster``. -Usage ------ +Commonly Used Arguments ++++++++++++++++++++++++ -:: + * ``-c CONFIG, --config=CONFIG`` - Specify the path to a `config file`_ + * ``-b BIND, --bind=BIND`` - Specify a server socket to bind. Server sockets + can be any of $(HOST), $(HOST):$(PORT), or unix:$(PATH) where $(HOST) can + also be an IP. + * ``-w WORKERS, --workers=WORKERS`` - The number of worker processes. This + number should generally be between 2-4 workers per core in the server. + Check the FAQ_ for ideas on tuning this parameter. + * ``-k WORKERCLASS, --worker-class=WORKERCLASS`` - The type of worker process + to run. You'll definitely want to read the FAQ_ for the implications of + this parameter. + * ``-n APP_NAME, --name=APP_NAME`` - If setproctitle_ is installed you can + adjust the name of Gunicorn process as they appear in the process system + table (which affects tools like ``ps`` and ``top``). - $ gunicorn --help - Usage: gunicorn [OPTIONS] [APP_MODULE] - - Options: - -c CONFIG, --config=CONFIG - Config file. [none] - -b BIND, --bind=BIND Adress to listen on. Ex. 127.0.0.1:8000 or - unix:/tmp/gunicorn.sock - -k WORKERCLASS, --worker-class=WORKERCLASS - The type of request processing to use - [egg:gunicorn#sync] - -w WORKERS, --workers=WORKERS - Number of workers to spawn. [1] - -p PIDFILE, --pid=PIDFILE - set the background PID FILE - -D, --daemon Run daemonized in the background. - -m UMASK, --umask=UMASK - Define umask of daemon process - -u USER, --user=USER Change worker user - -g GROUP, --group=GROUP - Change worker group - -n APP_NAME, --name=APP_NAME - Application name - --log-level=LOGLEVEL Log level below which to silence messages. [info] - --log-file=LOGFILE Log to a file. - equals stdout. [-] - -d, --debug Debug mode. only 1 worker. - --spew Install a trace hook - --version show program's version number and exit - -h, --help show this help message and exit - +There are various other parameters that affect user privileges, logging, etc. +You can see the complete list with the expected:: + + $ gunicorn -h + +gunicorn +++++++++ + +The first and most basic script is used to server 'bare' WSGI applications +that don't require a translation layer. Basic usage:: + + $ gunicorn [OPTIONS] APP_MODULE + +Where APP_MODULE is of the pattern $(MODULE_NAME):$(VARIABLE_NAME). The module +name can be a full dotted path. The variable name refers to a WSGI callable +that should be found in the specified module. Example with test app:: - $ cd examples - $ gunicorn --workers=2 test:app + $ cd examples + $ gunicorn --workers=2 test:app -Django projects +gunicorn_django +++++++++++++++ -For django projects use the `gunicorn_django` command:: +You might not have guessed it, but this script is used to server Django +applications. Basic usage:: - $ cd yourdjangoproject + $ gunicorn_django [OPTIONS] [SETTINGS_PATH] + +By default SETTINGS_PATH will look for settings.py in the current directory. + +Example with your Django project: + + $ cd path/to/yourdjangoproject $ gunicorn_django --workers=2 -or use `run_gunicorn` command. +Alternatively, you can install some Gunicorn magic directly into your Django +project and use the provided command for running the server. -add `gunicorn` to INSTALLED_APPS in the settings file:: +First you'll need to add ``gunicorn`` to your INSTALLED_APPS in the settings +file:: - INSTALLED_APPS = ( - ... - "gunicorn", - ) + INSTALLED_APPS = ( + ... + "gunicorn", + ) -Then run:: +Then you can run:: python manage.py run_gunicorn -Paste-compatible projects -+++++++++++++++++++++++++ +gunicorn_paster ++++++++++++++++ -For paste-compatible projects (like Pylons, TurboGears 2, ...) use the `gunicorn_paste` command:: +Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We +apologize for the lack of script name creativity. And some usage:: + + $ gunicorn_paster [OPTIONS] paste_config.ini + +Simple example:: $ cd your pasteproject $ gunicorn_paste --workers=2 development.ini -or usual paster command:: +If you're wanting to keep on keeping on with the usual paster serve command, +you can specify the Gunicorn server settings in your configuration file:: - $ cd your pasteproject - $ paster serve development.ini workers=2 - -In last case don't forget to add a server section for gunicorn. Here is an example that use -gunicorn as main server:: + [server:main] + use = egg:gunicorn#main + host = 127.0.0.1 + port = 5000 - [server:main] - use = egg:gunicorn#main - host = 127.0.0.1 - port = 5000 - -Kernel Parameters ------------------ +And then as per usual:: -There are various kernel parameters that you might want to tune in order to deal with a large number of simultaneous connections. Generally these should only affect sites with a large number of concurrent requests and apply to any sort of network server you may be running. They're listed here for ease of reference. + $ cd your pasteproject + $ paster serve development.ini workers=2 -The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use slightly different flags. Always reference the appropriate man pages if uncertain. - -Increasing the File Descriptor Limit -++++++++++++++++++++++++++++++++++++ - -One of the first settings that usually needs to be bumped is the maximum number of open file descriptors for a given process. For the confused out there, remember that Unices treat sockets as files. - -:: - - $ sudo ulimit -n 1024 - -Increasing the Listen Queue Size -++++++++++++++++++++++++++++++++ - -Listening sockets have an associated queue of incoming connections that are waiting to be accepted. If you happen to have a stampede of clients that fill up this queue new connections will eventually start getting dropped. - -:: - - $ sudo sysctl -w kern.ipc.somaxconn="1024" - -Widening the Ephemeral Port Range -+++++++++++++++++++++++++++++++++ - -After a socket is closed it eventually enters the TIME_WAIT state. This can become an issue after a prolonged burst of client activity. Eventually the ephemeral port range is used up which can cause new connections to stall while they wait for a valid port. - -This setting is generally only required on machines that are being used to test a network server. - -:: - - $ sudo sysctl -w net.inet.ip.portrange.first="8048" - -Check `this article`_ for more information on ephemeral ports. - -.. _this article: http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html +.. _Unicorn: http://unicorn.bogomips.org/ +.. _#gunicorn: http://webchat.freenode.net/?channels=gunicorn .. _freenode: http://freenode.net .. _Eventlet: http://eventlet.net .. _Gevent: http://gevent.org +.. _FAQ: http://gunicorn.org/faq.html +.. _libev: http://software.schmorp.de/pkg/libev.html +.. _`config file`: http://gunicorn.org/configuration.html +