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.
deployer.pl -c CONFIG TAG
deployer.pl -b -c CONFIG
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.
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 email@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:
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.
These all allow for tilde (~) and list (@) expansion.
Define the default domain that will be appended (only) to any
non-fully-qualified domain names in all following tags.
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).
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
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
Define the username that will be applied (only) to any host that does not have
a username defined in all following tags.
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.
These are not expanded by other static variables, nor do they expand tilde (~)
or lists (@).
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
- =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
mytag /path/to/$somepath firstname.lastname@example.org:/path/to/dest
Future versions of deployer may make use of these almost exclusively.
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.
Reverse deploy from host to local ~/.deployer directory and present a unified
diff. Considered experimental, run in dryrun (-n, --dryrun) first.
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
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
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 email@example.com:/home/somebody,firstname.lastname@example.org:/home/somebody
test1 /home/hardyjm/workspace/perl/sample.pl email@example.com:/home/somebody,firstname.lastname@example.org:/home/somebody
# then with some useful variables specified
test2 perl/test.pl,testproject helios,armk
test3 perl/test.pl,testproject fritz,midas
# set the variables back to null
test4 testproject helios
# rsync options can also be overridden from defaults in script
test5 testproject helios
And now some example runs on the above configuration:
$ deployer.pl test0
=== test0:0 ===
rsync /home/hardyjm/workspace/perl/test.pl email@example.com:/home/somebody
rsync /home/hardyjm/workspace/perl/test.pl firstname.lastname@example.org:/home/somebody
rsync /home/hardyjm/workspace/testproject email@example.com:/home/somebody
rsync /home/hardyjm/workspace/testproject firstname.lastname@example.org:/home/somebody
$ deployer.pl test1
=== test1:0 ===
rsync /home/hardyjm/workspace/perl/sample.pl email@example.com:/home/somebody
rsync /home/hardyjm/workspace/perl/sample.pl firstname.lastname@example.org:/home/somebody
$ deployer.pl test2
=== test2:0 ===
rsync /home/hardyjm/workspace/perl/test.pl email@example.com:~/
rsync /home/hardyjm/workspace/perl/test.pl firstname.lastname@example.org:~/
rsync /home/hardyjm/workspace/testproject email@example.com:~/
rsync /home/hardyjm/workspace/testproject firstname.lastname@example.org:~/
$ deployer.pl test3
=== test3:0 ===
rsync /home/hardyjm/workspace/perl/sample.pl email@example.com:~/
rsync /home/hardyjm/workspace/perl/sample.pl firstname.lastname@example.org:~/
$ 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.
deployer.pl 1.00 (20120516)
- Initial release.