How To Serve Django Applications with uWSGI and Nginx on Debian 8

We can create a virtual environment easily by using some commands that the virtualenvwrapper script makes available to us.

Create your first virtual environment with the name of your first site or project by typing:

mkvirtualenv firstsite

This will create a virtual environment, install Python and pip within it, and activate the environment. Your prompt will change to indicate that you are now operating within your new virtual environment. It will look something like this: (firstsite)user@hostname:~$. The value in the parentheses is the name of your virtual environment. Any software installed through pip will now be installed into the virtual environment instead of on the global system. This allows us to isolate our packages on a per-project basis.

Our first step will be to install Django itself. We can use pip for this without sudo since we are installing this locally in our virtual environment:

pip install django

With Django installed, we can create our first sample project by typing:

cd ~
django-admin.py startproject firstsite

This will create a directory called firstsite within your home directory. Within this is a management script used to handle various aspects of the project and another directory of the same name used to house the actual project code.

Move into the first level directory so that we can begin setting up the minimum requirements for our sample project.

cd ~/firstsite

Begin by migrating the database to initialize the SQLite database that our project will use. You can set up an alternative database for your application if you wish, but this is outside of the scope of this guide:

./manage.py migrate

You should now have a database file called db.sqlite3 in your project directory. Now, we can create an administrative user by typing:

./manage.py createsuperuser

You will have to select a username, give a contact email address, and then select and confirm a password.

Next, open the settings file for the project with your text editor:

nano ~/firstsite/firstsite/settings.py

Start by locating the ALLOWED_HOSTS directive. This defines a whitelist of addresses or domain names may be used to connect to the Django instance. Any incoming requests with a Host header that is not in this list will raise an exception. Django requires that you set this to prevent a certain class of security vulnerability.

In the square brackets, list the IP addresses or domain names that are associated with your Django server. Each item should be listed in quotations with entries separated by a comma. If you wish requests for an entire domain and any subdomains, prepend a period to the beginning of the entry. In the snippet below, there are a few commented out examples used to demonstrate:

. . .
# The simplest case: just add the domain name(s) and IP addresses of your Django server
# ALLOWED_HOSTS = [ 'example.com', '203.0.113.5']
# To respond to 'example.com' and any subdomains, start the domain with a dot
# ALLOWED_HOSTS = ['.example.com', '203.0.113.5']
ALLOWED_HOSTS = ['your_server_domain_or_IP', 'second_domain_or_IP', . . .]

Since we will be setting up Nginx to serve our site, we need to configure a directory which will hold our site’s static assets. This will allow Nginx to serve these directly, which will have a positive impact on performance. We will tell Django to place these into a directory called static in our project’s base directory. Add this line to the bottom of the file to configure this behavior:

. . .
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static/')

Save and close the file when you are finished. Now, collect our site’s static elements and place them within that directory by typing:

./manage.py collectstatic

You can type “yes” to confirm the action and collect the static content. There will be a new directory called static in your project directory.

You may have to adjust your firewall settings to allow traffic to our Django development server, which we’ll run on port 8080.

If you are running a ufw firewall, you can allow traffic to port 8080 by typing:

sudo ufw allow 8080

If you are running iptables instead, the exact command you need depends on your current firewall configuration. For most configurations, this command should work:

sudo iptables -I INPUT -p tcp --dport 8080 -j ACCEPT

With all of that out of the way, we can test our project by temporarily starting the development server. To start the development server, type:

./manage.py runserver 0.0.0.0:8080

This will start up the development server on port 8080. Visit your server’s domain name or IP address followed by 8080 in your browser:

http://server_domain_or_IP:8080

You should see a page that looks like this:

Add /admin to the end of the URL in your browser’s address bar and you will be taken to the admin login page:

Using the administrative login credentials you selected with the createsuperuser command, log into the server. You will then have access to the administration interface:

After testing this functionality out, stop the development server by typing CTRL-C in your terminal. We can now move on to our second project.

The second project will be created in exactly the same way as the first. We will abridge the explanation in this section, seeing as how you have already completed this once.

Move back to your home directory and create a second virtual environment for your new project. Install Django inside of this new environment once it is activated:

cd ~
mkvirtualenv secondsite
pip install django

The new environment will be created and changed to, leaving your previous virtual environment. This Django instance is entirely separate from the other one you configured. This allows you to manage them independently and customize as necessary.

Create the second project and move into the project directory:

django-admin.py startproject secondsite
cd ~/secondsite

Initialize the database and create an administrative user:

./manage.py migrate
./manage.py createsuperuser

Open the settings file:

nano ~/secondsite/secondsite/settings.py

Set the ALLOWED_HOSTS to your second project’s domain, the server’s IP address, or both, just like you did with the first project:

ALLOWED_HOSTS = ['second_project_domain_or_IP', 'another_domain_or_IP', . . .]

Add the location for the static files, just as you did in the previous project:

. . .
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static/')

Save and close the file. Now, collect the static elements into that directory by typing:

./manage.py collectstatic

Finally, fire up the development server to test out the site:

./manage.py runserver 0.0.0.0:8080

You should check the regular site at:

http://server_domain_or_IP:8080

Also log into the admin site:

http://server_domain_or_IP:8080/admin

When you’ve confirmed that everything is working as expected, type CTRL-C in your terminal to stop the development server.

Since we are now done with the Django portion of the guide, we can deactivate our second virtual environment:

deactivate

If you need to work on either of your Django sites again, you should reactivate their respective environments. You can do that by using the workon command:

workon firstsite

Or:

workon secondsite

Again, deactivate when you are finished working on your sites:

deactivate

Unlike the guide linked above, in this tutorial, we’ll be installing uWSGI globally. This will create less friction in handling multiple Django projects. Before we can install uWSGI, we need the Python development files that the software relies on. We can install this directly from Debian’s repositories.

If you have been using Django with Python 2, type:

sudo apt-get install python-dev

If you have been using Python 3, type:

sudo apt-get install python3-dev

Now that the development files are available, we can install uWSGI globally through pip.

If you are using Python 2, type:

sudo pip install uwsgi

If you are using Python 3, type:

sudo pip3 install uwsgi

We can quickly test this application server by passing it the information for one of our sites. For instance, we can tell it to serve our first project by typing:

uwsgi --http :8080 --home /home/sammy/Env/firstsite --chdir /home/sammy/firstsite -w firstsite.wsgi

Here, we’ve told uWSGI to use our virtual environment located in our ~/Env directory, to change to our project’s directory, and to use the wsgi.py file stored within our inner firstsite directory to serve the file. For our demonstration, we told it to serve HTTP on port 8080. If you go to server’s domain name or IP address in your browser, followed by :8080, you will see your site again (the static elements in the /admin interface, like CSS, won’t work yet). When you are finished testing out this functionality, type CTRL-C in the terminal.

Running uWSGI from the command line is useful for testing, but isn’t particularly helpful for an actual deployment. Instead, we will run uWSGI in “Emperor mode”, which allows a master process to manage separate applications automatically given a set of configuration files.

Create a directory that will hold your configuration files. Since this is a global process, we will create a directory called /etc/uwsgi/sites to store our configuration files. Move into the directory after you create it:

sudo mkdir -p /etc/uwsgi/sites
cd /etc/uwsgi/sites

In this directory, we will place our configuration files. We need a configuration file for each of the projects we are serving. The uWSGI process can take configuration files in a variety of formats, but we will use .ini files due to their simplicity.

Create a file for your first project and open it in your text editor:

sudo nano firstsite.ini

Inside, we must begin with the [uwsgi] section header. All of our information will go beneath this header. We are also going to use variables to make our configuration file more reusable. After the header, set a variable called project with the name of your first project. Add a variable called uid which holds your sudo username.

We will also add a variable called base with the path to your user’s home directory. This will be constructed from the username we set using the %(variable_name) syntax. This will be replaced by the value of the variable when the config is read:

[uwsgi]
project = firstsite
uid = sammy
base = /home/%(uid)

Next, we need to configure uWSGI so that it handles our project correctly. We need to move into the root project directory by setting the chdir option. We can combine the home directory and project name using the same variable syntax.

In a similar way, we will indicate the virtual environment for our project. By setting the module, we can indicate exactly how to interface with our project (by importing the “application” callable from the wsgi.py file within our project directory). The configuration of these items will look like this:

[uwsgi]
project = firstsite
uid = sammy
base = /home/%(uid)

# Next, add the lines below
chdir = %(base)/%(project)
home = %(base)/Env/%(project)
module = %(project).wsgi:application

We want to create a master process with 5 workers. We can do this by adding this:

[uwsgi]
project = firstsite
uid = sammy
base = /home/%(uid)

chdir = %(base)/%(project)
home = %(base)/Env/%(project)
module = %(project).wsgi:application

# Next, add these lines
master = true
processes = 5

Next we need to specify how uWSGI should listen for connections. In our test of uWSGI, we used HTTP and a network port. However, since we are going to be using Nginx as a reverse proxy, we have better options.

Instead of using a network port, since all of the components are operating on a single server, we can use a Unix socket. This is more secure and offers better performance. This socket will not use HTTP, but instead will implement uWSGI’s uwsgi protocol, which is a fast binary protocol for designed for communicating with other servers. Nginx can natively proxy using the uwsgi protocol, so this is our best choice.

We will also modify the ownership and permissions of the socket because we will be giving the web server write access. We’ll set the vacuum option so that the socket file will be automatically cleaned up when the service is stopped:

[uwsgi]
project = firstsite
uid = sammy
base = /home/%(uid)

chdir = %(base)/%(project)
home = %(base)/Env/%(project)
module = %(project).wsgi:application

master = true
processes = 5

# Finish off the configuration with the following lines
socket = /run/uwsgi/%(project).sock
chown-socket = %(uid):www-data
chmod-socket = 660
vacuum = true

With this, our first project’s uWSGI configuration is complete. Save and close the file.

The advantage of setting up the file using variables is that it makes it incredibly simple to reuse. Copy your first project’s configuration file to use as a base for your second configuration file:

sudo cp /etc/uwsgi/sites/firstsite.ini /etc/uwsgi/sites/secondsite.ini

Open the second configuration file with your text editor:

sudo nano /etc/uwsgi/sites/secondsite.ini

We only need to change a single value in this file in order to make it work for our second project. Modify the project variable with the name you’ve used for your second project:

[uwsgi]
project = secondsite
uid = sammy
base = /home/%(uid)

chdir = %(base)/%(project)
home = %(base)/Env/%(project)
module = %(project).wsgi:application

master = true
processes = 5

socket = /run/uwsgi/%(project).sock
chown-socket = %(uid):www-data
chmod-socket = 660
vacuum = true

Save and close the file when you are finished. Your second project should be ready to go now.

We now have the configuration files we need to serve our Django projects, but we still haven’t automated the process. Next, we’ll create a systemd unit file to automatically start uWSGI at boot.

We will create the unit file in the /etc/systemd/system directory, where user-created unit files are kept. We will call our file uwsgi.service:

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

Start with the [Unit] section, which is used to specify metadata and ordering information. We’ll simply put a description of our service here:

[Unit]
Description=uWSGI Emperor service

Next, we’ll open up the [Service] section. We’ll use the ExecStartPre directive to set up the pieces we need to run our server. This will make sure the /run/uwsgi directory is created and that our normal user owns it with the www-data group as the group owner. Both mkdir with the -p flag and the chown command return successfully even if their operation is not needed. This is what we want.

For the actual start command, specified by the ExecStart directive, we will point to the uwsgi executable. We will tell it to run in “Emperor mode”, allowing it to manage multiple applications using the files it finds in /etc/uwsgi/sites. We will also add the pieces needed for systemd to correctly manage the process. These are taken from the uWSGI documentation here.

[Unit]
Description=uWSGI Emperor service

[Service]
ExecStartPre=/bin/bash -c 'mkdir -p /run/uwsgi; chown sammy:www-data /run/uwsgi'
ExecStart=/usr/local/bin/uwsgi --emperor /etc/uwsgi/sites
Restart=always
KillSignal=SIGQUIT
Type=notify
NotifyAccess=all

Now, all we need to do is add the [Install] section. This allows us to specify when the service should be automatically started. We will tie our service to the multi-user system state. Whenever the system is set up for multiple users (the normal operating condition), our service will be activated:

[Unit]
Description=uWSGI Emperor service

[Service]
ExecStartPre=/bin/bash -c 'mkdir -p /run/uwsgi; chown sammy:www-data /run/uwsgi'
ExecStart=/usr/local/bin/uwsgi --emperor /etc/uwsgi/sites
Restart=always
KillSignal=SIGQUIT
Type=notify
NotifyAccess=all

[Install]
WantedBy=multi-user.target

When you are finished, save and close the file.

We will be unable to start the service successfully at this point because it relies on the www-data user being available. We will have to wait to start the uWSGI service until after Nginx is installed.