How to Run Django with mod_wsgi and Apache with a virtualenv Python environment on a Debian VPS
Working with Django applications, and Python applications in general, is a complex matter with many tools in use. There are multiple ways of achieving the same goal and often there is no single way to do things.
One of the most popular ways of deploying Django applications to the web on a dedicated server is to use Nginx paired with Gunicorn. A great way to do that has already been described in depth in this article. It is however a quite popular scenario to host Django applications alongside existing websites served using Apache. We will try to cover the quick route to achieve that particular goal. Please note, however, that this is not a definitive guide to Django and Apache pairing and there are configuration aspects not covered here.
This text will make several assumptions:
You have already set up your droplet with Debian 7.0 or later. There are many differences between different Linux distributions; therefore for the sake of clarity we will focus on a Debian server.
You are at least somewhat familiar with common Python tools such as pip package manager and virtualenv for making virtual environments. These tools are wonderfully explained in this article.
You are at least somewhat familiar with Django project structure, as this article is not intended to walk through using and configuring Django itself.
You are familiar with basic Apache administration, as this tutorial will cover only the simple installation of the server itself and necessary configuration changes to pair Django with Apache.
Before installing new packages, it is always a good practice to update your system packages and package indexes. To do that execute:
apt-get update apt-get upgrade
Since this text focuses on using Apache to serve the application, the server itself is necessary. To install the necessary packages execute:
apt-get install apache2
Straight after installation Apache will already be running. You can check whether the Apache web server has been properly set-up by opening your web browser and pointing it to the server IP address. You should see a simple It works! page on the screen.
Installing pip and virtualenv
To begin working with Python and Django on a webserver, pip and virtualenv must be installed first. Pip is a Python package manager that facilitates installing Python software packages such as Django itself, whereas virtualenv makes it possible to create separate virtual environments for Python applications in order to separate libraries needed for different applications and avoid version clash between them.
To do that execute:
apt-get install python-pip python-virtualenv
This command will install pip and virtualenv from the Debian package repository. You can verify that both tools have been properly installed by running them with
root@django:~# virtualenv --version 22.214.171.124 root@django:~# pip --version pip 1.1 from /usr/lib/python2.7/dist-packages (python 2.7) root@django:~#
Creating a virtual environment using virtualenv
Upon Apache installation a
/var/www directory is automatically created in which the default web server root is set up. We will put our new Django application there with all its dependencies.
Let's create a new directory called
sampleapp inside that directory and enter the new directory:
cd /var/www mkdir sampleapp cd sampleapp
Then let's create a new virtual environment using
virtualenv. A Python virtual environment is basically a directory in which the Python interpreter and a local instance of
pip resides. The local instance of
pip installs all packages inside the virtual environment. That way no installed packages pollute global Python installation and also there is no possibility of package version clash in a hypothetical scenario of two applications running two different versions of Django or any other library.
To create a new virtual environment enter:
env is the virtual environment name - it could be any other word. The output from this command should look like this:
root@django:/var/www/sampleapp# virtualenv env New python executable in env/bin/python Installing distribute.............................................................................................................................................................................................done. Installing pip...............done. root@django:/var/www/sampleapp#
The virtual environment is now ready and can be used in two different ways.
One way is to run commands using virtual environment interpreter directly. With this method it is necessary to always remember to execute the correct interpreter or
pip instance, as there is a possibility to run a system-wide one.
root@django:/var/www/sampleapp# env/bin/pip --version pip 1.1 from /var/www/sampleapp/env/lib/python2.7/site-packages/pip-1.1-py2.7.egg (python 2.7) root@django:/var/www/sampleapp# env/bin/python --version Python 2.7.3 root@django:/var/www/sampleapp#
The other way is to activate the environment first, using
the environment name will then be prepended to the command line as such
root@django:/var/www/sampleapp# source env/bin/activate (env)root@django:/var/www/sampleapp#
and all commands executed will be using local virtual environment versions
(env)root@django:/var/www/sampleapp# pip --version pip 1.1 from /var/www/sampleapp/env/lib/python2.7/site-packages/pip-1.1-py2.7.egg (python 2.7) (env)root@django:/var/www/sampleapp# python --version Python 2.7.3 (env)root@django:/var/www/sampleapp#
it is easier to work that way; however it is necessary to deactivate the environment after the work is done using the following command
it will return the shell to normal
(env)root@django:/var/www/sampleapp# deactivate root@django:/var/www/sampleapp#
The freshly created environment will be used to store all necessary dependencies, including Django and related libraries. It will also be used by Apache and mod_wsgi later on to serve the application using correct dependencies.
Installing Django inside virtual environment
Next necessary step is to install Django inside the virtual environment. Let's do that without activating the environment beforehand using:
env/bin/pip install django
The last messages shown after executing this command should look like this
Successfully installed django Cleaning up...
Django is now installed inside virtual environment and is not available from within system-wide Python installation. You can verify that behavior by importing
django module using both interpreters
root@django:/var/www/sampleapp# python Python 2.7.3 (default, Mar 13 2014, 11:03:55) [GCC 4.7.2] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import django Traceback (most recent call last): File "<stdin>", line 1, in <module> ImportError: No module named django >>> exit()
Import using system-wide interpreter failed, whereas
root@django:/var/www/sampleapp# env/bin/python Python 2.7.3 (default, Mar 13 2014, 11:03:55) [GCC 4.7.2] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import django >>>
the one executed inside the virtual environment succeeded.
Creating first Django project
To create a simple, basic example project we can use
django-admin.py script as follows
env/bin/django-admin.py startproject sampleapp .
Please note the trailing
. in the command - without it the project will be created in an additional subdirectory. After executing that command a new
sampleapp directory and
manage.py script will be created in
manage.py script is used to execute Django commands for this particular project. One of the possible uses of
manage.py is to run a test server instance to verify that everything is working as intended.
env/bin/python manage.py runserver 0.0.0.0:8000
This will run a test server bound to all interfaces on port 8000. The output should look like this:
Validating models... 0 errors found April 08, 2014 - 12:29:31 Django version 1.6.2, using settings 'sampleapp.settings' Starting development server at http://0.0.0.0:8000/ Quit the server with CONTROL-C.
If you open your server IP address with port 8000 in your browser (the address should look like
http://<ip address>:8000/) you should see the It worked! example Django page. This is the result we will work towards using Apache web server instead of the built-in Django development server.
Since the Django application is working properly, we can proceed to pair the application with Apache.
Installing mod_wsgi for Apache
The easiest and also recommended way to serve Python applications using Apache is to use mod_wsgi module. It is not installed by default with neither Python nor Apache, so we have to install an additional package.
apt-get install libapache2-mod-wsgi
The next step will be to configure default Apache virtual host that at the beginning of the article served It works! page to serve our Django application.
Configuring mod_wsgi in a default virtual host
The idea behind configuring mod_wsgi for any other virtual host in Apache is the same as the one presented here. We will use the default virtual host for simplicity, since it is the one already provided by a clean Apache installation.
Open the default virtual host configuration file in
and add three following lines just below
WSGIDaemonProcess sampleapp python-path=/var/www/sampleapp:/var/www/sampleapp/env/lib/python2.7/site-packages WSGIProcessGroup sampleapp WSGIScriptAlias / /var/www/sampleapp/sampleapp/wsgi.py
The first line spawns a WSGI daemon process called
sampleapp that will be responsible for serving our Django application. The daemon name can be basically anything, but is good practice to *use descriptive names such as application names here.
If we were using global Python installation and global Django instance, the
python-path directive would not be necessary. However, using virtual environment makes it obligatory to specify the alternate Python path so that mod_wsgi will know where to look for Python packages.
The path must contain two directories: the directory of Django project itself -
/var/www/sampleapp - and directory of Python packages inside our virtual environment for that project -
/var/www/sampleapp/env/lib/python2.7/site-packages. Directories in path definition are delimited using a colon sign.
The second line tells that particular virtual host to use the WSGI daemon created beforehand, and as such, the daemon name must match between those two. We used
sampleapp in both lines.
The third line is the most important, as it tells Apache and mod_wsgi where to find WSGI configuration. The
wsgi.py supplied by Django contains the barebone default configuration for WSGI for serving Django application that works just fine and changing the configuration in this file is out of this article scope.
After these changes it is necessary to restart Apache
service apache2 restart
After that, upon opening the web browser on your server IP address, without any additional ports, you should see the same Django page as before instead of initial It works! page that we have seen earlier.
That makes our configuration complete.
Please note: using the default virtual host without additional care is not the recommended way of configuring a production server. It is used for demonstration purposes.
The topic of configuring mod_wsgi and Django itself is vast. Many configuration aspects are application specific and difficult to explain or demonstrate without working with a real world Django application. This guide is not a complete howto for deployment of Django applications using Apache, but a quickstart guide on how to begin.
One of the best resources around is the official Django documentation. There are also great articles on DigitalOcean that can be found by using Django as a search keyword.