Django web app deployment using Gunicorn, Supervisor and nginx

Django deployment

It is easy to get started with django and hard to go on a long run and deployment is even cumbersome, if you don’t follow the right principle it will kill your time.

Most of the time, for development, I use Ubuntu, for deployment, Centos has done me a favor as it’s just become a defacto os for deployment.

here is my workflow.

Setup a VPS.

Prepare postgresql database

For most of my application, I use Postgresql, so, let’s install postgresql in centos distribution.

# Install database packages
yum install postgresql-devel postgresql-libs postgresql postgresql-server \
postgresql-contrib -y
# Install database driver
sudo yum install python-psycopg2

After installing postgresql, let’s start postgresql server and enable postgresql for different run levels.

sudo systemctl enable postgresql
sudo systemctl start postgresql

After successful installation of postgresql, it’s time to prepare a database for our webapp. postgresql create a user postgres as a super user during installation, we will use postgres user to create database for our webapp, a database user and a database user password.

# login using postgres user
sudo su - postgres
# create a database
createdb example_db
# create a user for example_db
createuser example_user --interactive
# login to psql shell
psql example_db
# set a password for example_user
ALTER USER example_user WITH PASSWORD 'yourpassword';
# grant all privileges for example user on example_db database
GRANT ALL ON DATABASE example_db to example_user;
# quit the database

Now it’s time to configure our webapp so that we can use a recently created database. Open your or any other database configuration file as per your web application architecture. Configure the following values as shown below.

    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'example_db',
        'USER': 'example_user',
        'PASSWORD': 'yourpassword',
        'HOST': '',
        'PORT': '5432',

Ok, we are done with database server configuration. Now its time to install and setup Gunicorn.

Gunicorn install and setup.

Issue the following commands in your centos VPS to install gunicorn.

 (venv)# pip install gunicorn

After installing gunicorn, we will create a script to run the gunicorn server, which will ultimately controlled by supervisorctl.

On your project directory create a script called as shown below. This script will used to launch gunicorn server.

# Purpose: Gunicorn starter
# Author: [email protected]
# Name of an application
NAME="Your projectname"
# project directory
# django project virutalenv directory
# Project source directory
# Sock file as gunicorn will communicate using unix socket
# User who runs the app
# the group to run as
# how many worker processes should Gunicorn spawn
# which settings file should Django use
# If you haven't spit your file it should example.settings only
# WSGI module name
# Activate the virtual environment
source $VENVDIR/bin/activate
# Export the settings module
# Export the python path from virtualenv dir
# move to src dir !IMPORTANT otherwise it won't work.
# Start your Django Unicorn
# Programs meant to be run under supervisor should not daemonize themselves (do not use --daemon)
exec $VENVDIR/bin/gunicorn ${DJANGO_WSGI_MODULE}:application \
  --name $NAME \
  --workers $NUM_WORKERS \
  --user=$USER --group=$GROUP \
  --bind=unix:$SOCKFILE \
  --log-level=debug \

After configuring script, we need to install and configure supervisor to manage our webapp.

Install and Configure supervisor

Install supevisor.

  # install Supervisor
  sudo yum install Supervisor
  # create the supervisor configuration script
  # you need to create this script to work
  echo_supervisord_conf > /etc/supervisord.conf
  # create the site specific configuration and include in supervisord.conf file
  # to include the below use include directives
  files = /etc/supervisor/conf.d/*.conf

To, manage and start web application starter script, we need to create a web application specific configuration file.

Create a configuration file inside /etc/supervisor/conf.d/ directory. as shown below.

touch /etc/supervisor/conf.d/

Paste the following contents in file.


Install nginx

We will use Nginx as a webserver for our django web application. Issue the following commands to install nginx.

sudo yum install nginx
sudo systemctl enable nginx
sudo systemctl start nginx

Create a web server configuration file for Django web app inside /etc/nginx/conf.d/ directory as example.conf as shown below.

upstream example {
  # fail_timeout=0 means we always retry an upstream even if it failed
  # to return a good HTTP response (in case the Unicorn master nukes a
  # single worker for timing out).

  server unix:/webapps/ fail_timeout=0;

	listen 80;
	client_max_body_size 4G;
	access_log /webapps/;
	error_log /webapps/;

	# Robot.txt configuration
  # developers work on robot.txt more so it is suitable to push inside source code.
      	location /robots.txt {
      	  alias /webapps/;
	# Static assets configuration
 	location /static/ {
        alias   /webapps/;
        expires 30d;

	# Media configuration
	location /media/ {
        alias   /webapps/;
        expires 30d;

        # Need to review
      location / {
    	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   	  proxy_set_header Host $http_host;
    	proxy_redirect off;
   	  if (!-f $request_filename) {
        	proxy_pass http://example; #app name

        # Favicon configuration
        location /favicon.ico {
    	 alias /webapps/;

        # Prevent hidden files being serverd
	location ~ /\. { access_log off; log_not_found off; deny all; }

	# Error page configuration
        error_page 500 502 503 504 /500.html;
    	location = /500.html {
        root /webapps/;

Now, restart the nginx server to load the configuration file for your django web application.

Start a web application using supervisorctl

  supervisorctl start example

To stop the web application you can use supervisorctl as shown below.

supervisorctl stop example