Installing uWSGI with Python support¶

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 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
  

• 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 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 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 (it could make no sense for you, just continue reading).

The first WSGI application¶

Let’s start with a simple “Hello World” example (this is for Python 2.x, Python 3.x requires the returned string to be bytes, see lower):

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 of a single Python function. It is called “application” as this is 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"]

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.

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 --processes 4 --threads 2

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 --processes 4 --threads 2 --stats 127.0.0.1:9191

Make some request to your app and then telnet to the port 9191, you’ll get a lot of funny information. You may want to use “uwsgitop” (just pip install it), which is a top-like tool for monitoring instances.

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 --processes 4 --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.

Automatically starting uWSGI on boot¶

If you think about writing some init.d script for spawning uWSGI, just sit (and calm) down and check if your system offers you a better (more modern) approach.

Each distribution has chosen its startup system (Upstart, SystemD, etc.) and there are tons of process managers available: Supervisor, god, Circus, etc.

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.

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 --processes 4 --threads 2 --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) version of Django. 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()" --processes 4 --threads 2 --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.

[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 (.. allow us to reach the myproject.settings module).

Deploying Flask¶

Flask is popular Python web microframework.

Save the following example as myflaskapp.py:

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 beginning of this quickstart) 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 --processes 4 --threads 2 --stats 127.0.0.1:9191

(the only addition is the --callable option).

Deploying web2py¶

Again a popular choice. Unzip the web2py source distribution on a directory of choice and write a uWSGI config file:

[uwsgi]
http = :9090
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

We used the HTTP router again. Just go to port 9090 with your browser and you will see the web2py welcome page.

Click on the administrative interface and... oops, it does not work as it requires HTTPS. Do not worry, the uWSGI router is HTTPS-capable (be sure you have OpenSSL development headers: install them and rebuild uWSGI, the build system will automatically detect it).

First of all generate your key and certificate:

openssl genrsa -out foobar.key 2048
openssl req -new -key foobar.key -out foobar.csr
openssl x509 -req -days 365 -in foobar.csr -signkey foobar.key -out foobar.crt

Now you have 2 files (well 3, counting the foobar.csr), foobar.key and foobar.crt. Change the uWSGI config:

[uwsgi]
https = :9090,foobar.crt,foobar.key
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

Re-run uWSGI and connect to port 9090 using https:// with your browser.

A note on Python threads¶

If you start uWSGI without threads, the Python GIL will not be enabled, so threads generated by your application will never run. You may not like that choice, but remember that uWSGI is a language-independent server, so most of its choices are for maintaining it “agnostic”.

But do not worry, there are basically no choices made by the uWSGI developers that cannot be changed with an option.

If you want to maintain Python threads support without starting multiple threads for your application, just add the --enable-threads option (or enable-threads = true in ini style).

Virtualenvs¶

uWSGI can be configured to search for Python modules in a specific virtualenv.

Just add virtualenv = <path> to your options.

Security and availability¶

Always avoid running your uWSGI instances as root. You can drop privileges using the uid and gid options:

[uwsgi]
https = :9090,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

If you need to bind to privileged ports (like 443 for HTTPS), use shared sockets. They are created before dropping privileges and can be referenced with the =N syntax, where N is the socket number (starting from 0):

[uwsgi]
shared-socket = :443
https = =0,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

A common problem with webapp deployment is “stuck requests”. All of your threads/workers are stuck (blocked on request) and your app cannot accept more requests. To avoid that problem you can set a harakiri timer. It is a monitor (managed by the master process) that will destroy processes stuck for more than the specified number of seconds (choose harakiri value carefully). For example, you may want to destroy workers blocked for more than 30 seconds:

[uwsgi]
shared-socket = :443
https = =0,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8
harakiri = 30

In addition to this, since uWSGI 1.9, the stats server exports the whole set of request variables, so you can see (in realtime) what your instance is doing (for each worker, thread or async core).

Offloading¶

The uWSGI offloading subsystem allows you to free your workers as soon as possible when some specific pattern matches and can be delegated to a pure-C thread (sending static file from the filesystem, transferring data from the network to the client and so on).

Offloading is very complex, but its use is transparent to the end user. If you want to try, just add --offload-threads <n>, where <n> is the number of threads to spawn (one per CPU is a good value).

When offload threads are enabled, all of the parts that can be optimized will be automatically detected.

And now¶

You should already be able to go in production with such few concepts, but uWSGI is an enormous project with hundreds of features and configurations. If you want to be a better sysadmin, continue reading the full docs.

Installing uWSGI with Perl support¶

To build uWSGI you need a c compiler (gcc and clang are supported) and the python binary (it will only run the uwsgiconfig.py script that will execute the various compilation steps). As we are building a uWSGI binary with perl support we need perl development headers too (libperl-dev package on debian-based distros)

You can build uWSGI manually:

python uwsgiconfig.py --build psgi

that is the same as

UWSGI_PROFILE=psgi make

or using the network installer:

curl http://uwsgi.it/install | bash -s psgi /tmp/uwsgi

that will create a uWSGI binary in /tmp/uwsgi (feel free to change the path to whatever you want)

Note for distro packages¶

You distribution very probably contains a uWSGI package set. Those uWSGI packages tend to be highly modulars, so in addition to the core you need to install the required plugins. Plugins must be loaded in your configs. In the learning phase we strongly suggest to not use distribution packages to easily follow documentation and tutorials.

Once you feel confortable with the “uWSGI way” you can choose the best approach for your deployments.

Your first PSGI app¶

save it to a file named myapp.pl

my $app = sub {
     my $env = shift;
     return [
             '200',
             [ 'Content-Type' => 'text/html' ],
             [ "<h1>Hello World</h1>" ],
     ];
};

then run it via uWSGI in http mode:

uwsgi --http :8080 --http-modifier1 5 --psgi myapp.pl

(remember to replace ‘uwsgi’ if it is not in your current $PATH)

or if you are using a modular build (like the one of your distro)

uwsgi --plugins http,psgi --http :8080 --http-modifier1 5 --psgi myapp.pl

What is that ‘–http-modifier1 5’ thing ???¶

uWSGI supports various languages and platform. When the server receives a request it has to know where to ‘route’ it.

Each uWSGI plugin has an assigned number (the modifier), the perl/psgi one has the 5. So –http-modifier1 5 means “route to the psgi plugin”

Albeit uWSGI has a more “human-friendly” internal routing system using modifiers is the fastest way, so, if possible always use them

Using a full webserver: nginx¶

The supplied http router, is (yes, incredible) only a router. You can use it as a load balancer or a proxy, but if you need a full webserver (for efficiently serving static files or all of those task a webserver is good at), you can get rid of the uwsgi http router (remember to change –plugins http,psgi to –plugins psgi if you are using a modular build) and put your app behind nginx.

To communicate with nginx, uWSGI can use various protocol: http, uwsgi, fastcgi, scgi...

The most efficient one is the uwsgi one. Nginx includes uwsgi protocol support out of the box.

Run your psgi application on a uwsgi socket:

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl

then add a location stanza in your nginx config

location / {
    include uwsgi_params;
    uwsgi_pass 127.0.0.1:3031;
    uwsgi_modifier1 5;
}

Reload your nginx server, and it should start proxying requests to your uWSGI instance

Note that you do not need to configure uWSGI to set a specific modifier, nginx will do it using the uwsgi_modifier1 5; directive

Adding concurrency¶

You can give concurrency to to your app via multiprocess,multithreading or various async modes.

To spawn additional processes use the –processes option

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --processes 4

To have additional threads use –threads

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --threads 8

Or both if you feel exotic

A very common non-blocking/coroutine library in the perl world is Coro::AnyEvent. uWSGI can use it (even combined with multiprocessing) simply including the coroae plugin.

To build a uWSGI binary with coroae support just run

UWSGI_PROFILE=coroae make

or

curl http://uwsgi.it/install | bash -s coroae /tmp/uwsgi

you will end with a uWSGI binary including both the psgi and coroae plugins.

Now run your application in Coro::AnyEvent mode:

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --coroae 1000 --processes 4

it will run 4 processes each able to manage up to 1000 coroutines (or Coro microthreads).

Adding robustness: the Master process¶

It is highly recommended to have the master process always running on productions apps.

It will constantly monitor your processes/threads and will add funny features like the The uWSGI Stats Server

To enable the master simply add –master

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --processes 4 --master

Using config files¶

uWSGI has literally hundreds of options. Dealing with them via command line is basically silly, so try to always use config files. uWSGI supports various standards (xml, .ini, json, yaml...). Moving from one to another is pretty simple. The same options you can use via command line can be used on config files simply removing the -- prefix:

[uwsgi]
socket = 127.0.0.1:3031
psgi = myapp.pl
processes = 4
master = true

or xml:

<uwsgi>
  <socket>127.0.0.1:3031</socket>
  <psgi>myapp.pl</psgi>
  <processes>4</processes>
  <master/>
</uwsgi>

To run uWSGI using a config file, just specify it as argument:

uwsgi yourconfig.ini

if for some reason your config cannot end with the expected extension (.ini, .xml, .yml, .js) you can force the binary to use a specific parser in this way:

uwsgi --ini yourconfig.foo

uwsgi --xml yourconfig.foo

uwsgi --yaml yourconfig.foo

and so on

You can even pipe configs (using the dash to force reading from stdin):

perl myjsonconfig_generator.pl | uwsgi --json -

Automatically starting uWSGI on boot¶

If you are thinking about writing some init.d script for spawning uWSGI, just sit (and calm) down and check if your system does not offer you a better (more modern) approach.

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.

Security and availability¶

ALWAYS avoid running your uWSGI instances as root. You can drop privileges using the uid and gid options

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
psgi = myapp.pl
master = true
processes = 8

A common problem with webapp deployment is “stuck requests”. All of your threads/workers are stuck blocked on a request and your app cannot accept more of them.

To avoid that problem you can set an harakiri timer. It is a monitor (managed by the master process) that will destroy processes stuck for more than the specified number of seconds

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
psgi = myapp.pl
master = true
processes = 8
harakiri = 30

will destroy workers blocked for more than 30 seconds. Choose carefully the harakiri value !!!

In addition to this, since uWSGI 1.9, the stats server exports the whole set of request variables, so you can see (in realtime) what your instance is doing (for each worker, thread or async core)

Enabling the stats server is easy:

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
psgi = myapp.pl
master = true
processes = 8
harakiri = 30
stats = 127.0.0.1:5000

just bind it to an address (UNIX or TCP) and just connect (you can use telnet too) to it to receive a JSON representation of your instance.

The uwsgitop application (you can find it in the official github repository) is an example of using the stats server to have a top-like realtime monitoring tool (with colors !!!)

Offloading¶

The uWSGI offloading subsystem allows you to free your workers as soon as possible when some specific pattern matches and can be delegated to a pure-c thread. Examples are sending static file from the filesystem, transferring data from the network to the client and so on.

Offloading is very complex, but its use is transparent to the end user. If you want to try just add –offload-threads <n> where <n> is the number of threads to spawn (one for cpu is a good value).

When offload threads are enabled, all of the parts that can be optimized will be automatically detected

And now¶

You should already be able to go in production with such few concepts, but uWSGI is an enormous project with hundreds of features and configurations. If you want to be a better sysadmin, continue reading the full docs.

Installing uWSGI with Ruby support¶

To build uWSGI you need a c compiler (gcc and clang are supported) and the python binary (it will only run the uwsgiconfig.py script that will execute the various compilation steps). As we are building a uWSGI binary with ruby support we need ruby development headers too (ruby-dev package on debian-based distros)

You can build uWSGI manually:

make rack

that is the same as

UWSGI_PROFILE=rack make

that is the same of

make PROFILE=rack

and

python uwsgiconfig.py --build rack

If you are lazy, you can download, build and install a uWSGI+ruby binary in a single shot:

curl http://uwsgi.it/install | bash -s rack /tmp/uwsgi

Or, more ruby-friendly:

gem install uwsgi

All of this methods build a “monolithic” uWSGI binary. The uWSGI project is composed by dozens of plugins, you can choose to build the server core and having a plugin for every feature (that you will load when needed), or you can build a single binary with the features you need. This kind of builds are called ‘monolithic’.

This quickstart assumes a monolithic binary (so you do not need to load plugins). If you prefer to use your package distributions (instead of building uWSGI from official sources), see below

Note for distro packages¶

You distribution very probably contains a uWSGI package set. Those uWSGI packages tend to be highly modulars, so in addition to the core you need to install the required plugins. Plugins must be loaded in your configs. In the learning phase we strongly suggest to not use distribution packages to easily follow documentation and tutorials.

Once you feel confortable with the “uWSGI way” you can choose the best approach for your deployments.

As an example, the tutorial makes use of the ‘http’ and ‘rack’ plugins. If you are using a modular build be sure to load them with the --plugins http,rack option

Your first Rack app¶

Rack is the standard way for writing ruby web apps.

This is a standard Rack Hello world script (call it app.ru):

class App

  def call(environ)
    [200, {'Content-Type' => 'text/html'}, ['Hello']]
  end

end

run App.new

The .ru extension stands for “rackup” that is the deployment tool included in the rack distribution. Rackup uses a little DSL, so to use it into uWSGI you need to install the rack gem:

gem install rack

Now we are ready to deploy with uWSGI:

uwsgi --http :8080 --http-modifier1 7 --rack app.ru

(remember to replace ‘uwsgi’ if it is not in your current $PATH)

or if you are using a modular build (like the one of your distro)

uwsgi --plugins http,rack --http :8080 --http-modifier1 7 --rack app.ru

Whit this command line we spawned an http proxy routing each request to a process (named the ‘worker’) that manages it and send back the response to the http router (that sends back to the client).

If you are asking yourself why spawning two processes, it is because this is the normal architecture you will use in production (a frontline webserver with a backend application server).

If you do not want to spawn the http proxy and directly force the worker to answer http requests just change the command line to

uwsgi --http-socket :8080 --http-socket-modifier1 7 --rack app.ru

now you have a single process managing requests (but remember that directly exposing the application server to the public is generally dangerous and less versatile)

What is that ‘–http-modifier1 7’ thing ???¶

uWSGI supports various languages and platforms. When the server receives a request it has to know where to ‘route’ it.

Each uWSGI plugin has an assigned number (the modifier), the ruby/rack one has the 7. So –http-modifier1 7 means “route to the rack plugin”

Albeit uWSGI has a more “human-friendly” internal routing system using modifiers is the fastest way, so, if possible always use them

Using a full webserver: nginx¶

The supplied http router, is (yes, incredible) only a router. You can use it as a load balancer or a proxy, but if you need a full webserver (for efficiently serving static files or all of those task a webserver is good at), you can get rid of the uwsgi http router (remember to change –plugins http,rack to –plugins rack if you are using a modular build) and put your app behind nginx.

To communicate with nginx, uWSGI can use various protocol: http, uwsgi, fastcgi, scgi...

The most efficient one is the uwsgi one. Nginx includes uwsgi protocol support out of the box.

Run your rack application on a uwsgi socket:

uwsgi --socket 127.0.0.1:3031 --rack app.ru

then add a location stanza in your nginx config

location / {
    include uwsgi_params;
    uwsgi_pass 127.0.0.1:3031;
    uwsgi_modifier1 7;
}

Reload your nginx server, and it should start proxying requests to your uWSGI instance

Note that you do not need to configure uWSGI to set a specific modifier, nginx will do it using the uwsgi_modifier1 5; directive

Adding concurrency¶

With the previous example you deployed a stack being able to serve a single request at time.

To increase concurrency you need to add more processes. If you hope there is a magic math formula to find the right number of processes to spawn, lose it. You need to experiment and monitor your app to find the right value. Take in account every single process is a complete copy of your app, so memory should be taken in account.

To add more processes just use the –processes <n> option:

uwsgi --socket 127.0.0.1:3031 --rack app.ru --processes 8

will spawn 8 processes.

Ruby 1.9/2.0 introduced an improved threads support and uWSGI supports it via the ‘rbthreads’ plugin. This plugin is automatically build when you compile the uWSGI+ruby (>=1.9) monolithic binary.

To add more threads:

uwsgi --socket 127.0.0.1:3031 --rack app.ru --rbthreads 4

or threads + processes

uwsgi --socket 127.0.0.1:3031 --rack app.ru --processes --rbthreads 4

There are other (generally more advanced/complex) ways to increase concurrency (for example ‘fibers’), but most of the time you will end with plain old multiprocesses or multithreads models. (if you are interested you can check to uWSGI rack full docs)

Adding robustness: the Master process¶

It is highly recommended to have the master process always running on productions apps.

It will constantly monitor your processes/threads and will add funny features like the The uWSGI Stats Server

To enable the master simply add –master

uwsgi --socket 127.0.0.1:3031 --rack app.ru --processes 4 --master

Using config files¶

uWSGI has literally hundreds of options (but generally you will not use more than a dozens of them). Dealing with them via command line is basically silly, so try to always use config files. uWSGI supports various standards (xml, .ini, json, yaml...). Moving from one to another is pretty simple. The same options you can use via command line can be used on config files simply removing the -- prefix:

[uwsgi]
socket = 127.0.0.1:3031
rack = app.ru
processes = 4
master = true

or xml:

<uwsgi>
  <socket>127.0.0.1:3031</socket>
  <rack>app.ru</rack>
  <processes>4</processes>
  <master/>
</uwsgi>

To run uWSGI using a config file, just specify it as argument:

uwsgi yourconfig.ini

if for some reason your config cannot end with the expected extension (.ini, .xml, .yml, .js) you can force the binary to use a specific parser in this way:

uwsgi --ini yourconfig.foo

uwsgi --xml yourconfig.foo

uwsgi --yaml yourconfig.foo

and so on

You can even pipe configs (using the dash to force reading from stdin):

ruby myjsonconfig_generator.rb | uwsgi --json -

The fork() problem when you spawn multiple processes¶

uWSGI is “perlish”, there is nothing we can do to hide this thing. Most of its choices (starting from “There’s more than one way to do it”) cames from the perl world (and more generally from the UNIX sysadmins approaches).

Sometimes this approach could lead to unexpected behaviours when applied to other languages/platform.

One of the “problems” you can face when starting to learn uWSGI is its fork() usage.

By default uWSGI loads your application in the first spawned process and then fork() itself multiple times.

It means your app is loaded a single time and then copied.

While this approach speedups the start of the server, some application could have problems with this technique (expecially those initializing db connections on startup, as the file descirptor of the connection will be inherited in the subprocesses)

If you are unsure about the brutal preforking used by uWSGI, just disable it with the --lazy-apps option. It will force uWSGI to completely load your app one time per-worker

Deploying Sinatra¶

Let’s forget about fork(), and back to funny things. This time we deploy a Sinatra application:

require 'sinatra'

get '/hi' do
  "Hello World"
end

run Sinatra::Application

save it as config.ru and run as seen before:

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true

uwsgi yourconf.ini

well maybe you have already noted that basically nothing changed from the previous app.ru examples.

That is because basically every modern Rack app exposes itself as a .ru file (generally called config.ru), so there is no need for multiple options for loading application (like for example in the python/WSGI world)

Deploying RubyOnRails >= 3¶

Starting from 3.0, Rails is fully rack compliant, and exposes a config.ru file you can directly load (like we did with sinatra)

The only difference from sinatra is that your project has a specific layout/convention expecting your current working directory is the one containing the project, so le’ts add a chdir option:

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
chdir = <path_to_your_rails_app>
env = RAILS_ENV=production

uwsgi yourconf.ini

in addition to chdir we have added the ‘env’ option that set the RAILS_ENV environment variable.

Starting from 4.0, Rails support multiple threads (only for ruby 2.0):

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
rbthreads = 2
lazy-apps = true
chdir = <path_to_your_rails_app>
env = RAILS_ENV=production

Deploying older RubyOnRails¶

Older Rails versions are not fully Rack-compliant. For such a reason a specific option is available in uWSGI to load older rails app (you will need the ‘thin’ gem too).

[uwsgi]
socket = 127.0.0.1:3031
master = true
processes = 4
lazy-apps = true
rails = <path_to_your_rails_app>
env = RAILS_ENV=production

the ‘rails’ options must be specified instead of ‘rack’ passing the rails app directory as the argument

Bundler and RVM¶

Bundler is the standard-de-facto ruby tool for managing dependancies. Basically you specify the gem needed by your app in the Gemfile text file and then you launch bundler to install them.

To allow uWSGI to honour bundler installations you only need to add:

rbrequire = rubygems
rbrequire = bundler/setup
env = BUNDLE_GEMFILE=<path_to_your_Gemfile>

the first line is not required for ruby 1.9/2.x

Basically those lines force uWSGI to load the bundler engine and to use the Gemfile specified in the BUNDLE_GEMFILE environment variable.

When using Bundler (like modern frameworks do) your common deployment configuration will be:

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
rbrequire = rubygems
rbrequire = bundler/setup
env = BUNDLE_GEMFILE=<path_to_your_Gemfile>

In addition to Bundler, RVM is another common tool.

It allows you to have multiple (independent) ruby installations (with their gemsets) on a single system.

To instruct uWSGI to use the gemset of a specific rvm version just use the –gemset option:

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
rbrequire = rubygems
rbrequire = bundler/setup
env = BUNDLE_GEMFILE=<path_to_your_Gemfile>
gemset = ruby-2.0@foobar

just pay attention you need a uWSGI binary (or a plugin if you are using a modular build) for every ruby version (ruby version, not gemset !!!)

If you are interested this is a list of commands to build a uWSGI core + 1 one plugin for every ruby version installed in rvm:

# build the core
make nolang
# build plugin for 1.8.7
rvm use 1.8.7
./uwsgi --build-plugin "plugins/rack rack187"
# build for 1.9.2
rvm use 1.9.2
./uwsgi --build-plugin "plugins/rack rack192"
# and so on...

then if you want to use ruby 1.9.2 with the @oops gemset:

[uwsgi]
plugins = ruby192
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
rbrequire = rubygems
rbrequire = bundler/setup
env = BUNDLE_GEMFILE=<path_to_your_Gemfile>
gemset = ruby-1.9.2@oops

Automatically starting uWSGI on boot¶

If you are thinking about writing some init.d script for spawning uWSGI, just sit (and calm) down and check if your system does not offer you a better (more modern) approach.

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.

Security and availability¶

ALWAYS avoid running your uWSGI instances as root. You can drop privileges using the uid and gid options

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
rack = app.ru
master = true
processes = 8

A common problem with webapp deployment is “stuck requests”. All of your threads/workers are stuck blocked on a request and your app cannot accept more of them.

To avoid that problem you can set an harakiri timer. It is a monitor (managed by the master process) that will destroy processes stuck for more than the specified number of seconds

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
rack = app.ru
master = true
processes = 8
harakiri = 30

will destroy workers blocked for more than 30 seconds. Choose carefully the harakiri value !!!

In addition to this, since uWSGI 1.9, the stats server exports the whole set of request variables, so you can see (in realtime) what your instance is doing (for each worker, thread or async core)

Enabling the stats server is easy:

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
rack = app.ru
master = true
processes = 8
harakiri = 30
stats = 127.0.0.1:5000

just bind it to an address (UNIX or TCP) and just connect (you can use telnet too) to it to receive a JSON representation of your instance.

The uwsgitop application (you can find it in the official github repository) is an example of using the stats server to have a top-like realtime monitoring tool (with colors !!!)

Memory usage¶

Low memory usage is one of the selling point of the whole uWSGI project.

Unfortunately being aggressive with memory by default could (read well: could) lead to some performance problem.

By default the uWSGI rack plugin, calls the ruby GC after every request. If you want to reduce this rate just add the --rb-gc-freq <n> option, where n is the number of requests after the GC is called.

If you plan to make benchmarks of uWSGI (or compare it with other solutions) take in account its use of GC.

Ruby can be a memory devourer, so we prefer to be aggressive with memory by default instead of making hello-world benchmarkers happy.

Offloading¶

The uWSGI offloading subsystem allows you to free your workers as soon as possible when some specific pattern matches and can be delegated to a pure-c thread. Examples are sending static file from the filesystem, transferring data from the network to the client and so on.

Offloading is very complex, but its use is transparent to the end user. If you want to try just add –offload-threads <n> where <n> is the number of threads to spawn (one for cpu is a good value).

When offload threads are enabled, all of the parts that can be optimized will be automatically detected

And now¶

You should already be able to go in production with such few concepts, but uWSGI is an enormous project with hundreds of features and configurations. If you want to be a better sysadmin, continue reading the full docs.

X-Sendfile emulation¶

Even if your frontend proxy/webserver does not support X-Sendfile (or cannot access your static resources) you can emulate it using offloading (your process/thread will delegate the static file serving to offload threads

[uwsgi]
...
; load router_static plugin (compiled in by default in monolithic profiles)
plugins = router_static
; spawn 2 offload threads
offload-threads = 2
; files under /private can be safely served
static-safe = /private
; collect the X-Sendfile response header as X_SENDFILE var
collect-header = X-Sendfile X_SENDFILE
; if X_SENDFILE is not empty, pass its value to the "static" routing action (it will automatically use offloading if available)
response-route-if-not = empty:${X_SENDFILE} static:${X_SENDFILE}

Force HTTPS¶

this will force HTTPS for the whole site

[uwsgi]
...
; load router_redirect plugin (compiled in by default in monolithic profiles)
plugins = router_redirect
route-if-not = equal:${HTTPS};on redirect-permanent:https://${HTTP_HOST}${REQUEST_URI}

and this for /admin

[uwsgi]
...
; load router_redirect plugin (compiled in by default in monolithic profiles)
plugins = router_redirect
route = ^/admin goto:https
; stop the chain
route-run = last:

route-label = https
route-if-not = equal:${HTTPS};on redirect-permanent:https://${HTTP_HOST}${REQUEST_URI}

Python Auto-reloading (DEVELOPMENT-ONLY !!!)¶

In production you can monitor file/directory changes for triggering reloads (touch-reload, fs-reload...).

During development having a monitor for all of the loaded/used python modules can be handy. But please use it only during development.

The check is done by a thread that scans the modules list with the specified frequency:

[uwsgi]
...
py-autoreload = 2

will check for python modules changes every 2 seconds and eventually restart the instance.

Hey, use it only in development...

Installing from a distribution package¶

Installing from source¶

To build uWSGI you need Python and a C compiler (gcc and clang are supported). Depending on the languages you wish to support you will need their development headers. On a Debian/Ubuntu system you can install them (and the rest of the infrastructure required to build software) with:

apt-get install build-essential python

And if you want to build a binary with python/wsgi support (as an example)

apt-get install python-dev

If you have a variant of make available in your system you can simply run make. If you do not have make (or want to have more control) simply run:

python uwsgiconfig.py --build

You can also use pip to install uWSGI (it will build a binary with python support).

# Install the latest stable release:
pip install uwsgi
# ... or if you want to install the latest LTS (long term support) release,
pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz

Or you can use ruby gems (it will build a binary with ruby/rack support).

# Install the latest stable release:
gem install uwsgi

At the end of the build, you will get a report of the enabled features. If something you require is missing, just add the development headers and rerun the build. For example to build uWSGI with ssl and perl regexp support you need libssl-dev and pcre headers.

Alternative build profiles¶

For historical reasons when you run ‘make’, uWSGI is built with Python as the only supported language. You can build customized uWSGI servers using build profiles, located in the buildconf/ directory. You can use a specific profile with:

python uwsgiconfig --build <profile>

Or you can pass it via an environment variable:

UWSGI_PROFILE=lua make
# ... or even ...
UWSGI_PROFILE=gevent pip install uwsgi

Modular builds¶

This is the approach your distribution should follow, and this is the approach you MUST follow if you want to build a commercial service over uWSGI (see below). The vast majority of uWSGI features are available as plugins. Plugins can be loaded using the –plugin option. If you want to give users the maximum amount of flexibility allowing them to use only the minimal amount of resources, just create a modular build. A build profile named “core” is available.

This will build a uWSGi binary without plugins. This is called the “server core”. Now you can start building all of the plugins you need. Check the plugins/ directory in the source distribution for a full list.

python uwsgiconfig.py --plugin plugins/psgi core
python uwsgiconfig.py --plugin plugins/rack core
python uwsgiconfig.py --plugin plugins/python core
python uwsgiconfig.py --plugin plugins/lua core
python uwsgiconfig.py --plugin plugins/corerouter core
python uwsgiconfig.py --plugin plugins/http core
...

Remember to always pass the build profile (‘core’ in this case) as the third argument.

uwsgiconfig.py¶

This is the python script aimed at calling the various compile/link stage.

During 2009, when uWSGI guidelines (and mantra) started to be defined, people agreed that autotools, cmake and friends was not loved by a lot of sysadmins. Albeit they are pretty standardized, the amount of packages needed and the incompatibility between them (expecially in the autotools world) was a problem for a project with fast development/evolution where “compile from sources” was, is and very probably will be the best way to get the best from the product. In addition to this the build procedure MUST BE fast (less than 1 minute on entry level x86 is the main rule)

For such a reason, to compile uWSGI you only need to have a c compiler suite (gcc, clang...) and a python interpreter. Someone could argue that perl could have been a better choice, and maybe it is the truth (it is generally installed by default in lot of operating systems), but we decided to stay with python mainly because when uWSGI started it was a python-only application. (Obviously if you want to develop an alternative build system you are free to do it)

The uwsgiconfig.py basically detects the available features in the system and builds a uwsgi binary (and eventually its plugins) using the so called ‘build profile’

build profiles¶

First example¶

CC and CPP¶

This 2 environment variables for uwsgiconfig.py to use an alternative C compiler and C preprocessor.

If they are not defined the procedure is the following:

For CC -> try to get the CC config_var from the python binary running uwsgiconfig.py, fallback to ‘gcc’

For CPP -> fallback to ‘cpp’

As an example, on a system with both gcc and clang you will end with

CC=clang CPP=clang-cpp python uwsgiconfig.py --build

CPUCOUNT¶

In the spirit of “easy and fast build even on production systems”, uwsgiconfig.py tries to use all of your cpu cores spawning multiple instances of the c compiler (one per-core).

You can override this system using the CPUCOUNT environment variable, forcing the number of detected cpu cores (setting to 1 will disable parallel build).

CPUCOUNT=2 python uwsgiconfig.py --build

UWSGI_FORCE_REBUILD¶

Plugins and uwsgiplugin.py¶

A uWSGI plugin is a shared library exporting the <name>_plugin symbol. Where <name> is the name of the plugin.

As an example the psgi plugin will export the psgi_plugin symbol as well as pypy will export he pypy_plugin symbol and so on.

This symbol is a uwsgi_plugin C struct defining the hooks of the plugin.

When you ask uWSGI to load a plugin it simply calls dlopen() and get the uwsgi_plugin struct via dlsym().

The vast majority of the uWSGI project is developed as a plugin, this ensure a modular approach to configuration and an obviously saner development style.

The sysadmin is free to embed each plugins in the server binary or to build it as an external shared library.

Embedded plugins are defined in the ‘embedded_plugins’ directive of the build profile. You can add more embedded plugins from command line using UWSGI_EMBED_PLUGINS environment variable (see below).

Instead, if you want to build a plugin as a shared library just run uwsgiconfig.py with the –plugin option

python uwsgiconfig.py --plugin plugins/psgi

this will build the plugin in plugins/psgi to the psgi_plugin.so file

To specify a build profile when you build a plugin you can pass it as additional argument

python uwsgiconfig.py --plugin plugins/psgi mybuildprofile

UWSGI_INCLUDES¶

• this has been added in 1.9.13

On startup, the CPP binary is run to detect default include paths. You can add more paths using the UWSGI_INCLUDES environment variable

UWSGI_INCLUDES=/usr/local/include,/opt/dev/include python uwsgiconfig.py --build

UWSGI_EMBED_PLUGINS¶

UWSGI_EMBED_CONFIG¶

allows embedding the specified .ini file in the server binary (currently Linux only)

On startup the server parses the embedded file as soon as possible.

Custom options defined in the embedded config will be available as standard ones.

UWSGI_BIN_NAME¶

CFLAGS and LDFLAGS¶

UWSGICONFIG_* for plugins¶

libuwsgi.so¶

uwsgibuild.log¶

uwsgibuild.lastcflags¶

cflags and uwsgi.h magic¶

embedding files¶

The fake make¶

Starting the server¶

Starting an uWSGI server is the role of the system administrator, like starting the Web server. It should not be the role of the Web server to start the uWSGI server – though you can also do that if it fits your architecture.

How to best start uWSGI services as boot depends on the operating system you use.

On modern systems the following should hold true. On “classic” operating systems you can use init.d/rc.d scripts, or tools such as Supervisor, Daemontools or inetd/xinetd.

Signals for controlling uWSGI¶

You can instruct uWSGI to write the master process PID to a file with the pidfile option.

The uWSGI server responds to the following signals.

Reloading the server¶

When running with the master process mode, the uWSGI server can be gracefully restarted without closing the main sockets.

This functionality allows you patch/upgrade the uWSGI server without closing the connection with the web server and losing a single request.

When you send the SIGHUP to the master process it will try to gracefully stop all the workers, waiting for the completion of any currently running requests.

Then it closes all the eventually opened file descriptor not related to uWSGI.

Lastly, it binary patches (using execve()) the uWSGI process image with a new one, inheriting all of the previous file descriptors.

The server will know that it is a reloaded instance and will skip all the sockets initialization, reusing the previous ones.

There are several ways to make uWSGI gracefully restart.

# using kill to send the signal
kill -HUP `cat /tmp/project-master.pid`
# or the convenience option --reload
uwsgi --reload /tmp/project-master.pid
# or if uwsgi was started with touch-reload=/tmp/somefile
touch /tmp/somefile

Or from your application, in Python:

uwsgi.reload()

Or in Ruby,

UWSGI.reload

Stopping the server¶

If you have the uWSGI process running in the foreground for some reason, you can just hit CTRL+C to kill it off.

When dealing with background processes, you’ll need to use the master pidfile again. The SIGINT signal will kill uWSGI.

kill -INT `cat /tmp/project-master.pid`
# or for convenience...
uwsgi --stop /tmp/project-master.pid

The Master FIFO¶

Starting from uWSGI 1.9.17 a new management system has been added using unix named pipes (fifo): The Master FIFO

Cherokee¶

The Cherokee webserver officially supports uWSGI. Cherokee is fast and lightweight, has a beautiful admin interface and a great community. Their support for uWSGI has been awesome since the beginning and we recommend its use in most situations. The userbase of the Cherokee uWSGI handler is probably the biggest of all. The Cherokee uWSGI handler is commercially supported by Unbit.

Nginx¶

The uWSGI module is included in the official Nginx distribution since version 0.8.40. A version supporting Nginx 0.7.x is maintained in the uWSGI package.

This is a stable handler commercially supported by Unbit.

Apache¶

The Apache2 mod_uwsgi module was the first web server integration module developed for uWSGI. It is stable but could be better integrated with the Apache API.

It is commercially supported by Unbit.

Since uWSGI 0.9.6-dev a second Apache2 module called mod_Ruwsgi is included. It’s more Apache API friendly. mod_Ruwsgi is not commercially supported by Unbit.

During the 1.2 development cycle, another module called mod_proxy_uwsgi has been added. In the near future this should be the best choice for Apache based deployments.

Mongrel2¶

Support for the Mongrel2 Project has been available since 0.9.8-dev via the ZeroMQ protocol plugin.

In our tests Mongrel2 survived practically all of the loads we sent.

Very good and solid project. Try it :)

Lighttpd¶

This module is the latest developed, but its inclusion in the official Lighttpd distribution has been rejected, as the main author considers the uwsgi protocol a “reinventing the wheel” technology while suggesting a FastCGI approach. We respect this position. The module will continue to reside in the uWSGI source tree, but it is currently unmaintained.

There is currently no commercial support for this handler. We consider this module “experimental”.

Twisted¶

This is a “commodity” handler, useful mainly for testing applications without installing a full web server. If you want to develop an uWSGI server, look at this module. Twisted.

Tomcat¶

The included servlet can be used to forward requests from Tomcat to the uWSGI server. It is stable, but currently lacks documentation.

There is currently no commercial support for this handler.

CGI¶

The CGI handlers are for “lazy” installations. Their use in production environments is discouraged.

Why should I choose uWSGI?¶

Because you can! :) uWSGI wants to be a complete web application deployment solution with batteries included:

• ProcessManagement
• Management of long-running tasks
• uWSGI RPC Stack
• Clustering
• LoadBalancing
• Monitoring
• ResourceLimiting

... and many other annoying everyday tasks that you’d have to delegate to external scripts and manual sysadmin tasks.

If you are searching for a simple server for your WSGI, PSGI or Rack app, uWSGI may not be for you. Though, if you are building an app which needs to be rock solid, fast, and easy to distribute and optimize for various loads, you will most likely find yourself needing uWSGI.

The best definition for uWSGI is “Swiss Army Knife for your network applications”.

What about the protocol?¶

The uwsgi (all lowercase) protocol is derived from SCGI but with binary string length representations and a 4-byte header that includes the size of the var block (16 bit length) and a couple of general-purpose bytes. We are not reinventing the wheel. Binary management is much easier and cheaper than string parsing, and every single bit of power is required for our projects. If you need proof, look at the official protocol documentation and you will understand why a new protocol was needed. Obviously, you are free to use the other supported protocols. Remember, if you cannot use uWSGI in some scenario, it is a uWSGI bug.

Can I use it in cluster environments?¶

Yes, this is one of the main features of the uWSGI stack. You can have multiple instances bound on different servers, and using the load balancing facilities of your webserver/proxy/router you can distribute your load. Systems like uWSGI RPC Stack allows you to fast call functions on remote nodes, and The uWSGI Legion subsystem allows you to elect a master in a multi-node setup.

So, why all those timeout configuration flags?¶

Choosing sane timeouts is the key to high availability. Do not trust network applications that do not permit you to choose a timeout.

I need help! What do I do?¶

Post a message on the uWSGI mailing list including your

• Operating system version
• CPU architecture
• Webserver used (if any)
• uWSGI version
• uWSGI command line or config files

You should add the –show-config option and post the output in the message. It will be very useful for finding out just what’s wrong with your uWSGI. You can also rebuild uWSGI with debug symbols and run it under a debugger like gdb.

uWSGI is an enormous project with hundreds of options. You should be prepared that not everything will go right at the first shot. Ask for help, ask for help and ask for help. If you are frustrated, do not waste time blaming and ranting - instead simply join the list and ask for help. This is open source, if you only rant you are doing nothing useful.

I am not a sysadmin, nor a UNIX guru. Can I use uWSGI?¶

That’s a good question :) But sadly there is no simple answer. uWSGI has not been developed with simplicity in mind, but with versatility. You can try it by starting with one of the quickstarts and if you have problems, simply ask for help in the list or on the IRC channel.

How can I buy commercial support for my company?¶

Send an email to info at unbit.it with the word “uWSGI” in the subject. The email you send should include your company information and your specific request. We will reply as soon as possible.

Will this allow me to run my awesome apps on my ancient close-minded ISP?¶

Probably not. The uWSGI server requires a modern platform/environment.

Where are the benchmarks?¶

Sorry, we only do “official” benchmarks for regression testing. If benchmarks are very important to you, you can search on the mailing list, make your own benchmarks or search on Google. uWSGI gives precedence to machine health, so do not expect that your ab test with an unrealistic number of concurrent connections will be managed flawlessly without tuning. Some socket and networking knowledge is required if you want to make a valid benchmark (and avoid geek rage in your blog comments ;). Also remember that uWSGI can be run in various modes, so avoid comparing it configured in preforking mode with another server in non-blocking/async mode if you do not want to look ridiculous.

Ha! Server XXX is faster than uWSGI! Take that!¶

As already stated uWSGI is not a silver bullet, it is not meant to be liked by the whole world and it is obviously not the fastest server out there. It is a piece of software following an “approach” to problems you may not like or that you may conversely love. The approach taken will work better for certain cases than others, and each application should be analyzed on it’s own merits using appropriate and accruate real-world benchmarks.

What is ‘Harakiri mode’?¶

At Unbit we host hundreds of unreliable web apps on our servers. All of them run on hardly constrained (at kernel level) environments where having processes block due to an implementation error will result on taking down an entire site. The harakiri mode has two operational modes:

• one that we define as “raw and a bit unreliable” (used for simple setup without a process manager)
• and another one that we define as “reliable” that depends on the presence of the uWSGI process manager (see ProcessManagement).

The first one sets a simple alarm at the start of every request. If the process gets a SIGALRM signal, it terminates itself. We call this unreliable, because your app or some module you use could overwrite or simply cancel the alarm with a simple call to alarm().

The second one uses a master process shared memory area (via mmap) that maintains statistics on every worker in the pool. At the start of every request, the worker sets a timestamp representing the time after the process will be killed in its dedicated area. This timestamp is zeroed after every successful request. If the master process finds a worker with a timestamp in the past it will mercilessly kill it.

Will my app run faster with uWSGI?¶

It’s unlikely. The biggest bottleneck in web app deployment is the application itself. If you want a faster environment, optimize your code or use techniques such as clustering or caching. We say that uWSGI is fast because it introduces a very little overhead in the deployment structure.

What are the most important options for performance and robustness in the uWSGI environment?¶

By default, uWSGI is configured with sane “almost-good-for-all” values. But if and when things start going wild, tuning is a must.

• Increasing (or decreasing) timeout is important, as is modifying the socket listen queue size.
• Think about threading. If you do not need threads, do not enable them.
• If you are running only a single application you can disable multiple interpreters.
• Always remember to enable the master process in production environments. See ProcessManagement.
• Adding workers does not mean “increasing performance”, so choose a good value for the workers option based on the nature of your app (IO bound, CPU bound, IO waiting...)

Why not simply use HTTP as the protocol?¶

A good question with a simple answer: HTTP parsing is slow, really slow. Why should we do a complex task twice? The web server has already parsed the request! The uwsgi protocol is very simple to parse for a machine, while HTTP is very easy to parse for a human. As soon as humans are being used as servers, we will abandon the uwsgi protocol in favor of the HTTP protocol. All this said, you can use uWSGI via Native HTTP support, FastCGI, ZeroMQ and other protocols as well.

Why do you support multiple methods of configuration?¶

System administration is all about skills and taste. uWSGI tries to give sysadmins as much choice as possible for integration with whatever infrastructure already available. Having multiple methods of configuration is just one way we achieve this.

What is the best webserver handler?¶

See Web server integration.

Loading configuration files¶

uWSGI supports loading configuration files over several methods other than simple disk files:

uwsgi --ini http://uwsgi.it/configs/myapp.ini # HTTP
uwsgi --xml - # standard input
uwsgi --yaml fd://0 # file descriptor
uwsgi --json 'exec://nc 192.168.11.2:33000' # arbitrary executable

Magic variables¶

uWSGI configuration files can include “magic” variables, prefixed with a percent sign. Currently the following magic variables (you can access them in Python via uwsgi.magic_table) are defined.

Note that most of these refer to the file they appear in, even if that file is included from another file.

An exception are most of the uppercase versions, which refer to the first non-template config file loaded. This means the first config file not loaded through --include or --inherit, but through for example --ini, --yaml or --config. These are intended to use with the emperor, to refer to the actual vassal config file instead of templates included with --vassals-include or --vassals-inherit.

For example, here’s funnyapp.ini.

[uwsgi]
socket = /tmp/%n.sock
module = werkzeug.testapp:test_app
processes = 4
master = 1

%n will be replaced with the name of the config file, sans extension, so the result in this case will be

[uwsgi]
socket = /tmp/funnyapp.sock
module = werkzeug.testapp:test_app
processes = 4
master = 1

Placeholders¶

Placeholders are custom magic variables defined during configuration time by setting a new configuration variable of your own devising.

[uwsgi]
; These are placeholders...
my_funny_domain = uwsgi.it
set-ph = max_customer_address_space = 64
set-placeholder = customers_base_dir = /var/www
; And these aren't.
socket = /tmp/sockets/%(my_funny_domain).sock
chdir = %(customers_base_dir)/%(my_funny_domain)
limit-as = %(max_customer_address_space)

Placeholders can be assigned directly, or using the set-placeholder / set-ph option. These latter options can be useful to:

• Make it more explicit that you’re setting placeholders instead of regular options.
• Set options on the commandline, since unknown options like --foo=bar are rejected but --set-placeholder foo=bar is ok.
• Set placeholders when strict mode is enabled.

Placeholders are accessible, like any uWSGI option, in your application code via uwsgi.opt.

import uwsgi
print uwsgi.opt['customers_base_dir']

This feature can be (ab)used to reduce the number of configuration files required by your application.

Similarly, contents of evironment variables and external text files can be included using the @(file_name) and $(ENV_VAR) syntax. See also How uWSGI parses config files.

Placeholders math (from uWSGI 1.9.20-dev)¶

You can apply math formulas to placeholders using this special syntax:

[uwsgi]
foo = 17
bar = 30
; total will be 50
total = %(foo + bar + 3)

Remember to not miss spaces between operations.

Operations are executed in a pipeline (not in common math style):

[uwsgi]
foo = 17
bar = 30
total = %(foo + bar + 3 * 2)

‘total’ will be evaluated as 100:

(((foo + bar) + 3) * 2)

Incremental and decremental shortcuts are available

[uwsgi]
foo = 29
; remember the space !!!
bar = %(foo ++)

bar will be 30

If you do not specify an operation between two items, ‘string concatenation’ is assumed:

[uwsgi]
foo = 2
bar = 9
; remember the space !!!
bar = %(foo bar ++)

the first two items will be evaluated as ‘29’ (not 11 as no math operation has been specified)

Command line arguments¶

Example:

uwsgi --socket /tmp/uwsgi.sock --socket 127.0.0.1:8000 --master --workers 3

Environment variables¶

When passed as environment variables, options are capitalized and prefixed with UWSGI_, and dashes are substituted with underscores.

Example:

UWSGI_SOCKET=127.0.0.1 UWSGI_MASTER=1 UWSGI_WORKERS=3 uwsgi

INI files¶

.INI files are a standard de-facto configuration format used by many applications. It consists of [section]``s and ``key=value pairs.

An example uWSGI INI configuration:

[uwsgi]
socket = /tmp/uwsgi.sock
socket = 127.0.0.1:8000
workers = 3
master = true

By default, uWSGI uses the [uwsgi] section, but you can specify another section name while loading the INI file with the syntax filename:section, that is:

uwsgi --ini myconf.ini:app1

Alternatively, you can load another section from the same file by omitting the filename and specifying just the section name. Note that technically, this loads the named section from the last .ini file loaded instead of the current one, so be careful when including other files.

[uwsgi]
# This will load the app1 section below
ini = :app1
# This will load the defaults.ini file
ini = defaults.ini
# This will load the app2 section from the defaults.ini file!
ini = :app2

[app1]
plugin = rack

[app2]
plugin = php

• Whitespace is insignificant within lines.
• Lines starting with a semicolon (;) or a hash/octothorpe (#) are ignored as comments.
• Boolean values may be set without the value part. Simply master is thus equivalent to master=true. This may not be compatible with other INI parsers such as paste.deploy.
• For convenience, uWSGI recognizes bare .ini arguments specially, so the invocation uwsgi myconf.ini is equal to uwsgi --ini myconf.ini.

XML files¶

The root node should be <uwsgi> and option values text nodes.

An example:

<uwsgi>
  <socket>/tmp/uwsgi.sock</socket>
  <socket>127.0.0.1:8000</socket>
  <master/>
  <workers>3</workers>
</uwsgi>

You can also have multiple <uwsgi> stanzas in your file, marked with different id attributes. To choose the stanza to use, specify its id after the filename in the xml option, using a colon as a separator. When using this id mode, the root node of the file may be anything you like. This will allow you to embed uwsgi configuration nodes in other XML files.

<i-love-xml>
  <uwsgi id="turbogears"><socket>/tmp/tg.sock</socket></uwsgi>
  <uwsgi id="django"><socket>/tmp/django.sock</socket></uwsgi>
</i-love-xml>

• Boolean values may be set without a text value.
• For convenience, uWSGI recognizes bare .xml arguments specially, so the invocation uwsgi myconf.xml is equal to uwsgi --xml myconf.xml.

JSON files¶

The JSON file should represent an object with one key-value pair, the key being “uwsgi” and the value an object of configuration variables. Native JSON lists, booleans and numbers are supported.

An example:

{"uwsgi": {
  "socket": ["/tmp/uwsgi.sock", "127.0.0.1:8000"],
  "master": true,
  "workers": 3
}}

Again, a named section can be loaded using a colon after the filename.

{"app1": {
  "plugin": "rack"
}, "app2": {
  "plugin": "php"
}}

And then load this using:

uwsgi --json myconf.json:app2

YAML files¶

The root element should be uwsgi. Boolean options may be set as true or 1.

An example:

uwsgi:
  socket: /tmp/uwsgi.sock
  socket: 127.0.0.1:8000
  master: 1
  workers: 3

Again, a named section can be loaded using a colon after the filename.

app1:
  plugin: rack
app2:
  plugin: php

And then load this using:

uwsgi --yaml myconf.yaml:app2

SQLite configuration¶

LDAP configuration¶

LDAP is a flexible way to centralize configuration of large clusters of uWSGI servers. Configuring it is a complex topic. See Configuring uWSGI with LDAP for more information.

Simple case¶

A very common problem is screwing-up the port on which the instance is listening.

To emulate this kind of error we try to bind on port 80 as unprivileged user:

uwsgi --uid 1000 --http-socket :80

uWSGI will exit with:

bind(): Permission denied [core/socket.c line 755]

Internally (from the kernel point of view) the instance exited with status 1

Now we want to allow the instance to automatically bind on port 8080 when the user supplied config fails.

Let’s define a fallback config (you can save it as safe.ini):

[uwsgi]
print = Hello i am the fallback config !!!
http-socket = :8080
wsgi-file = welcomeapp.wsgi

Now we can re-run the (broken) instance:

uwsgi --fallback-config safe.ini --uid 1000 --http-socket :80

Your error will be now something like:

bind(): Permission denied [core/socket.c line 755]
Thu Jul 25 21:55:39 2013 - !!! /home/roberto/uwsgi/uwsgi (pid: 7409) exited with status 1 !!!
Thu Jul 25 21:55:39 2013 - !!! Fallback config to safe.ini !!!
[uWSGI] getting INI configuration from safe.ini
*** Starting uWSGI 1.9.15-dev-a0cb71c (64bit) on [Thu Jul 25 21:55:39 2013] ***
...

as you can see the instance has detected the exit code 1, and binary patched itself with a new one (without changing the pid, or calling fork())

Broken apps¶

Another common problem is the inhability to load an application, but instead bringing down the whole site we want to load an alternate application:

uwsgi --fallback-config safe.ini --need-app --http-socket :8080 --wsgi-file brokenapp.py

Here the key is –need-app. It will call exit(1) if the instance has not been able to load at least one application.

Multiple fallback levels¶

Your fallback config file can specify a fallback-config directive too, allowing multiple fallback levels. BEWARE OF LOOPS !!!3

How it works¶

The objective is catching the exit code of a process before the process itself is destroyed (we do not want to call another fork(), or destroy already opened file descriptors)

uWSGI makes heavy usage of atexit() hooks, so we only need to register the fallback handler as the first one (hooks are executed in reverse order).

In addition to this we need to get the exit code in our atexit() hook, something is not supported by default (the on_exit() function is now deprecated).

The solution is “patching” exit(x) with uwsgi_exit(x) that is a simple wrapper setting uwsgi.last_exit_code memory pointer.

Now the hook only needs to check for uwsgi.last_exit_code == 1 and eventually execve() the binary again passing the fallback config to it

char *argv[3];
argv[0] = uwsgi.binary_path;
argv[1] = uwsgi.fallback_config;
argv[2] = NULL;
execvp(uwsgi.binary_path, argv);

Notes¶

Try to place –fallback-config as soon as possibile in your config tree. The various config parsers may fail (calling exit(1)) before the fallback file is registered

for¶

For iterates over space-separated strings. The following three code blocks are equivalent.

[uwsgi]
master = true
; iterate over a list of ports
for = 3031 3032 3033 3034 3035
socket = 127.0.0.1:%(_)
endfor =
module = helloworld

<uwsgi>
  <master/>
  <for>3031 3032 3033 3034 3035</for>
    <socket>127.0.0.1:%(_)</socket>
  <endfor/>
  <module>helloworld</module>
</uwsgi>

uwsgi --for="3031 3032 3033 3034 3035" --socket="127.0.0.1:%(_)" --endfor --module helloworld

Note that the for-loop is applied to each line inside the block separately, not to the block as a whole. For example, this:

[uwsgi]
for = a b c
socket = /var/run/%(_).socket
http-socket = /var/run/%(_)-http.socket
endfor =

is expanded to:

[uwsgi]
socket = /var/run/a.socket
socket = /var/run/b.socket
socket = /var/run/c.socket
http-socket = /var/run/a-http.socket
http-socket = /var/run/b-http.socket
http-socket = /var/run/c-http.socket

if-env¶

Check if an environment variable is defined, putting its value in the context placeholder.

[uwsgi]
if-env = PATH
print = Your path is %(_)
check-static = /var/www
endif =
socket = :3031

if-exists¶

Check for the existence of a file or directory. The context placeholder is set to the filename found.

[uwsgi]
http = :9090
; redirect all requests if a file exists
if-exists = /tmp/maintainance.txt
route = .* redirect:/offline
endif =

if-file¶

Check if the given path exists and is a regular file. The context placeholder is set to the filename found.

<uwsgi>
  <plugins>python</plugins>
  <http-socket>:8080</http-socket>
  <if-file>settings.py</if-file>
    <module>django.core.handlers.wsgi:WSGIHandler()</module>
  <endif/>
</uwsgi>

if-dir¶

Check if the given path exists and is a directory. The context placeholder is set to the filename found.

uwsgi:
  socket: 4040
  processes: 2
  if-file: config.ru
  rack: %(_)
  endif:

if-opt¶

Check if the given option is set, or has a given value. The context placeholder is set to actual value of the option reference.

To check if an option was set, pass just the option name to if-opt.

uwsgi:
  cheaper: 3
  if-opt: cheaper
  print: Running in cheaper mode, with initially %(_) processes
  endif:

To check if an option was set to a specific value, pass option-name=value to if-opt.

uwsgi:
  # Set busyness parameters if it was chosen
  if-opt: cheaper-algo=busyness
  cheaper-busyness-max: 25
  cheaper-busyness-min: 10
  endif:

Due to the way uWSGI parses its configs, you can only refer to options that uWSGI has previously seen. In particular, this means:

• Only options that are set above the if-opt option are taken into account. This includes any options set by previous include (or type specific includes like ini) options, but does not include options set by previous inherit options).

• if-opt is processed after expanding magic variables, but before expanding placeholders and other variables. So if you use if-opt to compare the value of an option, check against the value as stated in the config file, with only the magic variables filled in.

  If you use the context placeholder %(_) inside the if-opt block, you should be ok: any placeholders will later be expanded.

• If an option is specified multiple times, only the value of the first one will be seen by if-opt.

• Only explicitely set values will be seen, not implicit defaults.

Networking/sockets¶

Process Management¶

Process Management - Emperor¶

Process Management - Zerg¶

Debugging¶

Configuration¶

Config logic¶

Logging¶

Alarms¶

uWSGI Process¶

Miscellaneous¶

/usr/bin/uwsgi --workers 4 --worker-exec /usr/bin/php53-cgi

[uwsgi]
master = true
attach-daemon = memcached

Locks¶

Cache¶

Queue¶

Spooler¶

Mules¶

Application loading¶

Request handling¶

/upload?X-Progress-ID=550e8400-e29b-41d4-a716-446655440000

{"state": "uploading", "received": 170000, "size": 300000}

Clustering¶

Subscriptions¶

Router¶

Static files¶

Clocks¶

Loop engines¶

Greenlet¶

Gevent¶

Stackless¶

uGreen¶

Fiber¶

CoroAE¶

tornado¶

Carbon¶

CGI¶

Busyness Cheaper algorithm¶

Erlang¶

Fastrouter¶