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