From 5127b8bd26a58cb9ac8214a89cee16eb14349e59 Mon Sep 17 00:00:00 2001
From: Merlin <merlin@merlinsbox.net>
Date: Fri, 10 Jun 2011 01:38:26 -0700
Subject: [PATCH] Added initial uwsgi deployment documentation for nginx;
 updated nginx URL in fastcgi deployment docs; added uwsgi to deployment index

---
 docs/deploying/fastcgi.rst |  2 +-
 docs/deploying/index.rst   |  1 +
 docs/deploying/uwsgi.rst   | 63 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 docs/deploying/uwsgi.rst

diff --git a/docs/deploying/fastcgi.rst b/docs/deploying/fastcgi.rst
index eeaee43e..31d93fb9 100644
--- a/docs/deploying/fastcgi.rst
+++ b/docs/deploying/fastcgi.rst
@@ -148,5 +148,5 @@ path.  Common problems are:
 -   different python interpreters being used.
 
 .. _lighttpd: http://www.lighttpd.net/
-.. _nginx: http://nginx.net/
+.. _nginx: http://nginx.org/
 .. _flup: http://trac.saddi.com/flup
diff --git a/docs/deploying/index.rst b/docs/deploying/index.rst
index a59e4e9a..64c1a239 100644
--- a/docs/deploying/index.rst
+++ b/docs/deploying/index.rst
@@ -16,4 +16,5 @@ is the actual WSGI application.
    mod_wsgi
    cgi
    fastcgi
+   uwsgi
    others
diff --git a/docs/deploying/uwsgi.rst b/docs/deploying/uwsgi.rst
new file mode 100644
index 00000000..7ec153fd
--- /dev/null
+++ b/docs/deploying/uwsgi.rst
@@ -0,0 +1,63 @@
+uWSGI
+=====
+
+A newly popular deployment method on servers like `cherokee`_ and `nginx`_
+is uWSGI.  To use your WSGI application with uWSGI protocol you will need
+a uWSGI server first. uWSGI is both a protocol and an application server;
+the application server can serve uWSGI, FastCGI, and HTTP protocols.
+
+The most popular server is `uwsgi`_, which we will use for this guide.
+Make sure to have it installed.
+
+.. admonition:: Watch Out
+
+   Please make sure in advance that your ``app.run()`` call you might
+   have in your application file, is inside an ``if __name__ ==
+   '__main__':`` or moved to a separate file.  Just make sure it's not
+   called because this will always start a local WSGI server which we do
+   not want if we deploy that application to uWSGI.
+
+Starting your app with uwsgi
+----------------------------
+
+`uwsgi` is designed to operate on WSGI callables found in python modules.
+
+Given a flask application in myapp.py, use the following command:
+
+.. sourcecode:: text
+
+    $ uwsgi -s /tmp/uwsgi.sock --module myapp --callable app
+
+Or, if you prefer:
+
+.. sourcecode:: text
+
+    $ uwsgi -s /tmp/uwsgi.sock myapp:app
+
+Configuring nginx
+-----------------
+
+A basic flask uWSGI configuration for nginx looks like this::
+
+    location = /yourapplication { rewrite ^ /yourapplication/; }
+    location /yourapplication { try_files $uri @yourapplication; }
+    location @yourapplication {
+      include uwsgi_params;
+      uwsgi_param SCRIPT_NAME /yourapplication;
+      uwsgi_modifier1 30;
+      uwsgi_pass unix:/tmp/uwsgi.sock;
+    }
+
+This configuration binds the application to `/yourapplication`.  If you want
+to have it in the URL root it's a bit simpler because you don't have to tell
+it the WSGI `SCRIPT_NAME` or set the uwsgi modifer to make use of it::
+
+    location / { try_files $uri @yourapplication; }
+    location @yourapplication {
+        include uwsgi_params;
+        uwsgi_pass unix:/tmp/uwsgi.sock;
+    }
+
+.. _cherokee: http://www.cherokee-project.com/
+.. _nginx: http://nginx.org/
+.. _uwsgi: http://projects.unbit.it/uwsgi/