Push is a perl script to deploy code to one or more remote servers. ------------------------------------------------------------------------------- USAGE ------------------------------------------------------------------------------- push [options] [target [target2 [target3] ...]] Options: -p Only push the specified file or directory. --partial= -c, --clean Remove remote files and directories that don't exist locally (same as in config). -f, --force Force update all remote files, even if sizes and modtimes match (may take a long time). -h, --help Print this help message. For examples, see EXAMPLES below. ------------------------------------------------------------------------------- CONFIGURATION FILE ------------------------------------------------------------------------------- The configuration file is named "push.xml" and should be placed in the project root directory. When you run "push" anywhere in the project tree, it will find its configuration in the project root and push code out to the deployment target specified on the command line. If you wish to override the config filename, you can use the -f/--file switch. A sample configuration file is below: 10.1.1.1 10.1.1.2 10.1.1.3 10.2.1.1 10.2.1.2 10.2.1.3 10.1.1.4 10.1.1.5 cp ${root}/config/default.inc.php ${root}/www/lib/config/ sudo /usr/local/apache22/bin/apachectl reload

lib/local.inc.php

updateconfig myproject.primary-colo myproject.backup-colo reloadapache

lib/local.inc.php

myproject.staging

lib/local.inc.php

myproject.proofing The main element of a configuration file is the element. Use this to give your project a name, and specify a default target to execute if none is provided. Within the element are multiple elements. Although you can define other types of elements (, , ) outside of a element to make them global, it is usually advised to define them in a element and call it via the "depends" attribute when needed. With the sample configuration above, if a user ran "push live", the following would happen: 1) Since the "depends" attribute is set on the "live" target, the "init" target is found, and all serverset and commandset definitions are loaded. 2) All dependencies are met, so execution begins on the "live" target 3) The "updateconfig" commandset is executed, which copies the local file "config/default.inc.php" to "www/lib/config/". 4) The "www" directory is pushed to /usr/local/www/myproject.com/www on 10.1.1.1, connecting over SSH as the "www" user. www/lib/local.inc.php is not copied to the server. 5) The "reloadapache" commandset is executed, which remotely reloads the web server on 10.1.1.1 to clear any code cache. 6) Steps 4 and 5 are repeated for the servers 10.1.1.2, 10.1.1.3, 10.2.1.1, 10.2.1.2, and 10.2.1.3. 7) Push is complete. ------------------------------------------------------------------------------- USING PROPERTIES ------------------------------------------------------------------------------- Any properties defined in the configuration file (see ELEMENT REFERENCE below) can be referenced in any other attribute or element body using the notation ${propname}. For example, in the sample file above, the "myproject.proofing" serverset uses the following path: usr/local/www/proofing/{$user}/myproject.com/www This results in a unique destination path for each user, since the "user" property is automatically set by push each time it is executed. Built-in properties are: user The currently logged in username root The directory that push.xml is located in Other properties can be defined in push.xml, or on a user-specific basis in ~/.push-global.xml. The structure of ~/.push-global.xml is identical to push.xml, except that instead of a element, the top-level element is , and only properties, serversets and commandsets may be defined in it. This can be useful to override built-in properties like ${user} if you are logged in under a different username than the server is expecting. In this case, you can create a ~/.push-global.xml file containing the following: ------------------------------------------------------------------------------- ELEMENT REFERENCE ------------------------------------------------------------------------------- Defines a set of commands to execute before or after a push as defined in the element. Attributes: id A unique id for the commandset scope The scope of this commandset. Possible values are: single: The set of commands is executed (in order) once for each server being pushed to. group: The set of commands is executed (in order) once for for the entire push. Always assumes execute="local". execute Where to execute the command(s). Possible values are: local: Execute the command(s) locally. remote: Execute the command(s) remotely via SSH (only when using ). Body text: None Child elements: command Context: , , Defines a single command in a Attributes: None Body text: The command to execute Child elements: None Context:

Specifies an external file to load configuration from Attributes: None Body text: A local path or remote URL for the configuration file. Child elements: None Context: , , The root element of a user's global configuration file Attributes: None Body text: None Child elements: commandset include-file property serverset target Context: Top level element Exclude the specified file path from the push Attributes: None Body text: A pattern of files to exclude from the push. To match subdirectories, use "**". For example, the attribute exclude="**/local.inc.php" will omit all files named local.inc.php in any directory of the project. This can be useful to prevent local testing configuration from being deployed to a production server. Child elements: None Context: Specifies a commandset to execute AFTER the push occurs. Whether it is executed locally or remotely, and once per server or once per push, is defined in the element Attributes: None Body text: The id of the commandset to execute Child elements: None Context: Specifies a commandset to execute BEFORE the push occurs. Whether it is executed locally or remotely, and once per server or once per push, is defined in the element Attributes: None Body text: The id of the commandset to execute Child elements: None Context: Defines a named property Attributes: name The name of the property value The value of the property Body text: None Child elements: None Context: , , The root element of a push configuration file Attributes: id A unique id for the project name A descriptive name for the project default The default target to execute if none is specified on the command line Body text: None Child elements: commandset include-file property serverset target Context: Top level element Pushes the named files or directories to the specifed serversets Attributes: localdir The local directory to push out. This is relative to the project root (where push.xml is located). To push out all directories, omit this attribute. remotedir The remote directory to push to. This is relative to the path. exclude A pattern of files to exclude from the push. To match subdirectories, use "**". For example, the attribute exclude="**/local.inc.php" will omit all files named local.inc.php in any directory of the project. This can be useful to prevent local testing configuration from being deployed to a production server. clean If set to "true", the push will not only push out files to the remote server, but it will all remove any files from the remote server that do not exist locally. Use this option with care if your application writes data to the source code directory. Body text: None Child elements: serverset prepcmd postcmd Context: Defines a set of servers to push a project out to Attributes: id A unique id for the serverset. mode The transport mode; either "rsync", "ssh" or "ftp". "ssh" is the recommended mode for security reasons; to avoid typing in a password each time, you should enable public key authentication on your servers and make sure all of your users' public keys are registered with the push account (in the sample above, "www") on the servers they have permission to push to. If "ftp" is specified, the "user" and "password" fields must be set. path The remote path to push the code to. user The user to connect as (when using mode="ftp" or mode="ssh"). password The password to connect with (when using mode="ftp"). Body text: None, except when used in an tag, in which case the element should set no attributes and simply reference the serverset id in the body (i.e. myServer). Child elements: server Context: , , Defines a single server in a Attributes: None Body text: The domain or IP of the server Child elements: None Context: Defines a set of properties or actions to execute Attributes: id A unique id for the target depends A comma-separated list of targets that must be executed before this one can be successfully executed Body text: None Child elements: commandset include-file property sync serverset Context: ------------------------------------------------------------------------------- EXAMPLES ------------------------------------------------------------------------------- Push all files to the "live" target: push live Push all files to the "staging" and "proofing" targets: push staging proofing Push only the "data" directory to staging: push -p data staging Push all files to the default target: push ------------------------------------------------------------------------------- SYSTEM REQUIREMENTS ------------------------------------------------------------------------------- Perl libraries: POSIX XML::Simple Getopt::Long LWP::UserAgent File::Basename Local executables: ssh (only if using mode="ssh") ftp (only if using mode="ftp") whoami rsync Remote executables: sshd (only if using mode="ssh") rsync ------------------------------------------------------------------------------- CREDITS ------------------------------------------------------------------------------- Author: Jeremy Jongsma (jeremy@jongsma.org)