============================ 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 content. 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 speak the uWSGI protocol. It just needs to be able to proxy HTTP requests to the HTTP server built-in uWSGI. The procedure is the same as proxying to 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 is not a 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 Cherokee), it is the role of the system administrator to make uWSGI 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 understands the uWSGI protocol:: uwsgi --chdir=/path/to/your/project --module='mysite.wsgi:application' \ --env DJANGO_SETTINGS_MODULE=mysite.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 This assumes that you have a top-level project package named ``mysite``, and within it a module :file:`mysite/wsgi.py` that contains a WSGI ``application`` object. This is the layout you will have if you ran ``django-admin.py startproject mysite`` (using your own project name in place of ``mysite``) with a recent version of Django. If this file does not exist, you'll need to create it. See the :doc:`/howto/deployment/wsgi/index` documentation for the default contents you should put in this file, and what else you can add to it. The Django-specific options here are: * ``chdir``: the path to the directory that needs to be on Python's import path; i.e. the directory containing the ``mysite`` package. * ``module``: The WSGI module to use, probably the ``mysite.wsgi`` module which :djadmin:`startproject` creates. * ``env``: should probably contain at least ``DJANGO_SETTINGS_MODULE`` * ``home``: optional path to your project virtualenv Example ini configuration file:: [uwsgi] chdir=/path/to/your/project module='mysite.wsgi:application' 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 components 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 losing any requests. 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 thing 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 in the foreground, this will make errors easily visible to the system administrator.