fabfile.py API


  • Write a function populating env.hosts and env.conf for each server configuration.

  • Call update_env() at the end of each function.

  • It is possible to reduce boilerplate by using define_host decorator:

    from fab_deploy import *
    def my_site():
        return {
            # ...
  • In order to specify configuration the fab commands should use, run the configuring function as a first fab command:

    fab my_site mysql_install
  • In order to make configuration default call the configuring function at the end of fabfile.py:

    from fab_deploy import *
    def my_site():
        env.hosts = ['my_site@example.com']
        env.conf = {
            # ...
        # ...

    This way it’ll be possible to run fab commands omitting the config name:

    fab mysql_install



Updates env.conf configuration with some defaults and converts it to state._AttributeDict (that’s a dictionary subclass enabling attribute lookup/assignment of keys/values).

Call update_env() at the end of each server-configuring function.

from fabric.api import env, task
from fab_deploy.utils import update_env

def my_site():
    env.hosts = ['my_site@example.com']
    env.conf = dict(
        DB_USER = 'my_site',
        DB_PASSWORD = 'password',

A list with host string. Example:

env.hosts = ['user@example.com']

See fabric docs for explanation.

User obtained from this string will be used for ssh logins and as a default value for env.conf.INSTANCE_NAME.


multiple hosts are supported via multiple config functions, not via this option.


Due to bug in Fabric please don’t use env.user and env.port. Put the username and non-standard ssh port directly into host string.


django-fab-deploy server configuration.

All env.conf keys are available in config templates as jinja2 template variables.


Project instance name. It equals to username obtained from env.hosts by default. INSTANCE_NAME should be unique for server. If there are several sites running as one linux user, set different INSTANCE_NAMEs for them.


Site url for webserver configs. It equals to the first host from env.hosts by default.


Database name. It equals to env.conf.INSTANCE_NAME by default.


Database user. It equals to ‘root’ by default.


Database password.


Database password for a ‘root’ user. django-fab-deploy will ask for mysql root password when necessary if this option is not set.


User with sudo privileges. It is ‘root’ by default. Use create_sudo_linux_account in order to create non-root sudoer.


The number of mod_wsgi daemon processes. It is a good idea to set it to number of processor cores + 1 for maximum performance or to 1 for minimal memory consumption. Default is 1.


The number of mod_wsgi threads per daemon process. Default is 15.


Set env.conf.THREADS to 1 and env.conf.PROCESSES to a bigger number if your software is not thread-safe (it will consume more memory though).


A string with server operating system name. Set it to the correct value if autodetection fails for some reason. Supported operating systems:

  • lenny
  • squeeze
  • maverick

The name of VCS the project is stored in. Supported values:

  • hg
  • git
  • none

Default is ‘hg’.

VCS is used for making project clones and for pushing code updates. ‘none’ VCS is able to upload tar.gz file with project sources on server via ssh and then extract it. Please prefer ‘hg’ or ‘git’ over ‘none’ if possible.

One can write custom VCS module and set env.conf.VCS to its import path:

env.conf = dict(
    # ...
    VCS = 'my_utils.my_vcs',

VCS module should provide ‘init’, ‘up’, ‘push’ and ‘configure’ functions. Look at fab_deploy.vcs.hg or fab_deploy.vcs.none for examples.


Named hg branch that should be active on server. Default is “default”. This option can be used to have 1 repo with several named branches and run different servers from different branches.


Git branch that should be active on server. Default is “master”. This option can be used to run different servers from different git branches.


Path to django project (relative to repo root). Default is ‘’. This should be set to a folder where project’s manage.py reside.


Local django config file name. Default is ‘config.py’. Common values include ‘local_settings.py’ and ‘settings_local.py’. This file should be placed inside env.conf.PROJECT_PATH, imported from settings.py and excluded from version control.


Default value is not set to one of widely-used file names by default (e.g. ‘local_settings.py’) in order to prevent potential data loss during converting existing project to django-fab-deploy: this file is overwritten on server during deployment process; it is usually excluded from VCS and contains important information.


The name of file with remote config template. Default is ‘config.server.py’. This file should be placed inside env.conf.PROJECT_PATH. It will become env.conf.LOCAL_CONFIG on server.


An iterable with paths to web server and other config templates. Default is ['config_templates'].


Default is ‘reqs’. This path is relative to repo root.


The name of main requirements file. Requirements from it are installed during deployment. Default is ‘all.txt’.


The name of pip requirements file with commonly updated requirements. Requirements from this file are updated by fab_deploy.virtualenv.pip_install() and fab_deploy.virtualenv.pip_update() commands when they are executed without arguments.

fab push:pip_update command also updates only requirements listed here.

Default is ‘all.txt’.

You can put any other variables into the env.conf. They will be accessible in config templates as template context variables.

Writing custom commands

While django-fab-deploy commands are just Fabric commands, there are some helpers to make writing them easier.


Decorator. Use it to perform actions inside remote project dir (that’s a folder where manage.py resides) with virtualenv activated:

from fabric.api import run, task
from fab_deploy.utils import inside_project

def cleanup():
    # the current dir is a project source dir and
    # virtualenv is activated
    run('python manage.py cleanup')

Decorator. Use it to perform actions inside remote source dir (repository root) with virtualenv activated.


Decorator. By default all commands are executed as user without sudo access for security reasons. Use this decorator to run fabric command as user with sudo access (env.conf.SUDO_USER):

from fabric.api import run, task
from fab_deploy import utils

def aptitude_update():
    run('aptitude update')
fab_deploy.utils.define_host(host_string, defaults=None)[source]

This decorator populates env.hosts, env.conf and calls update_env():

from fab_deploy.utils import define_host

def my_site():
    return {
        'DB_USER': 'my_site',
        'DB_PASSWORD': 'password',

Decorated function should return a dict with desired env.conf values.

There is no need to wrap function in @fabric.api.task decorator because define_host will do it for you.

define_host also accepts a dict with default values:

from fab_deploy.utils import define_host

DEFAULTS = dict(
    PROCESSES = 3,
    VCS = 'git',

@define_host('my_site@example.com', DEFAULTS)
def my_site():
    return {
        'DB_USER': 'my_site',
        'DB_PASSWORD': 'password',
        'PROCESSES': 2,

# env.conf will contain PROCESSES=2 and VCS='git'.