Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
  • Loading branch information...
commit aad6f21b29946bf4cc78d5d28330497cb916e35f 1 parent 439cbea
Jannis Leidel authored June 16, 2011
10  docs/howto/deployment/index.txt
@@ -10,16 +10,18 @@ ways to easily deploy Django:
10 10
    :maxdepth: 1
11 11
 
12 12
    modwsgi
  13
+   uwsgi
13 14
    fastcgi
14 15
    mod_python (deprecated) <modpython>
15 16
 
16 17
 If you're new to deploying Django and/or Python, we'd recommend you try
17  
-:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be the easiest,
18  
-fastest, and most stable deployment choice.
  18
+:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be
  19
+the easiest, fastest, and most stable deployment choice.
19 20
 
20 21
 .. seealso::
21 22
 
22  
-    * `Chapter 12 of The Django Book`_ discusses deployment and especially
23  
-      scaling in more detail.
  23
+    * `Chapter 12 of the Django Book`_ discusses deployment and especially
  24
+      scaling in more detail. However, it hasn't been updated since mod_python
  25
+      was deprecated.
24 26
 
25 27
 .. _chapter 12 of the django book: http://djangobook.com/en/2.0/chapter12/
255  docs/howto/deployment/uwsgi.txt
... ...
@@ -0,0 +1,255 @@
  1
+============================
  2
+How to use Django with uWSGI
  3
+============================
  4
+
  5
+.. highlight:: bash
  6
+
  7
+uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application
  8
+container server coded in pure C.
  9
+
  10
+It also provides a fast `caching framework`_ but its documentation is not the
  11
+purpose of this document.
  12
+
  13
+.. _uWSGI: http://projects.unbit.it/uwsgi/
  14
+.. _caching framework: http://projects.unbit.it/uwsgi/wiki/CachingFramework
  15
+
  16
+
  17
+Prerequisite: uWSGI
  18
+===================
  19
+
  20
+The wiki describes several `installation procedures`_. Using pip, the python
  21
+package manager, installing any uWSGI version can be done with one command
  22
+line. For example::
  23
+
  24
+    # install current stable version
  25
+    pip install uwsgi
  26
+
  27
+    # or install LTS (long term support)
  28
+    pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
  29
+
  30
+.. _installation procedures: http://projects0.unbit.it/uwsgi/wiki/Install
  31
+
  32
+Prerequisite: general concept
  33
+=============================
  34
+
  35
+uWSGI model
  36
+-----------
  37
+
  38
+uWSGI operates on a client-server model. Your Web server (ie. nginx, Apache)
  39
+communicates with a django-uwsgi "worker" process to serve dynamic contents.
  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 do uWSGI protocol. It just
  52
+needs to be able to proxy HTTP requests to the HTTP server built-in uWSGI.
  53
+The procedure is the same than proxying 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.
  72
+This guide demonstrates the most important of them, but does not intent to
  73
+substitute the official manual and online documentation.
  74
+
  75
+uWSGI supports configuration through:
  76
+
  77
+* environment variables
  78
+* command line switches
  79
+* ldap
  80
+* ini files
  81
+* xml files
  82
+* yaml files
  83
+
  84
+Managing the uWSGI server
  85
+-------------------------
  86
+
  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.
  91
+
  92
+Starting the server
  93
+-------------------
  94
+
  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 Cheerokee), it is the role of the system administrator to make
  102
+  uWSGI to 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 understand the uWSGI protocol::
  113
+
  114
+    uwsgi --chdir=/path/to/your/project
  115
+        --module='django.core.handlers.wsgi:WSGIHandler()' \
  116
+        --env DJANGO_SETTINGS_MODULE=settings \
  117
+        --master --pidfile=/tmp/project-master.pid \
  118
+        --socket=127.0.0.1:49152 \      # can also be a file
  119
+        --processes=5 \                 # number of worker processes
  120
+        --uid=1000 --gid=2000 \         # if root, uwsgi can drop privileges
  121
+        --harakiri=20 \                 # respawn processes taking more than 20 seconds
  122
+        --limit-as=128 \                # limit the project to 128 Megabytes
  123
+        --max-requests=5000 \           # respawn processes after serving 5000 requests
  124
+        --vacuum \                      # clear environment on exit
  125
+        --home=/path/to/virtual/env \   # optionnal path to a virtualenv
  126
+        --daemonize=/var/log/uwsgi/yourproject.log      # background the process
  127
+
  128
+Django specific options are:
  129
+
  130
+* ``chdir``: should be the path to your project
  131
+* ``module``: uwsgi module to use
  132
+* ``pythonpath``: optional path to your project virtualenv
  133
+* ``env``: should contain at least ``DJANGO_SETTINGS_MODULE``
  134
+
  135
+Example ini configuration file::
  136
+
  137
+    [uwsgi]
  138
+    chdir=/path/to/your/project
  139
+    master=True
  140
+    pidfile=/tmp/project-master.pid
  141
+    vacuum=True
  142
+    max-requests=5000
  143
+    deamonize=/var/log/uwsgi/yourproject.log
  144
+
  145
+Example ini configuration file usage::
  146
+
  147
+    uwsgi --ini uwsgi.ini
  148
+
  149
+Read more `uWSGI configuration examples
  150
+<http://projects.unbit.it/uwsgi/wiki/Example>`_.
  151
+
  152
+.. admonition:: Massive application hosting
  153
+
  154
+    `uWSGI emperor <http://projects.unbit.it/uwsgi/wiki/Emperor>`_ is a special
  155
+    uWSGI process that can manage many master processes at once.
  156
+
  157
+Reloading the daemon
  158
+--------------------
  159
+
  160
+As mentioned above, the uWSGI master process is one of the core component of
  161
+the uWSGI stack. The signal to brutally reload all the workers and the master
  162
+process is SIGTERM. Example command to brutally reload the uWSGI processes::
  163
+
  164
+    kill -TERM `cat /tmp/project-master.pid`
  165
+
  166
+Patching the daemon
  167
+-------------------
  168
+
  169
+One of the great advantages of uWSGI is its ability to gradually restart each
  170
+worker without loosing any request.
  171
+
  172
+For example, uWSGI can be signaled that worker should reload the code after
  173
+handling their current request (if any) from bash::
  174
+
  175
+    # using kill to send the signal
  176
+    kill -HUP `cat /tmp/project-master.pid`
  177
+
  178
+    # if uwsgi was started with --touch-reload=/tmp/somefile
  179
+    touch /tmp/somefile
  180
+
  181
+Or from Python::
  182
+
  183
+    uwsgi.reload()
  184
+
  185
+Stopping the daemon
  186
+-------------------
  187
+
  188
+If you have the process running in the foreground, it's easy enough to stop it:
  189
+Simply hitting ``Ctrl-C`` will stop and quit the uWSGI server. However, when
  190
+you're dealing with background processes, you'll need to resort to the Unix
  191
+``kill`` command.
  192
+
  193
+The ``kill`` is used to send a signal to the uWSGI master process. The
  194
+`uWSGI signals are documented online
  195
+<http://projects.unbit.it/uwsgi/wiki/uWSGISignals>`_. Example command to
  196
+completely stop the uWSGI stack::
  197
+
  198
+    kill -INT `cat /tmp/project-master.pid`
  199
+
  200
+HTTP server configuration
  201
+=========================
  202
+
  203
+Nginx setup
  204
+-----------
  205
+
  206
+Nginx provides the `uwsgi module <http://wiki.nginx.org/HttpUwsgiModule>`_ by
  207
+default since nginx 0.8.40. Configuring Nginx to use an uWSGI server is as
  208
+simple as setting it up to proxy requests::
  209
+
  210
+    location / {
  211
+        uwsgi_pass 127.0.0.1:49152;
  212
+        # in case of a socket file:
  213
+        # uwsgi_pass unix:/tmp/yourproject.sock;
  214
+    }
  215
+
  216
+Note that default uwsgi parameters should be included somewhere in your Nginx
  217
+configuration. For example::
  218
+
  219
+    http {
  220
+        include       uwsgi_params;
  221
+        # [...] normal nginx configuration here
  222
+    }
  223
+
  224
+Cherokee setup
  225
+--------------
  226
+
  227
+Cherokee setup is documented in the `official Cherokee uWSGI documentation
  228
+<http://www.cherokee-project.com/doc/cookbook_uwsgi.html>`_.
  229
+
  230
+Lighttpd setup
  231
+--------------
  232
+
  233
+`Lighttpd uwsgi module <http://projects.unbit.it/uwsgi/wiki/RunOnLighttpd>`_ is
  234
+still experimental.
  235
+
  236
+Troubleshooting
  237
+===============
  238
+
  239
+As usual, the first things to do is to check the logs. This implies:
  240
+
  241
+* the web server log, which will indicate if it couldn't connect to the uWSGI
  242
+  process,
  243
+* the uWSGI log, which will indicate if an exception was thrown.
  244
+
  245
+Typical gotchas:
  246
+
  247
+* If the socket is a file, the Web server process should have read, write and
  248
+  execute permissions on the socket file. The ``--chmod-socket`` option can do
  249
+  it.
  250
+* In some cases, for instance if uWSGI was started without ``--vacuum`` or
  251
+  killed with ``SIGKILL``, it won't remove the socket and pidfile when it is
  252
+  interrupted. It is safe to remove them manually and to start uWSGI again in
  253
+  that case.
  254
+* uWSGI can start the process on the foreground, this will make errors easily
  255
+  visible to the system administrator.
3  docs/index.txt
@@ -155,7 +155,8 @@ The development process
155 155
     * **Deployment:**
156 156
       :doc:`Overview <howto/deployment/index>` |
157 157
       :doc:`Apache/mod_wsgi <howto/deployment/modwsgi>` |
158  
-      :doc:`Apache/mod_python <howto/deployment/modpython>` |
  158
+      :doc:`uWSGI <howto/deployment/uwsgi>` |
  159
+      :doc:`Apache/mod_python (deprecated) <howto/deployment/modpython>` |
159 160
       :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
160 161
       :doc:`Apache authentication <howto/apache-auth>` |
161 162
       :doc:`Handling static files <howto/static-files>` |
8  docs/topics/install.txt
@@ -28,11 +28,11 @@ Install Apache and mod_wsgi
28 28
 =============================
29 29
 
30 30
 If you just want to experiment with Django, skip ahead to the next
31  
-section; Django includes a lightweight Web server you can use for
  31
+section; Django includes a lightweight web server you can use for
32 32
 testing, so you won't need to set up Apache until you're ready to
33 33
 deploy Django in production.
34 34
 
35  
-If you want to use Django on a production site, use Apache with
  35
+If you want to use Django on a production site, use `Apache`_ with
36 36
 `mod_wsgi`_. mod_wsgi can operate in one of two modes: an embedded
37 37
 mode and a daemon mode. In embedded mode, mod_wsgi is similar to
38 38
 mod_perl -- it embeds Python within Apache and loads Python code into
@@ -53,7 +53,8 @@ for information on how to configure mod_wsgi once you have it
53 53
 installed.
54 54
 
55 55
 If you can't use mod_wsgi for some reason, fear not: Django supports
56  
-many other deployment options. Another option is :doc:`FastCGI
  56
+many other deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`;
  57
+it works very well with `nginx`_. Another is :doc:`FastCGI
57 58
 </howto/deployment/fastcgi>`, perfect for using Django with servers
58 59
 other than Apache. Additionally, Django follows the WSGI_ spec, which
59 60
 allows it to run on a variety of server platforms. See the
@@ -61,6 +62,7 @@ allows it to run on a variety of server platforms. See the
61 62
 instructions for each platform.
62 63
 
63 64
 .. _Apache: http://httpd.apache.org/
  65
+.. _nginx: http://nginx.net/
64 66
 .. _mod_wsgi: http://code.google.com/p/modwsgi/
65 67
 .. _WSGI: http://www.python.org/dev/peps/pep-0333/
66 68
 .. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements

0 notes on commit aad6f21

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