dalembertian / fabmanager

Useful set of Fabric commands to manage Django projects using virtualenv, git, MySQL

fabmanager

fabmanager is a set of useful tasks to be used with Fabric[1] to manage Django projects. It provides commands such as:

bootstrap           Builds everything from scratch: installs and configures python, git, virtualenv, Apache, MySQL, etc.
update_project      Uploads latest git master branch, invokes Django and South to update things (DBs, statics, etc.), and touches the WSGI file to restart app
backup_database     Backs up (and optionally downloads) a .tar.gz with the MySQL dump of the production database
restore_database    Restores the database, either remotelly or locally, from a previous .tar.gz generated by backup_database
find_in_log         Searches remote Django log for patterns
gen_apache_conf     Prepares the needed Apache (and WSGI) conf files for production
install_apache      Installation of several tools
install_git
install_mysql
install_python

Use fab -l to see the complete list, after installation.

Fabmanager expects the following:

• Apache 2.4
• MySQL 5.5 (maybe >= 5.0 is OK)
• mod_wsgi 3.4
• Django 1.6 (maybe >= 1.4 is OK [2])
• South 0.8
• fab-classic 1.19.1
• pip, virtualenv, virtualenvwrapper

[1] Fabric is a Python tool for application deployment and systems administration over SSH. Fabmanager was created for Fabric 1.x, and it's not compatible with Fabric 2.x. For this reason, it's now using fab-classic, a fork of Fabrix 1.14 with added support for Python 3.

[2] There is a branch called "django1.3" that's compatible with Django 1.3. I've then jumped directly to Django 1.6, but I believe the new directory structure was introduced in Django 1.4, so the master branch should probably work with Django 1.4 or higher - I only tested it with Django 1.6, though.

Contents

Installation

Currently fabmanager should be installed from source. The easiest way is using pip:

Django 1.4+:
$ pip install [-e] git+https://github.com/dalembertian/fabmanager.git

Django 1.3:
$ pip install [-e] git+https://github.com/dalembertian/fabmanager.git@django1.3

The option -e asks pip to install the complete source files. It can also be installed by first cloning the repository and then running setup.py, or even pip:

$ git clone git://github.com/dalembertian/fabmanager.git
$ cd fabmanager
$ python setup.py install
  or
$ pip install .

Instructions

• Create a fabfile.py at your Django project's directory (e.g.: $VIRTUAL_ENV/project), with the following imports:

  from fabmanager import fabfile
  from fabmanager.fabfile import *
  

• Extend (do not replace!) the ENVS dictionary. See below for an example and the complete description of all possible entries.

• Create tasks for each environment you defined in ENVS, so that they can be specified in the command line (e.g.: fab myenv task):

  def myenv():
      fabfile._setup_environment('myenv')
  

• That's it!

Reference

ENVS dictionary

An empty ENVS dictionary is defined by fabmanager/fabfile.py. Your project's fabfile.py must extend (not replace!) this dictionary with an update() command:

ENVS.update({
    'myenv': {
        'host': 'servername.domain.com',
        'workon': '/opt/python',
        'virtualenv': 'myvirtualenv',
        'project': 'myproject',
        'settings': 'settings',
        etc.

Below is the complete list of parameters. Starred items are usually mandatory:

* host                Name or IP of the remote server
  host_alias          Host alias(es), separated by ' ', for Apache conf file
  user                Username to use on remote server (defaults do current local username)
  password            Password for the remote username (defaults to None, that is, it's going to be asked during the process)
* workon              Parent of the virtualenv directory (equals virtualenvwrapper WORKON_HOME)
* virtualenv          Virtualenv name
* project             Project name. Actual project location is thus given by $workon/$virtualenv/$project
* settings            settings.py being used (e.g.: 'settings', 'settings_custom')
  database            Dictionary of database settings (as defined in settings.py). If not provided, extracts from current settings.py.
  git_repo            Git repo, mandatory if setup is being made by fabmanager
  git_branch          If not provided, 'master' is assumed
  extra_commands      List of commands to be issued at the project's dir level, during setup, after git clone
  extra_backup_files  List of extra files, besides the database SQL dump, that should go into a backup (from project' dir level)

See also the sample fabfile.py provided.

To Do List

• MySQL asks for root's password for each single command; it would be better to ask the user once and reuse, but without showing it on the console - how?

License

This software is licensed under the New BSD License. See the LICENSE file in the top distribution directory for the full license text.