---
title: "Django quickstart"
date: "2015-01-24"
category: "python"
slug: "django-quickstart"
---

## Overview

[Django](https://www.djangoproject.com/) is a web framework based on [Python](https://www.python.org/). Python is available on all packages, and Django applications can be uploaded on any package. However, [[is-terminal-access-available]] is required to create a new project on the server. This guide covers running Django with [Passenger](https://www.phusionpassenger.com/) on [[determining-platform-version]].

## Quickstart

From the [[accessing-terminal]], install Django and the MySQL adapter from PyPI using [[installing-packages]]:

`pip install django mysql`

**Important (v6+ platforms):** First designate a [[changing-python-versions]] (do not use the default "system"), then after installation, fix the [[python-bins-fail-import-library]] of `/usr/local/bin/django-admin`.

### Step-by-Step Setup

1. Switch to /var/www to create a new project:
    - `cd /var/www`
2. Initialize an application named myapp:
    - `django-admin startproject myapp`
    - **Note:** Per Django documentation, initializing projects under /var/www is discouraged. This is only true if /var/www is a [[where-is-site-content-served-from]] (which it is not).
3. Django creates a management controller (`manage.py`) within the project folder, plus an app folder one level down. Move to the app folder:
    - `cd myapp/myapp`
4. Create `public/` and `tmp/` directories for serving public files and managing application restarts:
    - `mkdir tmp public`
5. Create a Passenger startup symlink. Passenger looks for `passenger_wsgi.py` inside `/var/www/myapp/myapp`:
    - `ln -s wsgi.py passenger_wsgi.py`
6. Edit `passenger_wsgi.py` to add your application path to Python. Two lines need to change:
    - **Before:**
        
        import os
        os.environ.setdefault("DJANGO\_SETTINGS\_MODULE", "myapp.settings")
        from django.core.wsgi import get\_wsgi\_application
        application = get\_wsgi\_application()
        
    - **After:**
        
        import os, sys
        sys.path.append("/var/www/myapp")
        os.environ.setdefault("DJANGO\_SETTINGS\_MODULE", "myapp.settings")
        from django.core.wsgi import get\_wsgi\_application
        application = get\_wsgi\_application()
        
    - **Explanation:** The `sys` module is imported alongside `os`, then `sys.path.append` adds the project root (`/var/www/myapp`) to the Python library path.

7. Connect the application to a web-accessible URL:
    - Go to **Web** > **Subdomains** in the [[logging-into-the-control-panel]]. Create a new subdomain called _myapp_ with the [[where-is-site-content-served-from]] set to `/var/www/myapp/myapp/public`.
        
        ![Linking a Django subdomain underneath a project called myapp and its first app called "myapp" using Passenger.](kb-image:django-subdomain-ex.png)
*Linking a Django subdomain underneath a project called myapp and its first app called "myapp" using Passenger.*

8. Configure Passenger in the public directory:
    - Create `.htaccess`: `nano public/.htaccess` and add:
      
       PassengerEnabled On
       PassengerAppRoot /var/www/myapp/myapp
       PassengerPython /usr/local/share/python/pyenv/shims/python
      
    - If `public/index.html` exists, remove it: `rm public/index.html`

9. Access your Django application.
    
    ![Confirmation page that Django is up and running a-OK!](kb-image:django-confirmation-page.png)
*Confirmation page that Django is up and running a-OK!*

## Restarting Your Application

Passenger manages application processes. To restart:

- **On every request:** Create `tmp/always_restart.txt`: `touch tmp/always_restart.txt`
- **One-time restart:** Create `tmp/restart.txt`: `touch tmp/restart.txt`

Passenger compares the file timestamp with its internal record to determine when to restart. To trigger another restart, reissue the `touch` command.

## Viewing Launcher Errors

On v6+ platforms, launcher errors are logged to `/var/log/passenger.log`.

## See Also

- [Django tutorial](https://docs.djangoproject.com/en/1.7/intro/tutorial01/)
- [The Django Book](http://www.djangobook.com/en/2.0/index.html)
- [Django vs Flask vs Pyramid](https://www.airpair.com/python/posts/django-flask-pyramid)
- Django [demo](http://django.sandbox.apnscp.com) on Sol, a v6 platform
