Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #17073 - focused uwsgi docs to Django integration; thanks Prest…

…on Holmes.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17586 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 5a013cebd92e5d935088043398e6c04ff6107879 1 parent ce4cd78
Tim Graham authored February 24, 2012

Showing 1 changed file with 13 additions and 182 deletions. Show diff stats Hide diff stats

  1. 195  docs/howto/deployment/wsgi/uwsgi.txt
195  docs/howto/deployment/wsgi/uwsgi.txt
@@ -7,12 +7,7 @@ How to use Django with uWSGI
7 7
 uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application
8 8
 container server coded in pure C.
9 9
 
10  
-It also provides a fast `caching framework`_ but its documentation is not the
11  
-purpose of this document.
12  
-
13 10
 .. _uWSGI: http://projects.unbit.it/uwsgi/
14  
-.. _caching framework: http://projects.unbit.it/uwsgi/wiki/CachingFramework
15  
-
16 11
 
17 12
 Prerequisite: uWSGI
18 13
 ===================
@@ -27,89 +22,27 @@ line. For example::
27 22
     # or install LTS (long term support)
28 23
     pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
29 24
 
30  
-.. _installation procedures: http://projects0.unbit.it/uwsgi/wiki/Install
31  
-
32  
-Prerequisite: general concept
33  
-=============================
  25
+.. _installation procedures: http://projects.unbit.it/uwsgi/wiki/Install
34 26
 
35 27
 uWSGI model
36 28
 -----------
37 29
 
38 30
 uWSGI operates on a client-server model. Your Web server (ie. nginx, Apache)
39 31
 communicates with a django-uwsgi "worker" process to serve dynamic content.
40  
-The Web server can communicate with the uWSGI process either:
41  
-
42  
-* directly by the uWSGI protocol through a socket created by uWSGI,
43  
-* or by proxying HTTP requests to the minimalist HTTP server built in uWSGI.
44  
-
45  
-In the first case: the Web server can do uWSGI protocol (often with a
46  
-module). It can then use either a Unix domain socket (a "named pipe" on Win32
47  
-systems), or it can use a TCP socket. What you choose is a matterr of
48  
-preference. Usually, a TCP socket is easier because connecting to a port
49  
-doesn't require special permissions.
50  
-
51  
-In the second case, the Web server doesn't need to speak the uWSGI protocol. It
52  
-just needs to be able to proxy HTTP requests to the HTTP server built-in uWSGI.
53  
-The procedure is the same as proxying to any HTTP server. Note that the Web
54  
-server is a "reverse proxy" in this case.
55  
-
56  
-Configuring the uWSGI server
57  
-----------------------------
58  
-
59  
-In any case, when you set up your Web server, you'll just need to point its
60  
-uwsgi or proxy module to the host/port or socket you specified when starting
61  
-the uWSGI server.
62  
-
63  
-.. admonition:: Choosing the socket
64  
-
65  
-    The easiest is to set the socket to a high level (>49152) local port like
66  
-    127.0.0.1:49152. If the socket is a file, the system administrator must
67  
-    ensure that the Web server process has read, write and execute privileges
68  
-    on that file.
69  
-
70  
-uWSGI is highly configurable and thus there are many ways to start the
71  
-process. For example, uwsgi version 0.9.6.8 provides a hundred switches.  This
72  
-guide demonstrates the most important of them, but is not a substitute the
73  
-official manual and online documentation.
74  
-
75  
-uWSGI supports configuration through:
  32
+See uWSGI's `background documentation`_ for more detail.
76 33
 
77  
-* environment variables
78  
-* command line switches
79  
-* ldap
80  
-* ini files
81  
-* xml files
82  
-* yaml files
  34
+.. _background documentation: http://projects.unbit.it/uwsgi/wiki/Background
83 35
 
84  
-Managing the uWSGI server
85  
--------------------------
  36
+Configuring and starting the uWSGI server for Django
  37
+----------------------------------------------------
86 38
 
87  
-The system administrator controls the worker process pool by sending signals
88  
-to the master process. For example, the unix kill command sends such signals.
89  
-uWSGI can write the master process id to a "pidfile". A "pidfile" is a plain
90  
-text file containing just a process id.
  39
+uWSGI supports multiple ways to configure the process, see uWSGI's
  40
+`configuration documentation`_ and `examples`_
91 41
 
92  
-Starting the server
93  
--------------------
  42
+.. _configuration documentation: http://projects.unbit.it/uwsgi/wiki/Doc
  43
+.. _examples: http://projects.unbit.it/uwsgi/wiki/Example
94 44
 
95  
-Starting an uWSGI server is the role of the system administrator, like
96  
-starting the Web server. It is *not* the role of the Web server to start the
97  
-uWSGI server. This means:
98  
-
99  
-* the uWSGI server can be restarted or reloaded independently from the Web
100  
-  server,
101  
-* (except with Cherokee), it is the role of the system administrator to make
102  
-  uWSGI start on boot or reboot: either through tools like supervisor or
103  
-  daemontools, either directly at init level in a file like /etc/rc.local or
104  
-  /etc/conf.d/local
105  
-
106  
-Managing uWSGI
107  
-==============
108  
-
109  
-Starting the server
110  
--------------------
111  
-
112  
-Example command line for a Web server that understands the uWSGI protocol::
  45
+An example command to start a uWSGI server::
113 46
 
114 47
     uwsgi --chdir=/path/to/your/project
115 48
         --module='mysite.wsgi:application' \
@@ -156,110 +89,8 @@ Example ini configuration file usage::
156 89
 
157 90
     uwsgi --ini uwsgi.ini
158 91
 
159  
-Read more `uWSGI configuration examples
160  
-<http://projects.unbit.it/uwsgi/wiki/Example>`_.
161  
-
162  
-.. admonition:: Massive application hosting
163  
-
164  
-    `uWSGI emperor <http://projects.unbit.it/uwsgi/wiki/Emperor>`_ is a special
165  
-    uWSGI process that can manage many master processes at once.
166  
-
167  
-Reloading the daemon
168  
---------------------
169  
-
170  
-As mentioned above, the uWSGI master process is one of the core components of
171  
-the uWSGI stack. The signal to brutally reload all the workers and the master
172  
-process is SIGTERM. Example command to brutally reload the uWSGI processes::
173  
-
174  
-    kill -TERM `cat /tmp/project-master.pid`
175  
-
176  
-Patching the daemon
177  
--------------------
178  
-
179  
-One of the great advantages of uWSGI is its ability to gradually restart each
180  
-worker without losing any requests.
181  
-
182  
-For example, uWSGI can be signaled that worker should reload the code after
183  
-handling their current request (if any) from bash::
184  
-
185  
-    # using kill to send the signal
186  
-    kill -HUP `cat /tmp/project-master.pid`
187  
-
188  
-    # if uwsgi was started with --touch-reload=/tmp/somefile
189  
-    touch /tmp/somefile
190  
-
191  
-Or from Python::
192  
-
193  
-    uwsgi.reload()
194  
-
195  
-Stopping the daemon
196  
--------------------
197  
-
198  
-If you have the process running in the foreground, it's easy enough to stop it:
199  
-Simply hitting ``Ctrl-C`` will stop and quit the uWSGI server. However, when
200  
-you're dealing with background processes, you'll need to resort to the Unix
201  
-``kill`` command.
202  
-
203  
-The ``kill`` is used to send a signal to the uWSGI master process. The
204  
-`uWSGI signals are documented online
205  
-<http://projects.unbit.it/uwsgi/wiki/uWSGISignals>`_. Example command to
206  
-completely stop the uWSGI stack::
207  
-
208  
-    kill -INT `cat /tmp/project-master.pid`
209  
-
210  
-HTTP server configuration
211  
-=========================
212  
-
213  
-Nginx setup
214  
------------
215  
-
216  
-Nginx provides the `uwsgi module <http://wiki.nginx.org/HttpUwsgiModule>`_ by
217  
-default since nginx 0.8.40. Configuring Nginx to use an uWSGI server is as
218  
-simple as setting it up to proxy requests::
219  
-
220  
-    location / {
221  
-        uwsgi_pass 127.0.0.1:49152;
222  
-        # in case of a socket file:
223  
-        # uwsgi_pass unix:/tmp/yourproject.sock;
224  
-    }
225  
-
226  
-Note that default uwsgi parameters should be included somewhere in your Nginx
227  
-configuration. For example::
228  
-
229  
-    http {
230  
-        include       uwsgi_params;
231  
-        # [...] normal nginx configuration here
232  
-    }
233  
-
234  
-Cherokee setup
235  
---------------
236  
-
237  
-Cherokee setup is documented in the `official Cherokee uWSGI documentation
238  
-<http://www.cherokee-project.com/doc/cookbook_uwsgi.html>`_.
239  
-
240  
-Lighttpd setup
241  
---------------
242  
-
243  
-`Lighttpd uwsgi module <http://projects.unbit.it/uwsgi/wiki/RunOnLighttpd>`_ is
244  
-still experimental.
245  
-
246  
-Troubleshooting
247  
-===============
248  
-
249  
-As usual, the first thing to do is to check the logs. This implies:
250  
-
251  
-* the web server log, which will indicate if it couldn't connect to the uWSGI
252  
-  process,
253  
-* the uWSGI log, which will indicate if an exception was thrown.
254 92
 
255  
-Typical gotchas:
  93
+See the uWSGI docs on `managing the uWSGI process`_ for information on
  94
+starting, stoping, and reloading the uWSGI workers.
256 95
 
257  
-* If the socket is a file, the Web server process should have read, write and
258  
-  execute permissions on the socket file. The ``--chmod-socket`` option can do
259  
-  it.
260  
-* In some cases, for instance if uWSGI was started without ``--vacuum`` or
261  
-  killed with ``SIGKILL``, it won't remove the socket and pidfile when it is
262  
-  interrupted. It is safe to remove them manually and to start uWSGI again in
263  
-  that case.
264  
-* uWSGI can start the process in the foreground, this will make errors easily
265  
-  visible to the system administrator.
  96
+.. _managing the uWSGI process: http://projects.unbit.it/uwsgi/wiki/Management

0 notes on commit 5a013ce

Please sign in to comment.
Something went wrong with that request. Please try again.