From 9eba21fb8eef781933b38c17ad7d6e0be1219b8c Mon Sep 17 00:00:00 2001 From: Prateek Singh Paudel Date: Wed, 3 Oct 2012 16:25:26 +0545 Subject: [PATCH] Consistent formatting and some addditions. Ensures sphinx will generate consistent html headings. Some addition of header text. --- docs/source/community.rst | 12 +++------ docs/source/configure.rst | 28 +++++++------------ docs/source/deploy.rst | 57 ++++++++++++++++++--------------------- docs/source/design.rst | 12 +++------ docs/source/faq.rst | 15 +++-------- docs/source/index.rst | 45 +++++++++++++++++++------------ docs/source/install.rst | 32 ++++++++++------------ docs/source/news.rst | 12 +++------ docs/source/run.rst | 27 +++++++++---------- 9 files changed, 104 insertions(+), 136 deletions(-) diff --git a/docs/source/community.rst b/docs/source/community.rst index 782eb09d..0e4dab5d 100644 --- a/docs/source/community.rst +++ b/docs/source/community.rst @@ -1,12 +1,8 @@ -template: doc.html -title: Community +========= +Community +========= -_TOC_TOP_ - -.. contents:: - :backlinks: top - -_TOC_BOT_ +Use these channels to communicate about the project. Mailing list ============ diff --git a/docs/source/configure.rst b/docs/source/configure.rst index 6de02218..90340b96 100644 --- a/docs/source/configure.rst +++ b/docs/source/configure.rst @@ -1,16 +1,6 @@ -template: doc.html -title: Configure -insert_settings: true - -_TOC_TOP_ - -.. contents:: - :backlinks: top - -_TOC_BOT_ - -Overview --------- +====================== +Configuration Overview +====================== Gunicorn pulls configuration information from three distinct places. @@ -31,7 +21,7 @@ Once again, in order of least to most authoritative: 3. Command Line Framework Settings ------------------- +================== Currently, only Paster applications have access to framework specific settings. If you have ideas for providing settings to WSGI applications or @@ -41,7 +31,7 @@ let us know. .. _issue: http://github.com/benoitc/gunicorn/issues Paster Applications -+++++++++++++++++++ +------------------- In your INI file, you can specify to use Gunicorn as the server like such:: @@ -57,7 +47,7 @@ the base configuration. Remember that these will be overridden by the config file and/or the command line. Configuration File ------------------- +================== The configuration file should be a valid Python source file. It only needs to be readable from the file system. More specifically, it does not need to be @@ -78,14 +68,14 @@ On a side note, Python's older than 2.6 can use sysconf to get the number of processors:: import os - + def numCPUs(): if not hasattr(os, "sysconf"): raise RuntimeError("No sysconf detected.") return os.sysconf("SC_NPROCESSORS_ONLN") Command Line ------------- +============ If an option is specified on the command line, it overrides all other values that may have been specified in the app specific settings, or in the optional @@ -99,7 +89,7 @@ There is also a ``--version`` flag available to the command line scripts that isn't mentioned in the list of settings. Settings --------- +======== This is an exhaustive list of settings for Gunicorn. Some settings are only able to be set from a configuration file. The setting name is what should be diff --git a/docs/source/deploy.rst b/docs/source/deploy.rst index a8e8c43e..72cd9574 100644 --- a/docs/source/deploy.rst +++ b/docs/source/deploy.rst @@ -1,15 +1,11 @@ -template: doc.html -title: Deploy +================== +Deploying Gunicorn +================== -_TOC_TOP_ - -.. contents:: - :backlinks: top - -_TOC_BOT_ +We strongly recommend to use Gunicorn behind a proxy server. 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 @@ -20,16 +16,16 @@ 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; @@ -41,17 +37,17 @@ An `example configuration`_ file for fast clients with Nginx_:: # 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 / { # checks for static file, if not found proxy to app try_files $uri @proxy_to_app; @@ -61,10 +57,10 @@ An `example configuration`_ file for fast clients with Nginx_:: proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Host $http_host; proxy_redirect off; - + proxy_pass http://app_server; } - + error_page 500 502 503 504 /500.html; location = /500.html { root /path/to/app/current/public; @@ -95,7 +91,7 @@ To turn off buffering, you only need to add ``proxy_buffering off;`` to your ... Using 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 @@ -120,7 +116,7 @@ passing ``-I`` or ``--ignore-installed`` option to pip:: $ pip install -I gunicorn Monitoring ----------- +========== .. note:: Make sure that when using either of these service monitors you do not @@ -130,7 +126,7 @@ Monitoring confuses the monitor services. Circus -++++++ +------ `Circus `_ can be used to monitor gunicorn. A simple configuration is:: @@ -143,37 +139,36 @@ used to monitor gunicorn. A simple configuration is:: Then you can easily manage Gunicorn using the `circusctl `_ command. Runit -+++++ +----- A popular method for deploying Gunicorn is to have it monitored by runit_. Here is 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 --pid=$PID $APP Save this as ``/etc/sv/[app_name]/run``, and make it executable (``chmod u+x /etc/sv/[app_name]/run``). Then run ``ln -s /etc/sv/[app_name] /etc/service/[app_name]``. -If runit is installed, gunicorn should start running automatically as soon +If runit is installed, gunicorn should start running automatically as soon as you create the symlink. If it doesn't start automatically, run the script directly to troubleshoot. - Supervisor -++++++++++ +---------- -Another useful tool to monitor and control Gunicorn is Supervisor_. A +Another useful tool to monitor and control Gunicorn is Supervisor_. A `simple configuration`_ is:: [program:gunicorn] @@ -185,7 +180,7 @@ Another useful tool to monitor and control Gunicorn is Supervisor_. A redirect_stderr=True Logging -------- +======= Logging can be configured by using various flags detailed in the `configuration documentation`_ or by creating a `logging configuration file`_. diff --git a/docs/source/design.rst b/docs/source/design.rst index 777c97a2..b5cac093 100644 --- a/docs/source/design.rst +++ b/docs/source/design.rst @@ -1,12 +1,8 @@ -template: doc.html -title: Design +====== +Design +====== -_TOC_TOP_ - -.. contents:: - :backlinks: top - -_TOC_BOT_ +A brief description of an architecture of Gunicorn. Server Model ============ diff --git a/docs/source/faq.rst b/docs/source/faq.rst index eba313e0..66408a85 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -1,13 +1,6 @@ -template: doc.html -title: FAQ - -_TOC_TOP_ - -.. contents:: - :backlinks: top - -_TOC_BOT_ - +=== +FAQ +=== WSGI Bits ========= @@ -118,7 +111,7 @@ of open file descriptors for a given process. For the confused out there, remember that Unices treat sockets as files. :: - + $ sudo ulimit -n 2048 How can I increase the maximum socket backlog? diff --git a/docs/source/index.rst b/docs/source/index.rst index a101f18b..5cc9d80d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,22 +1,33 @@ -.. Gunicorn documentation master file, created by - sphinx-quickstart on Wed Oct 3 04:59:09 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +====================== +Gunicorn - wsgi server +====================== -Welcome to Gunicorn's documentation! -==================================== +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 +resources, and fairly speedy. -Contents: +Features +-------- + +* Natively supports WSGI, Django, and Paster +* Automatic worker process management +* Simple Python configuration +* Multiple worker configurations +* Various server hooks for extensibility +* Compatible with Python 2.x >= 2.5 + +Contents +======== .. toctree:: - :maxdepth: 2 - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + :maxdepth: 2 + install + run + configure + deploy + design + community + faq + news diff --git a/docs/source/install.rst b/docs/source/install.rst index 13a4e900..038b4ee2 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -1,22 +1,18 @@ -template: doc.html -title: Install +============ +Installation +============ -_TOC_TOP_ - -.. contents:: - :backlinks: top - -_TOC_BOT_ +Follow the following steps to install Gunicorn. Requirements ------------- +============ - **Python 2.x >= 2.5** (Python 3.x will be supported soon) - setuptools >= 0.6c6 - nosetests (for the test suite only) With easy_install ------------------ +================= If you don't already have ``easy_install`` available you'll want to download and run the ``ez_setup.py`` script:: @@ -38,7 +34,7 @@ To install or upgrade to the latest released version of Gunicorn:: $ pip install -f http://github.com/tilgovi/gunicorn/tarball/py24 gunicorn 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 @@ -67,7 +63,7 @@ well as make changes to the source:: $ python setup.py develop 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 @@ -92,7 +88,7 @@ want to consider one of the alternate worker types. installed, this is the most likely reason. Debian GNU/Linux ----------------- +================ If you are using Debian GNU/Linux and it is recommended that you use system packages to install Gunicorn except maybe when you want to use @@ -114,7 +110,7 @@ advantages: entirely from the system in seconds. Stable ("squeeze") -++++++++++++++++++ +------------------ The version of Gunicorn in the Debian_ "stable" distribution is 0.10.0 (July 2010). It is not recommended that you use this version. @@ -133,7 +129,7 @@ You can then install the latest version using:: $ sudo apt-get -t squeeze-backports install gunicorn Testing ("wheezy") / Unstable ("sid") -+++++++++++++++++++++++++++++++++++++ +------------------------------------- "wheezy" and "sid" contain the latest released version of Gunicorn. You can install it in the usual way:: @@ -142,7 +138,7 @@ install it in the usual way:: Ubuntu ------- +====== If you use Ubuntu_, you can update your system with packages from our PPA_ by adding ``ppa:gunicorn/ppa`` to your system's Software @@ -160,14 +156,14 @@ and adding them to your system's software sources:: Replace 'lucid' with your Ubuntu distribution series. Signing key -+++++++++++ +----------- :: 1024R/5370FF2A Fingerprint -+++++++++++ +----------- :: diff --git a/docs/source/news.rst b/docs/source/news.rst index 870815ea..922fcc22 100644 --- a/docs/source/news.rst +++ b/docs/source/news.rst @@ -1,12 +1,6 @@ -template: doc.html -title: News - -_TOC_TOP_ - -.. contents:: - :backlinks: top - -_TOC_BOT_ +========= +Changelog +========= 0.14.6 / 2012-07-26 ------------------- diff --git a/docs/source/run.rst b/docs/source/run.rst index 044ae190..98f7a6f3 100644 --- a/docs/source/run.rst +++ b/docs/source/run.rst @@ -1,15 +1,12 @@ -template: doc.html -title: Run +================ +Running Gunicorn +================ -_TOC_TOP_ - -.. contents:: - :backlinks: top - -_TOC_BOT_ +You can run Gunicorn by using commands or integrate with Django or Paster. For +deploying Gunicorn in production see :doc:`deploy`. Commands --------- +======== After installing Gunicorn you will have access to three command line scripts that can be used for serving the various supported web frameworks: @@ -19,7 +16,7 @@ that can be used for serving the various supported web frameworks: * ``gunicorn_paster`` gunicorn -++++++++ +-------- The first and most basic script is used to serve 'bare' WSGI applications that don't require a translation layer. Basic usage:: @@ -53,7 +50,7 @@ Example with test app:: $ gunicorn --workers=2 test:app gunicorn_django -+++++++++++++++ +--------------- You might not have guessed it, but this script is used to serve Django applications. Basic usage:: @@ -74,7 +71,7 @@ Example with your Django project:: the `gunicorn`_ command. gunicorn_paster -+++++++++++++++ +--------------- Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We apologize for the lack of script name creativity. And some usage:: @@ -87,14 +84,14 @@ Simple example:: $ gunicorn_paste --workers=2 development.ini Integration ------------ +=========== Alternatively, we also provide integration for both Django and Paster applications in case your deployment strategy would be better served by such invocation styles. Django ./manage.py -++++++++++++++++++ +------------------ You can add a ``run_gunicorn`` command to your ``./manage.py`` simply by adding gunicorn to your ``INSTALLED_APPS``:: @@ -109,7 +106,7 @@ Then you can run:: python manage.py run_gunicorn paster serve -++++++++++++ +------------ 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::