Gunicorn Python WSGI HTTP Server for UNIX

Gunicorn

The gunicorn is a python web server gateway interface (WSGI) HTTP server. WSGI is a simple calling convention for web servers  to forward requests to web application or frameworks written in the Python programming language.

In late 1990’s a appache module called mod_python is used to run most python web applications. But is not a standard specification, it was an implemetation that allowed python code to run on a server. Also some development stalled and security vulnerability were discovered. Therefore the python community introduce WSGI a standard interface that modules and containers could implement.

 

Server Model

• Central Master Process to manage the workers
• Requests are handled by worker processes
• Components
• Master
• Sync Workers
• Async Workers
• Tornado Workers
• AsyncIO Worker

Features

Natively supports WSGI web2py, Django and Paster

•  Worker process management
• Simple Python configuration
• Multiple worker configurations
• Various server hooks for extensibility
• Compatible with Python 2.6+ and Python 3.2+

Installation of gunicorn

$ pip install gunicorn

Basic usage:

$ gunicorn [OPTIONS] APP_MODULE

where app module is the pattern of module name and variable name.

Deployment

Gunicorn is a WSGI a HTTP server,

take an example of nginx HTTP proxy server.

server {
    listen 80;
    server_name example.org;
    access_log  /var/log/nginx/example.log;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
  }

A flask application with Gunicorn and nginx on ubuntu 18.04

STEP 1 : Install the components from Ubuntu repositories

update local packages and  build python environment

sudo apt update

sudo apt install python3-pip python3-dev build-essential libssl-dev libffi-dev python3-setuptools

STEP 2 : Creating python virtual environment

sudo apt install python3-venv

Make a parent directory for  Flask project. Move into the directory after you create it.

mkdir ~/myproject
cd ~/myproject

Next Create a virtual environment to store your Flask project's Python requirements.

python3.6 -m venv myprojectenv

Before installing applications within the virtual environment, you need to activate it.

source myprojectenv/bin/activate

 

STEP 3 : Setting up a flask application

Now that you are in your virtual environment, you can install Flask and Gunicorn and get started on designing your application.

Install wheel with the local instance of pip to ensure that our packages will install even if they are missing wheel archives.

$ pip install wheel

Install Flask and Gunicorn:

(myprojectenv) $ pip install gunicorn flask

 

Creating a Sample App

Create flask app in a single file myproject.py

(myprojectenv) $ vim ~/myproject/myproject.py

sudo apt-get -y upgrade

from flask import Flask

app = Flask(__name__)

@app.route("/")

def hello():

    return "<h1 style='color:blue'>Hello There!</h1>"

if __name__ == "__main__":

    app.run(host='0.0.0.0')

Save the file.

Create a file wsgi.py this file tell to gunicorn server how to interact with he application.

(myprojectenv) nano ~/myproject/wsgi.py

from myproject import app

if __name__ == "__main__":
    app.run()

Step 4 — Configuring Gunicorn

Specify the interface and port to bind to so that the application will be started on a publicly available interface:

cd ~/myproject
gunicorn --bind 0.0.0.0:5000 wsgi:app

Visit your server's IP address with :5000 appended to the end in your web browser :

http://your_server_ip:5000

Then stop the process and Deactivate it.

(myprojectenv) $ deactive

 

 Create the systemd service unit file

Allow Ubuntu's init system to automatically start Gunicorn and serve the Flask application whenever the server boots.

sudo nano /etc/systemd/system/myproject.service

[Unit]
Description=Gunicorn instance to serve myproject
After=network.target
[Service]

User=user
Group=www-data
WorkingDirectory=/home/user/myproject
Environment="PATH=/home/user/myproject/myprojectenv/bin"
ExecStart=/home/user/myproject/myprojectenv/bin/gunicorn --workers 3 --bind unix:myproject.sock -m 007 wsgi:app

[Install]
WantedBy=multi-user.target

In this file a [unit] section which is used to specify metadata and dependencies and init system to only start this after the networking target has been reached.

In [service] section specify the user and group and give group ownership to the www-data group so that Nginx can communicate easily with the Gunicorn processes.

Map out the working directory and set the PATH environmental variable so that the init system knows that the executables for the process are located within our virtual environment.

Finally add [install] section This will tell systemd what to link this service to if we enable it to start at boot.

We can now start the Gunicorn service we created and enable it so that it starts at boot:

sudo systemctl start myproject

sudo systemctl enable myproject

 

STEP 5 : Configuring Nginx to Proxy Requests

Now configure Nginx to pass web requests to that socket by making some small additions to its configuration file.

sudo nano /etc/nginx/sites-available/myproject

server {
    listen 80;
    server_name your_domain www.your_domain;

location / {
        include proxy_params;
        proxy_pass http://unix:/home/sammy/myproject/myproject.sock;
    }
}

To enable the Nginx server block configuration

sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled
sudo systemctl restart nginx

on your browser http://your_domain

Output

Hello There!

Created a simple Flask application within a Python virtual environment and a WSGI entry point so that any WSGI capable application server can interface with it, and then configured the Gunicorn app server to provide this function.