BackupFu
========

The backup_fu plugin makes it redonkulously easy to:

 A) dump your database and/or static files to tar/gzipped or zipped archives, and
 B) upload these archives to a private Amazon S3 bucket for safekeeping

Allows restore of PostgreSQL databases.

It also uses credentials in config/amazon_s3.yml if not supplied in backup_fu.yml

Installation
============

The 'right_aws' gem is required for backup_fu to function properly.  Install with:

  sudo gem install right_aws

Install the plugin with:

  script/plugin install git://github.com/gravelpup/backup_fu.git


Configuration
=============

Run the following to copy over the example backup_fu.yml config file:

  rake backup_fu:setup

This copies the example config file to: config/backup_fu.yml.

For encryption support, you can run:

  rake backup_fu:setup_encryption

This will generate the encryption files/keys for encrypting your archives. This command runs
an interactive program (which is just `gpg --gen-key`). You can mostly choose the default values for
generating this key, or choose your own settings if you are familiar with encrypting with gpg. Of course,
for this to work you must have a system with gpg already installed. Type `which gpg` to find out if you
have this command in your path.
After generating the gpg keys, you must still make changes to your backup_fu.yml file to tell backup_fu
which user's key to sign the encrypted file with (so you can decrypt it later if needed).
See vendor/plugins/backup_fu/config/backup_fu.yml.advanced_example for example.

Usage
=====

For the list of available rake tasks:

  rake -T backup_fu

Backing up your database:

  rake backup

Dumping your database:

  rake backup_fu:dump

Backing up your static files:

  rake backup_fu:static:backup

Backing up both your database + static files:

  rake backup_fu:all

Restoring from S3:
  BACKUP_FILE=myapp_1999-12-31_12345679_db.tar.gz rake backup_fu:restore
  
Advanced Configuration
======================

See vendor/plugins/backup_fu/config/backup_fu.yml.advanced_example for
the list of advanced configuration options.

Advanced options include:
* specify static path(s) that should be backed up -- i.e. backup your entire 'public/static' directory
* change default dump path from RAILS_ROOT/tmp/backup to whatever
* specify fully-qualified 'mysqldump' path
* disable compression of database dump
* choose between zip or tar/gzip compression
* enable encryption on systems with the gpg program available
* enable 'nice' with level specification to prevent backup_fu from bogarting your server

Cronjob Installation
====================

Here are some cron job examples.

	# Backup just the database everyday at 1am
	0 1 * * * cd /apps/foo/current; RAILS_ENV=production rake backup > /dev/null

  # Backup db + static @ 2am every 3 days, log the results to ~/backup.log (verbosity should be turned on if logging results)
  0 2 1-31/3  * * cd /u/apps/shanti.railsblog/current; RAILS_ENV=production rake backup_fu:all >> ~/backup.log


Debugging
=========

--- Enabling Verbosity

If you are experiencing any difficulties, the first thing you should do is enable verbosity by
dropping this into config/backup_fu.yml:

  verbose: true
	
--- Mysqldump Issues

If your 'mysqldump' command is not in your path, you will need to specify it explicitly.

To see if mysqldump is in your path, execute:

  which mysqldump

If you see output like "/usr/bin/which: no mysqldump in (...)" then you will need to specify the path manually.

Use 'locate mysqldump' or a similar tool to find the full path to your mysqldump utility.

Place an entry like the following in your config/backup_fu.yml file:

  mysqldump_path: /usr/local/mysql-standard-5.0.27-linux-i686/bin/mysqldump

--- Database Connection Issues

If you are seeing an error when running 'rake backup' like:

  mysqldump: Got error: 2002: Can't connect to local MySQL server ...

Make sure you are specifying the RAILS_ENV for the target environment.  i.e. for production:

  RAILS_ENV=production rake backup
  or
  rake backup RAILS_ENV=production

--- Connection reset by peer

When backing up, if you receive an error like:

  rake aborted!
  Connection reset by peer

Chances are this is because your backup is huuge.  There is currently no great solution for
this problem.

On some systems, I have backed up 4GB+ files without a hitch.  On other machines, an 80mb
backup was choking on the S3 upload.  After 3 attempts it went through.

Patching in some kind of email notification system on failure would probably be nice.

Patches welcome =)

--- Tiny Static file .tar.gz Archive (static files not actually getting archived)

This may result if you are using a symlink for your static dir, such as:

  public/static -> /shared/apps/foo/static

The solution to this is to specify the absolute static path in config/backup_fu.yml:
 
  static_paths: /shared/apps/foo/static



Copyright (c) 2009, released under the MIT license