= Carpet

== What is Carpet? (short version)

* Capistrano recipes for building a virtualized infrastructure on OpenSolaris
* Declarative server definitions
* Capistrano recipes for pre-defined, custom-built appliances for a complete Ruby on Rails stack
* Uses latest and greatest OpenSolaris goodies (Zones, ZFS, SMF, ...) out of the box

== What is Carpet? (long version)

Carpet is a tool for bootstrapping and maintaining your physical or virtual
servers. It's extracted from our real world Capistrano deployment recipes with
which we have provisioned and maintained our production servers for over a year.
Currently, it supports OpenSolaris but its extensible architecture makes it
easy to add support for other target platforms as well.

Carpet is heavily inspired by both Capistrano and Puppet and tries to leverage
the simplicity of extending Capistrano with the declarative approach of puppet.
Carpet has some common goals with Puppet:

* Reproducable deployments
* Shareable recipes
* Maintainability
* Extensibility

Due to that declarative approach you don't need to remember all the tasks you
have to run in order to change the state of your server. You simply tell
Carpet how your configuration shall look like and Carpet will execute all the
necessary steps for you.

As Carpet is based on Capistrano, it's trivial to extend. All your custom
deployment scripts are written as Capistrano tasks. And even if you've never
written one before, you'll find it to be very easy.

Carpet extends Capistrano by providing you with:

* Self-resolving remote dependencies using the new :assure keyword
* Node declarations describing your physical and virtual servers
* Node types (aka roles) describing what tasks to call for building a server
  of that type
* Ability to provision Solaris Zones on your physical servers out of the box
* An easy to use ruby wrapper for the most common Unix shell commands required
  by your Capistrano tasks (like adm.ln, src.install, zfs.create, nfs.mount, etc.)
* Pre-built appliances like an apache loadbalancer (apache_lb),
  a memcached server (memcached), a mysql 5.0 single instance server (mysql)
  and an app server with rails 2.1.0

The pre-built appliances let you bootstrap a brand new physical OpenSolaris
box with a fully fledged Ruby on Rails stack separated into individual zones
(OpenSolaris' version of virtual machines).

== INSTALLATION

	git clone git://github.com/webops/carpet.git
	cd carpet
	rake install
	
	(This will build and install the Carpet gem)

== USAGE

In general, you'll use Carpet as follows:

* require 'carpet' in your Capfile
* Describe all your server types and instances you want to set up with the new
  +node+ and +type+ keywords in your Capfile
* Use the +cap+ script to provision your servers

Use the +cap+ script as follows:

	cap nodename
	
You will define your nodes as follows:

	# physical nodes
	node 'host1', :physical_node, {
	  :ipaddress => "10.0.0.100",
	  :nfs_server => true,
	  :no_release => true
	}
	
	# virtual nodes hosted on the physical one (Solaris zones)
	node 'web1', :web, {
	  :hosted_on => 'host1',
	  :ipaddress => "10.0.0.80",
	  :interface => "bnx0",
	  :mem => "768m",
	  :swap => "768m",
	  :disk => "20G",
	  :domain => "example.com",
	  :name_server => ["ns1.example.com", "ns2.example.com", "ns3.example.com"],
	  :user => "james",
	  :basic_auth => true,
	  :no_release => true
	}
	
where +:physical_node+ and +:web+ are node types defined as follows:

	type :physical_node do
	  adm.enable_ntp("ntp1.example.com")
	  assure :user, "james", {:keys => your_ssh_keys}
	  needs :nfs_shares
	end

	type :web do
	  needs :apache_lb
	  assure :package, "SUNWsvn"
	  needs :nfs_mounts
	end
	
Carpet will automatically set up all servers and roles in Capistrano for you.
The new +:needs+ keyword is defining dependencies. Dependencies are simple
Capistrano tasks, which will be executed when a node is set up.

== LIMITATIONS / TODOs

As Carpet is extracted from our real live deployment recipes, there are still
a lot of limitations, which are ok for us but your milage might vary.
Patches for overcoming them are always appreciated.

* The rails appliance has gems and versions hardcoded. What should be there by
  default and what should be added by application specific tasks?
* Carpet relies heavily on pfexec instead of sudo. Should be refactored to use
  sudo by default, as sudo is shipped now with OpenSolaris 2008.11 and is the
  default in Capistrano
* Documentation. For now, you have to look at the specs to see how to use it, sorry.

== LICENSE:
(The MIT License)

Copyright © 2008-2009 Matthias Marschall <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.