Latest Stable Release)3
Total Page:16
File Type:pdf, Size:1020Kb
uWSGI Documentation Release 2.0 uWSGI Jun 17, 2020 Contents 1 Included components (updated to latest stable release)3 2 Quickstarts 5 3 Table of Contents 33 4 Tutorials 303 5 Articles 343 6 uWSGI Subsystems 375 7 Scaling with uWSGI 457 8 Securing uWSGI 485 9 Keeping an eye on your apps 503 10 Async and loop engines 511 11 Web Server support 525 12 Language support 541 13 Other plugins 629 14 Broken/deprecated features 633 15 Release Notes 643 16 Contact 741 17 Commercial support 743 18 Donate 745 19 Sponsors 747 20 Indices and tables 749 i Python Module Index 751 Index 753 ii uWSGI Documentation, Release 2.0 The uWSGI project aims at developing a full stack for building hosting services. Application servers (for various programming languages and protocols), proxies, process managers and monitors are all implemented using a common api and a common configuration style. Thanks to its pluggable architecture it can be extended to support more platforms and languages. Currently, 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 2.0 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 events and concurrency, components can be run in preforking, threaded, asyn- chronous/evented and green thread/coroutine modes. Various technologies are supported, including uGreen, Greenlet, Stackless, Gevent, Coro::AnyEvent, Tornado, Goroutines and Fibers) Note: uWSGI is a very active project with a fast release cycle. For this reason the code and the documentation may not always be in sync. We try our best to have good documentation, but it is a hard work. Sorry for that. If you are in trouble, the mailing list is the best source for help regarding uWSGI. Contributors for documentation (in addition to code) are always welcome. 3 uWSGI Documentation, Release 2.0 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 web frameworks. Python here is meant as CPython, for PyPy you need to use the specific plugin: The PyPy plugin, Jython support is under construction. Note: You need at least uWSGI 1.4 to follow the quickstart. Anything older is no longer maintained and is highly buggy! 2.1.1 Installing uWSGI with Python support Tip: When you start learning uWSGI, try to build from official sources: using distribution-supplied packages may bring you plenty of headaches. When things are clear, you can use modular builds (like the ones available in your distribution). uWSGI is a (big) C application, so you need a C compiler (like gcc or clang) and the Python development headers. On a Debian-based distro an apt-get install build-essential python-dev will be enough. You have various ways to install uWSGI for Python: • via pip pip install uwsgi 5 uWSGI Documentation, Release 2.0 • using the network installer curl http://uwsgi.it/install | bash -s default /tmp/uwsgi (this will install the uWSGI binary into /tmp/uwsgi, feel free to change it). • via downloading a source tarball and “making” it wget https://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 impossible to make everyone happy), but all of the general rules apply. One thing you may want to take into 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 this quickstart, you have to prepend --plugin python,http to the first series of examples, and --plugin python when the HTTP router is removed (if this doesn’t make sense to you, just continue reading). 2.1.2 The first WSGI application Let’s start with a simple “Hello World” example: def application(env, start_response): start_response('200 OK', [('Content-Type','text/html')]) return [b"Hello World"] (save it as foobar.py). As you can see, it is composed of 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). 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. Note: Do not use --http when you have a frontend webserver or you are doing some form of benchmark, use --http-socket. Continue reading the quickstart to understand why. 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 option (or you can have both). 6 Chapter 2. Quickstarts uWSGI Documentation, Release 2.0 uwsgi --http :9090 --wsgi-file foobar.py --master --processes4 --threads2 This will spawn 4 processes (each with 2 threads), a master process (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’s internal statistics as 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’ll get lots of fun information. You may want to use “uwsgitop” (just pip install it), which is a top-like tool for monitoring instances. Attention: Bind the stats socket to a private address (unless you know what you are doing), otherwise everyone could access it! 2.1.5 Putting behind a full webserver Even though 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 uwsgi, 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 --threads ,!2 --stats 127.0.0.1:9191 If you’ll 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. If your proxy/webserver/router speaks HTTP, you have to tell uWSGI to natively speak the http protocol (this is different from –http that will spawn a proxy by itself): uwsgi --http-socket 127.0.0.1:3031 --wsgi-file foobar.py --master --processes4-- ,!threads2 --stats 127.0.0.1:9191 2.1.6 Automatically starting uWSGI on boot If you are thinking about firing up vi and writing an init.d script for spawning uWSGI, just sit (and calm) down and make sure your system doesn’t offer a better (more modern) approach first. 2.1. Quickstart for Python/WSGI applications 7 uWSGI Documentation, Release 2.0 Each distribution has chosen a startup system (Upstart, Systemd. ) and there are tons of process managers available (supervisord, god, monit, circus. ). 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 more or less the dream of every devops engineer. 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. Argh! What the hell is this?! Yes, you’re right, you’re right. dealing with such long command lines is unpractical, foolish and error-prone. Never fear! uWSGI supports various configuration styles. In this quickstart we will use .ini files. [uwsgi] socket= 127.0.0.1:3031 chdir= /home/foobar/myproject/ wsgi-file= myproject/wsgi.py processes=4 threads=2 stats= 127.0.0.1:9191 A lot better! Just run it: uwsgi yourfile.ini 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) version of Django.