Run Django on a Linux + Apache2 Box

Preface

This article applies to those who are new to the Django ecosystem and wish to get a live Apache server up and running painlessly. It took me a long time to learn the first time around, with a lot of mistakes along the way. I’ll try to cover all of the bases and make note of the main gotchas.

In particular, this article covers:

• Setting up a Python virtual environment (super important!!)

• Installing and verifying the WSGI Apache module

• Writing a Apache configuration file for the site

At the time of this writing, I’m running Ubuntu 14.04. If you are on a different Linux flavor, then some of the commands may change (but the overall strategy should be the same). If you’re on Windows… why?!

Also, for convenience of writing, I make the assumption that your username is myuser, your Django project is located at /home/myuser/myproject/, and your site’s domain name is example.com. It’s highly doubtful that those conditions match your environment, so you’ll need to modify the commands accordingly.

I further assume that you know which Python version you’ll be using and that you’ve got it properly installed on your system. I’ll be using Python 3.4. Make sure that the development package is installed as well.

sudo apt-get install python3.4 python3.4-dev

As a final note: once you’ve finished with this guide, you might be interested in learning how to integrate Celery, RabbitMQ, and/ or Supervisor for asynchronous task management. If so, check out another of my posts: here.

Python Virtual Environment

I won’t go into why using virtualenv is so important — it just is. It takes about 10 seconds to initially setup and it will save you a whole lot of time later on. So, without further ado, navigate to your project directory and create an environment for the Python version of your choice.

cd /home/myuser/myproject/
virtualenv -p /usr/bin/python3.4 .venv

This creates an entire Python environment within the folder /home/myuser/myproject/.venv/. You then can “activate” and “deactivate” the environment by doing:

source .venv/bin/activate
deactivate

Note: if you use a version tracking system like git, then you should ensure that the .venv folder is ignored. Not only can the folder get big, but it is specific to your local system.

To install Python packages, use pip while the virtualenv is active. For example:

pip install Django

As far as developing your Django application goes, you’re now on your own. Check out Django’s top-notch documentation for reference material and tutorials.

WSGI

To run the Django code on a live Apache server, you must configure Apache to use Python. This involves installing the WSGI module for Apache. For projects using Python 2.7 or 3.2, this is easy, as the modules are available in the main Ubuntu repositories. Simply do sudo apt-get install libapache2-mod-wsgi (for Python 2.7) or sudo apt-get install libapache2-mod-wsgi-py3 (for Python 3.2).

However, my example project uses Python 3.4, so we must compile and install our own WSGI module. Apache can be touchy, so make extra sure that any previous WSGI modules are deactivated and uninstalled:

sudo a2dismod wsgi
sudo service apache2 stop
sudo apt-get remove libapache2-mod-wsgi libapache2-mod-wsgi-py3

Next, download the latest WSGI module source code to a convenient directory, compile it, and install it:

sudo apt-get install apache2-dev
wget https://github.com/GrahamDumpleton/mod_wsgi/archive/4.4.21.tar.gz
tar -zxvf 4.4.21.tar.gz
cd mod_wsgi-4.4.21/
./configure --with-python=/usr/bin/python3.4
make
sudo make install

Assuming that the target OS is Ubuntu 14.04, it may be necessary to create a module loader for the a2enmod command. Simply create a new file, /etc/apache2/mods-available/wsgi.load, and save into it a single line:

LoadModule wsgi_module /usr/lib/apache2/modules/mod_wsgi.so

Last, enable the new module and start Apache:

sudo a2enmod wsgi
sudo service apache2 start

If you look at Apache’s main error log, you should see a line similar to the following.

Apache/2.2.22 (Ubuntu) mod_wsgi/4.4.21 Python/3.4.3 configured -- resuming normal operations

Make sure that the WSGI and Python versions are correct. If there are segfaults or other errors during Apache restart, you might have to completely remove Apache and start from scratch with a clean install.

Apache Conf File

Once the WSGI module is successfully installed, you’ll need to write an Apache configuration file for the project. It will tell Apache how and where to serve up your project to the outside world. Since everybody’s individual use-case is different, I can only provide a starting example. You’ll need to modify it to your tastes. The important parts to take note of are the lines related to your Django project and your virtual environment.

But before all that, it’s probably a good idea to setup a default public directory for Apache. Although it has nothing to do with Django, it can be convenient. The error logs will live here.

cd /home/myuser
mkdir example.com example.com/{log,public}
touch example.com/public/index.html

Navigate to the Apache directory for site configuration. On Ubuntu that’s:

cd /etc/apache2/sites-available/

Create a new file, example.com.conf. Copy, paste, and edit the following configuration code.

# domain: example.com
# public: /home/myuser/example.com/public/

<VirtualHost *:80>

  # Admin email, Server Name (domain name), and any aliases
  ServerAdmin webmaster@example.com
  ServerName  example.com

  # Index file and Document Root (where the public files are located)
  DirectoryIndex index.html
  DocumentRoot /home/myuser/example.com/public

  # Log file locations
  LogLevel warn
  ErrorLog  /home/myuser/example.com/log/error.log
  CustomLog /home/myuser/example.com/log/access.log combined

  # Django project WSGI
  WSGIScriptAlias / /home/myuser/myproject/path/to/wsgi.py process-group=myproject-site
  WSGIDaemonProcess myproject-site python-path=/home/myuser/myproject:/home/myuser/myproject/.venv/lib/python3.4/site-packages
  WSGIProcessGroup myproject-site

  # Django project
  <Directory /home/myuser/myproject>
    <Files wsgi.py>
      Require all granted
    </Files>
  </Directory>

</VirtualHost>

Finally, enable the new site and and reload Apache:

sudo a2ensite example.com.conf
sudo service apache2 reload

Open your browser, visit your domain URL and see what happens. If all went well, your Django project will be displaying in all its glory!