fabfile.py API

Overview

  • 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 *
    
    @define_host('my_site@example.com')
    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 = {
            # ...
        }
        # ...
        update_env()
    
    my_site()
    

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

    fab mysql_install

Configuring

fab_deploy.utils.update_env()[source]

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 fab_deploy import *

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

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.

Note

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

Warning

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.

env.conf

django-fab-deploy server configuration.

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

env.conf.INSTANCE_NAME

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.

env.conf.SERVER_NAME

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

env.conf.DB_NAME

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

env.conf.DB_USER

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

env.conf.DB_PASSWORD

Database password.

env.conf.DB_ROOT_PASSWORD

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

env.conf.SUDO_USER

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

env.conf.PROCESSES

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.

env.conf.THREADS

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

Note

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).

env.conf.OS

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
env.conf.VCS

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.

env.conf.HG_BRANCH

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.

env.conf.GIT_BRANCH

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

env.conf.PROJECT_PATH

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

env.conf.LOCAL_CONFIG

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.

Note

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.

env.conf.REMOTE_CONFIG_TEMPLATE

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.

env.conf.CONFIG_TEMPLATES_PATHS

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

env.conf.PIP_REQUIREMENTS_PATH

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

env.conf.PIP_REQUIREMENTS

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

env.conf.PIP_REQUIREMENTS_ACTIVE

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’.

env.conf.APACHE_PORT

The port used by apache backend. It is managed automatically and shouldn’t be set manually.

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.

fab_deploy.utils.inside_project(func)[source]

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 *
from fab_deploy.utils import inside_project

@inside_project
def cleanup():
    # the current dir is a project source dir and
    # virtualenv is activated
    run('python manage.py cleanup')
fab_deploy.utils.inside_src(func)[source]

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

fab_deploy.utils.run_as_sudo(func)[source]

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
from fab_deploy import utils

@utils.run_as_sudo
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 import *

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

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