Configuring a single Nginx + uWSGI server to serve multiple Flask apps
Someone on the Flask mailing list asked how to serve multiple Flask apps via uWSGI + Nginx. Anytime you’re working with uWSGI there are multiple ways to do things, but here’s how I do things for RockClimbing.com. I spent several days reading the uWSGI docs + various blog posts around the net, so this should be reasonably correct.
This example shows how to serve multiple Flask apps where each app has its own domain name. If you want to mount multiple Flask apps under a single domain name, see this example in the Flask docs (the pull request hasn’t been merged yet as of time of this writing).
In general, use the uWSGI Emperor, even if you’re only running a single Flask app. The Emperor is a master process that watches over the app(s) to make sure everything is running correctly. Each child app is called a ‘vassal’. If for some reason an app/vassal crashes, then the Emperor will reload it. A number of older blog posts recommend managing your uWSGI apps with supervisord… use the Emperor instead because it offers extra benefits like automatically reloading the app/vassal if you make changes to the vassal’s uWSGI config file.
Create a very basic uWSGI Emperor config called /etc/uwsgi/emperor.ini:
|
1 2 |
[uwsgi] emperor = /etc/uwsgi/vassals |
If you want to pass a particular option to all vassals, you can specify the option in the emperor.ini file using the vassal-set parameter.
Create a simple vassal config file in /etc/uwsgi/vassals/app_name.ini. By default, the config file name will be used for the vassal process name. I manage my vassals using Ansible, so this config has several Jinja2 variables that look like {{ variable }}. Just manually replace those with what you need.
You can bind the app to either a TCP socket or a Unix socket. Just make sure Nginx is passing requests to the same socket that the vassal is listening on.
For security, specify a non-root Linux user/group for the vassal to run under. Typically you’ll run each vassal as a separate user/group, and then run the Emperor as root so it can start each app process and then drop privileges before actually serving requests.
Since we’re walking through how to run multiple Flask apps, you’ll want to run each under a separate virtualenv to avoid package conflicts. For example, if one Flask app requires sqlalchemy 0.8 and another requires sqlalchemy 0.9, they’ll need to be in separate virtualenvs. uWSGI makes it easy to specify which virtualenv to run the vassal under by passing the virtualenv parameter.
For Flask, typically the callable is app, and the module is the filename where app is defined. You’ll also need to tell uWSGI to cd to the path of the Flask app before trying to import module.
Lastly, if you do any googling about how to scale Flask + uWSGI, you’ll hit a blog post by David Cramer where he found it better to running multiple uWSGI instances and have Nginx handle the load balancing. The thundering herd problem that David experienced is better solved by setting thunder-lock = true in your vassal config (or set it globally for all vassals in your emperor.ini config). It’s better to let uWSGI handle the load balancing rather than Nginx because Nginx doesn’t know which uWSGI processes are busy and just round-robins through them when it sends requests. If instead you let uWSGI handle the load balancing, it will intelligently pass requests to the processes that are free. If you’re wondering why thunder-lock = true isn’t enabled by default, see this note in the uWSGI help docs.
There’s also a number of options commented out–those are simply reminders to myself that those options exist, but I don’t currently use them.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 |
[uwsgi] socket = 127.0.0.1:3031 # for unix sockets, see `chmod-socket` and `chown-socket` stats = 127.0.0.1:9191 # use with uwsgitop: # http://uwsgi-docs.readthedocs.org/en/latest/StatsServer.html logto = /var/log/uwsgi/%n.log uid = {{ api_rc_flask_linux_user }} gid = {{ api_rc_flask_linux_user }} binary-path = /usr/bin/uwsgi virtualenv = {{ api_rc_flask_virtualenv }} chdir = {{ api_rc_flask_path }} module = manage callable = app processes = 2 threads = 4 # to dynamically scale workers see: # http://uwsgi-docs.readthedocs.org/en/latest/Cheaper.html enable-threads = true thunder-lock = true # http://uwsgi-docs.readthedocs.org/en/latest/OffloadSubsystem.html offload-threads = 1 # one per CPU is a basic start # harakiri = 30 # respawn processes after serving 5000 requests (avoid memory leaks) max-requests = 5000 # clear environment on exit # vacuum = true # checks python modules every N seconds for changes and autoreloads # useful in development, avoid in production # {% if py_autoreload is defined %} # py-autoreload = 2 # {% endif %} # limit-as = 512 # ?? for monitoring memory? # From the uWSGI mailing list: # 30-40 MB per worker is pretty normal. # # To gain memory you can move to multithreading: # # master = true # processes = 2 # threads = 2 # thread-stacksize = 512 # # should be good enough. Monitoring memory is a good thing, # use --reload-on-rss 80 to avoid your app growing up |
At this point, test that the Emperor starts and correctly loads the vassals by running uwsgi --emperor /etc/uwsgi/emperor.ini. In production, I use systemd to manage the Emperor–the uWSGI docs have an excellent example systemd config file.
Next you need to configure Nginx to pass requests to the proper socket. Here’s an extremely simple Nginx config showing the server and location blocks. I run something a bit more complex in production, but this is easier to understand:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
# Very useful: # https://www.digitalocean.com/community/tutorials/understanding-nginx-server-and-location-block-selection-algorithms # http://blog.martinfjordvald.com/2012/08/understanding-the-nginx-configuration-inheritance-model/ server { listen 80; listen [::]:80; #listen 443 ssl; server_name api.example.com; # Static files should be served through nginx... # for simplicity, can handle authentication in Flask as long as X-Sendfile # header enabled so Flask generates url, then offloads data streaming to Nginx: # http://mattspitz.me/2013/11/20/serving-authenticated-media-with-nginx.html # root /srv/example.com/static/; access_log /var/log/nginx/api_access.log combined buffer=32k; # TODO syslog and logrotate policy error_log /var/log/nginx/api_error.log; # TODO syslog and logrotate policy location / { include uwsgi_params; uwsgi_pass 127.0.0.1:3031; } } |
Feel free to ask questions or suggest improvements in the comments.
Hi Jeff, thank you for the post! I’m using uwsgi’s emperor mode to serve a big number of apps. I would like to scale it down by keeping a limited number of processes while serving all the instances, like what mod_wsgi does with WSGIDaemonProcess and the processes parameter. Do you have any tip to do it?
Nothing springs to mind immediately. You’re probably better off writing a question on StackOverflow with a more detailed description of the problem.