From aad6f21b29946bf4cc78d5d28330497cb916e35f Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Thu, 16 Jun 2011 16:34:12 +0000 Subject: [PATCH] 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 --- docs/howto/deployment/index.txt | 10 +- docs/howto/deployment/uwsgi.txt | 255 ++++++++++++++++++++++++++++++++ docs/index.txt | 3 +- docs/topics/install.txt | 8 +- 4 files changed, 268 insertions(+), 8 deletions(-) create mode 100644 docs/howto/deployment/uwsgi.txt diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt index c3777bb299f..a2fd31257c2 100644 --- a/docs/howto/deployment/index.txt +++ b/docs/howto/deployment/index.txt @@ -10,16 +10,18 @@ ways to easily deploy Django: :maxdepth: 1 modwsgi + uwsgi fastcgi mod_python (deprecated) If you're new to deploying Django and/or Python, we'd recommend you try -:doc:`mod_wsgi ` first. In most cases it'll be the easiest, -fastest, and most stable deployment choice. +:doc:`mod_wsgi ` 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/ diff --git a/docs/howto/deployment/uwsgi.txt b/docs/howto/deployment/uwsgi.txt new file mode 100644 index 00000000000..11cb51c5448 --- /dev/null +++ b/docs/howto/deployment/uwsgi.txt @@ -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 +`_. + +.. 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/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 +`_. 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 `_ 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 +`_. + +Lighttpd setup +-------------- + +`Lighttpd uwsgi module `_ 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. diff --git a/docs/index.txt b/docs/index.txt index 6a502adac87..0425da438e0 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -155,7 +155,8 @@ The development process * **Deployment:** :doc:`Overview ` | :doc:`Apache/mod_wsgi ` | - :doc:`Apache/mod_python ` | + :doc:`uWSGI ` | + :doc:`Apache/mod_python (deprecated) ` | :doc:`FastCGI/SCGI/AJP ` | :doc:`Apache authentication ` | :doc:`Handling static files ` | diff --git a/docs/topics/install.txt b/docs/topics/install.txt index 46d6615a828..1058eb25698 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -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 `; +it works very well with `nginx`_. Another is :doc:`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