gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX, fast clients and sleepy applications.
Fetching latest commit…
Cannot retrieve the latest commit at this time
About ----- Gunicorn 'Green Unicorn' is a Python 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. Feel free to join us in `#gunicorn`_ on freenode_. Installation ------------ Gunicorn requires **Python 2.x >= 2.5**. Python 3.x support is planned. Install from sources:: $ python setup.py install Or from Pypi:: $ easy_install -U gunicorn 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 If you encounter errors when compiling the extensions for Eventlet_ or Gevent_ you most likely need to install a newer version of libev_ or libevent_. Basic 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``). sync=gunicorn.workers.sync:SyncWorker eventlet=gunicorn.workers.geventlet:EventletWorker gevent=gunicorn.workers.ggevent:GeventWorker tornado 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 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 LICENSE ------- Gunicorn is released under the MIT License. See the LICENSE_ file for more details. .. _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 .. _libevent: http://monkey.org/~provos/libevent .. _`production page`: http://gunicorn.org/deployment.html .. _`config file`: http://gunicorn.org/configuration.html .. _setproctitle: http://pypi.python.org/pypi/setproctitle/ .. _LICENSE: http://github.com/benoitc/gunicorn/blob/master/LICENSE