fabfile

Setup

Hosts

Create a .fabhosts in your project directory. It is a JSON file with the following structure:

{
    "_": {
        "host_string": "example.com",
        "path": "~/sites/project-env/project",
        "repo_url": "git@github.com/bruth/project.git",
        "nginx_conf_dir": "~/etc/nginx/conf.d",
        "supervisor_conf_dir": "~/etc/supervisor.d"
    },
    "production": {},
    "development": {
        "host_string": "dev.example.com",
        "path": "~/sites/project-dev-env/project"
    },
    "staging": {
        "host_string": "stage.example.com",
        "path": "~/sites/project-stage-env/project"
    }
}

The "_" entry acts as the default/fallback across all host settings, so you only have to define the host-specific settings. The below settings are required:

• host_string - hostname or IP address of the host server
• path - path to the deployed project within it's virtual environment
• repo_url - URL to project git repository
• nginx_conf_dir - path to host's nginx conf.d directory
• supervisor_conf_dir - path to host's supervisor

Note, additional settings can be defined and will be set on the env object, but the above settings are required at a minimum.

Server Configs

The server/ directory contains directories corresponding to each server/service that is used by the application. Currently, this includes:

• nginx/ - nginx configuration files
• supervisor/ - supervisor configuration files
• uwsgi/ - uwsgi configuration files

Each directory contains files named after each host:

server/
    nginx/
        production.conf
        development.conf
        staging.conf
    supervisor/
        ...
    uwsgi/
        ...

For other services, this pattern should be used to maintain consistency.

Settings

The local_settings.py file is ignored by default from version control since it contains sensitive and/or host-specific settings. If a settings/ directory is present in the project directory, it will copy the host-specific settings file to the deployed project in myproject/conf/local_settings.py.

As mentioned above, files in settings/ are named after the host it corresponds to, e.g. settings/production.py.

Usage

The deploy command is intended to act as the big green button for deployment since it performs all necessary steps and checks for issues along the way.

Single Host

fab -H development deploy:master@abc123

Multiple Hosts

Comma separate hosts (no spaces) to deploy the same revision across hosts.

fab -H development,production deploy:master@abc123

Commands

Although other commands exist, below are the primary ones that encapsulate the other helper commands.

deploy(commit, [force=False])

Single command deploy. This works the same for first time and subsequent deployments. This includes the following steps:

• Creates a virtual environment at the parent of the path defined in the host settings (initial)
• Uploads host-specific settings to project/conf/local_settings.py
• Turns on maintenance mode
• Clones (initial), fetches, merges and checkouts a particular branch, tag or commit based on the commit argument
• Installs dependencies using Pip. If force is true, Pip will be forced to update to the latest allowed versions of each dependency.
• Run Django's syncdb command with the --migrate flag to trigger South migrations for apps that support it
• Runs make which utilizes the supplied Makefile for compiling and collecting static files using Django's collectstatic command
• Reloads nginx
• Updates supervisord to add/update the project's supervisor config
• Reloads the uwsgi process (via supervisor)
• Turns off maintenance mode

mm_on

Turns maintenance mode on.

mm_off

Turns maintenance mode off.