fabfile.py API¶
Overview¶
Write a function populating
env.hosts
andenv.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 fabric.api import env, task from fab_deploy.utils import update_env @task 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
andenv.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 andenv.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
orfab_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 becomeenv.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()
andfab_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.
-
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 run, task from fab_deploy.utils import inside_project @task @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, task from fab_deploy import utils @task @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 callsupdate_env()
:from fab_deploy.utils import define_host @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.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'.