Reference Django app for Debian packaging
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Reference Django application for building Debian packages.

All feedback or enhancements appreciated!


To follow some Debian packaging guides as well as LSB/FHS standards, following hierarchy is used for Django installations:

Location Purpose
/usr/lib/django-debian Virtualenv root, this is read-only place where app ant it's dependencies live. Additional scripts like and are installed in bin directory of this root.




Variable files, media and statically served files. Static files are collected during package configuration with collectstatic, run dpkg-reconfigure django-debian to re-create static directory.




Configuration directory, place for overrides of default configuration, shipped with package. This configuration is also managed by debconf.
/etc/django-debian/templates Optional place for sysadmin maintained templates.



All support files that are not being changed over time and are not binaries or libraries should belong to /usr/share. For Django application, templates are the best example.



Place for non-syslog log files. Debconf script will set correct permissions on directory and django.log file for user/group used to run Django app.
/usr/share/doc/django-debian Additional documentation, readme, debian changelog, etc.



Sane defaults should be already part of distribution and set in django_helpdesk.settings and eventually django_helpdesk.celery_settings. At best it should be defaults that will run on any machine without additional configuration.

Default settings can be overriden in:

  • /etc/django-debian/
  • /etc/django-debian/
  • /etc/django-debian/gunicorn
    • this is sourced by script
    • it could be also /etc/default/django-debian as it contains common and startup settings for application

These configuration files are included from distribution by following simple mechanism:

    with open("/etc/django-debian/") as f:
        code = compile(, "/etc/django-debian/", 'exec')
except IOError:

Alternatively it can support configuration overrides in some common configuration format, like yaml, ini, etc.

Some basic configuration is done immediately after package installation or when dpkg-reconfigure. For more informations see debian/templates and debian/postinst.

Package build

To build version in current branch, you should use git-buildpackage and pbuilder. Pbuilder will create clean chroot environment and install required dependencies so you don't need to mess up your system.

Alternatively you can install build dependencies on your own and execute plain dpkg-buildpackage -uc -us

Install required packages
apt-get install cowbuilder pbuilder git-buildpackage dh-virtualenv dh-python


In case you are building whole virtualenv, you need latest dh-virtualenv (latest master, unreleased version 0.10) with support for overriding destination directory. This package is built in our repository but it probably won't be present in your OS distribution. Install it manually from our repo or build it on your own from

Configure pbuilder to allow network access (dh-virtualenv only)

Create or edit ~/.pbuilderrc and put following inside:

Create cowbuilder environment
cowbuilder --create
Build the package
git-buildpackage --git-pbuilder -uc -us --git-ignore-branch

That will create source archive and run pbuilder which will create chroot, You need to commit or stash all your changes first.


  • setup gunicorn and optionally nginx or apache
  • setup database with dbconfig-common