Deployer

Deployer is a script to simplify the deployment of files and directories. We use it to deploy code to edge systems, keeping code and deployer configuration alike in our version control system. This very website is "deployed" on a regular bassis.

Download Deployer

NAME

deployer.pl

SYNOPSIS

deployer.pl TAG

deployer.pl -c CONFIG TAG

deployer.pl -b -c CONFIG

DESCRIPTION

Deployer is a script to deploy files or file trees to remote locations using rsync via ssh. Its purpose is to allow for standardizing complex deployment scenarios into a more digestible format at the command line. A user needs only remember a configured tag name for a set of deployments, rather than source directories, remote locations, and hostnames.

Deployer requires a config file, and arguments to describe what tags will be deployed, with options to modify behavior. Tags are merely user-identifiable names for a group of source files and their associated destination locations. Options and arguments can come in any order.

Deployer searches for a configuration file in ~/.deployer.conf, and then /etc/deployer.conf in that order, taking the first one found and failing if neither exists. This does not apply if a config file is specified on the command-line: it must exist, or deployer will exit without failing over.

CONFIGURATION

The configuration file syntax for deployer is based around the very simple idea of a tag, which is simply a name to describe a given pairing of source files with a destination location:

 mytag          /path/to/src            somebody@host.example.com:/path/to/dest

Static Pre-defined Variables

A number of pre-defined variables can be defined over and over in the configuration file to simplify configuration, essentially functioning as macros at time of deployment. They must begin the line. Using the syntax =variable:value, the above can be re-written thus:

 =docroot:/path/to
 =user:somebody
 =defaultdomain:example.com
 =remdocroot:/path/to/dest
 
 mytag          src                                     host

Static variables can be divided roughly into expansion variables that provide for macro-like expansion at time of deployment, and deployment variables that change the behavior of deployer at time of deployment.

Expansion Variables

These all allow for tilde (~) and list (@) expansion.

=defaultdomain:example.com

Define the default domain that will be appended (only) to any non-fully-qualified domain names in all following tags.

=docroot:/path/to/src

Define the path to the source directory that will be applied (only) to any non-fully-qualifed source paths in all following tags. Deployer currently expects that at root, each tag source will consist of at least the last atom of the path (src in /path/to/src).

=password:password

Define the password that will be applied (only) to any user that does not have password defined as part of the username (user%password). Proverbial rope for hanging onself. Use ssh keys instead of defining plaintext passwords in text files.

=remdocroot:/path/to/dest

Define the path to the destination directory that will be applied (only) to any non-fully qualified destination paths in all following tags. Deployer currently expects that at root, each tag destination will consist of at least the hostname.

=user:user

Define the username that will be applied (only) to any host that does not have a username defined in all following tags.

@list:item1,item2,item3

Define a list of items to be referenced in a config. List definitions begin the line with @name:item1,item2,item3, and are later referenced using @name. This option is deprecated, use dynamic pre-processor variables instead.

Deployment Variables

These are not expanded by other static variables, nor do they expand tilde (~) or lists (@).

=include:/path/to/include.conf

Include another deployer config file. Tags from included files are parsed and stored in the same global config hash as all other config tags.

=rsyncopts:-rlptD -v ...

Override the rsync options used for all following tags. Default is defined in global @RSYNC_DEF_OPTS.

=preexec:run some local command

=rempreexec:run some remote command

=postexec:run some local command

=rempostexec:run some remote command

Run commands on the local and/or remote host, before and/or after deployment.

Dynamic Pre-processor Variables

Users can define their own custom variables to be used anywhere in the config. The pre-processor will always parse, if it exists, ~/.deployer.conf for variables, EVEN IF A DIFFERENT CONFIG FILE HAS BEEN SPECIFIED. Dynamic variable definitions begin the line with %name:value and are referenced by $name.

 %somepath:files
 
 mytag          /path/to/$somepath              somebody@host.example.com:/path/to/dest

Future versions of deployer may make use of these almost exclusively.

OPTIONS

A number of command-line options affect deployer behavior.

-b, --batch

Deploy all instances of all tags in config file. Note that a config file must be specified (-c) for batch mode.

-c, --config=/path/to/config

Specify path to a config file. If it does not exist, deployer fails.

--diff

Reverse deploy from host to local ~/.deployer directory and present a unified diff. Considered experimental, run in dryrun (-n, --dryrun) first.

--help

Brief help message.

-n, --dryrun

Show what would be done.

-o, --override=statvar1=value,statvar2=value

Override static configuration variables at the command-line. This can be useful for tricky generic deployments, choosing host at deploy time for instance. Static variables that can be overridden include: defaultdomain, docroot, host, password, remdocroot, and user.

-v, --verbose

Increase verbosity.

Some arguments have changed since initial release. The arguments 'dryrun' and 'verbose' are no longer passed down to rsync. The 'list' argument for listing all the sources and destinations in a given config file with expanded variables was quite bizarre and has been removed. The 'dryrun' argument does that same thing for a specific tag, and combined with 'batch' will produce the same behavior.

EXAMPLES

Sample Config

Assume the following sample configuration stored in ~/.deployer.conf:

 #tag   #src files                                              #destination locations
 
 # first with no variables
 test0  ~/workspace/perl/test.pl,~/workspace/testproject        somebody@helios.example.com:/home/somebody,somebody@armk.example.com:/home/somebody
 test1  /home/hardyjm/workspace/perl/sample.pl                  somebody@fritz.example.com:/home/somebody,somebody@midas.example.com:/home/somebody
 
 # then with some useful variables specified
 =docroot:~/workspace
 =user:somebody
 =defaultdomain:example.com
 =remdocroot:~
 
 test2  perl/test.pl,testproject                                helios,armk
 test3  perl/test.pl,testproject                                fritz,midas
 
 # set the variables back to null
 =docroot:
 =user:
 =defaultdomain:
 =remdocroot:
 
 test4  testproject                                             helios
 
 # rsync options can also be overridden from defaults in script
 =rsyncopts:-a --exclude=test.sh
 
 test5  testproject                                             helios

Example Runs

And now some example runs on the above configuration:

 $ deployer.pl test0
 === test0:0 ===
 rsync /home/hardyjm/workspace/perl/test.pl somebody@helios.example.com:/home/somebody
 rsync /home/hardyjm/workspace/perl/test.pl somebody@armk.example.com:/home/somebody
 rsync /home/hardyjm/workspace/testproject somebody@helios.example.com:/home/somebody
 rsync /home/hardyjm/workspace/testproject somebody@armk.example.com:/home/somebody
 $ deployer.pl test1
 === test1:0 ===
 rsync /home/hardyjm/workspace/perl/sample.pl somebody@fritz.example.com:/home/somebody
 rsync /home/hardyjm/workspace/perl/sample.pl somebody@midas.example.com:/home/somebody
 $ deployer.pl test2
 === test2:0 ===
 rsync /home/hardyjm/workspace/perl/test.pl somebody@helios.example.com:~/
 rsync /home/hardyjm/workspace/perl/test.pl somebody@armk.example.com:~/
 rsync /home/hardyjm/workspace/testproject somebody@helios.example.com:~/
 rsync /home/hardyjm/workspace/testproject somebody@armk.example.com:~/
 $ deployer.pl test3
 === test3:0 ===
 rsync /home/hardyjm/workspace/perl/sample.pl somebody@helios.example.com:~/
 rsync /home/hardyjm/workspace/perl/sample.pl somebody@helios.example.com:~/
 $ deployer.pl test4
 === test4:0 ===
 rsync testproject helios:
 ssh: Could not resolve hostname helios: Name or service not known

Many of the fancy variable substitions are presented here. Tests 0 and 2, and 1 and 3 are identical in their results, but specified very differently in the config. Also notice that the variables can be reset throughout the config, and even set back to NULL, which causes test 4 to fail. Lastly, a tag may be specified more than once so if we wanted all the files presented by tags 0 and 2 to go out at once, we could simply name them the same thing.

CHANGES

deployer.pl 1.00 (20120516)

- Initial release.