Skip to main content

Opionated django deployment tool

Project description

django-fab-deploy is intended to be an easy deployment and management solution for django projects using mercurial, fabric, virtualenv, pip, nginx and apache with mod_wsgi. The supported OS is Debian Lenny.

This software is very opionated. It is a collection of fabric scripts that work well together for my projects.

Several projects can be deployed on the same VPS using django-fab-deploy. One project can be deployed on several servers. Projects are isolated with virtualenv.

Please don’t use OpenVZ or Virtuozzo VPS’s for deployment! Use XEN or KVM or real servers instead. OpenVZ has very serious issues with memory management (VIRT is counted and limited instead of RSS or something) so apache (and a lot of other software like mysql’s InnoDB engine) is totally unusable on OpenVZ while being memory-wise and performant on XEN.


  • python 2.5+
  • your project is stored in mercurial repository
  • Debian Lenny server or VPS with ssh access. I don’t have other servers so e.g. Ubuntu is untested but it will possibly work with some small changes.
  • South is used for migrations
  • Fabric trunk (
  • jinja2
  • Optional: django-compress is used for css and js bundling

I tested the setup only with mysql.


Licensed under a MIT license.

What is it for

  1. Deploying several small django sites on one Debian Lenny VPS.
  2. Deploying and managing django project with several hg branches that should go to different servers (e.g. staging and production).
  3. Repeatable deployments

Getting started

  1. Install django-fab-deploy

  2. Make shure that your project match this structure:

        hosting          <- this folder should be copied from django-fab-deploy
        reqs             <- a folder with project's pip requirement files
            all.txt      <- include all other files in here using pip '-r' syntax
            active.txt   <- put recently modified apps here
        static           <- static files folder
          <- your project's Fabric deployment script, see below        <- this file should be included in and ignored in .hgignore <- this is a production config template, see below
 trick is also known as

  3. Copy ‘hosting’ folder from django-fab-deploy to your project and adjust web server configs if it is needed. Basic configs are good starting point and should work as-is.

  4. Make shure your .hgignore has these lines:

    syntax: regexp
  5. Create It should provide functions with your server-specific environment variables and you own deployment utils. Example:

    from fabric.api import *
    from fab_deploy import *
    def stage():
        # how to connect via ssh:
        env.hosts = ['']   # host
        env.user = 'user'                     # user (must not be root)
        # instance parameters
        env.conf = dict(
            # distinct instance name
            INSTANCE_NAME = "my_site",
            # server name. It will be used for web server configs.
            SERVER_NAME = "",
            # DB credentials
            DB_NAME = 'my_site_testing',
            DB_PASSWORD = '123',
            # apache and mod_wsgi config
            PROCESSES = 1,
            THREADS = 5,
            # port should be distinct from other instances' ports
            APACHE_PORT = 8083,
            # named hg branch that will be active by default
            HG_BRANCH = 'default',
            # any other parameters. They will be available in config
            # templates as template variables
            VERSION = 'STAGING',
    def prod():
        env.hosts = ['']
        env.user = 'user'
        env.conf = dict(
            # this should be different if stage and production
            # instances share the same server
            INSTANCE_NAME = "my_site",
            SERVER_NAME = "",
            # DB credentials
            DB_NAME = 'my_site_production',
            DB_PASSWORD = '345',
            # apache and mod_wsgi config
            PROCESSES = 5,
            THREADS = 15,
            # port should be distinct from other instances'
            # ports on the same server
            APACHE_PORT = 8083,
            # named hg branch that will be active by default
            HG_BRANCH = 'production',
            # any other parameters. They will be available in config
            # templates as template variables
            VERSION = 'PROD',
    stage() # use stage versions as default
  6. Create Example:

    #config file for environment-specific settings
    DEBUG = False
        'default': {
            'ENGINE': 'django.db.backends.mysql',
            'NAME': '{{ DB_NAME }}',
            'USER': 'root',
            'PASSWORD': '{{ DB_PASSWORD }}',
            'HOST': '',
            'PORT': '',
            'OPTIONS': {
                "init_command": "SET storage_engine=INNODB"
    MEDIA_URL = 'http://{{ SERVER_NAME }}/static/'
  7. You should be able to run fab full_deploy from project root now. Run it. ‘stage’ server will be configured: neccessary system and python packages will be installed, apache and ngnix will be configured, virtualenv is created and project is on the server. If you want to deploy on prod server, run fab prod full_deploy.

    Project sources will be available under ~/src/<instance_name>, virtualenv will be placed in ~/envs/<instance_name>.

  8. TODO: this step should be eliminated. Finish some tasks that were not handled by django-fab-tools:

    1. For now mysql should be installed manually:

      $ aptitude install mysql-server
    2. Then you should create a DB using mysql shell:

    3. Then perform the ‘syncdb’ step on your server:

      $ ./manage syncdb
    4. And then ‘migrate’ step (from local machine):

      $ fab migrate
    5. Django session tables MUST be MyISAM. If the default engine is InnoDB then the following command should be performed in mysql shell:

      alter table django_session engine=myisam;
    6. Configuring the email server:

      $ dpkg-reconfigure exim4-config
  9. You project should be now up and running.

Some common tasks (dig into source code for more)

  1. Deploy changes on default server:

    $ fab push
  2. Deploy changes on another server, update pip requirements and perform migrations:

    $ fab prod push:pip_update,migrate
  3. Update requirements specified in reqs/active.txt:

    $ fab pip_update
  4. Update requirements specified in reqs/my_apps.txt:

    $ fab pip_update:my_apps
  5. Remotely change hg branch:

    $ fab up:my_branch

TODO: provide complete list of commands

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-fab-deploy, version 0.0.1
Filename, size File type Python version Upload date Hashes
Filename, size django-fab-deploy-0.0.1.tar.gz (9.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page