uWSGI Documentation Release 1.9 uWSGI February 08, 2016 Contents 1 Included components (updated to latest stable release)3 2 Quickstarts 5 3 Table of Contents 11 4 Tutorials 137 5 Articles 139 6 uWSGI Subsystems 141 7 Scaling with uWSGI 197 8 Securing uWSGI 217 9 Keeping an eye on your apps 223 10 Async and loop engines 231 11 Web Server support 237 12 Language support 251 13 Release Notes 317 14 Contact 359 15 Donate 361 16 Indices and tables 363 Python Module Index 365 i ii uWSGI Documentation, Release 1.9 The uWSGI project aims at developing a full stack for building (and hosting) clustered/distributed network applica- tions. Mainly targeted at the web and its standards, it has been successfully used in a lot of different contexts. Thanks to its pluggable architecture it can be extended without limits to support more platforms and languages. Cur- rently, you can write plugins in C, C++ and Objective-C. The “WSGI” part in the name is a tribute to the namesake Python standard, as it has been the first developed plugin for the project. Versatility, performance, low-resource usage and reliability are the strengths of the project (and the only rules fol- lowed). Contents 1 uWSGI Documentation, Release 1.9 2 Contents CHAPTER 1 Included components (updated to latest stable release) The Core (implements configuration, processes management, sockets creation, monitoring, logging, shared memory areas, ipc, cluster membership and the uWSGI Subscription Server) Request plugins (implement application server interfaces for various languages and platforms: WSGI, PSGI, Rack, Lua WSAPI, CGI, PHP, Go ...) Gateways (implement load balancers, proxies and routers) The Emperor (implements massive instances management and monitoring) Loop engines (implement concurrency, components can be run in preforking, threaded, asynchronous/evented and green thread/coroutine modes. Various technologies are supported, including uGreen, Greenlet, Stackless, Gevent, Coro::AnyEvent, Goroutines and Fibers) Note: With a large open source project such as uWSGI the code and the documentation may not always be in sync. The mailing list is the best source for help regarding uWSGI. 3 uWSGI Documentation, Release 1.9 4 Chapter 1. Included components (updated to latest stable release) CHAPTER 2 Quickstarts 2.1 Quickstart for python/WSGI applications This quickstart will show you how to deploy simple WSGI applications and common frameworks Python here is meant as CPython, for PyPy you need to use the specific plugin: The PyPy plugin, Jython support is on work. 2.1.1 Installing uWSGI with python support Suggestion: when you start learning uWSGI try to build from official sources, using distro-supplied packages could bring you lot of headaches. When things are clear you can use modular builds (like the ones available in your distro) uWSGI is a (big) C application, so you need a C compiler (like the gcc or clang) and python development headers. On a debian-based distro a apt-get install build-essential python-dev will be enough You have various ways to install uWSGI for python via pip pip install uwsgi using the network installer curl http://uwsgi.it/install | bash -s default /tmp/uwsgi (this will install the uWSGI binary in /tmp/uwsgi, feel free to change it) or simply downloading a source tarball and ‘making’ it wget http://projects.unbit.it/downloads/uwsgi-latest.tar.gz tar zxvf uwsgi-latest.tar.gz cd <dir> make after the build you will have a ‘uwsgi’ binary in the current directory Installing via your package distribution is not covered (would be impossibile to make everyone happy), but all the general rules applies. 5 uWSGI Documentation, Release 1.9 One thing you may want to take in account when testing this quickstart with distro supplied packages, is that very probably your distribution has built uWSGI in modular way (every feature is a different plugin that must be loaded). To complete the quickstart you have to prepend --plugin python,http to the first serie of example and --plugin python when the HTTP router is removed (it could make no sense for you, just continue reading) 2.1.2 The first WSGI application Let’s start with the simple hello world example (this is for python 2.x, python 3.x requires the returned string to be bytes, see later): def application(env, start_response): start_response('200 OK', [('Content-Type','text/html')]) return "Hello World" save it as foobar.py As you can see it is composed by a single python function. It is called “application” as this is the default function that the uWSGI python loader will search for (but you can obviously customize it) The python 3.x version is the following: def application(env, start_response): start_response('200 OK', [('Content-Type','text/html')]) return b"Hello World" 2.1.3 Deploy it on HTTP port 9090 Now start uwsgi to run an http server/router passing requests to your WSGI application: uwsgi --http :9090 --wsgi-file foobar.py That’s all 2.1.4 Adding concurrency and monitoring The first tuning you would like to make is adding concurrency (by default uWSGI starts with a single process and a single thread) You can add more processes with the --processes option or more threads with the --threads options (or you can have both). uwsgi --http :9090 --wsgi-file foobar.py --master --processes4 --threads 2 this will spawn 4 processes (each with 2 threads), a master process that will respawn your processes when they die and the HTTP router seen before. One important task is monitoring. Understanding what is going on is vital in production deployment. The stats subsystem allows you to export uWSGI internal statistics via json uwsgi --http :9090 --wsgi-file foobar.py --master --processes4 --threads2 --stats 127.0.0.1:9191 make some request to your app and then telnet to the port 9191. You will get lot of funny information. There is a top-like tool for monitoring instances, named ‘uwsgitop’ (just pip install it) Pay attention: bind the stats socket to a private address (unless you know what you are doing) otherwise everyone could access it !!! 6 Chapter 2. Quickstarts uWSGI Documentation, Release 1.9 2.1.5 Putting behind a full webserver Even if the uWSGI http router is solid and high-performance, you may want to put your application behind a fully capable webserver. uWSGI natively speaks HTTP, FastCGI, SCGI and its specific protocol named “uwsgi” (yes, wrong naming choice). The best performing protocol is obviously the uwsgi one, already supported by nginx and Cherokee (while various Apache modules are available). A common nginx config is the following location/{ include uwsgi_params; uwsgi_pass 127.0.0.1:3031; } this means, “pass every request to the server bound to port 3031 speaking the uwsgi protocol”. Now we can spawn uWSGI to natively speak the uwsgi protocol uwsgi --socket 127.0.0.1:3031 --wsgi-file foobar.py --master --processes4 --threads2 --stats 127.0.0.1:9191 if you run ps aux you will see one process less. The http router has been removed as our “workers” (the processes assigned to uWSGI) natively speak the uwsgi protocol. 2.1.6 Automatically starting uWSGI on boot If you think about writing some init.d script for spawning uWSGI, just sit down and realize that we are no more in 1995. Each distribution has choosen its startup system (Upstart, SystemD...) and there are tons of process managers available (supervisord, god...). uWSGI will integrate very well with all of them (we hope), but if you plan to deploy a big number of apps check the uWSGI Emperor it is the dream of every devops. 2.1.7 Deploying Django Django is very probably the most used python web framework around. Deploying it is pretty easy (we continue our configuration with 4 processes with 2 threads each) We suppose the django project is in /home/foobar/myproject uwsgi --socket 127.0.0.1:3031 --chdir /home/foobar/myproject/ --wsgi-file myproject/wsgi.py --master --processes4 --threads2 --stats 127.0.0.1:9191 with –chdir we move to a specific directory. In django this is required to correctly load modules. if the file /home/foobar/myproject/myproject/wsgi.py (or whatever you have called your project) does not exist, you are very probably using an old (<1.4) django version. In such a case you need a little bit more configuration. uwsgi --socket 127.0.0.1:3031 --chdir /home/foobar/myproject/ --pythonpath .. --env DJANGO_SETTINGS_MODULE=myproject.settings --module "django.core.handlers.wsgi.WSGIHandler()" --processes4 --threads2 --stats 127.0.0.1:9191 ARGH !!! what the hell is this ??? Yes, you are right, dealing with such long command lines is basically unpractical (and foolish). uWSGI supports various configuration styles. In this quickstart we will use .ini files. 2.1. Quickstart for python/WSGI applications 7 uWSGI Documentation, Release 1.9 [uwsgi] socket= 127.0.0.1:3031 chdir= /home/foobar/myproject/ pythonpath=.. env= DJANGO_SETTINGS_MODULE=myproject.settings module= django.core.handlers.wsgi:WSGIHandler() processes=4 threads=2 stats= 127.0.0.1:9191 ...a lot better Just run it uwsgi yourfile.ini older (<1.4) Django releases need to set env, module and the pythonpath (note the .. that allows us to reach the myproject.settings module) 2.1.8 Deploying Flask Flask is another popular python web microframework from flask import Flask app= Flask(__name__) @app.route('/') def index(): return "<span style='color:red'>I am app 1</span>" Flask exports its WSGI function (the one we called ‘application’ at the start of the page) as ‘app’, so we need to instruct uwsgi to use it We still continue to use the 4 processes/2 threads and the uwsgi socket as the base uwsgi --socket 127.0.0.1:3031 --wsgi-file myflaskapp.py --callable app --processes4 --threads2 --stats 127.0.0.1:9191 the only addition is the –callable option.