Browse files

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

…or uWSGI. Thanks, jpic and aaugustin.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 439cbea commit aad6f21b29946bf4cc78d5d28330497cb916e35f @jezdez jezdez committed Jun 16, 2011
Showing with 268 additions and 8 deletions.
  1. +6 −4 docs/howto/deployment/index.txt
  2. +255 −0 docs/howto/deployment/uwsgi.txt
  3. +2 −1 docs/index.txt
  4. +5 −3 docs/topics/install.txt
@@ -10,16 +10,18 @@ ways to easily deploy Django:
:maxdepth: 1
+ uwsgi
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:
@@ -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:
+.. _caching framework:
+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
+.. _installation procedures:
+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
+ 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 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/ \
+ --socket= \ # 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/
+ 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
+.. admonition:: Massive application hosting
+ `uWSGI 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/`
+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/`
+ # 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
+<>`_. Example command to
+completely stop the uWSGI stack::
+ kill -INT `cat /tmp/`
+HTTP server configuration
+Nginx setup
+Nginx provides the `uwsgi module <>`_ 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;
+ # 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
+Lighttpd setup
+`Lighttpd uwsgi module <>`_ is
+still experimental.
+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.
@@ -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>` |
@@ -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
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:
+.. _nginx:
.. _mod_wsgi:
.. _WSGI:
.. _server-arrangements wiki page:

0 comments on commit aad6f21

Please sign in to comment.