Snooze Deployment Tool

Snooze is a deployment tool written in Java that can be used to deploy projects to multiple servers using SSH and Subversion.

A common case for this is to deploy website code to multiple webservers.

Download

Snooze 1.0	snooze-1.0.zip	Download
Snooze 1.0 Source	snooze-1.0-src.zip	Download

Convensions

The assumption is made that a number of conventions are followed, which can be further extended with configuration on a per project basis.

Authentication

Snooze makes the assumption that SSH keys are setup to allow password-less logins to the deployment servers and to subversion.

Subversion

Projects are maintained within subversion with the following layout.

Main development	/<repository>/<project>/trunk
Development branches	/<repository>/<project>/branches/<branch>
Release branches	/<repository>/<project>/branches/releases/<version>
Release tags	/<repository>/<project>/tags/<version>

Deployment locations

Projects are deployed to one or more servers with the following mirrored layout. For a webserver the active directory would be configured to be the document root.

Live directory	/<deployment root>/<project>/active
Switching directory	/<deployment root>/<project>/spare

Deployment lifecycle

Deploying new features to production.

A new release branch version number is created from the development branch (trunk).
The release branch is deployed to a testing environment.
Any fixes or changes are made on the development branch (trunk), merged into the release branch and then redeployed to the testing environment.
A tag of the same version number is created from the release branch once that release branch has passed testing.
The tag is deployed to the production environment.

Deploying bug fixes to production.

Fixes are made on the development branch (trunk).
Those fixes (and only those fixes) are merged into the current release branch. The current release branch is the branch of which the currently deployed tag was derived from.
The release branch is deployed to a testing environment.
Any further fixes or changes are made on the development branch (trunk), merged into the release branch and then redeployed to the testing environment.
A new tag is created from the release branch once that release branch has passed testing. The version number remains the same, however "-pX" is appended, where X is an incremented integer.
The tag is deployed to the production environment.

Tasks

Snooze is comprised as a collection of tasks. The following core tasks are used to perform the above deployment lifecycle.

Creation of a release branch from the development branch (trunk).
Creation of a tag from a release branch.
Updating of the switching directory to a specified tag, (using svn switch or svn checkout).
Deployment of the switching directory to the live directory, (the live and switching directories are swapped).

The help task "./bin/release help" or "./bin/release help <task>" can be run to view further details.

Configuration

Configuration is maintained within the file ./etc/conf.xml. An example configuration is shown below.

<?xml version="1.0" encoding="UTF-8" ?>
<release>

	<!--
	The user to login with on the deployment servers, 
	SSH keys should be set up to allow password-less logins.
	-->
	<config>
		<remote-user>www</remote-user>
	</config>

	<!-- A list of server names against IP addresses or hostnames -->
	<servers>
		<server>
			<name>web-1</name>
			<host>1.2.3.4</host>
		</server>
		<server>
			<name>web-2</name>
			<host>2.3.4.5</host>
		</server>
		<server>
			<name>test-web-1</name>
			<host>1.1.1.1</host>
		</server>
	</servers>

	<!-- 
	A logical grouping of servers,
	it is acceptable for a server to exist in multiple groups
	-->
	<clusters>
		<cluster name="prod">
			<server>web-1</server>
			<server>web-2</server>
		</cluster>
		<cluster name="stage">
			<server>test-web-1</server>
		</cluster>
	</clusters>

	<!-- A list of svn repository names against base paths -->
	<repos>
		<repo>
			<name>websites</name>
			<base>svn+ssh://localhost/svn</base>
		</repo>
	</repos>

	<!-- A list of deployment path names against base paths -->
	<deploy-paths>
		<deploy-path>
			<name>varwww</name>
			<base>/var/www</base>
		</deploy-path>
	</deploy-paths>

	<!--
	Project configuration, mapping to subversion repository, 
	deployment directory and environments to deployment servers
	-->
	<projects>

		<project>
			<!--
			The svn path is svn+ssh://localhost/svn/my-project
			The deployment directory is /var/www/my-project
			Deploying to the stage environment deploys to servers: test-web-1
			Deploying to the prod environment deploys to servers: web-1, web-2
			-->
			<name>my-project</name>
			<repo>websites</repo>
			<deploy>varwww</deploy>
			<envs>
				<env name="stage">stage</env>
				<env name="prod">prod</env>
			</envs>
		</project>

		<project>
			<!--
			The svn path is svn+ssh://localhost/svn/foo/your-project
			The deployment directory is /var/www/foo/your-project
			Deploying to the foo-stage environment deploys to servers: test-web-1
			Deploying to the foo-prod environment deploys to servers: web-1, web-2
			-->
			<name>your-project</name>
			<repo>websites</repo>
			<deploy>varwww</deploy>
			<repo-path>/foo/your-project</repo-path>
			<deploy-path>/foo/your-project</deploy-path>

			<!--
			Commands to run pre and post switch,
			Either absolute, or relative to the switching directory
			-->
			<pre-switch>bin/pre-switch</pre-switch>
			<post-switch>bin/post-switch</post-switch>

			<!--
			Commands to run pre and post deploy,
			Either absolute, or relative to the live directory
			-->
			<pre-deploy>bin/pre-deploy</pre-deploy>
			<post-deploy>bin/post-deploy</post-deploy>

			<envs>
				<env name="foo-stage">stage</env>
				<env name="foo-prod">prod</env>
			</envs>
		</project>

	</projects>

	<!--
	Additional remote commands, each command has the following attributes,

	buffer [true|false] (default false)
		Whether to buffer the commands output before displaying it to the
		terminal or flush per line.
	parallel [true|false] (defult true)
		Whether to run the commands in parallel or sequentially
		across machines.
	-->
	<remote-commands>
		<command buffer="true" parallel="true">
			<name>uptime</name>
			<exec>/usr/bin/uptime</exec>
		</command>
		<command buffer="true" parallel="true">
			<name>ps</name>
			<exec>/bin/ps aux</exec>
		</command>
	</remote-commands>

</release>

Examples

Using the above configuration the following commands can be run to perform deployment tasks.

# Create a release branch of the my-project project
# The version is auto incremented from the previous branch unless stated
./bin/release branch my-project

# Switch the switching directory for the my-project project on the testing
# environment to prepare for deployment of branch 1.0.0
./bin/release switch my-project stage branch 1.0.0

# Deploy the switching directory to the live directory on the testing environment
./bin/release deploy my-project stage

# Create a tag from the release branch
# The tag version is taken from the latest release branch version unless stated
./bin/release tag my-project

# Switch the switching directory for the my-project project on the production
# environment to prepare for deployment of tag 1.0.0
./bin/release switch my-project prod tag 1.0.0

# Deploy the switching directory to the live directory on the production environment
./bin/release deploy my-project prod

# Check uptime for all the servers for the my-project project
# on the production environment.
./bin/release uptime my-project prod

Open Source

Snooze makes use of the following open source libraries, any changes made will be listed here for download.

JSch

License

Redistribution and use of this software in source and binary forms, with or without modification, are permitted providing the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer.
Distributions in binary form compiled from source must make that source available for redistribution without sublicense, retaining all copyright notices, including the above copyright notice, this list of conditions and the following disclaimer.
Distributions must provide a link to http://www.bedican.co.uk
Neither the name bedican, bedican solutions nor the name of the author, may be used to endorse or promote any website or products without specific prior written permission. The name bedican is a trademark of bedican solutions.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.