Getting Started

Getting Started with Backup

To get started with Backup, install the gem:

$ gem install backup

This will install the latest version of Backup, along with the Thor and POpen4 gems. These gems are required to operate the command line interface and inspect all unix commands/processes. There are a lot of other dependencies that are NOT installed when you install the Backup gem. This is because it may conflict with gems in your environment and will literally put you in "dependency hell". When you manually try to run your backup later, Backup will check what dependencies are required to perform your backup and guide you through the installation process by providing all the commands you need to run. It's easy and self-explanatory once you try to run a backup for the first time, so don't worry.

Anyway, let's generate a simple Backup model file:

$ backup generate:model --trigger my_backup --databases='mysql' --storages='s3' --compressors='gzip'

(For a full list of options, view the Generator Page)

The above generator will provide us with a backup model file (located in ~/Backup/models/my_backup.rb) that looks like this:

##
# Backup Generated: my_backup
# Once configured, you can run the backup with the following command:
#
# $ backup perform -t my_backup [-c <path_to_configuration_file>]
#
Backup::Model.new(:my_backup, 'Description for my_backup') do
  ##
  # Split [Splitter]
  #
  # Split the backup file in to chunks of 250 megabytes
  # if the backup file size exceeds 250 megabytes
  #
  split_into_chunks_of 250

  ##
  # MySQL [Database]
  #
  database MySQL do |db|
    db.name               = "my_database_name"
    db.username           = "my_username"
    db.password           = "my_password"
    db.host               = "localhost"
    db.port               = 3306
    db.socket             = "/tmp/mysql.sock"
    db.skip_tables        = ['skip', 'these', 'tables']
    db.only_tables        = ['only', 'these' 'tables']
    db.additional_options = ['--quick', '--single-transaction']
  end

  ##
  # Amazon Simple Storage Service [Storage]
  #
  # Available Regions:
  #
  #  - ap-northeast-1
  #  - ap-southeast-1
  #  - eu-west-1
  #  - us-east-1
  #  - us-west-1
  #
  store_with S3 do |s3|
    s3.access_key_id      = 'my_access_key_id'
    s3.secret_access_key  = 'my_secret_access_key'
    s3.region             = 'us-east-1'
    s3.bucket             = 'bucket-name'
    s3.path               = '/path/to/my/backups'
    s3.keep               = 10
  end

  ##
  # Gzip [Compressor]
  #
  compress_with Gzip do |compression|
    compression.level = 6
  end

end

Now just omit the options you do not care about in this configuration file, and fill in the options of the remaining values.

Once you're done, you can run this backup process by issuing the following command:

$ backup perform --trigger my_backup

The my_backup refers to the :my_backup symbol in:

Backup::Model.new(:my_backup, 'My Backup') do

You may change this trigger to whatever you like.

You will also notice, this generated a ~/Backup/config.rb file.

This is Backup's main configuration file. When you run the backup with the command above, Backup will look for this file. This is where you will setup any global defaults. It is setup to automatically include all your model files in ~/Backup/models. See the Generator page for details.

That's it.

I highly encourage you to just briefly look through the Wiki pages to see what Backup is capable of doing and how it works. It's very simple, but worth a read to see how to set it up and configure it to your needs.