Gunicorn is one of many WSGI server implementations, but it's particularly important because it is a stable, commonly-used part of web app deployments that's powered some of the largest Python-powered web applications in the world, such as Instagram.
Gunicorn implements the PEP3333 WSGI server standard specification so that it can run Python web applications that implement the application interface. For example, if you write a web application with a web framework such as Django, Flask or Bottle, then your application implements the WSGI specification.
Gunicorn knows how to run a web application based on the hook between the WSGI server and the WSGI-compliant web app.
Here is an example of a typical Django web application and how it is run by Gunicorn. We'll use the django_defaults as an example Django project. Within the django_defaults project subdirectory, there is a short wsgi.py file with the following contents:
""" WSGI config for django_defaults project. It exposes the WSGI callable as a module-level variable named ``application``. For more information on this file, see https://docs.djangoproject.com/en/1.8/howto/deployment/wsgi/ """ import os from django.core.wsgi import get_wsgi_application os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_defaults.settings") application = get_wsgi_application()
wsgi.py file was generated by the
django-admin.py startproject command
when the Django project was first created. Django exposes an
variable via that
wsgi.py file so that a WSGI server can use
as a hook for running the web app. Here's how the situation looks visually:
Gunicorn is based on a pre-fork worker model, compared to a worker model architecture. The pre-work worker model means that a master thread spins up workers to handle requests but otherwise does not control how those workers perform the request handling. Each worker is independent of the controller.
There are three framework-specific posts on the Full Stack Python blog for configuring Gunicorn for development on Ubuntu:
gunicorn as your Django development server is a short post with a few good tips on using Gunicorn for local application development.
The Full Stack Python Guide to Deployments provides detailed step-by-step instructions for deploying Gunicorn as part of an entire Python web application deployment.
The answers to the question "what's the best practice for running Django with Gunicorn?" provide some nuance for how Gunicorn should be invokin the callable application variable provided by Django within a deployment.
How to Install Django with Gunicorn and Nginx on FreeBSD 10.2 is a tutorial for FreeBSD, which is not often used in walkthroughs compared to the frequency that Ubuntu and CentOS tutorials appear.
How to make a Scalable Python Web App using Flask, Gunicorn, NGINX on Ubuntu 14.04 and Deploy a Flask App on Ubuntu both provide steps for setting up a Flask web app using Gunicorn. There isn't much explanation provided with each tutorial but they can still be good concise references in case you're having issues with Ubuntu.
Deploying a Flask Site Using Nginx, Gunicorn, Supervisor and Virtualenv on Ubuntu is a similar tutorial to the previous two links. It provides some good screenshots along the way with what to expect while you are configuring the deployment server.
Set up Django, Nginx and Gunicorn in a Virtualenv controled by Supervisor is a GitHub Gist with some great explanations for why we're setting up virtualenv and what to watch out for while you're doing the deployment.
The Gunicorn design document is worth reading because it describes the server model and gives some context on how to choose the number of workers for your execution environment.