Frak is a deployment tool that uses rsync to upload file changes to remote servers. With this tool you can rapidly deploy code without having to commit it into your version control repository, which, although controversial to some, is preferred when working in a fast-paced environment.

Simply copy the bin/frak file to a location in your $PATH. Or, you can symlink it as well.

$ git clone https://github.com/fstrube/frak.git
$ ln -s `pwd`/frak/bin/frak ~/bin/frak

The frak script relies on the Highline gem for prompting and ANSI-colored output. Simply run gem install highline and you should be good to go.

Also, you will need rsync installed on your machine. This should already be installed in most cases. However, if it is not installed you can find it in your Homebrew or apt repositories.

All configuration options are stored in a dotfile in the root of your project. This dotfile contains the details necessary to deploy your application. You can run the command frak init in the root of your project to get the configuration process started. Below is a sample configuration file.

label: Example Frak Project
server: dev.example.com
remote_path: /var/www/com.example
after: cd /var/www/com.example; rm cache/*
method: rsync
become: true

stage:
  server: dev.example.com

production:
  server: www.example.com
  webhook_url: http://api.example.com/frak/frak.php

You can see in the example above that there are three environments. The first four lines constitute the "default" environment. Then, you have a "stage" environment and a "production" environment where the server option varies. You can specify which environment to use when you run frak by doing frak env=production.

By default, frak will backup your file changes to a .backups folder on the remote server in the path specified by the remote_path configuration parameter. Backups contain full copies of any modified or deleted files, as well as a patch file containing line-by-line changes. Currently, restoring from backup is still a manual process.

Backups will remain available for 30 days by default, but you can set the retention policy with the backup_retention parameter in the configuration.

When deploying your app, often times you will want to exclude certain files and directories from being pushed to the server. By default, frak will ignore the following files:

- .frak*
- .git*
- .svn*
- .tags*
- Capfile
- Gemfile*
- Vagrantfile*

You can tell frak to ignore additional files by configuring a .frakignore file. The syntax of this file follows rsync's filter rules. Refer to the Filter Rules section in the rsync man pages. The most common filter is the exclude pattern, as seen below:

# Sample .frakignore file
- var/log
- *.bak
- *.DS_Store

By default, simply running frak will attempt to deploy your application. A dry-run is always conducted first, and you are prompted whether or not you want to continue with the deployment. Other commands exist to allow you to pull changes from the server to your local copy, view the diff between your files locally and on the remote server, and execute commands on the remote server.

 Usage: frak <command> [option=value option=value ...]

 Commands
   init          Initialize the current directory for frak deployment
   console       Connect to the remote server via SSH
   diff          Show differences between local and remote files
   pull          Download the remote file(s)
   push          Deploy website via the method specified in the config
   backups:list  List any backups found on the server
   backups:purge Purge all backups
   --help        Display this help message
   --version     Display the current version of frak, also checks for upgrades

 Options
   label         a short name for the project, used by webhooks
   env           load the specified environment into the config
   method        currently only supports rsync
   command       execute a command on the remote server
   path          defaults to current directory
   remote_path   override what is read from .frak file
   rsync_path    override the rsync-path read from .frak file (if present)
   ignore        ignore certain files or folders when deploying
   webhook_url   URL for a webhook which will receive information about the code pushed via frak

 Examples

   Execute a command on your deployment server:
     frak console command="vi index.html"

   Compare specific files before deploying:
     frak diff path="*.html"

   Deploy files but exclude certain paths:
     frak ignore="logs uploads"

As of version 1.1.0, frak keeps itself up-to-date with the latest code on Github. Any time a new version is available, you will be prompted to update the frak executable.