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.
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
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:
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.
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.
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:
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 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:
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:
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.
Massive application hosting
uWSGI emperor is a special uWSGI process that can manage many master processes at once.
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`
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()
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`
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 is documented in the official Cherokee uWSGI documentation.
Lighttpd uwsgi module is still experimental.
As usual, the first things to do is to check the logs. This implies:
Typical gotchas:
Oct 05, 2011