p31829507
/
django
mirror of https://github.com/django/django.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fixed #16057 -- Extended deployment documentation with instructions for uWSGI. Thanks, jpic and aaugustin. 

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16413 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jannis Leidel 2011-06-16 16:34:12 +00:00
parent 439cbeaa68
commit aad6f21b29
4 changed files with 268 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/howto/deployment/index.txt
View File

@ -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/

255
docs/howto/deployment/uwsgi.txt Normal file
View File

@ -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.

3
docs/index.txt
View File

@ -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>` |

8
docs/topics/install.txt
View File

@ -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,7 +53,8 @@ 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
@ -61,6 +62,7 @@ allows it to run on a variety of server platforms. See the
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