Fixed #16057 -- Extended deployment documentation with instructions f…

…or uWSGI. Thanks, jpic and aaugustin.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16413 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/howto/deployment/index.txt

@@ -10,16 +10,18 @@ ways to easily deploy Django:
    :maxdepth: 1
 
    modwsgi
+   uwsgi
    fastcgi
    mod_python (deprecated) <modpython>
 
 If you're new to deploying Django and/or Python, we'd recommend you try
-:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be the easiest,
-fastest, and most stable deployment choice.
+:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be
+the easiest, fastest, and most stable deployment choice.
 
 .. seealso::
 
-    * `Chapter 12 of The Django Book`_ discusses deployment and especially
-      scaling in more detail.
+    * `Chapter 12 of the Django Book`_ discusses deployment and especially
+      scaling in more detail. However, it hasn't been updated since mod_python
+      was deprecated.
 
 .. _chapter 12 of the django book: http://djangobook.com/en/2.0/chapter12/

docs/howto/deployment/uwsgi.txt

@@ -0,0 +1,255 @@
+============================
+How to use Django with uWSGI
+============================
+
+.. highlight:: bash
+
+uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application
+container server coded in pure C.
+
+It also provides a fast `caching framework`_ but its documentation is not the
+purpose of this document.
+
+.. _uWSGI: http://projects.unbit.it/uwsgi/
+.. _caching framework: http://projects.unbit.it/uwsgi/wiki/CachingFramework
+
+
+Prerequisite: uWSGI
+===================
+
+The wiki describes several `installation procedures`_. Using pip, the python
+package manager, installing any uWSGI version can be done with one command
+line. For example::
+
+    # install current stable version
+    pip install uwsgi
+
+    # or install LTS (long term support)
+    pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
+
+.. _installation procedures: http://projects0.unbit.it/uwsgi/wiki/Install
+
+Prerequisite: general concept
+=============================
+
+uWSGI model
+-----------
+
+uWSGI operates on a client-server model. Your Web server (ie. nginx, Apache)
+communicates with a django-uwsgi "worker" process to serve dynamic contents.
+The Web server can communicate with the uWSGI process either:
+
+* directly by the uWSGI protocol through a socket created by uWSGI,
+* or by proxying HTTP requests to the minimalist HTTP server built in uWSGI.
+
+In the first case: the Web server can do uWSGI protocol (often with a
+module). It can then use either a Unix domain socket (a "named pipe" on Win32
+systems), or it can use a TCP socket. What you choose is a matterr of
+preference. Usually, a TCP socket is easier because connecting to a port
+doesn't require special permissions.
+
+In the second case, the Web server doesn't need to do uWSGI protocol. It just
+needs to be able to proxy HTTP requests to the HTTP server built-in uWSGI.
+The procedure is the same than proxying any HTTP server. Note that the Web
+server is a "reverse proxy" in this case.
+
+Configuring the uWSGI server
+----------------------------
+
+In any case, when you set up your Web server, you'll just need to point its
+uwsgi or proxy module to the host/port or socket you specified when starting
+the uWSGI server.
+
+.. admonition:: Choosing the socket
+
+    The easiest is to set the socket to a high level (>49152) local port like
+    127.0.0.1:49152. If the socket is a file, the system administrator must
+    ensure that the Web server process has read, write and execute privileges
+    on that file.
+
+uWSGI is highly configurable and thus there are many ways to start the
+process. For example, uwsgi version 0.9.6.8 provides a hundred switches.
+This guide demonstrates the most important of them, but does not intent to
+substitute the official manual and online documentation.
+
+uWSGI supports configuration through:
+
+* environment variables
+* command line switches
+* ldap
+* ini files
+* xml files
+* yaml files
+
+Managing the uWSGI server
+-------------------------
+
+The system administrator controls the worker process pool by sending signals
+to the master process. For example, the unix kill command sends such signals.
+uWSGI can write the master process id to a "pidfile". A "pidfile" is a plain
+text file containing just a process id.
+
+Starting the server
+-------------------
+
+Starting an uWSGI server is the role of the system administrator, like
+starting the Web server. It is *not* the role of the Web server to start the
+uWSGI server. This means:
+
+* the uWSGI server can be restarted or reloaded independently from the Web
+  server,
+* (except with Cheerokee), it is the role of the system administrator to make
+  uWSGI to start on boot or reboot: either through tools like supervisor or
+  daemontools, either directly at init level in a file like /etc/rc.local or
+  /etc/conf.d/local
+
+Managing uWSGI
+==============
+
+Starting the server
+-------------------
+
+Example command line for a Web server that understand the uWSGI protocol::
+
+    uwsgi --chdir=/path/to/your/project
+        --module='django.core.handlers.wsgi:WSGIHandler()' \
+        --env DJANGO_SETTINGS_MODULE=settings \
+        --master --pidfile=/tmp/project-master.pid \
+        --socket=127.0.0.1:49152 \      # can also be a file
+        --processes=5 \                 # number of worker processes
+        --uid=1000 --gid=2000 \         # if root, uwsgi can drop privileges
+        --harakiri=20 \                 # respawn processes taking more than 20 seconds
+        --limit-as=128 \                # limit the project to 128 Megabytes
+        --max-requests=5000 \           # respawn processes after serving 5000 requests
+        --vacuum \                      # clear environment on exit
+        --home=/path/to/virtual/env \   # optionnal path to a virtualenv
+        --daemonize=/var/log/uwsgi/yourproject.log      # background the process
+
+Django specific options are:
+
+* ``chdir``: should be the path to your project
+* ``module``: uwsgi module to use
+* ``pythonpath``: optional path to your project virtualenv
+* ``env``: should contain at least ``DJANGO_SETTINGS_MODULE``
+
+Example ini configuration file::
+
+    [uwsgi]
+    chdir=/path/to/your/project
+    master=True
+    pidfile=/tmp/project-master.pid
+    vacuum=True
+    max-requests=5000
+    deamonize=/var/log/uwsgi/yourproject.log
+
+Example ini configuration file usage::
+
+    uwsgi --ini uwsgi.ini
+
+Read more `uWSGI configuration examples
+<http://projects.unbit.it/uwsgi/wiki/Example>`_.
+
+.. admonition:: Massive application hosting
+
+    `uWSGI emperor <http://projects.unbit.it/uwsgi/wiki/Emperor>`_ is a special
+    uWSGI process that can manage many master processes at once.
+
+Reloading the daemon
+--------------------
+
+As mentioned above, the uWSGI master process is one of the core component of
+the uWSGI stack. The signal to brutally reload all the workers and the master
+process is SIGTERM. Example command to brutally reload the uWSGI processes::
+
+    kill -TERM `cat /tmp/project-master.pid`
+
+Patching the daemon
+-------------------
+
+One of the great advantages of uWSGI is its ability to gradually restart each
+worker without loosing any request.
+
+For example, uWSGI can be signaled that worker should reload the code after
+handling their current request (if any) from bash::
+
+    # using kill to send the signal
+    kill -HUP `cat /tmp/project-master.pid`
+
+    # if uwsgi was started with --touch-reload=/tmp/somefile
+    touch /tmp/somefile
+
+Or from Python::
+
+    uwsgi.reload()
+
+Stopping the daemon
+-------------------
+
+If you have the process running in the foreground, it's easy enough to stop it:
+Simply hitting ``Ctrl-C`` will stop and quit the uWSGI server. However, when
+you're dealing with background processes, you'll need to resort to the Unix
+``kill`` command.
+
+The ``kill`` is used to send a signal to the uWSGI master process. The
+`uWSGI signals are documented online
+<http://projects.unbit.it/uwsgi/wiki/uWSGISignals>`_. Example command to
+completely stop the uWSGI stack::
+
+    kill -INT `cat /tmp/project-master.pid`
+
+HTTP server configuration
+=========================
+
+Nginx setup
+-----------
+
+Nginx provides the `uwsgi module <http://wiki.nginx.org/HttpUwsgiModule>`_ by
+default since nginx 0.8.40. Configuring Nginx to use an uWSGI server is as
+simple as setting it up to proxy requests::
+
+    location / {
+        uwsgi_pass 127.0.0.1:49152;
+        # in case of a socket file:
+        # uwsgi_pass unix:/tmp/yourproject.sock;
+    }
+
+Note that default uwsgi parameters should be included somewhere in your Nginx
+configuration. For example::
+
+    http {
+        include       uwsgi_params;
+        # [...] normal nginx configuration here
+    }
+
+Cherokee setup
+--------------
+
+Cherokee setup is documented in the `official Cherokee uWSGI documentation
+<http://www.cherokee-project.com/doc/cookbook_uwsgi.html>`_.
+
+Lighttpd setup
+--------------
+
+`Lighttpd uwsgi module <http://projects.unbit.it/uwsgi/wiki/RunOnLighttpd>`_ is
+still experimental.
+
+Troubleshooting
+===============
+
+As usual, the first things to do is to check the logs. This implies:
+
+* the web server log, which will indicate if it couldn't connect to the uWSGI
+  process,
+* the uWSGI log, which will indicate if an exception was thrown.
+
+Typical gotchas:
+
+* If the socket is a file, the Web server process should have read, write and
+  execute permissions on the socket file. The ``--chmod-socket`` option can do
+  it.
+* In some cases, for instance if uWSGI was started without ``--vacuum`` or
+  killed with ``SIGKILL``, it won't remove the socket and pidfile when it is
+  interrupted. It is safe to remove them manually and to start uWSGI again in
+  that case.
+* uWSGI can start the process on the foreground, this will make errors easily
+  visible to the system administrator.

docs/index.txt

@@ -155,7 +155,8 @@ The development process
     * **Deployment:**
       :doc:`Overview <howto/deployment/index>` |
       :doc:`Apache/mod_wsgi <howto/deployment/modwsgi>` |
-      :doc:`Apache/mod_python <howto/deployment/modpython>` |
+      :doc:`uWSGI <howto/deployment/uwsgi>` |
+      :doc:`Apache/mod_python (deprecated) <howto/deployment/modpython>` |
       :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
       :doc:`Apache authentication <howto/apache-auth>` |
       :doc:`Handling static files <howto/static-files>` |

docs/topics/install.txt

@@ -28,11 +28,11 @@ Install Apache and mod_wsgi
 =============================
 
 If you just want to experiment with Django, skip ahead to the next
-section; Django includes a lightweight Web server you can use for
+section; Django includes a lightweight web server you can use for
 testing, so you won't need to set up Apache until you're ready to
 deploy Django in production.
 
-If you want to use Django on a production site, use Apache with
+If you want to use Django on a production site, use `Apache`_ with
 `mod_wsgi`_. mod_wsgi can operate in one of two modes: an embedded
 mode and a daemon mode. In embedded mode, mod_wsgi is similar to
 mod_perl -- it embeds Python within Apache and loads Python code into
@@ -53,14 +53,16 @@ for information on how to configure mod_wsgi once you have it
 installed.
 
 If you can't use mod_wsgi for some reason, fear not: Django supports
-many other deployment options. Another option is :doc:`FastCGI
+many other deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`;
+it works very well with `nginx`_. Another is :doc:`FastCGI
 </howto/deployment/fastcgi>`, perfect for using Django with servers
 other than Apache. Additionally, Django follows the WSGI_ spec, which
 allows it to run on a variety of server platforms. See the
 `server-arrangements wiki page`_ for specific installation
 instructions for each platform.
 
 .. _Apache: http://httpd.apache.org/
+.. _nginx: http://nginx.net/
 .. _mod_wsgi: http://code.google.com/p/modwsgi/
 .. _WSGI: http://www.python.org/dev/peps/pep-0333/
 .. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements