incubator-deltacloud-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mar...@redhat.com
Subject =?UFT-8?q?=5BPATCH=203/3=5D=20Site=20Docs=20update=20-=20Adds=20information=20for=20developers=2C=20getting=20started=20and=20installation=20guide=2E?=
Date Fri, 09 Sep 2011 11:28:13 GMT
From: marios <marios@redhat.com>


Signed-off-by: marios <marios@redhat.com>
---
 site/content/_credentials.haml  |  174 ++++++++++
 site/content/_drivers.mdown     |   86 +++---
 site/content/_navigation.haml   |    5 +-
 site/content/_providers.haml    |    8 +-
 site/content/contribute.mdown   |  101 ------
 site/content/developers.mdown   |  562 ++++++++++++++++++++++++++++++
 site/content/documentation.haml |  727 +++++++++++++++++++++++++++++----------
 site/content/drivers.haml       |    2 +
 site/content/framework.mdown    |  258 --------------
 site/content/roadmap.mdown      |    9 +-
 site/lib/documentation.rb       |    9 +-
 site/output/client-ruby.html    |   12 +-
 site/output/contribute.html     |  148 --------
 site/output/dcloud-demo.html    |    9 +-
 site/output/dcloud.html         |    9 +-
 site/output/developers.html     |  571 ++++++++++++++++++++++++++++++
 site/output/documentation.html  |  718 ++++++++++++++++++++++++---------------
 site/output/drivers.html        |  383 +++++++++++++++++----
 site/output/framework.html      |  357 -------------------
 site/output/libdeltacloud.html  |   12 +-
 site/output/roadmap.html        |   11 +-
 21 files changed, 2689 insertions(+), 1482 deletions(-)
 create mode 100644 site/content/_credentials.haml
 delete mode 100644 site/content/contribute.mdown
 create mode 100644 site/content/developers.mdown
 delete mode 100644 site/content/framework.mdown
 delete mode 100644 site/output/contribute.html
 create mode 100644 site/output/developers.html
 delete mode 100644 site/output/framework.html

diff --git a/site/content/_credentials.haml b/site/content/_credentials.haml
new file mode 100644
index 0000000..cd36d1a
--- /dev/null
+++ b/site/content/_credentials.haml
@@ -0,0 +1,174 @@
+---
+filter:
+  - haml
+---
+%p
+  Deltacloud uses basic HTTP
+  %a{:href=>"api.html#h1_3"}
+    authentication
+  to receive credentials from the
+  client and passes them through to the backend cloud it is talking to. The
+  credentials always consist of a username and password, and are never
+  stored on the server.  The exact credentials for logging into the server,
+  and where you find them, depends on the backend cloud that the server is
+  talking to.
+%a(name="credentials")
+%p
+  The following table gives details about the credentials that must be
+  provided for each of the supported clouds. The entry from
+  the Driver column needs to be passed as the
+  %tt
+    \-i
+  option to the
+  %tt
+    deltacloudd
+  server daemon. Note that some of the drivers require additional information, e.g.,
+  API endpoint URL's, be passed through environment variables, as addressed in the
+  %a{:href=>"drivers.html#specific_driver_notes"}
+    Notes
+  for Specific Drivers section below.
+
+%h3 Cloud provider credentials
+%table#providers
+  %tr
+    %th
+      %strong Cloud
+    %th
+      %strong Driver
+    %th
+      %strong Username
+    %th
+      %strong Password
+    %th
+      %strong Notes
+  %tr
+    %td
+      %strong mock
+    %td
+      %tt mock
+    %td
+      %tt
+        mockuser
+    %td
+      %tt
+        mockpassword
+    %td
+      The mock driver doesn't talk to any cloud; it just pretends to be a cloud
+  %tr
+    %td
+      %strong Amazon EC2/S3
+    %td
+      %tt ec2
+    %td
+      Access Key ID
+    %td
+      Secret Access Key
+    %td
+      This information can be found on the
+      %a{ :href => "http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key"} Security Credentials
+      page in your AWS account
+  %tr
+    %td
+      %strong Eucalyptus
+    %td
+      %tt eucalyptus
+    %td
+      Access Key ID
+    %td
+      Secret Access Key
+    %td
+  %tr
+    %td
+      %strong GoGrid
+    %td
+      %tt gogrid
+    %td
+      API Key
+    %td
+      Shared Secret
+    %td
+      Go to
+      %tt My Account &gt; API Keys
+      for
+      %a{ :href => "https://my.gogrid.com/gogrid/com.servepath.gogrid.GoGrid/index.html" } your account
+      and click on the key you want to use to find the shared secret.
+  %tr
+    %td
+      %strong IBM SBC
+    %td
+      %tt sbc
+    %td
+      Username
+    %td
+      Password
+    %td
+  %tr
+    %td
+      %strong Microsoft Azure (Storage Account only)
+    %td
+      %tt azure
+    %td
+      Public Storage Account Name
+    %td
+      Primary Access Key
+    %td
+      The Storage Account Name is chosen when you create the service (e.g. name in http://name.blob.core.windows.net/). This and the access key are available from the service control panel.
+  %tr
+    %td
+      %strong OpenNebula
+    %td
+      %tt opennebula
+    %td
+      OpenNebula user
+    %td
+      OpenNebula password
+    %td
+      Set the environment variable
+      %tt OCCI_URL
+      to the address on which OpenNebula's OCCI server is listening.
+  %tr
+    %td
+      %strong Rackspace Cloud Servers/Cloud Files
+    %td
+      %tt rackspace
+    %td
+      Rackspace user name
+    %td
+      API Key
+    %td
+      Obtain the key from the
+      %a{ :href => "https://manage.rackspacecloud.com/APIAccess.do"} API Access
+      page in your control panel
+  %tr
+    %td
+      %strong RHEV-M
+    %td
+      %tt rhevm
+    %td
+      %a{ :href => "http://markmc.fedorapeople.org/rhevm-api/en-US/html/chap-REST_API_Guide-Authentication.html" } RHEV-M user name plus Windows domain
+      , e.g.,
+      %tt admin@rhevm.example.com
+    %td
+      RHEV-M password
+    %td
+      Set environment variable
+      %tt API_PROVIDER
+      to the URL of the RHEV-M REST API endpoint.
+  %tr
+    %td
+      %strong Rimuhosting
+    %td
+      %tt rimuhosting
+    %td not used (?)
+    %td API Key
+    %td
+  %tr
+    %td
+      %strong Terremark
+    %td
+      %tt terremark
+    %td
+      Username
+    %td
+      Password
+    %td
diff --git a/site/content/_drivers.mdown b/site/content/_drivers.mdown
index 56254fe..0fb5112 100644
--- a/site/content/_drivers.mdown
+++ b/site/content/_drivers.mdown
@@ -1,44 +1,33 @@
 # Deltacloud Drivers
 
-Deltacloud provides drivers for a growing number of popular clouds. All drivers
-can handle a set of standard operations, some of them also support a number of
-optional operations to expose the features of specific clouds more closely. The
-drivers and their capabilities are:
+Deltacloud provides drivers for a [growing number](drivers.html#providers) of popular
+IaaS cloud providers. This page contains notes pertinent to specific cloud provider drivers, such
+as the [credentials](drivers.html#credentials) that should be used for a given cloud provider.
+Furthermore the information here outlines the mechanism through which any API call sent by a
+given client to a Deltacloud server instance may be routed to a specific driver, regardless
+of the 'default' driver that the Deltacloud server was invoked for.
 
-## Setting up the code
+------------------------------------------------
 
-To set up a Deltacloud core and the drivers, install the
-[deltacloud-core][coregem] Ruby gem:
-
-[coregem]: http://rubygems.org/gems/deltacloud-core
-
-    # gem install deltacloud-core
-
-RPM package will be available soon.
-
-## Launch the server
-
-The server is launched with the `deltacloudd` command and pass it the name
-of the driver you want to use:
-
-    $ deltacloudd -i mock
+## Dynamic driver switching
 
-This will start a webserver running the mock driver on
-`http://localhost:3001/api`; you can simply browse to that URL to get a
-pretty view of the objects the driver deals with.
+When the Deltacloud server is started it is passed a parameter
+that specifies the **default** driver to be used for API operations:
 
-## Dynamic driver switching
+    $ deltacloudd -i ec2
 
-The driver specified with the `-i` switch when `deltacloudd` is launched is
-the default driver. Clients can switch drivers for any request. The list of
-drivers supported by the server can be obtained from the `drivers`
-collection.
+The above for example starts the Detlacloud server with the Amazon EC2 driver. Whilst
+it is possible to start a number of Deltacloud server instances for each cloud provider
+that you wish to connect to (e.g., on different ports), a mechanism is provided with which
+to instruct the server to use a specific driver, regardless of the current default. The
+Deltacloud API **drivers** colletion (e.g. GET /api/drivers) provides a list of all currently
+supported cloud provider drivers.
 
 Some drivers also support the notion of a *provider*. Changing the provider
 makes it possible to use the same driver against different instances of a
 cloud, for example different regions in EC2 or different installations of
 RHEV-M. The possible range of values for the provider is driver-specific,
-and listed below for each driver.
+and listed in the notes for each driver below.
 
 The driver and provider can be selected in one of two ways:
 
@@ -50,33 +39,32 @@ The driver and provider can be selected in one of two ways:
 2. Through the matrix request parameters `driver` and `provider` in the
    `api` component of the server's URL. For example, requesting
    `http://localhost:3001/api;driver=ec2;provider=eu-west-1` has the same
-   effect as using the two request headers mentioned above.
+   effect as using the two request headers in the example above.
 
-## Notes on specific drivers
+------------------------------------------------
 
+## Driver functionality and Credentials
 <table providers></table>
+<a name=providers>.
 
-### EC2 Driver
 
-For the Amazon EC2 you need to install the
-[aws](https://github.com/appoxy/aws) Ruby gem:
 
-    # gem install aws
+------------------------------------------------
 
-When using the driver for Amazon EC2, the credentials passed in
-response to the HTTP 401 authentication challenge should be your
-*access_key* and *secret_access_key*
+<a name=specific_driver_notes> .
 
-These credentials may be found on the [Access Identifiers](http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key)
-page at Amazon AWS.
+## Notes on specific drivers
+
+### EC2 Driver
 
 The providers for the EC2 driver correspond to AWS's regions, and currently
 are `us-east-1`, `us-east-1`, `eu-west-1`, `ap-southeast-1`.
 
+------------------------------------------------
+
 ### Eucalyptus Driver
 
-The Eucalyptus driver is based on the EC2 driver, and therefore also
-requires the `aws` gem.
+The Eucalyptus driver is based on the EC2 driver.
 
 The driver allows selecting the Eucalyptus installation by setting a
 provider in the format
@@ -90,6 +78,8 @@ that installation by passing the request headers
     X-Deltacloud-Driver: eucalyptus
     X-Deltacloud-Provider: ec2=192.168.1.1:8773;s3=192.168.1.2:8773
 
+------------------------------------------------
+
 ### RHEV-M Driver
 
 The RHEV-M driver needs to be installed on a Windows machine which has the
@@ -103,17 +93,23 @@ The actual RHEVM instance you are connecting to is controlled by
 the RHEVM.dll.config file which is referenced from the profile.ps1
 file located in My Documents/WindowsPowershell directory
 
+------------------------------------------------
+
 ### Rackspace Driver
 
 When using the Rackspace-cloud driver (Rackspace cloud used to be called
 "Mosso") - the password in a HTTP 401 challenge should be your API key, NOT
-your rackspace account password.  (you can get the API-key, or generate a
-new one, from the rackspace console).
+your rackspace account password.  You can get the API-key, or generate a
+new one, from the rackspace console.
+
+------------------------------------------------
 
 ### RimuHosting
 
 Further details coming soon.
 
+------------------------------------------------
+
 ### OpenNebula
 
 When using the [OpenNebula](http://www.opennebula.org/) driver, the
@@ -123,6 +119,8 @@ should be your OpenNebula user and password.
 The address, on which the OCCI server is listening, needs to be defined in
 an environment variable called OCCI_URL.
 
+------------------------------------------------
+
 ### IBM Smartcloud Driver
 
 When using the IBM SmartCloud driver, the credentials passed in response to
diff --git a/site/content/_navigation.haml b/site/content/_navigation.haml
index 8a2e002..0ad7e81 100644
--- a/site/content/_navigation.haml
+++ b/site/content/_navigation.haml
@@ -3,8 +3,9 @@ filter: haml
 ---
 - menu = [ { :href => "index.html", :title => "Deltacloud Home", :text => "Home" }, |
   { :href => "download.html", :title => "Get the latest releases", :text => "Download" }, |
-  { :href => "contribute.html", :title => "Information about design/development process", :text => "Contribute" }, |
-  { :href => "documentation.html", :title => "Project documentation", :text => "Documentation" } ] |
+  { :href => "developers.html", :title => "Information for developers", :text => "Developers" }, |
+  { :href => "documentation.html", :title => "Project documentation", :text => "Documentation" }, |
+  { :href => "contact.html", :title => "Contact us!", :text => "Contact"} ] |
 
 #navigation
   #menu.container
diff --git a/site/content/_providers.haml b/site/content/_providers.haml
index d713858..93e6f3d 100644
--- a/site/content/_providers.haml
+++ b/site/content/_providers.haml
@@ -2,7 +2,7 @@
 filter:
   - haml
 ---
-%h3 Compute Drivers
+%h3 Compute Driver Functionality
 %table#providers
   %tr
     %th.emptycell &nbsp;
@@ -49,16 +49,16 @@ filter:
       = support_indicator(provider[:list][:images])
       = support_indicator(provider[:list][:instances])
 
-%h3 Storage Drivers
+%h3 Storage Driver Functionality
 %table#providers
   %tr
     %th.emptycell &nbsp;
     %th
       %strong Create
-      new containers
+      new buckets
     %th
       %strong Update/delete
-      containers
+      buckets
     %th
       %strong Create
       new blobs
diff --git a/site/content/contribute.mdown b/site/content/contribute.mdown
deleted file mode 100644
index e9fd595..0000000
--- a/site/content/contribute.mdown
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: Deltacloud - Contribute
-extension: html
-filter:
-  - markdown
-  - outline
----
-Help make Deltacloud better
-===========================
-
-<toc class="toc" numbering="off" toc_style="ul" toc_range="h2-h3" />
-
-All development of Deltacloud takes place in the open. Communication is run
-through the mailing list and all source code changes are tracked publicly.
-
-* <strong>Mailing Lists</strong><br/>
-  For Deltacloud API: [deltacloud-dev@incubator.apache.org](mailto:deltacloud-dev@incubator.apache.org).
-  To subscribe to it, send an email to [deltacloud-dev-subscribe@incubator.apache.org](deltacloud-dev-subscribe@incubator.apache.org). You can also view [Archive][1] in case you are missing something.
-
-  [1]: http://mail-archives.apache.org/mod_mbox/incubator-deltacloud-dev/
-* <strong>IRC</strong><br/>
-  You can also join us on the Freenode IRC channel #deltacloud. Deltacloud
-  developers are generally available on the IRC channel
-* <strong>Bugs</strong><br/>
-  We track bugs in [Apache JIRA][2]. You can [view open bugs][view-bugs] or
-  [file a new one][new-bug] there.
-
-  [2]: https://issues.apache.org/jira/browse/DTACLOUD
-  [view-bugs]: https://issues.apache.org/jira/browse/DTACLOUD
-  [new-bug]: https://issues.apache.org/jira/secure/CreateIssue!default.jspa
-* <strong>Patches</strong><br/>
-  Patches are very welcome. Please send them to the [development
-  list][3]. Patches should be generated with [`git`&nbsp;`format-patch`][4]
-  and sent to the list with [`git`&nbsp;`send-email`][5].
-* <strong>Roadmap</strong><br/>
-  We maintain our roadmap in
-  [teambox](https://teambox.com/projects/deltacloud/task_lists) so that
-  anyone can comment on tasks and suggest new ones.
-
-  [3]: http://mail-archives.apache.org/mod_mbox/incubator-deltacloud-dev/
-  [4]: http://kernel.org/pub/software/scm/git/docs/git-format-patch.html
-  [5]: http://kernel.org/pub/software/scm/git/docs/git-send-email.html
-
-Getting the sources
--------------------
-
-Then Deltacloud Core gives you the API and drivers to various cloud providers.
-It also provides a client library and a commandline interface.
-
-The Deltacloud Core repository is hosted on Apache Incubator.
-Apache uses Subversion, but there is a git mirror available:
-
-    $ mkdir deltacloud
-    $ cd deltacloud
-    $ git clone git://git.apache.org/deltacloud.git core
-
-You can find the Subversion repository at: <https://svn.apache.org/repos/asf/incubator/deltacloud>.
-
-Required packages
------------------
-In order to make the Deltacloud components work, you'll need to
-have the following packages installed (on Fedora 14; the names may vary on
-your distro):
-
-    ruby
-    ruby-devel
-    rubygem-rake
-    gcc-c++
-    libxml2-devel
-    libxslt-devel
-
-**Note:** these packages are necessary for building all the required ruby gems
-that Deltacloud requires. If you want to install the gems using your system's
-package manager (yum, apt, ports, etc.) you won't need to install these
-packages manually.
-
-To install all required ruby gems manually you should run:
-
-    $ yum install rubygem-haml rubygem-sinatra rubygem-thin rubygem-json \
-      rubygem-net-json rubygem-rack-accept rubygem-nokogiri rubygem-aws \
-      rubygem-rest-client
-
-Installing the Deltacloud Core
-------------------------------
-
-First, you need to install the server that will give you the Deltacloud API:
-
-    $ cd path/to/deltacloud/core/server
-    $ rake package
-    $ sudo gem install pkg/deltacloud-core-<version>.gem
-
-Then install the client library:
-
-    $ cd path/to/deltacloud/core/client
-    $ rake package
-    $ sudo gem install pkg/deltacloud-client-<version>.gem
-
-Once you have the client installed, run the following command:
-
-    $ cd path/to/deltacloud/core/client
-    $ rake fixtures
diff --git a/site/content/developers.mdown b/site/content/developers.mdown
new file mode 100644
index 0000000..9da2c2c
--- /dev/null
+++ b/site/content/developers.mdown
@@ -0,0 +1,562 @@
+---
+title: Deltacloud - Information for Developers
+extension: html
+filter:
+  - markdown
+  - outline
+---
+# Contribute to the Deltacloud Project
+
+[Apache](http://www.apache.org/ "The Apache Software Foundation") Deltacloud is
+free, open source software licensed under the
+[apache license](http://www.apache.org/licenses/LICENSE-2.0 "The Apache License").
+Please feel free to [contact us](contact.html) if you have any questions about the
+project or with any suggestions on how to improve Deltacloud. The Deltacloud
+developer community is open to anyone that wants to contribute!
+
+This page contains information for developers:
+
+<a name=contents>
+
+<toc class="toc" numbering="off" toc_style="ul" toc_range="h2-h3" />
+
+<br>
+--------------------------------------
+<br>
+
+## Setting up the developer environment
+
+The information here is about setting up a dev environment for Deltacloud. If you
+are interested in first trying out Deltacloud, you should instead follow the
+instructions in the [Download](download.html) page and read the
+[installation and quick start guide](documentation.html#install_deltacloud).
+
+Before setting up the development environment, make sure you have all the
+[installation dependencies](documentation.html#dependencies).
+
+### Getting the sources
+
+Deltacloud provides the API server and drivers to various cloud providers.
+It also includes a ruby client library and a commandline interface.
+
+**First, make sure you have installed all [dependencies](documentation.html#dependencies).**
+
+The Deltacloud repository is hosted at the Apache Software Foundation.
+Apache uses ***subversion*** and you can find the Deltacloud subversion repository
+at <https://svn.apache.org/repos/asf/incubator/deltacloud>.
+
+However many of the Deltacloud developers use the
+[git version control system](http://git-scm.com/download) and the Deltacloud
+code is available through a git mirror. The instructions on this page are
+thus specific to using ***git*** for getting the code and also
+for making and sending patches.
+
+If you don't already have ***git*** there are
+[git binaries](http://git-scm.com/download) available for specific systems.
+Alternatively, if you use the ***yum*** or ***apt*** package managers:
+
+    $ sudo yum install git
+            <OR>
+    $ sudo apt-get install git
+
+With ***git*** in place, to get the latest HEAD of the Deltacloud git repo:
+
+    $ mkdir DeltacloudProject
+    $ cd DeltacloudProject
+    $ git clone git://git.apache.org/deltacloud.git
+
+<br>
+[contents](#contents)
+
+--------------------------------------
+
+<br>
+
+### Development dependencies
+
+Apart from the [installation dependencies](documentation.html#dependencies),
+in order to develop for Deltacloud you will need some additional libraries,
+such as [cucumber](http://cukes.info/),
+[ruby-debug](http://bashdb.sourceforge.net/ruby-debug/home-page.html) and
+[rpsec](http://rspec.info/). The Deltacloud source includes a Gemfile which
+lists these development dependencies: **/path/to/deltacloud/server/Gemfile**.
+
+Thus, the recommended way to get all development dependencies is with
+[Bundler](http://gembundler.com/). If you don't already have bundler, install
+it:
+
+    $ sudo gem install bundler
+
+Then, you can get all the required developer dependencies by:
+
+    $ cd /path/to/deltacloud/server
+    $ bundle install --system
+
+
+<br>
+[contents](#contents)
+
+--------------------------------------
+
+<br>
+
+### Building from source and installing the Deltacloud gem
+
+To build and install the Deltacloud server gem:
+
+    $ cd path/to/DeltacloudProject/deltacloud/server
+    $ rake package
+    $ sudo gem install pkg/deltacloud-core-<version>.gem
+
+Then install the Deltacloud client gem:
+
+    $ cd path/to/DeltacloudProject/deltacloud/client
+    $ rake package
+    $ sudo gem install pkg/deltacloud-client-<version>.gem
+
+<br>
+[contents](#contents)
+
+--------------------------------------
+
+<br>
+
+## Contribute to Deltacloud
+
+The information here is aimed at helping developers more quickly understand the Deltacloud
+project code, the process used by the development community for contributing and some
+guidelines on how to go about adding a cloud provider driver to the Deltacloud project.
+
+### Overview of the Deltacloud directory structure
+
+**Note:** the following is not an exhaustive list of all files and directories in the
+Deltacloud project. Rather it is intended as an aid to ease familirisation
+with the project files for developers - for example to quickly identify where
+the Deltacloud cloud provider drivers are stored:
+
+<a name=deltacloud_directories> .
+
+    deltacloud
+    |-----------------------------------------------------------------------------------
+    |-d-->tests                           Contains Cucumber tests
+    |-----------------------------------------------------------------------------------
+    |-d-->site                            Files for this website
+    |-----------------------------------------------------------------------------------
+    |-d-->client                          Contains the Deltacloud ruby client
+    |-----------------------------------------------------------------------------------
+    |-d-->clients                         Contains other Deltacloud clients (e.g. java)
+    |-----------------------------------------------------------------------------------
+    |-d--> server
+           |----------------------------------------------------------------------------
+           |-f-->server.rb                Contains the sinatra routes
+           |----------------------------------------------------------------------------
+           |-d-->bin                      Contains the Deltacloud executable deltacloudd
+           |----------------------------------------------------------------------------
+           |-d-->views                    Contains haml views for each collection
+           |----------------------------------------------------------------------------
+           |-d-->tests                    Contains unit tests for drivers
+           |----------------------------------------------------------------------------
+           |-d-->lib
+                 |----------------------------------------------------------------------
+                 |-d-->sinatra            Contains rabbit DSL and various helpers
+                 |----------------------------------------------------------------------
+                 |-d-->deltacloud
+                       |----------------------------------------------------------------
+                       |-d-->models       Definition of each collection model
+                       |----------------------------------------------------------------
+                       |-d-->drivers      Contains the drivers for each cloud provider
+                       |----------------------------------------------------------------
+                       |-d-->helpers      Various helper methods used by the drivers
+                       |----------------------------------------------------------------
+                       |-d-->base_driver  Contains the Deltacloud base driver
+                       |----------------------------------------------------------------
+
+<br>
+[contents](#contents)
+
+--------------------------------------
+
+<br>
+
+### Forming and sending patches
+
+There are many ways to work with git and there are many
+[good resources](http://book.git-scm.com/) on using git. The Deltacloud community uses
+a ***local_branch*** ---> ***patch*** ---> ***review*** ---> ***accept*** ---> ***commit***
+process for contributing to the project. The following shows the typical workflow used
+by the core developers.
+
+First you need to set some settings inside the git configuration file. In the root
+of the git project (Deltacloud in this case) there is a .git hidden directory containing
+the config file. Open this with your preferred editor:
+
+    $ vim deltacloud/.git/config
+
+Add the following to any existing configuration replacing the relevant values with your own:
+
+    [sendemail]
+    signedoffbycc = no
+    chainreplyto = no
+    smtpserver = your_smpt.server.address
+    thread = yes
+    from = your_email_address
+    suppresscc = all
+
+    [core]
+    whitespace = trailing-space,space-before-tab
+
+    [apply]
+    whitespace = error-all
+
+After getting the latest HEAD of the Deltacloud git repo, you will have one local
+ branch called ***trunk***.
+
+    $ git branch
+    * trunk
+
+Fetch the latest changes from the git repo:
+
+    $ git pull
+
+Make a new local branch for your edits and give it a name:
+
+    $ git checkout -b my_new_branch
+
+Make your edits/changes/voodoo. Once done, review which files you changed:
+
+    $ git status
+
+Once you are happy with the changes and everything is working, commit those changes
+to your local branch:
+
+    $ git commit -a
+
+This will open an editor (e.g., vi) for you to enter a commit message. Please keep this
+short and succint in general and keep individual lines at no longer than 80 characters.
+The command **git log** will show you recent commits together with their commit messages
+as examples.
+
+At this point, your local branch will contain the changes that you worked on and will
+be different from your ***local*** **trunk** branch. In the meantime, other developers
+may have already committed changes to the ***remote*** **trunk** branch in the Apache git repo.
+Thus, you need to fetch any new changes and merge into your ***local*** **trunk** and then
+rebase your local **trunk** onto the new branch which contains your changes.
+
+Change to trunk and fetch upstream changes if any:
+
+    $ git checkout trunk
+    $ git pull
+
+Your ***local*** trunk is now up-to-date with the ***remote*** trunk in the git repo.
+Next, rebase the ***local*** trunk onto the branch containing your changes:
+
+    $ git rebase trunk my_new_branch
+
+Now you are ready to make patches against trunk and send them to the Deltacloud mailing
+list for review by other developers in the community:
+
+    $ git format-patch -o /path/to/where/you/keep/patches/ trunk
+
+    $ git send-email --compose --subject 'some subject'
+      --thread /path/to/where/you/keep/patches/* --to deltacloud-dev@incubator.apache.org
+
+Your patches will be reviewed by other members of the community. The general rule used
+is that a patch will be committed to the repo if it receives at least one **ACK** and no
+**NACK**. Once a patch is **ACK**ed it will be committed by one of the Deltacloud community
+developers that have commit rights to the Apache repo. If your patches are on the mailing
+list for a few days and no-one is responding to them feel free to send a reminder email
+as patches may be missed/forgotten.
+
+You can also contribute to the project by reviewing patches sent by other contributors:
+
+Make a new branch where you will apply the patches and test:
+
+    $ git checkout -b jsmith_patches
+
+You can use either git am ("apply mail") to apply patches in mail format, or git apply for
+plain-text patches. Using git am will also commit the patches to the local branch
+preserving the author's commit messages whilst git apply will only apply the files but not
+commit them. For simple patch review the difference between these is insignificant and
+boils down to whether you like to save the patches as plain-text or in .mbox email format.
+
+Save the patches to some known location, make sure you're on the branch you wish to apply
+them onto, and then apply:
+
+    $ git checkout jsmith_patches
+
+    $ cat /path/to/patches/0001-name-of-patch.txt | git apply
+                             _OR_
+    $ git am /path/to/patches/0001-name-of-patch.eml
+
+If you think the patches are sane, do what the author intended and most importantly don't
+break anything else, then you can send an **ACK** in response to the patches on the
+Deltacloud [mailing list](contact.html). Similarly, if you think there is some problem
+with the patches you should send a **NACK** with an explanation of the problem you have
+found so that the author can address this.
+
+<br>
+[contents](#contents)
+
+--------------------------------------
+
+<br>
+
+### Use the Deltacloud github mirror
+
+The Deltacloud project maintains a
+[github page](https://github.com/apache/deltacloud) which mirrors the Apache
+repository. You can contribute through github if that is preferrable.
+[Fork](http://help.github.com/fork-a-repo/) the Deltacloud repo, make your changes and
+commit them back to your fork. Then issue a
+[pull request](http://help.github.com/send-pull-requests/). It may also be wise to
+send an email to the Deltacloud [mailing list](contact.html) to let the community know
+about your pull request as in general the mailing list is checked much more often than
+the github page.
+
+<br>
+[contents](#contents)
+
+--------------------------------------
+
+<br>
+
+### Writing a new cloud provider driver
+
+The deltacloud drivers live in
+[deltacloud/server/lib/deltacloud/drivers](#deltacloud_directories). The information here
+is intended as a primer for anybody that wants to contribute a new cloud provider driver to
+the Deltacloud project.
+
+To add a driver for a hypothetical **Foo** cloud, you should start by adding a a directory
+under /drivers/ and then a file for the driver itself, i.e.:
+
+    deltacloud/server/lib/deltacloud/drivers/foo/foo_driver.rb
+
+That file needs to define a class **Deltacloud::Drivers::Foo::FooDriver** and must be
+a subclass of the Deltacloud::BaseDriver (example follows).
+
+You need to decide which [collections](api.html#h1) the provider for which you're
+writing the driver supports - e.g. images, instances, keys, buckets/blobs (storage), etc.
+and declare these with:
+
+    def supported_collections
+      DEFAULT_COLLECTIONS + [ :buckets ] - [ :storage_snapshots, :storage_volumes ]
+    end
+
+The above declares that the driver supports the **DEFAULT_COLLECTIONS** (defined in
+**deltacloud/server/lib/drivers.rb**) except [storage_snapshots](api.html#h4_2) and
+[storage_volumes](api.html#h4_1) and additionally also supports the
+[buckets](api.html#h4_3) collection. For example, a storage only cloud provider driver
+would support only the **buckets** colletion.
+
+You can then start to define the methods for each of the collections that your driver
+will support. The methods for each collection, as well as the routes that map to them
+are defined in **/deltacloud/server/server.rb**. In general you can look at the existing
+drivers for pointers on how to implement any specific method.
+
+One important consideration is how your cloud provider driver will be communicating
+with the cloud provider. Many of the existing drivers use external ruby gems for this
+purpose: for example, the **ec2** driver uses the [aws](https://github.com/appoxy/aws/)
+gem, the **rackspace** driver uses the
+[cloudfiles](https://github.com/rackspace/ruby-cloudfiles) and
+[cloudservers](https://github.com/rackspace/ruby-cloudservers) gems. However, other drivers
+implement their own clients with which to communicate with the cloud provider, such as
+the IBM SBC driver and the Gogrid driver. This also explains why, under the /drivers
+directory, some drivers contain only the provider\_***driver***.rb file, whilst others also
+define a provider\_***client***.rb file. Whether you write your own client or use an existing
+one is entirey at your discretion.
+
+Thus, your driver for the cloud provider foo may start out looking something like:
+
+    require 'deltacloud/base_driver'
+    require 'foo_lib' # a library for talking to the foo cloud
+
+    module Deltacloud
+      module Drivers
+        module Foo
+
+    class FooDriver < Deltacloud::BaseDriver
+
+        def supported_collections
+          DEFAULT_COLLECTIONS + [ :buckets ]
+        end
+
+        def images(credentials, opts={})
+          client = new_foo_client(credentials)
+          # use client to get a list of images from the back-end cloud and then create
+          # a Deltacloud Image object for each of these. Filter the result
+          # (eg specific image requested) and return to user
+        end
+
+        def realms(credentials, opts={})
+          (...)
+        end
+
+        def instances(credentials, opts={})
+          (...)
+        end
+
+        ... ETC
+
+        private
+
+        def new_foo_client(credentials)
+          client = FooLib::Service.new({:user => credentials.user,
+                                        :pass => credentials.password })
+        end
+
+    end
+            end
+          end
+        end
+
+One important method for drivers that implement the [instances](api.html#h3_5)
+collection is **instance_states**. This method represents the finite-state-machine
+for instances which varies across cloud providers. For example, in some clouds
+an instance may be in the 'running' state after creation, whereas in other clouds
+an instance may need to be started explicitly. An example of what this method may
+look like is:
+
+
+    define_instance_states do
+      start.to( :pending )          .on( :create )
+      pending.to( :running )        .automatically
+      running.to( :running )        .on( :reboot )
+      running.to( :shutting_down )  .on( :stop )
+      shutting_down.to( :stopped )  .automatically
+      stopped.to( :finish )         .automatically
+    end
+
+The voodoo used here (i.e. definition of .to and .on etc) is defined in
+/deltacloud/server/lib/deltacloud/state\_machine.rb.
+
+Valid states are
+
+- **`:begin`**
+- **`:pending`**
+- **`:running`**
+- **`:shutting_down`**
+- **`:stopped`**
+- **`:end`**
+
+The `:begin` state is the state an instance is in immediate before
+being created. The `:end` state is the state an instance is in
+immediately after being destroyed.
+
+Valid transition actions are
+
+- **`:stop`**
+- **`:start`**
+- **`:reboot`**
+
+Additionally, to indicate a transition that may occur _without_ an
+action being triggered, the action **`:automatically`** may be used,
+as shown in the example above.
+
+Depending on the collections you'll be supporting, some other methods that
+your driver may implement are:
+
+- `hardware_profiles(credentials, opts=nil)`
+- `images(credentials, opts=nil )`
+- `realms(credentials, opts=nil)`
+- `instances(credentials, opts=nil)`
+- `create_instance(credentials, image_id, opts)`
+- `reboot_instance(credentials, id)`
+- `stop_instance(credentials, id)`
+- `destroy_instance(credentials, id)`
+
+
+As a further example, the `hardware_profiles(...)` method should
+return an array of `HardwareProfile` objects. The `opts` hash, if
+present, must be inspected for `:id` and `:architecture` keys. If these keys
+are present, the results should be filtered by the value associated with
+each key. The `filter_on(...)` helper method is used for this filtering
+and as you can see from existing driver method definitions, is invoked
+in many of the driver collection methods:
+
+    def hardware_profiles(credentials, opts=nil)
+      hardware_profiles = # get all hardware profiles from provider
+      hardware_profiles = filter_on( hardware_profiles, :id, opts )
+      hardware_profiles = filter_on( hardware_profiles, :architecture, opts )
+      return hardware_profiles
+    end
+
+
+Once you've implemented some of the methods for your driver you can start to
+'run' it and test that things are working as expected. To do this, you need to
+create a yaml file for your driver so that the Deltacloud server 'knows' about
+it. Assuming you've written the driver for cloud Foo and you've called it
+foo\_driver.rb (which contains the class Deltacloud::Drivers::Foo::FooDriver)
+, you need to drop a file into **/deltacloud/server/config/drivers** called
+**foo.yaml**, containing the following:
+
+    ---
+    :foo:
+      :name Foo
+
+You can then start the Deltacloud server with:
+
+    deltacloudd -i foo
+
+<br>
+[contents](#contents)
+
+--------------------------------------
+
+<br>
+
+### Writing and running tests
+
+If you add a new feature or write a new driver, you might like to add some tests to
+make sure everything is running as expected. At present the Deltacloud project uses
+Unit tests which live in **/deltacloud/server/tests** as well as Cucumber tests which live
+in **/deltacloud/tests**.
+
+You can invoke the Unit tests:
+
+    $ cd /path/to/deltacloud/server
+    $ rake test
+
+As you can see by inspecting the Rakefile in /deltacloud/server, this will invoke all
+Unit tests defined in /deltacloud/server/tests. You can invoke specific driver tests by:
+
+    $ cd /path/to/deltacloud/server
+    $ rake test:rackspace
+          _OR_
+    $ rake test:mock
+          _etc_
+
+You can invoke the Cucumber tests:
+
+    $ cd /path/to/deltacloud/server
+    $ rake cucumber
+
+Alternatively, you can bypass the Rakefile and invoke the cucumber tests directly:
+
+    $ cd /path/to/deltacloud/server
+    $ cucumber ../tests/mock
+          _OR_
+    $ cucumber ../tests/ec2
+          _etc_
+
+<br>
+[contents](#contents)
+
+--------------------------------------
+
+<br>
+
+### Licensing - the Apache Individual Contributor License Agreement
+
+Deltacloud is an [Apache Software Foundation](http://www.apache.org/) project. As such
+and in keeping with all Apache projects, contributors are required to sign an individual
+contributor license agreement. This, together with instructions on signing and sending
+the agreement can be [found here](http://www.apache.org/licenses/icla.txt). Please do
+not hesitate to [contact us](contact.html) if you have any queries or require any
+clarification about contributing to the Deltacloud project.
+
+<br>
+[contents](#contents)
+<br>
+
+
diff --git a/site/content/documentation.haml b/site/content/documentation.haml
index 8019d08..4d495f1 100644
--- a/site/content/documentation.haml
+++ b/site/content/documentation.haml
@@ -16,189 +16,544 @@ filter:
         %a{ :href => doc[:href] }
           = doc[:description]
 
-%h1 Usage
-%p
-  The server listens by default on
-  %tt
-    http://localhost:3001/.
-  For testing and exploring, the server can be used from a web browser and
-  will return HTML to it. If you want to see XML output from the server in
-  the browser, append
-  %tt
-    &#x3f;format=xml
-  to each URL.
-
-%p
-  On Webkit based browsers like Safari, you might need to instruct the
-  server explicitly to
-  %a{ :href => "http://www.gethifi.com/blog/webkit-team-admits-accept-header-error" }
-    return HTML
-  &#x2e; Do this by appending
-  %tt
-    &#x3f;format=html
-  to each URL.
-
-%h2 Logging into the server
-%p
-  Deltacloud uses basic HTTP authentication to receive credentials from the
-  client and passes them through to the backend cloud it is talking to. The
-  credentials always consist of a username and password, and are never
-  stored on the server.  The exact credentials for logging into the server,
-  and where you find them, depends on the backend cloud that the server is
-  talking to.
-
-%p
-  The following table gives details about how to set up the server and what
-  credentials to provide for each of the supported clouds. The entry from
-  the Driver column needs to be passed as the
-  %tt
-    \--driver
-  option to
-  %tt
-    deltacloudd.
-  Note that some of the drivers require additional information, e.g.,
-  API endpoint URL's, be passed through environment variables
-
-%table#providers
-  %tr
-    %th
-      %strong Cloud
-    %th
-      %strong Driver
-    %th
-      %strong Username
-    %th
-      %strong Password
-    %th
-      %strong Notes
-  %tr
-    %td
-      %strong mock
-    %td
-      %tt mock
-    %td
-      %tt
-        mockuser
-    %td
-      %tt
-        mockpassword
-    %td
-      The mock driver doesn't talk to any cloud; it just pretends to be a cloud
-  %tr
-    %td
-      %strong Amazon EC2/S3
-    %td
-      %tt ec2
-    %td
-      Access Key ID
-    %td
-      Secret Access Key
-    %td
-      This information can be found on the
-      %a{ :href => "http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key"} Security Credentials
-      page in your AWS account
-  %tr
-    %td
-      %strong Eucalyptus
-    %td
-      %tt eucalyptus
-    %td
-      Access Key ID
-    %td
-      Secret Access Key
-    %td
-  %tr
-    %td
-      %strong GoGrid
-    %td
-      %tt gogrid
-    %td
-      API Key
-    %td
-      Shared Secret
-    %td
-      Go to
-      %tt My Account &gt; API Keys
-      for
-      %a{ :href => "https://my.gogrid.com/gogrid/com.servepath.gogrid.GoGrid/index.html" } your account
-      and click on the key you want to use to find the shared secret.
-  %tr
-    %td
-      %strong IBM SBC
-    %td
-      %tt sbc
-    %td
-      Username
-    %td
-      Password
-    %td
-  %tr
-    %td
-      %strong Microsoft Azure (Storage Account only)
-    %td
-      %tt azure
-    %td
-      Public Storage Account Name
-    %td
-      Primary Access Key
-    %td
-      The Storage Account Name is chosen when you create the service (e.g. name in http://name.blob.core.windows.net/). This and the access key are available from the service control panel.
-  %tr
-    %td
-      %strong OpenNebula
-    %td
-      %tt opennebula
-    %td
-      OpenNebula user
-    %td
-      OpenNebula password
-    %td
-      Set the environment variable
-      %tt OCCI_URL
-      to the address on which OpenNebula's OCCI server is listening.
-  %tr
-    %td
-      %strong Rackspace Cloud Servers/Cloud Files
-    %td
-      %tt rackspace
-    %td
-      Rackspace user name
-    %td
-      API Key
-    %td
-      Obtain the key from the
-      %a{ :href => "https://manage.rackspacecloud.com/APIAccess.do"} API Access
-      page in your control panel
-  %tr
-    %td
-      %strong RHEV-M
-    %td
-      %tt rhevm
-    %td
-      %a{ :href => "http://markmc.fedorapeople.org/rhevm-api/en-US/html/chap-REST_API_Guide-Authentication.html" } RHEV-M user name plus Windows domain
-      , e.g.,
-      %tt admin@rhevm.example.com
-    %td
-      RHEV-M password
-    %td
-      Set environment variable
-      %tt API_PROVIDER
-      to the URL of the RHEV-M REST API endpoint.
-  %tr
-    %td
-      %strong Rimuhosting
-    %td
-      %tt rimuhosting
-    %td not used (?)
-    %td API Key
-    %td
-  %tr
-    %td
-      %strong Terremark
-    %td
-      %tt terremark
-    %td
-      Username
-    %td
-      Password
-    %td
+%br
+%br
+%hr
+%br
+
+%a(name="install_deltacloud")
+%h1 Install Deltacloud
+
+This page lists the libraries and packages that you will need in order to install
+the Deltacloud server, a "Hello Deltacloud" quick-start guide as well as some
+information on interacting with the Deltacloud server after a succesful installation.
+
+%h2 Installation of Deltacloud itself
+
+Once you've setup all the dependencies listed below, installing Deltacloud is as easy as
+typing:
+%br
+%br
+%pre
+  %code
+    $ sudo gem install deltacloud-core
+And
+%strong thats it!
+The
+%strong gem install
+command will automatically fetch and install all other gems that the Deltacloud server
+needs if you don't already have these. As an alternative you can get the latest
+releases of Deltacloud from the
+%a{:href=>"http://www.apache.org/dist/incubator/deltacloud/"}
+  Apache website.
+
+%br
+%br
+%hr
+%br
+
+%a(name="dependencies")
+
+%h2 Installation dependencies
+
+The Deltacloud server relies on a number of external rubygems and other libraries.
+You must have the following packages installed before trying to install and
+run the Deltacloud server. Please note that the names of the packages below
+may differ for your distribution (e.g. 'ruby-devel' vs 'ruby-dev'). In short, you need:
+%br
+%br
+%ul
+  %li ruby and ruby-devel,
+  %li gem (RubyGems),
+  %li gcc-c++,
+  %li libxml2 and libxml2-devel,
+  %li libxslt and libxslt-devel,
+  %li rake
+
+More info on getting these follows:
+
+%h3 ruby and ruby-devel
+
+You need to
+%a{ :href=> "http://www.ruby-lang.org/en/downloads/"}
+  install ruby.
+You can check to see if you already have a ruby installation by typing:
+%br
+%br
+%pre
+  %code
+    $ ruby -v
+
+If you see something that looks like the following:
+%br
+%br
+%pre
+  %code
+    ruby 1.8.7 (2010-08-16 patchlevel 302) [i686-linux]
+
+then you can skip the ruby installation. Deltacloud requires ruby to be
+at least version 1.8.7. You also need the development headers (ruby-devel) as
+Deltacloud relies on some rubygems with C extensions. If you use a package manager
+such as yum or apt-get:
+
+%br
+%br
+%pre
+  %code
+    sudo yum install ruby
+    sudo yum install ruby-devel
+OR
+%br
+%br
+%pre
+  %code
+    sudo apt-get install ruby
+    sudo apt-get install ruby-devel
+
+%h3 gem (RubyGems)
+
+Deltacloud relies on a number of ruby gems so you also need to
+%a{:href=> "http://docs.rubygems.org/read/chapter/3"}
+  install RubyGems.
+As with ruby, you can check if you already have the
+%strong gem
+executable installed by typing
+%strong gem -v
+\. Again, your package manager can help with the installation:
+%br
+%br
+%pre
+  %code
+    $ sudo yum install rubygems
+
+
+%h3 gcc-c++, libxml2, libxml2-devel, libxslt, libxslt-devel
+
+These are required to build RubyGems that have C extensions. Again, typically
+the easiest way to get these is with you package manager:
+
+%br
+%br
+%pre
+  %code
+    $ sudo yum install gcc-c++
+    $ sudo yum install libxml libxml2-devel
+    $ sudo yum install libxslt libxslt-devel
+
+%h3 rake
+%a{:href=>"http://rake.rubyforge.org/"}
+  Rake
+is Ruby's Make and is itself a ruby gem. Once you have RubyGems installed you can
+get rake with:
+%br
+%br
+%pre
+  %code
+    $ sudo gem install rake
+
+%br
+%br
+%hr
+%br
+
+%a(name="quick_start")
+%h1 "Hello Deltacloud!", quick-start guide
+
+This guide assumes a linux environment. Some of the Deltacloud developers
+are running recent versions of
+%a{:href=> "http://fedoraproject.org"}
+  Fedora.
+However, as Deltacloud is written in Ruby you should be able to install it on
+any OS that supports Ruby. If you have succesfully installed Deltacloud or are
+having any problems doing so, please
+%a{:href=>"contact.html"}
+  let us know,
+we'd love to hear from you!
+
+%h2 Running the Deltacloud server
+
+After you succesfully install Deltacloud, you can start the server by typing
+%strong
+  deltacloudd -i
+  %em
+    provider_id.
+The
+%strong
+  %em
+    provider_id
+is the name of the cloud provider that you have an account with, for example 'ec2'.
+If you don't yet have an account with a cloud provider, you can still try the Deltacloud
+mock driver:
+
+%br
+%br
+%pre
+  %code
+    deltacloudd -i mock
+
+
+This will start the Deltacloud server on your local machine with the mock driver, accepting
+connections on port 3001 (the default). From version 0.4.0 of Deltacloud, you can use the
+'-l' flag to see
+%a{:href=> "drivers.html#providers"}
+  all available
+%strong
+  %em
+    provider_ids
+that can be used with the
+%strong deltacloudd
+executable.
+
+%br
+%br
+%pre
+  %code
+    $ deltacloudd -l
+    %br
+    Available drivers:
+    * condor
+    * vsphere
+    * opennebula
+    * eucalyptus
+    * rhevm
+    * sbc
+    * azure
+    * gogrid
+    * mock
+    * rackspace
+    * rimuhosting
+    * terremark
+    * ec2
+
+After you start the server, the Deltacloud HTML interface is available at
+%strong
+  http://localhost:3001/api
+\- open this address in your web browser. If you want to see XML output from the
+server in the browser, append
+%strong
+  %em
+    format=xml
+to each URL. On Webkit based browsers like Safari, you might need to instruct the
+server explicitly to
+%a{ :href => "http://www.gethifi.com/blog/webkit-team-admits-accept-header-error" }
+  return HTML
+Do this by appending
+%strong
+  %em
+    format=html
+to each URL. Your browser will prompt you for
+%a{:href=> "drivers.html#credentials"}
+  credentials
+when you invoke an operation that requires
+%a{:href=> "api.html#authentication"}
+  authentication.
+
+
+%br
+%br
+
+The '-h' flag will list all available options for
+%strong deltacloudd.
+For example, to start the Deltacloud server with the Rackspace driver on port 10000
+you can use:
+
+%br
+%br
+%pre
+  %code
+    $ deltacloudd -i rackspace -P 10000
+
+You may want to install the server on another machine and make Deltacloud available on
+your local network. To do this you need to bind the Deltacloud server to an address other
+than 'localhost' (default). For instance, if you install and start Deltacloud on a machine
+with the IP address 192.168.10.200 you should start the server with:
+
+%br
+%br
+%pre
+  %code
+    $ deltacloudd -i ec2 -P 5000 -r 192.168.10.200
+
+This will make the Deltacloud server available at the address
+%strong
+  http://192.168.10.200:5000/api.
+%br
+%br
+
+
+%br
+%br
+%hr
+%br
+
+%h2 The Deltacloud ruby client
+
+The Deltacloud project also maintains a ruby client, which you need to install
+seperately to the Deltacloud API server. The Deltacloud client consists of a
+ruby library (packaged as a ruby gem) which you can use to programmatically
+interact with the Deltacloud server and control your cloud infrastructure
+across cloud providers. For example, assuming the Deltacloud server is
+running at
+
+%strong
+  192.168.10.244:5000
+
+%br
+%br
+%pre
+  %code
+    require 'deltacloud'
+    %br
+    api_url      = 'http://192.168.10.244:5000/api'
+    api_name     = 'TK2PJCAN9R1HKG2FK24Z'
+    api_password = 'aLe27rZlRhlBcVoQbL4JsVtaNga12vEL9d9kS5CA'
+    %br
+    client = DeltaCloud.new( api_name, api_password, api_url )
+    %br
+    \# get a list of currently running instances (virtual machines)
+    client.instances.each do |instance|
+    \ puts instance.name
+    end
+    %br
+    #do other work with client here
+
+More comprehensive information on using the Deltacloud ruby client in this way
+can be found in the
+%a{:href=>"client-ruby.html"}
+  client documentation.
+
+Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud
+client by simply typing:
+
+%br
+%br
+%pre
+  %code
+    $ sudo gem install deltacloud-client
+
+Installing the Deltacloud client also gives you the
+%strong
+  deltacloudc
+command line tool. This executable makes use of the Deltacloud client library to speak to the
+Deltacloud server using the
+%a{:href=>"api.html"}
+  REST API.
+This allows you to to control your IAAS cloud infrastructure form the command line;
+even better if you are familiar with linux scripting, you can knock up a bash script in no time
+to automate your cloud infrastructure tasks.
+
+The general usage pattern for deltacloudc is:
+
+%br
+%br
+%pre
+  %code
+    $ deltacloudc collection operation [options]
+
+%ul
+  %li
+    %strong
+      %em
+        collection
+    refers to the Deltacloud object collections, such as Instances,
+    Images, Buckets, Realms etc, as described in greater detail in the
+    %a{:href=> "api.html#h1"}
+      REST API
+  %li
+    %strong
+      %em
+        operation
+    is collection dependant. All collections respond to 'index'
+    and 'show' operations (retrieve details on all objects in a given collection
+    or on a specific object, respectively); some collections respond to 'create' and 'destroy'
+    operations. The instances collection (realised virtual servers) responds to operations
+    for managing the instance lifecycle, such as 'stop', 'reboot' etc.
+  %li
+    %strong
+      %em
+        options
+    are listed by invoking
+    %strong deltacloudc -h
+    One important option is
+    %strong -u,
+    with which you specify the API_URL where the Deltacloud server is running. The API_URL
+    takes the form
+    %strong
+      http://[user]:[password]@[api_url]:[port]/[api]
+    (examples follow). Alternatively, rather than having to supply the API_URL for every
+    invocation of
+    %strong
+      deltacloudc
+    you have the choice of setting the API_URL environment variable
+    (e.g., export API_URL=http://mockuser:mockpassword@localhost:3001/api). A
+    listing of the credentials you need to provide for each back-end cloud provider
+    is available
+    %a{:href=>"drivers.html#credentials"}
+      here.
+
+The following examples assume that the Deltacloud server is running on your local machine
+port 3001 (the
+%strong deltacloudd
+server daemon defaults to 'localhost:3001') and was started with the 'mock' provider
+(i.e.
+%strong deltacloudd -i mock
+).
+
+To list all collections available in the current driver:
+%br
+%br
+%pre
+  %code
+    $ deltacloudc -l -u http://mockuser:mockpassword@localhost:3001/api
+
+To get a list of all
+%strong images:
+%br
+%br
+%pre
+  %code
+    $ deltacloudc images index -u http://mockuser:mockpassword@localhost:3001/api
+
+To list all operations for the
+%strong buckets
+collection:
+%br
+%br
+%pre
+  %code
+
+    $ deltacloudc buckets -l -u http://mockuser:mockpassword@localhost:3001/api
+
+To create a new blob in the bucket called 'bucket1':
+%br
+%br
+%pre
+  %code
+
+    $ deltacloudc blob create -i 'my_new_blob' -b 'bucket1' -f /home/marios/file.txt
+
+
+%br
+%br
+%hr
+%br
+
+
+%h2 Other HTTP clients - cURL
+
+As interaction with the Deltacloud server is via HTTP calls, you can use any
+HTTP client to talk to it using the Deltacloud
+%a{:href=>"api.html"}
+  REST API.
+One popular command line tool available on most modern linux distributions is
+%a{:href=> "http://curl.haxx.se/"}
+  cURL.
+We give some examples here of how you can use cURL to interact with Deltacloud,
+demonstrating the flexibility and power of the Deltacloud REST API.
+
+The following examples assume the Deltacloud server is running on locahost:3001,
+and was started with the 'ec2' driver (i.e.,
+%strong deltacloudd -i ec2
+).
+
+To get a
+%a{:href=>"api.html#list_images"}
+  listing of all images
+available in the back-end cloud:
+
+%br
+%br
+%pre
+  %code
+    curl  --user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
+    "http://localhost:3001/api/images?format=xml"
+
+The cURL
+%strong --user
+option is used to specify the
+%strong username:password
+%a{:href=>"drivers.html#credentials"}
+  credentials
+for access to the back-end cloud provider (Amazon EC2 in this case).
+
+To
+%a{:href=>"api.html#create_instance"}
+  create a new instance
+from the
+%a{:href=>"api.html#h3_3"}
+  image
+with id 'ami-f51aff9c', in
+%a{:href=>"api.html#h3_1"}
+  realm
+'us-east-1c', with the
+%a{:href=>"api.html#h3_2"}
+  hardware profile
+'c1.medium', in
+%a{:href=>"api.html#h3_7"}
+  firewall
+'default':
+
+%br
+%br
+%pre
+  %code
+    curl -X POST -F "keyname=eftah" -F "image_id=ami-f51aff9c"
+    \-F "realm_id=us-east-1c" -F "hwp_id=c1.medium" -F "firewalls1=default"
+    \--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
+    "http://localhost:3001/api/instances?format=xml"
+
+To
+%a{:href=>"api.html#delete_firewall"}
+  delete a firewall
+called 'develgroup':
+%br
+%br
+%pre
+  %code
+    curl -X DELETE
+    \--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
+    http://localhost:3001/api/firewalls/develgroup?format=xml
+
+To
+%a{:href=>"api.html#create_blob"}
+  create a blob
+called 'my_new_blob' within the
+%a{:href=>"api.html#h4_3"}
+  bucket
+'mybucket' from a local file with
+%strong
+  %em
+    HTTP PUT
+specifying its content type and setting some some metadata
+%strong
+  %em
+    key:value
+pairs:
+
+%br
+%br
+%pre
+  %code
+    curl -H 'content-type: text/html' -H 'X-Deltacloud-Blobmeta-Name:mariosblob'
+    \-H 'X-Deltacloud-Blobmeta-Version:2.1' --upload-file
+    "/home/marios/Desktop/somefile.html"
+    \--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
+    http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml
+
+To
+%a{:href=>"api.html#h4_3_10"}
+  retrieve blob metadata
+for the blob called 'my_new_blob':
+
+%br
+%br
+%pre
+  %code
+    curl -iv -X HEAD
+    \--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
+    http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml
+
+Note the use of the '-iv' flags here which will ensure that cURL displays the
+request and response headers (blob metadata is reported in the response headers,
+with an empty response body).
+
diff --git a/site/content/drivers.haml b/site/content/drivers.haml
index c66cbb6..690aff6 100644
--- a/site/content/drivers.haml
+++ b/site/content/drivers.haml
@@ -12,4 +12,6 @@ filter:
 
 = render(:partial => "providers")
 
+= render(:partial => "credentials")
+
 = rest
diff --git a/site/content/framework.mdown b/site/content/framework.mdown
deleted file mode 100644
index 8eb34b7..0000000
--- a/site/content/framework.mdown
+++ /dev/null
@@ -1,258 +0,0 @@
----
-title: Deltacloud - Documentation
-area: documentation
-extension: html
-filter:
-  - markdown
-  - outline
----
-[framework]: styles/framework.png
-
-# Writing Deltacloud Drivers #
-
-<toc class="toc" numbering="off" toc_style="ul" toc_range="h2-h3" />
-
-The _Deltacloud Core framework_ is provided to assist in creating
-intermediary [drivers](drivers.html) that speak the [Deltacloud REST
-API](api.html) on the front while communicating with cloud providers
-using their own native APIs on the back.
-
-![Deltacloud framework][framework]
-
-The framework handles all aspects of the REST API, while allowing
-driver implementors to focus on the specific cloud provider native
-API.
-
-Drivers may be implemented in as little as one Ruby class and plugged
-into the Deltacloud Core for deployment.
-
-## Driver SPI
-
-### Credentials
-
-The framework will collect credentials when the driver indicates they
-are required by throwing a `DeltaCloud::AuthException`. Each driver
-method takes a credentials hash as the first parameter, but unless the
-client has provided credentials, this hash will be empty.
-
-    def images(credentials, opts)
-      if ( credentials[:name].nil? )
-        throw DeltaCloud::AuthException.new
-      end
-      unless ( credentials_valid?( credentials ) )
-        throw DeltaCloud::AuthException.new
-      end
-
-      # do work
-
-    end
-
-### Object models used by drivers
-
-To assist driver authors, the framework provides a handful of model
-classes, representing each resource available through the Deltacloud
-API. Please see the [API reference](api.html) for details about each
-model. All of these model objects may be initialized with a hash.
-Every instance _must_ be assigned an `id` in addition to other
-attributes it may have. Unless otherwise noted, attributes are text.
-
-For example
-
-    HardwareProfile.new(
-      :architecture=>'x86_64',
-      :memory=>4,
-      :storage=>650,
-    )
-
-The `base_driver` interface and the already implemented drivers are
-located at `server/lib/deltacloud/` in the Deltacloud Core repository.
-
-#### `HardwareProfile`
-
-Attributes are
-
-- **`id`**
-- **`architecture`**
-- **`memory`** - Decimal, gigabytes
-- **`storage`** - Decimal, gigabytes
-- **`cpu`** - Interger, count
-
-#### `Realm`
-
-Attributes are
-
-- **`id`**
-- **`name`**
-- **`state`**
-- **`limit`**
-
-#### `Image`
-
-Attributes are
-
-- **`id`**
-- **`name`**
-- **`architecture`**
-- **`owner_id`**
-- **`description`**
-
-#### `Instance`
-
-Attributes are
-
-- **`id`**
-- **`name`**
-- **`owner_id`** - Opaque, external reference
-- **`image`** - References an image
-- **`realm`** - References a realm
-- **`state`** - One of `PENDING`, `RUNNING`, `SHUTTING_DOWN`, `STOPPED`
-- **`actions`** - Array of applicable actions
-- **`public_addresses`** - Array of IP addresses or hostnames as text
-- **`private_addresses`** - Array of IP addresses or hostnames as text
-
-### Driver methods
-
-The primary methods a driver class must implement are
-
-- `hardware_profiles(credentials, opts=nil)`
-- `images(credentials, opts=nil )`
-- `realms(credentials, opts=nil)`
-- `instances(credentials, opts=nil)`
-- `create_instance(credentials, image_id, opts)`
-- `reboot_instance(credentials, id)`
-- `stop_instance(credentials, id)`
-- `destroy_instance(credentials, id)`
-
-Generally, the `BaseDriver` handles singular cases while the specific
-provider driver must implement only the plural cases, along with
-specific action methods against resources.
-
-Additionally, to assist clients in determining what actions may be
-available without making additional requests, the following must be
-implemented.
-
-While the `credentials` hash is passed as the first parameter to each
-method, it _may_ be empty until the driver throws at least one
-`DeltaCloud::AuthException`. This exception will indicate to the
-framework that a normal HTTP authentication challenge should be issued
-to the client. Depending on the underlying provider the driver is
-connecting to, the credentials may not be required for some methods.
-
-Some methods also allow an optional `opts` hash, which may be `nil` or
-empty if not used for a particular invocation. The `BaseDriver`
-provides a method `filter_on(...)` which may be used to safely filter
-collections. The `filter_on(..)` method will be demonstrated below.
-
-Each method will be described in more detail below.
-
-#### `hardware_profiles(credentials, opts=nil)`
-
-The `hardware_profiles(...)` method should return an array of
-`HardwareProfile` objects. The `opts` hash, if present, must be
-inspected for `:id` and `:architecture` keys. If these keys are
-present, the results should be filtered by the value associated with
-each key. The `filter_on(...)` method is useful in this case.
-
-For example
-
-    def hardware_profiles(credentials, opts=nil)
-      hardware_profiles = fetch_all_hardware_profiles()
-      hardware_profiles = filter_on( hardware_profiles, :id, opts )
-      hardware_profiles = filter_on( hardware_profiles, :architecture, opts )
-      return hardware_profiles
-    end
-
-#### `realms(credentials, opts=nil)`
-
-The `realms(...)` method should return an array of `Realm` objects.
-
-#### `images(credentials, opts=nil)`
-
-The `images(...)` method should return an array of `Image` objects
-visible and accessible to the current user, as defined by the
-`credentials` hash.
-
-The `opts` hash, if present, must be inspected for `:id`, `:owner_id`
-and `:architecture` keys. If these keys are present, the results
-should be filtered by the value assocaited with each key.
-
-#### `instances(credentials, opts=nil)`
-
-The `instances(...)` method should return an array of `Instance`
-objects visible and accessible to the current user, as defined bv the
-`credentials` hash. If the `opts` hash is present and contains an
-`:id` key, the results should be filtered by the value associated with
-the key.
-
-#### `create_instance(credentials, image_id, opts)`
-
-The `create_instance(...)` method should create within the cloud, a
-new running instance based from an image identifier. The method should
-return an `Instance` object representing the newly-created instance.
-
-The `image_id` parameter must be non-nil. The `opts` hash may contain
-keys for `hwp_id` and `realm_id`. If they are present, they should be
-used for the creation of the instance. If they are not present,
-reasonable defaults should be used. In the case of hardware profile,
-one compatible with the image should be used as the default.
-
-#### `reboot_instance(credentials, id)`
-
-The `reboot_instance(...)` method should trigger a running instance to
-be rebooted. This method should return an `Instance` object.
-
-#### `stop_instance(credentials, id)`
-
-The `stop_instance(...)` method should trigger a running instance to be
-stopped. This method should return an `Instance` object. A cloud provider
-may allow restarting an instance, or may not.
-
-#### `destroy_instance(credentials, id)`
-
-The `destroy_instance(...)` method should remove the instance from the
-cloud provider, stopping it first, if necessary.
-
-
-#### `instance_states()`
-
-The `instance_states()` method should return an array/hash structure
-representing the finite-state-machine for instances. Each state an
-instance may be in should be an element in the returned array. Each
-state itself is also an array with 2 members. The first member is the
-name of the state, and the second member is a hash indicating valid
-transitions.
-
-The general format for the entire FSM structure is
-
-    [
-      [ :origin_state1, {
-        :destination_state1=>:action1,
-        :destination_state2=>:action2,
-      } ],
-      [ :origin_state2, {
-        :destination_state3=>:action3,
-        :destination_state4=>:action4,
-      } ],
-    ]
-
-Valid states are
-
-- **`:begin`**
-- **`:pending`**
-- **`:running`**
-- **`:shutting_down`**
-- **`:stopped`**
-- **`:end`**
-
-The `:begin` state is the state an instance is in immediate before
-being created. The `:end` state is the state an instance is in
-immediately after being destroyed.
-
-Valid transition actions are
-
-- **`:stop`**
-- **`:start`**
-- **`:reboot`**
-
-Additionally, to indicate a transition that may occur _without_ an
-action being triggered, the action **`:_auto_` may be used.
diff --git a/site/content/roadmap.mdown b/site/content/roadmap.mdown
index 4564844..e735975 100644
--- a/site/content/roadmap.mdown
+++ b/site/content/roadmap.mdown
@@ -23,15 +23,12 @@ and a longer list of items we will address after the next release, roughly
 in order of priority.
 
 If you have anything you'd like to see added to the roadmap, or think that
-some items should receive more attention, please let us know on the
-[mailing list][1]. Of course, the quickest way to get anything into
-Deltacloud is to [send us patches][2] &mdash; we will of course take patches
+some items should receive more attention, please [let us know](contact.html).
+Of course, the quickest way to get anything into
+Deltacloud is to send us patches; we will of course take patches
 for anything, regardless of whether they adress items on the roadmap or
 anything else.
 
-[1]: /contribute.html
-[2]: /contribute.html
-
 
 <toc numbering="off" toc_style="ul" toc_range='h2-h3' />
 
diff --git a/site/lib/documentation.rb b/site/lib/documentation.rb
index d6bc1ff..f2b701d 100644
--- a/site/lib/documentation.rb
+++ b/site/lib/documentation.rb
@@ -1,12 +1,11 @@
 module DocumentationHelper
   def documentation_pages
     [
-      { :href => 'documentation.html', :menu => 'Overview' },
+      { :href => 'documentation.html', :menu => 'Installation', :description => 'Installation, dependencies and quick-start (this page)' },
       { :href => "api.html" , :menu => 'REST API', :description => 'REST API definition' },
-      { :href => "drivers.html" , :menu => 'Drivers', :description => 'Currently-supported drivers' },
-      { :href => "framework.html" , :menu => 'Framework', :description => 'Framework for writing additional drivers' },
-      { :href => "client-ruby.html" , :menu => 'Ruby Client', :description => 'Ruby client' },
-      { :href => "libdeltacloud.html", :menu => "Libdeltacloud", :description => "C library" },
+      { :href => "drivers.html" , :menu => 'Drivers', :description => 'Information about currently supported drivers' },
+      { :href => "client-ruby.html" , :menu => 'Ruby Client', :description => 'The Deltacloud Ruby client' },
+      { :href => "libdeltacloud.html", :menu => "Libdeltacloud", :description => "The libdeltacloud C library" },
     ]
   end
 
diff --git a/site/output/client-ruby.html b/site/output/client-ruby.html
index ff321a8..63f7aa8 100644
--- a/site/output/client-ruby.html
+++ b/site/output/client-ruby.html
@@ -31,11 +31,14 @@
             <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
           </li>
           <li>
-            <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+            <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
           </li>
           <li>
             <a class='active' href='./documentation.html' title='Project documentation'>Documentation</a>
           </li>
+          <li>
+            <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+          </li>
         </ul>
       </div>
     </div>
@@ -44,7 +47,7 @@
         <ul class='l1'>
           <li>
             <a class='inactive' href='documentation.html'>
-              Overview
+              Installation
             </a>
           </li>
           <li>
@@ -58,11 +61,6 @@
             </a>
           </li>
           <li>
-            <a class='inactive' href='framework.html'>
-              Framework
-            </a>
-          </li>
-          <li>
             <a class='active' href='client-ruby.html'>
               Ruby Client
             </a>
diff --git a/site/output/contribute.html b/site/output/contribute.html
deleted file mode 100644
index 0d80e5d..0000000
--- a/site/output/contribute.html
+++ /dev/null
@@ -1,148 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-  <head>
-    <title>
-      Deltacloud - Contribute
-    </title>
-    <meta content='' name='keywords' />
-    <meta content='' name='description' />
-    <meta content='text/html; charset=utf-8' http-equiv='Content-Type' />
-    <link href='./styles/favicon.ico' rel='shortcut icon' type='image/x-icon' />
-    <link href='./styles/default.css' rel='StyleSheet' title='Main style' type='text/css' />
-    <link href='./styles/default-debug.css' rel='Alternate StyleSheet' title='Debug main style' type='text/css' />
-  </head>
-  <body>
-    <div id='header'>
-      <div class='container'>
-        <div id='headerLogo' onclick="location.href='index.html';" style='cursor: pointer;'>
-          <h1>
-            Deltacloud - Many clouds. One API. No problem.
-          </h1>
-        </div>
-      </div>
-    </div>
-    <div id='navigation'>
-      <div class='container' id='menu'>
-        <ul class='l0'>
-          <li>
-            <a class='inactive' href='./index.html' title='Deltacloud Home'>Home</a>
-          </li>
-          <li>
-            <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
-          </li>
-          <li>
-            <a class='active' href='./contribute.html' title='Information about design/development process'>Contribute</a>
-          </li>
-          <li>
-            <a class='inactive' href='./documentation.html' title='Project documentation'>Documentation</a>
-          </li>
-        </ul>
-      </div>
-    </div>
-    <div id='frontpageHeader'></div>
-    <div id='main'>
-      <div class='container' id='content-deltacloud'>
-        <h1>Help make Deltacloud better</h1>
-        
-        <p><ul class="toc">
-        <li>
-        <a href="#h1">Getting the sources</a>
-        </li>
-        <li>
-        <a href="#h2">Required packages</a>
-        </li>
-        <li>
-        <a href="#h3">Installing the Deltacloud Core</a>
-        </li>
-        </ul></p>
-        
-        <p>All development of Deltacloud takes place in the open. Communication is run
-        through the mailing list and all source code changes are tracked publicly.</p>
-        
-        <ul>
-        <li><p><strong>Mailing Lists</strong><br />
-        For Deltacloud API: <a href="mailto:deltacloud-dev@incubator.apache.org">deltacloud-dev@incubator.apache.org</a>.
-        To subscribe to it, send an email to <a href="deltacloud-dev-subscribe@incubator.apache.org">deltacloud-dev-subscribe@incubator.apache.org</a>. You can also view <a href="http://mail-archives.apache.org/mod_mbox/incubator-deltacloud-dev/">Archive</a> in case you are missing something.</p></li>
-        <li><p><strong>IRC</strong><br />
-        You can also join us on the Freenode IRC channel #deltacloud. Deltacloud
-        developers are generally available on the IRC channel</p></li>
-        <li><p><strong>Bugs</strong><br />
-        We track bugs in <a href="https://issues.apache.org/jira/browse/DTACLOUD">Apache JIRA</a>. You can <a href="https://issues.apache.org/jira/browse/DTACLOUD">view open bugs</a> or
-        <a href="https://issues.apache.org/jira/secure/CreateIssue!default.jspa">file a new one</a> there.</p></li>
-        <li><p><strong>Patches</strong><br />
-        Patches are very welcome. Please send them to the <a href="http://mail-archives.apache.org/mod_mbox/incubator-deltacloud-dev/">development
-        list</a>. Patches should be generated with <a href="http://kernel.org/pub/software/scm/git/docs/git-format-patch.html"><code>git</code>&nbsp;<code>format-patch</code></a>
-        and sent to the list with <a href="http://kernel.org/pub/software/scm/git/docs/git-send-email.html"><code>git</code>&nbsp;<code>send-email</code></a>.</p></li>
-        <li><strong>Roadmap</strong><br />
-        We maintain our roadmap in
-        <a href="https://teambox.com/projects/deltacloud/task_lists">teambox</a> so that
-        anyone can comment on tasks and suggest new ones.</li>
-        </ul>
-        
-        
-        <h2 id="h1">Getting the sources</h2>
-        
-        <p>Then Deltacloud Core gives you the API and drivers to various cloud providers.
-        It also provides a client library and a commandline interface.</p>
-        
-        <p>The Deltacloud Core repository is hosted on Apache Incubator.
-        Apache uses Subversion, but there is a git mirror available:</p>
-        
-        <pre><code>$ mkdir deltacloud&#x000A;$ cd deltacloud&#x000A;$ git clone git://git.apache.org/deltacloud.git core&#x000A;</code></pre>
-        
-        <p>You can find the Subversion repository at: <a href="https://svn.apache.org/repos/asf/incubator/deltacloud">https://svn.apache.org/repos/asf/incubator/deltacloud</a>.</p>
-        
-        <h2 id="h2">Required packages</h2>
-        
-        <p>In order to make the Deltacloud components work, you'll need to
-        have the following packages installed (on Fedora 14; the names may vary on
-        your distro):</p>
-        
-        <pre><code>ruby&#x000A;ruby-devel&#x000A;rubygem-rake&#x000A;gcc-c++&#x000A;libxml2-devel&#x000A;libxslt-devel&#x000A;</code></pre>
-        
-        <p><strong>Note:</strong> these packages are necessary for building all the required ruby gems
-        that Deltacloud requires. If you want to install the gems using your system's
-        package manager (yum, apt, ports, etc.) you won't need to install these
-        packages manually.</p>
-        
-        <p>To install all required ruby gems manually you should run:</p>
-        
-        <pre><code>$ yum install rubygem-haml rubygem-sinatra rubygem-thin rubygem-json \&#x000A;  rubygem-net-json rubygem-rack-accept rubygem-nokogiri rubygem-aws \&#x000A;  rubygem-rest-client&#x000A;</code></pre>
-        
-        <h2 id="h3">Installing the Deltacloud Core</h2>
-        
-        <p>First, you need to install the server that will give you the Deltacloud API:</p>
-        
-        <pre><code>$ cd path/to/deltacloud/core/server&#x000A;$ rake package&#x000A;$ sudo gem install pkg/deltacloud-core-&lt;version&gt;.gem&#x000A;</code></pre>
-        
-        <p>Then install the client library:</p>
-        
-        <pre><code>$ cd path/to/deltacloud/core/client&#x000A;$ rake package&#x000A;$ sudo gem install pkg/deltacloud-client-&lt;version&gt;.gem&#x000A;</code></pre>
-        
-        <p>Once you have the client installed, run the following command:</p>
-        
-        <pre><code>$ cd path/to/deltacloud/core/client&#x000A;$ rake fixtures&#x000A;</code></pre>
-      </div>
-    </div>
-    <div id='footer-deltacloud'>
-      <div class='container'>
-        <p>
-          <a href='http://incubator.apache.org'>
-            <img alt='Apache Incubator Logo' src='http://incubator.apache.org/images/apache-incubator-logo.png' />
-          </a>
-        </p>
-        <p id='disclaimer'>
-          Apache Deltacloud is an effort undergoing incubation at The
-          Apache Software Foundation (ASF), sponsored by the Apache
-          Incubator PMC. Incubation is required of all newly accepted
-          projects until a further review indicates that the
-          infrastructure, communications, and decision making process have
-          stabilized in a manner consistent with other successful ASF
-          projects. While incubation status is not necessarily a reflection
-          of the completeness or stability of the code, it does indicate
-          that the project has yet to be fully endorsed by the ASF.
-        </p>
-      </div>
-    </div>
-  </body>
-</html>
diff --git a/site/output/dcloud-demo.html b/site/output/dcloud-demo.html
index da0adc1..09cf171 100644
--- a/site/output/dcloud-demo.html
+++ b/site/output/dcloud-demo.html
@@ -31,11 +31,14 @@
             <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
           </li>
           <li>
-            <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+            <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
           </li>
           <li>
             <a class='inactive' href='./documentation.html' title='Project documentation'>Documentation</a>
           </li>
+          <li>
+            <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+          </li>
         </ul>
       </div>
     </div>
@@ -49,7 +52,7 @@
             <param name='wmode' value='opaque' />
             <param name='scale' value='noscale' />
             <param name='salign' value='lt' />
-            <param name='FlashVars' value='&amp;amp;MM_ComponentVersion=1&amp;amp;skinName=Clear_Skin_1&amp;amp;streamName=video/DCloud_Demo&amp;amp;autoPlay=true&amp;amp;autoRewind=false' />
+            <param name='FlashVars' value='&amp;MM_ComponentVersion=1&amp;skinName=Clear_Skin_1&amp;streamName=video/DCloud_Demo&amp;autoPlay=true&amp;autoRewind=false' />
             <param name='swfversion' value='8,0,0,0' />
             <!--
               This param tag prompts users with Flash Player 6.0 r65 and higher to download the latest version of Flash Player. Delete it if you don’t want users to see the prompt.
@@ -69,7 +72,7 @@
               <param name='wmode' value='opaque' />
               <param name='scale' value='noscale' />
               <param name='salign' value='lt' />
-              <param name='FlashVars' value='&amp;amp;MM_ComponentVersion=1&amp;amp;skinName=Clear_Skin_1&amp;amp;streamName=video/DCloud_Demo&amp;amp;autoPlay=true&amp;amp;autoRewind=false' />
+              <param name='FlashVars' value='&amp;MM_ComponentVersion=1&amp;skinName=Clear_Skin_1&amp;streamName=video/DCloud_Demo&amp;autoPlay=true&amp;autoRewind=false' />
               <param name='swfversion' value='8,0,0,0' />
               <param name='expressinstall' value='Scripts/expressInstall.swf' />
               <!--
diff --git a/site/output/dcloud.html b/site/output/dcloud.html
index 1778aef..16a5b5e 100644
--- a/site/output/dcloud.html
+++ b/site/output/dcloud.html
@@ -31,11 +31,14 @@
             <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
           </li>
           <li>
-            <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+            <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
           </li>
           <li>
             <a class='inactive' href='./documentation.html' title='Project documentation'>Documentation</a>
           </li>
+          <li>
+            <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+          </li>
         </ul>
       </div>
     </div>
@@ -51,7 +54,7 @@
               <param name="scale" value="noscale">
             -->
             <param name='salign' value='lt' />
-            <param name='FlashVars' value='&amp;amp;MM_ComponentVersion=1&amp;amp;skinName=Clear_Skin_1&amp;amp;streamName=video/DCloud&amp;amp;autoPlay=true&amp;amp;autoRewind=false' />
+            <param name='FlashVars' value='&amp;MM_ComponentVersion=1&amp;skinName=Clear_Skin_1&amp;streamName=video/DCloud&amp;autoPlay=true&amp;autoRewind=false' />
             <param name='swfversion' value='8,0,0,0' />
             <!--
               This param tag prompts users with Flash Player 6.0 r65 and higher to download the latest version of Flash Player. Delete it if you don’t want users to see the prompt.
@@ -71,7 +74,7 @@
               <param name='wmode' value='opaque' />
               <param name='scale' value='noscale' />
               <param name='salign' value='lt' />
-              <param name='FlashVars' value='&amp;amp;MM_ComponentVersion=1&amp;amp;skinName=Clear_Skin_1&amp;amp;streamName=video/DCloud&amp;amp;autoPlay=true&amp;amp;autoRewind=false' />
+              <param name='FlashVars' value='&amp;MM_ComponentVersion=1&amp;skinName=Clear_Skin_1&amp;streamName=video/DCloud&amp;autoPlay=true&amp;autoRewind=false' />
               <param name='swfversion' value='8,0,0,0' />
               <param name='expressinstall' value='Scripts/expressInstall.swf' />
               <!--
diff --git a/site/output/developers.html b/site/output/developers.html
new file mode 100644
index 0000000..e859731
--- /dev/null
+++ b/site/output/developers.html
@@ -0,0 +1,571 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+  <head>
+    <title>
+      Deltacloud - Information for Developers
+    </title>
+    <meta content='' name='keywords' />
+    <meta content='' name='description' />
+    <meta content='text/html; charset=utf-8' http-equiv='Content-Type' />
+    <link href='./styles/favicon.ico' rel='shortcut icon' type='image/x-icon' />
+    <link href='./styles/default.css' rel='StyleSheet' title='Main style' type='text/css' />
+    <link href='./styles/default-debug.css' rel='Alternate StyleSheet' title='Debug main style' type='text/css' />
+  </head>
+  <body>
+    <div id='header'>
+      <div class='container'>
+        <div id='headerLogo' onclick="location.href='index.html';" style='cursor: pointer;'>
+          <h1>
+            Deltacloud - Many clouds. One API. No problem.
+          </h1>
+        </div>
+      </div>
+    </div>
+    <div id='navigation'>
+      <div class='container' id='menu'>
+        <ul class='l0'>
+          <li>
+            <a class='inactive' href='./index.html' title='Deltacloud Home'>Home</a>
+          </li>
+          <li>
+            <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
+          </li>
+          <li>
+            <a class='active' href='./developers.html' title='Information for developers'>Developers</a>
+          </li>
+          <li>
+            <a class='inactive' href='./documentation.html' title='Project documentation'>Documentation</a>
+          </li>
+          <li>
+            <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+          </li>
+        </ul>
+      </div>
+    </div>
+    <div id='frontpageHeader'></div>
+    <div id='main'>
+      <div class='container' id='content-deltacloud'>
+        <h1>Contribute to the Deltacloud Project</h1>
+        
+        <p><a href="http://www.apache.org/" title="The Apache Software Foundation">Apache</a> Deltacloud is
+        free, open source software licensed under the
+        <a href="http://www.apache.org/licenses/LICENSE-2.0" title="The Apache License">apache license</a>.
+        Please feel free to <a href="contact.html">contact us</a> if you have any questions about the
+        project or with any suggestions on how to improve Deltacloud. The Deltacloud
+        developer community is open to anyone that wants to contribute!</p>
+        
+        <p>This page contains information for developers:</p>
+        
+        <p><a name="contents" /></p>
+        
+        <p><ul class="toc">
+        <li>
+        <a href="#h1">Setting up the developer environment</a>
+        <ul>
+        <li>
+        <a href="#h1_1">Getting the sources</a>
+        </li>
+        <li>
+        <a href="#h1_2">Development dependencies</a>
+        </li>
+        <li>
+        <a href="#h1_3">Building from source and installing the Deltacloud gem</a>
+        </li>
+        </ul>
+        </li>
+        <li>
+        <a href="#h2">Contribute to Deltacloud</a>
+        <ul>
+        <li>
+        <a href="#h2_1">Overview of the Deltacloud directory structure</a>
+        </li>
+        <li>
+        <a href="#h2_2">Forming and sending patches</a>
+        </li>
+        <li>
+        <a href="#h2_3">Use the Deltacloud github mirror</a>
+        </li>
+        <li>
+        <a href="#h2_4">Writing a new cloud provider driver</a>
+        </li>
+        <li>
+        <a href="#h2_5">Writing and running tests</a>
+        </li>
+        <li>
+        <a href="#h2_6">Licensing - the Apache Individual Contributor License Agreement</a>
+        </li>
+        </ul></li></ul></p>
+        
+        <br>
+        
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h2 id="h1">Setting up the developer environment</h2>
+        
+        <p>The information here is about setting up a dev environment for Deltacloud. If you
+        are interested in first trying out Deltacloud, you should instead follow the
+        instructions in the <a href="download.html">Download</a> page and read the
+        <a href="documentation.html#install_deltacloud">installation and quick start guide</a>.</p>
+        
+        <p>Before setting up the development environment, make sure you have all the
+        <a href="documentation.html#dependencies">installation dependencies</a>.</p>
+        
+        <h3 id="h1_1">Getting the sources</h3>
+        
+        <p>Deltacloud provides the API server and drivers to various cloud providers.
+        It also includes a ruby client library and a commandline interface.</p>
+        
+        <p><strong>First, make sure you have installed all <a href="documentation.html#dependencies">dependencies</a>.</strong></p>
+        
+        <p>The Deltacloud repository is hosted at the Apache Software Foundation.
+        Apache uses <strong><em>subversion</em></strong> and you can find the Deltacloud subversion repository
+        at <a href="https://svn.apache.org/repos/asf/incubator/deltacloud">https://svn.apache.org/repos/asf/incubator/deltacloud</a>.</p>
+        
+        <p>However many of the Deltacloud developers use the
+        <a href="http://git-scm.com/download">git version control system</a> and the Deltacloud
+        code is available through a git mirror. The instructions on this page are
+        thus specific to using <strong><em>git</em></strong> for getting the code and also
+        for making and sending patches.</p>
+        
+        <p>If you don't already have <strong><em>git</em></strong> there are
+        <a href="http://git-scm.com/download">git binaries</a> available for specific systems.
+        Alternatively, if you use the <strong><em>yum</em></strong> or <strong><em>apt</em></strong> package managers:</p>
+        
+        <pre><code>$ sudo yum install git&#x000A;        &lt;OR&gt;&#x000A;$ sudo apt-get install git&#x000A;</code></pre>
+        
+        <p>With <strong><em>git</em></strong> in place, to get the latest HEAD of the Deltacloud git repo:</p>
+        
+        <pre><code>$ mkdir DeltacloudProject&#x000A;$ cd DeltacloudProject&#x000A;$ git clone git://git.apache.org/deltacloud.git&#x000A;</code></pre>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h3 id="h1_2">Development dependencies</h3>
+        
+        <p>Apart from the <a href="documentation.html#dependencies">installation dependencies</a>,
+        in order to develop for Deltacloud you will need some additional libraries,
+        such as <a href="http://cukes.info/">cucumber</a>,
+        <a href="http://bashdb.sourceforge.net/ruby-debug/home-page.html">ruby-debug</a> and
+        <a href="http://rspec.info/">rpsec</a>. The Deltacloud source includes a Gemfile which
+        lists these development dependencies: <strong>/path/to/deltacloud/server/Gemfile</strong>.</p>
+        
+        <p>Thus, the recommended way to get all development dependencies is with
+        <a href="http://gembundler.com/">Bundler</a>. If you don't already have bundler, install
+        it:</p>
+        
+        <pre><code>$ sudo gem install bundler&#x000A;</code></pre>
+        
+        <p>Then, you can get all the required developer dependencies by:</p>
+        
+        <pre><code>$ cd /path/to/deltacloud/server&#x000A;$ bundle install --system&#x000A;</code></pre>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h3 id="h1_3">Building from source and installing the Deltacloud gem</h3>
+        
+        <p>To build and install the Deltacloud server gem:</p>
+        
+        <pre><code>$ cd path/to/DeltacloudProject/deltacloud/server&#x000A;$ rake package&#x000A;$ sudo gem install pkg/deltacloud-core-&lt;version&gt;.gem&#x000A;</code></pre>
+        
+        <p>Then install the Deltacloud client gem:</p>
+        
+        <pre><code>$ cd path/to/DeltacloudProject/deltacloud/client&#x000A;$ rake package&#x000A;$ sudo gem install pkg/deltacloud-client-&lt;version&gt;.gem&#x000A;</code></pre>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h2 id="h2">Contribute to Deltacloud</h2>
+        
+        <p>The information here is aimed at helping developers more quickly understand the Deltacloud
+        project code, the process used by the development community for contributing and some
+        guidelines on how to go about adding a cloud provider driver to the Deltacloud project.</p>
+        
+        <h3 id="h2_1">Overview of the Deltacloud directory structure</h3>
+        
+        <p><strong>Note:</strong> the following is not an exhaustive list of all files and directories in the
+        Deltacloud project. Rather it is intended as an aid to ease familirisation
+        with the project files for developers - for example to quickly identify where
+        the Deltacloud cloud provider drivers are stored:</p>
+        
+        <p><a name="deltacloud_directories"> .</a></p>
+        
+        <pre><code>deltacloud&#x000A;|-----------------------------------------------------------------------------------&#x000A;|-d--&gt;tests                           Contains Cucumber tests&#x000A;|-----------------------------------------------------------------------------------&#x000A;|-d--&gt;site                            Files for this website&#x000A;|-----------------------------------------------------------------------------------&#x000A;|-d--&gt;client                          Contains the Deltacloud ruby client&#x000A;|-----------------------------------------------------------------------------------&#x000A;|-d--&gt;clients                         Contains other Deltacloud clients (e.g. java)&#x000A;|-----------------------------------------------------------------------------------&#x000A;|-d--&gt; server&#x000A;       |----------------------------------------------------------------------------&#x000A;       |-f--&gt;server.rb                Contains the !
 sinatra routes&#x000A;       |----------------------------------------------------------------------------&#x000A;       |-d--&gt;bin                      Contains the Deltacloud executable deltacloudd&#x000A;       |----------------------------------------------------------------------------&#x000A;       |-d--&gt;views                    Contains haml views for each collection&#x000A;       |----------------------------------------------------------------------------&#x000A;       |-d--&gt;tests                    Contains unit tests for drivers&#x000A;       |----------------------------------------------------------------------------&#x000A;       |-d--&gt;lib&#x000A;             |----------------------------------------------------------------------&#x000A;             |-d--&gt;sinatra            Contains rabbit DSL and various helpers&#x000A;             |----------------------------------------------------------------------&#x000A;             |-d--&gt;deltacloud&#x0!
 00A;                   |----------------------------------------------
------------------&#x000A;                   |-d--&gt;models       Definition of each collection model&#x000A;                   |----------------------------------------------------------------&#x000A;                   |-d--&gt;drivers      Contains the drivers for each cloud provider&#x000A;                   |----------------------------------------------------------------&#x000A;                   |-d--&gt;helpers      Various helper methods used by the drivers&#x000A;                   |----------------------------------------------------------------&#x000A;                   |-d--&gt;base_driver  Contains the Deltacloud base driver&#x000A;                   |----------------------------------------------------------------&#x000A;</code></pre>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h3 id="h2_2">Forming and sending patches</h3>
+        
+        <p>There are many ways to work with git and there are many
+        <a href="http://book.git-scm.com/">good resources</a> on using git. The Deltacloud community uses
+        a <strong><em>local_branch</em></strong> ---> <strong><em>patch</em></strong> ---> <strong><em>review</em></strong> ---> <strong><em>accept</em></strong> ---> <strong><em>commit</em></strong>
+        process for contributing to the project. The following shows the typical workflow used
+        by the core developers.</p>
+        
+        <p>First you need to set some settings inside the git configuration file. In the root
+        of the git project (Deltacloud in this case) there is a .git hidden directory containing
+        the config file. Open this with your preferred editor:</p>
+        
+        <pre><code>$ vim deltacloud/.git/config&#x000A;</code></pre>
+        
+        <p>Add the following to any existing configuration replacing the relevant values with your own:</p>
+        
+        <pre><code>[sendemail]&#x000A;signedoffbycc = no&#x000A;chainreplyto = no&#x000A;smtpserver = your_smpt.server.address&#x000A;thread = yes&#x000A;from = your_email_address&#x000A;suppresscc = all&#x000A;&#x000A;[core]&#x000A;whitespace = trailing-space,space-before-tab&#x000A;&#x000A;[apply]&#x000A;whitespace = error-all&#x000A;</code></pre>
+        
+        <p>After getting the latest HEAD of the Deltacloud git repo, you will have one local
+         branch called <strong><em>trunk</em></strong>.</p>
+        
+        <pre><code>$ git branch&#x000A;* trunk&#x000A;</code></pre>
+        
+        <p>Fetch the latest changes from the git repo:</p>
+        
+        <pre><code>$ git pull&#x000A;</code></pre>
+        
+        <p>Make a new local branch for your edits and give it a name:</p>
+        
+        <pre><code>$ git checkout -b my_new_branch&#x000A;</code></pre>
+        
+        <p>Make your edits/changes/voodoo. Once done, review which files you changed:</p>
+        
+        <pre><code>$ git status&#x000A;</code></pre>
+        
+        <p>Once you are happy with the changes and everything is working, commit those changes
+        to your local branch:</p>
+        
+        <pre><code>$ git commit -a&#x000A;</code></pre>
+        
+        <p>This will open an editor (e.g., vi) for you to enter a commit message. Please keep this
+        short and succint in general and keep individual lines at no longer than 80 characters.
+        The command <strong>git log</strong> will show you recent commits together with their commit messages
+        as examples.</p>
+        
+        <p>At this point, your local branch will contain the changes that you worked on and will
+        be different from your <strong><em>local</em></strong> <strong>trunk</strong> branch. In the meantime, other developers
+        may have already committed changes to the <strong><em>remote</em></strong> <strong>trunk</strong> branch in the Apache git repo.
+        Thus, you need to fetch any new changes and merge into your <strong><em>local</em></strong> <strong>trunk</strong> and then
+        rebase your local <strong>trunk</strong> onto the new branch which contains your changes.</p>
+        
+        <p>Change to trunk and fetch upstream changes if any:</p>
+        
+        <pre><code>$ git checkout trunk&#x000A;$ git pull&#x000A;</code></pre>
+        
+        <p>Your <strong><em>local</em></strong> trunk is now up-to-date with the <strong><em>remote</em></strong> trunk in the git repo.
+        Next, rebase the <strong><em>local</em></strong> trunk onto the branch containing your changes:</p>
+        
+        <pre><code>$ git rebase trunk my_new_branch&#x000A;</code></pre>
+        
+        <p>Now you are ready to make patches against trunk and send them to the Deltacloud mailing
+        list for review by other developers in the community:</p>
+        
+        <pre><code>$ git format-patch -o /path/to/where/you/keep/patches/ trunk&#x000A;&#x000A;$ git send-email --compose --subject 'some subject'&#x000A;  --thread /path/to/where/you/keep/patches/* --to deltacloud-dev@incubator.apache.org&#x000A;</code></pre>
+        
+        <p>Your patches will be reviewed by other members of the community. The general rule used
+        is that a patch will be committed to the repo if it receives at least one <strong>ACK</strong> and no
+        <strong>NACK</strong>. Once a patch is <strong>ACK</strong>ed it will be committed by one of the Deltacloud community
+        developers that have commit rights to the Apache repo. If your patches are on the mailing
+        list for a few days and no-one is responding to them feel free to send a reminder email
+        as patches may be missed/forgotten.</p>
+        
+        <p>You can also contribute to the project by reviewing patches sent by other contributors:</p>
+        
+        <p>Make a new branch where you will apply the patches and test:</p>
+        
+        <pre><code>$ git checkout -b jsmith_patches&#x000A;</code></pre>
+        
+        <p>You can use either git am ("apply mail") to apply patches in mail format, or git apply for
+        plain-text patches. Using git am will also commit the patches to the local branch
+        preserving the author's commit messages whilst git apply will only apply the files but not
+        commit them. For simple patch review the difference between these is insignificant and
+        boils down to whether you like to save the patches as plain-text or in .mbox email format.</p>
+        
+        <p>Save the patches to some known location, make sure you're on the branch you wish to apply
+        them onto, and then apply:</p>
+        
+        <pre><code>$ git checkout jsmith_patches&#x000A;&#x000A;$ cat /path/to/patches/0001-name-of-patch.txt | git apply&#x000A;                         _OR_&#x000A;$ git am /path/to/patches/0001-name-of-patch.eml&#x000A;</code></pre>
+        
+        <p>If you think the patches are sane, do what the author intended and most importantly don't
+        break anything else, then you can send an <strong>ACK</strong> in response to the patches on the
+        Deltacloud <a href="contact.html">mailing list</a>. Similarly, if you think there is some problem
+        with the patches you should send a <strong>NACK</strong> with an explanation of the problem you have
+        found so that the author can address this.</p>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h3 id="h2_3">Use the Deltacloud github mirror</h3>
+        
+        <p>The Deltacloud project maintains a
+        <a href="https://github.com/apache/deltacloud">github page</a> which mirrors the Apache
+        repository. You can contribute through github if that is preferrable.
+        <a href="http://help.github.com/fork-a-repo/">Fork</a> the Deltacloud repo, make your changes and
+        commit them back to your fork. Then issue a
+        <a href="http://help.github.com/send-pull-requests/">pull request</a>. It may also be wise to
+        send an email to the Deltacloud <a href="contact.html">mailing list</a> to let the community know
+        about your pull request as in general the mailing list is checked much more often than
+        the github page.</p>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h3 id="h2_4">Writing a new cloud provider driver</h3>
+        
+        <p>The deltacloud drivers live in
+        <a href="#deltacloud_directories">deltacloud/server/lib/deltacloud/drivers</a>. The information here
+        is intended as a primer for anybody that wants to contribute a new cloud provider driver to
+        the Deltacloud project.</p>
+        
+        <p>To add a driver for a hypothetical <strong>Foo</strong> cloud, you should start by adding a a directory
+        under /drivers/ and then a file for the driver itself, i.e.:</p>
+        
+        <pre><code>deltacloud/server/lib/deltacloud/drivers/foo/foo_driver.rb&#x000A;</code></pre>
+        
+        <p>That file needs to define a class <strong>Deltacloud::Drivers::Foo::FooDriver</strong> and must be
+        a subclass of the Deltacloud::BaseDriver (example follows).</p>
+        
+        <p>You need to decide which <a href="api.html#h1">collections</a> the provider for which you're
+        writing the driver supports - e.g. images, instances, keys, buckets/blobs (storage), etc.
+        and declare these with:</p>
+        
+        <pre><code>def supported_collections&#x000A;  DEFAULT_COLLECTIONS + [ :buckets ] - [ :storage_snapshots, :storage_volumes ]&#x000A;end&#x000A;</code></pre>
+        
+        <p>The above declares that the driver supports the <strong>DEFAULT_COLLECTIONS</strong> (defined in
+        <strong>deltacloud/server/lib/drivers.rb</strong>) except <a href="api.html#h4_2">storage_snapshots</a> and
+        <a href="api.html#h4_1">storage_volumes</a> and additionally also supports the
+        <a href="api.html#h4_3">buckets</a> collection. For example, a storage only cloud provider driver
+        would support only the <strong>buckets</strong> colletion.</p>
+        
+        <p>You can then start to define the methods for each of the collections that your driver
+        will support. The methods for each collection, as well as the routes that map to them
+        are defined in <strong>/deltacloud/server/server.rb</strong>. In general you can look at the existing
+        drivers for pointers on how to implement any specific method.</p>
+        
+        <p>One important consideration is how your cloud provider driver will be communicating
+        with the cloud provider. Many of the existing drivers use external ruby gems for this
+        purpose: for example, the <strong>ec2</strong> driver uses the <a href="https://github.com/appoxy/aws/">aws</a>
+        gem, the <strong>rackspace</strong> driver uses the
+        <a href="https://github.com/rackspace/ruby-cloudfiles">cloudfiles</a> and
+        <a href="https://github.com/rackspace/ruby-cloudservers">cloudservers</a> gems. However, other drivers
+        implement their own clients with which to communicate with the cloud provider, such as
+        the IBM SBC driver and the Gogrid driver. This also explains why, under the /drivers
+        directory, some drivers contain only the provider_<strong><em>driver</em></strong>.rb file, whilst others also
+        define a provider_<strong><em>client</em></strong>.rb file. Whether you write your own client or use an existing
+        one is entirey at your discretion.</p>
+        
+        <p>Thus, your driver for the cloud provider foo may start out looking something like:</p>
+        
+        <pre><code>require 'deltacloud/base_driver'&#x000A;require 'foo_lib' # a library for talking to the foo cloud&#x000A;&#x000A;module Deltacloud&#x000A;  module Drivers&#x000A;    module Foo&#x000A;&#x000A;class FooDriver &lt; Deltacloud::BaseDriver&#x000A;&#x000A;    def supported_collections&#x000A;      DEFAULT_COLLECTIONS + [ :buckets ]&#x000A;    end&#x000A;&#x000A;    def images(credentials, opts={})&#x000A;      client = new_foo_client(credentials)&#x000A;      # use client to get a list of images from the back-end cloud and then create&#x000A;      # a Deltacloud Image object for each of these. Filter the result&#x000A;      # (eg specific image requested) and return to user&#x000A;    end&#x000A;&#x000A;    def realms(credentials, opts={})&#x000A;      (...)&#x000A;    end&#x000A;&#x000A;    def instances(credentials, opts={})&#x000A;      (...)&#x000A;    end&#x000A;&#x000A;    ... ETC&#x000A;&#x000A;    private&#x000A;&#x000A;    def new_foo_client(credenti!
 als)&#x000A;      client = FooLib::Service.new({:user =&gt; credentials.user,&#x000A;                                    :pass =&gt; credentials.password })&#x000A;    end&#x000A;&#x000A;end&#x000A;        end&#x000A;      end&#x000A;    end&#x000A;</code></pre>
+        
+        <p>One important method for drivers that implement the <a href="api.html#h3_5">instances</a>
+        collection is <strong>instance_states</strong>. This method represents the finite-state-machine
+        for instances which varies across cloud providers. For example, in some clouds
+        an instance may be in the 'running' state after creation, whereas in other clouds
+        an instance may need to be started explicitly. An example of what this method may
+        look like is:</p>
+        
+        <pre><code>define_instance_states do&#x000A;  start.to( :pending )          .on( :create )&#x000A;  pending.to( :running )        .automatically&#x000A;  running.to( :running )        .on( :reboot )&#x000A;  running.to( :shutting_down )  .on( :stop )&#x000A;  shutting_down.to( :stopped )  .automatically&#x000A;  stopped.to( :finish )         .automatically&#x000A;end&#x000A;</code></pre>
+        
+        <p>The voodoo used here (i.e. definition of .to and .on etc) is defined in
+        /deltacloud/server/lib/deltacloud/state_machine.rb.</p>
+        
+        <p>Valid states are</p>
+        
+        <ul>
+        <li><strong><code>:begin</code></strong></li>
+        <li><strong><code>:pending</code></strong></li>
+        <li><strong><code>:running</code></strong></li>
+        <li><strong><code>:shutting_down</code></strong></li>
+        <li><strong><code>:stopped</code></strong></li>
+        <li><strong><code>:end</code></strong></li>
+        </ul>
+        
+        
+        <p>The <code>:begin</code> state is the state an instance is in immediate before
+        being created. The <code>:end</code> state is the state an instance is in
+        immediately after being destroyed.</p>
+        
+        <p>Valid transition actions are</p>
+        
+        <ul>
+        <li><strong><code>:stop</code></strong></li>
+        <li><strong><code>:start</code></strong></li>
+        <li><strong><code>:reboot</code></strong></li>
+        </ul>
+        
+        
+        <p>Additionally, to indicate a transition that may occur <em>without</em> an
+        action being triggered, the action <strong><code>:automatically</code></strong> may be used,
+        as shown in the example above.</p>
+        
+        <p>Depending on the collections you'll be supporting, some other methods that
+        your driver may implement are:</p>
+        
+        <ul>
+        <li><code>hardware_profiles(credentials, opts=nil)</code></li>
+        <li><code>images(credentials, opts=nil )</code></li>
+        <li><code>realms(credentials, opts=nil)</code></li>
+        <li><code>instances(credentials, opts=nil)</code></li>
+        <li><code>create_instance(credentials, image_id, opts)</code></li>
+        <li><code>reboot_instance(credentials, id)</code></li>
+        <li><code>stop_instance(credentials, id)</code></li>
+        <li><code>destroy_instance(credentials, id)</code></li>
+        </ul>
+        
+        
+        <p>As a further example, the <code>hardware_profiles(...)</code> method should
+        return an array of <code>HardwareProfile</code> objects. The <code>opts</code> hash, if
+        present, must be inspected for <code>:id</code> and <code>:architecture</code> keys. If these keys
+        are present, the results should be filtered by the value associated with
+        each key. The <code>filter_on(...)</code> helper method is used for this filtering
+        and as you can see from existing driver method definitions, is invoked
+        in many of the driver collection methods:</p>
+        
+        <pre><code>def hardware_profiles(credentials, opts=nil)&#x000A;  hardware_profiles = # get all hardware profiles from provider&#x000A;  hardware_profiles = filter_on( hardware_profiles, :id, opts )&#x000A;  hardware_profiles = filter_on( hardware_profiles, :architecture, opts )&#x000A;  return hardware_profiles&#x000A;end&#x000A;</code></pre>
+        
+        <p>Once you've implemented some of the methods for your driver you can start to
+        'run' it and test that things are working as expected. To do this, you need to
+        create a yaml file for your driver so that the Deltacloud server 'knows' about
+        it. Assuming you've written the driver for cloud Foo and you've called it
+        foo_driver.rb (which contains the class Deltacloud::Drivers::Foo::FooDriver)
+        , you need to drop a file into <strong>/deltacloud/server/config/drivers</strong> called
+        <strong>foo.yaml</strong>, containing the following:</p>
+        
+        <pre><code>---&#x000A;:foo:&#x000A;  :name Foo&#x000A;</code></pre>
+        
+        <p>You can then start the Deltacloud server with:</p>
+        
+        <pre><code>deltacloudd -i foo&#x000A;</code></pre>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h3 id="h2_5">Writing and running tests</h3>
+        
+        <p>If you add a new feature or write a new driver, you might like to add some tests to
+        make sure everything is running as expected. At present the Deltacloud project uses
+        Unit tests which live in <strong>/deltacloud/server/tests</strong> as well as Cucumber tests which live
+        in <strong>/deltacloud/tests</strong>.</p>
+        
+        <p>You can invoke the Unit tests:</p>
+        
+        <pre><code>$ cd /path/to/deltacloud/server&#x000A;$ rake test&#x000A;</code></pre>
+        
+        <p>As you can see by inspecting the Rakefile in /deltacloud/server, this will invoke all
+        Unit tests defined in /deltacloud/server/tests. You can invoke specific driver tests by:</p>
+        
+        <pre><code>$ cd /path/to/deltacloud/server&#x000A;$ rake test:rackspace&#x000A;      _OR_&#x000A;$ rake test:mock&#x000A;      _etc_&#x000A;</code></pre>
+        
+        <p>You can invoke the Cucumber tests:</p>
+        
+        <pre><code>$ cd /path/to/deltacloud/server&#x000A;$ rake cucumber&#x000A;</code></pre>
+        
+        <p>Alternatively, you can bypass the Rakefile and invoke the cucumber tests directly:</p>
+        
+        <pre><code>$ cd /path/to/deltacloud/server&#x000A;$ cucumber ../tests/mock&#x000A;      _OR_&#x000A;$ cucumber ../tests/ec2&#x000A;      _etc_&#x000A;</code></pre>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <hr />
+        
+        <br>
+        
+        
+        <h3 id="h2_6">Licensing - the Apache Individual Contributor License Agreement</h3>
+        
+        <p>Deltacloud is an <a href="http://www.apache.org/">Apache Software Foundation</a> project. As such
+        and in keeping with all Apache projects, contributors are required to sign an individual
+        contributor license agreement. This, together with instructions on signing and sending
+        the agreement can be <a href="http://www.apache.org/licenses/icla.txt">found here</a>. Please do
+        not hesitate to <a href="contact.html">contact us</a> if you have any queries or require any
+        clarification about contributing to the Deltacloud project.</p>
+        
+        <br>
+        
+        
+        <p><a href="#contents">contents</a></p>
+        
+        <br>
+        
+        
+        
+        </br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br>
+      </div>
+    </div>
+    <div id='footer-deltacloud'>
+      <div class='container'>
+        <p>
+          <a href='http://incubator.apache.org'>
+            <img alt='Apache Incubator Logo' src='http://incubator.apache.org/images/apache-incubator-logo.png' />
+          </a>
+        </p>
+        <p id='disclaimer'>
+          Apache Deltacloud is an effort undergoing incubation at The
+          Apache Software Foundation (ASF), sponsored by the Apache
+          Incubator PMC. Incubation is required of all newly accepted
+          projects until a further review indicates that the
+          infrastructure, communications, and decision making process have
+          stabilized in a manner consistent with other successful ASF
+          projects. While incubation status is not necessarily a reflection
+          of the completeness or stability of the code, it does indicate
+          that the project has yet to be fully endorsed by the ASF.
+        </p>
+      </div>
+    </div>
+  </body>
+</html>
diff --git a/site/output/documentation.html b/site/output/documentation.html
index e977bae..87ab130 100644
--- a/site/output/documentation.html
+++ b/site/output/documentation.html
@@ -31,11 +31,14 @@
             <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
           </li>
           <li>
-            <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+            <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
           </li>
           <li>
             <a class='active' href='./documentation.html' title='Project documentation'>Documentation</a>
           </li>
+          <li>
+            <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+          </li>
         </ul>
       </div>
     </div>
@@ -44,7 +47,7 @@
         <ul class='l1'>
           <li>
             <a class='active' href='documentation.html'>
-              Overview
+              Installation
             </a>
           </li>
           <li>
@@ -58,11 +61,6 @@
             </a>
           </li>
           <li>
-            <a class='inactive' href='framework.html'>
-              Framework
-            </a>
-          </li>
-          <li>
             <a class='inactive' href='client-ruby.html'>
               Ruby Client
             </a>
@@ -82,292 +80,462 @@
         <p>The Deltacloud documentation is divided into the following parts:</p>
         <ul>
           <li>
+            <a href='documentation.html'>
+              Installation, dependencies and quick-start (this page)
+            </a>
+          </li>
+          <li>
             <a href='api.html'>
               REST API definition
             </a>
           </li>
           <li>
             <a href='drivers.html'>
-              Currently-supported drivers
+              Information about currently supported drivers
             </a>
           </li>
           <li>
-            <a href='framework.html'>
-              Framework for writing additional drivers
+            <a href='client-ruby.html'>
+              The Deltacloud Ruby client
             </a>
           </li>
           <li>
-            <a href='client-ruby.html'>
-              Ruby client
+            <a href='libdeltacloud.html'>
+              The libdeltacloud C library
             </a>
           </li>
+        </ul>
+        <br />
+        <br />
+        <hr />
+        <br />
+        <a name='install_deltacloud'></a>
+        <h1>Install Deltacloud</h1>
+        This page lists the libraries and packages that you will need in order to install
+        the Deltacloud server, a "Hello Deltacloud" quick-start guide as well as some
+        information on interacting with the Deltacloud server after a succesful installation.
+        <h2>Installation of Deltacloud itself</h2>
+        Once you've setup all the dependencies listed below, installing Deltacloud is as easy as
+        typing:
+        <br />
+        <br />
+        <pre><code>$ sudo gem install deltacloud-core</code></pre>
+        And
+        <strong>thats it!</strong>
+        The
+        <strong>gem install</strong>
+        command will automatically fetch and install all other gems that the Deltacloud server
+        needs if you don't already have these. As an alternative you can get the latest
+        releases of Deltacloud from the
+        <a href='http://www.apache.org/dist/incubator/deltacloud/'>
+          Apache website.
+        </a>
+        <br />
+        <br />
+        <hr />
+        <br />
+        <a name='dependencies'></a>
+        <h2>Installation dependencies</h2>
+        The Deltacloud server relies on a number of external rubygems and other libraries.
+        You must have the following packages installed before trying to install and
+        run the Deltacloud server. Please note that the names of the packages below
+        may differ for your distribution (e.g. 'ruby-devel' vs 'ruby-dev'). In short, you need:
+        <br />
+        <br />
+        <ul>
+          <li>ruby and ruby-devel,</li>
+          <li>gem (RubyGems),</li>
+          <li>gcc-c++,</li>
+          <li>libxml2 and libxml2-devel,</li>
+          <li>libxslt and libxslt-devel,</li>
+          <li>rake</li>
+        </ul>
+        More info on getting these follows:
+        <h3>ruby and ruby-devel</h3>
+        You need to
+        <a href='http://www.ruby-lang.org/en/downloads/'>
+          install ruby.
+        </a>
+        You can check to see if you already have a ruby installation by typing:
+        <br />
+        <br />
+        <pre><code>$ ruby -v</code></pre>
+        If you see something that looks like the following:
+        <br />
+        <br />
+        <pre><code>ruby 1.8.7 (2010-08-16 patchlevel 302) [i686-linux]</code></pre>
+        then you can skip the ruby installation. Deltacloud requires ruby to be
+        at least version 1.8.7. You also need the development headers (ruby-devel) as
+        Deltacloud relies on some rubygems with C extensions. If you use a package manager
+        such as yum or apt-get:
+        <br />
+        <br />
+        <pre><code>sudo yum install ruby&#x000A;sudo yum install ruby-devel</code></pre>
+        OR
+        <br />
+        <br />
+        <pre><code>sudo apt-get install ruby&#x000A;sudo apt-get install ruby-devel</code></pre>
+        <h3>gem (RubyGems)</h3>
+        Deltacloud relies on a number of ruby gems so you also need to
+        <a href='http://docs.rubygems.org/read/chapter/3'>
+          install RubyGems.
+        </a>
+        As with ruby, you can check if you already have the
+        <strong>gem</strong>
+        executable installed by typing
+        <strong>gem -v</strong>
+        . Again, your package manager can help with the installation:
+        <br />
+        <br />
+        <pre><code>$ sudo yum install rubygems</code></pre>
+        <h3>gcc-c++, libxml2, libxml2-devel, libxslt, libxslt-devel</h3>
+        These are required to build RubyGems that have C extensions. Again, typically
+        the easiest way to get these is with you package manager:
+        <br />
+        <br />
+        <pre><code>$ sudo yum install gcc-c++&#x000A;$ sudo yum install libxml libxml2-devel&#x000A;$ sudo yum install libxslt libxslt-devel</code></pre>
+        <h3>rake</h3>
+        <a href='http://rake.rubyforge.org/'>
+          Rake
+        </a>
+        is Ruby's Make and is itself a ruby gem. Once you have RubyGems installed you can
+        get rake with:
+        <br />
+        <br />
+        <pre><code>$ sudo gem install rake</code></pre>
+        <br />
+        <br />
+        <hr />
+        <br />
+        <a name='quick_start'></a>
+        <h1>"Hello Deltacloud!", quick-start guide</h1>
+        This guide assumes a linux environment. Some of the Deltacloud developers
+        are running recent versions of
+        <a href='http://fedoraproject.org'>
+          Fedora.
+        </a>
+        However, as Deltacloud is written in Ruby you should be able to install it on
+        any OS that supports Ruby. If you have succesfully installed Deltacloud or are
+        having any problems doing so, please
+        <a href='contact.html'>
+          let us know,
+        </a>
+        we'd love to hear from you!
+        <h2>Running the Deltacloud server</h2>
+        After you succesfully install Deltacloud, you can start the server by typing
+        <strong>
+          deltacloudd -i
+          <em>
+            provider_id.
+          </em>
+        </strong>
+        The
+        <strong>
+          <em>
+            provider_id
+          </em>
+        </strong>
+        is the name of the cloud provider that you have an account with, for example 'ec2'.
+        If you don't yet have an account with a cloud provider, you can still try the Deltacloud
+        mock driver:
+        <br />
+        <br />
+        <pre><code>deltacloudd -i mock</code></pre>
+        This will start the Deltacloud server on your local machine with the mock driver, accepting
+        connections on port 3001 (the default). From version 0.4.0 of Deltacloud, you can use the
+        '-l' flag to see
+        <a href='drivers.html#providers'>
+          all available
+        </a>
+        <strong>
+          <em>
+            provider_ids
+          </em>
+        </strong>
+        that can be used with the
+        <strong>deltacloudd</strong>
+        executable.
+        <br />
+        <br />
+        <pre><code>$ deltacloudd -l&#x000A;<br />&#x000A;Available drivers:&#x000A;* condor&#x000A;* vsphere&#x000A;* opennebula&#x000A;* eucalyptus&#x000A;* rhevm&#x000A;* sbc&#x000A;* azure&#x000A;* gogrid&#x000A;* mock&#x000A;* rackspace&#x000A;* rimuhosting&#x000A;* terremark&#x000A;* ec2</code></pre>
+        After you start the server, the Deltacloud HTML interface is available at
+        <strong>
+          http://localhost:3001/api
+        </strong>
+        - open this address in your web browser. If you want to see XML output from the
+        server in the browser, append
+        <strong>
+          <em>
+            format=xml
+          </em>
+        </strong>
+        to each URL. On Webkit based browsers like Safari, you might need to instruct the
+        server explicitly to
+        <a href='http://www.gethifi.com/blog/webkit-team-admits-accept-header-error'>
+          return HTML
+        </a>
+        Do this by appending
+        <strong>
+          <em>
+            format=html
+          </em>
+        </strong>
+        to each URL. Your browser will prompt you for
+        <a href='drivers.html#credentials'>
+          credentials
+        </a>
+        when you invoke an operation that requires
+        <a href='api.html#authentication'>
+          authentication.
+        </a>
+        <br />
+        <br />
+        The '-h' flag will list all available options for
+        <strong>deltacloudd.</strong>
+        For example, to start the Deltacloud server with the Rackspace driver on port 10000
+        you can use:
+        <br />
+        <br />
+        <pre><code>$ deltacloudd -i rackspace -P 10000</code></pre>
+        You may want to install the server on another machine and make Deltacloud available on
+        your local network. To do this you need to bind the Deltacloud server to an address other
+        than 'localhost' (default). For instance, if you install and start Deltacloud on a machine
+        with the IP address 192.168.10.200 you should start the server with:
+        <br />
+        <br />
+        <pre><code>$ deltacloudd -i ec2 -P 5000 -r 192.168.10.200</code></pre>
+        This will make the Deltacloud server available at the address
+        <strong>
+          http://192.168.10.200:5000/api.
+        </strong>
+        <br />
+        <br />
+        <br />
+        <br />
+        <hr />
+        <br />
+        <h2>The Deltacloud ruby client</h2>
+        The Deltacloud project also maintains a ruby client, which you need to install
+        seperately to the Deltacloud API server. The Deltacloud client consists of a
+        ruby library (packaged as a ruby gem) which you can use to programmatically
+        interact with the Deltacloud server and control your cloud infrastructure
+        across cloud providers. For example, assuming the Deltacloud server is
+        running at
+        <strong>
+          192.168.10.244:5000
+        </strong>
+        <br />
+        <br />
+        <pre><code>require 'deltacloud'&#x000A;<br />&#x000A;api_url      = 'http://192.168.10.244:5000/api'&#x000A;api_name     = 'TK2PJCAN9R1HKG2FK24Z'&#x000A;api_password = 'aLe27rZlRhlBcVoQbL4JsVtaNga12vEL9d9kS5CA'&#x000A;<br />&#x000A;client = DeltaCloud.new( api_name, api_password, api_url )&#x000A;<br />&#x000A;# get a list of currently running instances (virtual machines)&#x000A;client.instances.each do |instance|&#x000A; puts instance.name&#x000A;end&#x000A;<br />&#x000A;<div id='do'>other work with client here</div></code></pre>
+        More comprehensive information on using the Deltacloud ruby client in this way
+        can be found in the
+        <a href='client-ruby.html'>
+          client documentation.
+        </a>
+        Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud
+        client by simply typing:
+        <br />
+        <br />
+        <pre><code>$ sudo gem install deltacloud-client</code></pre>
+        Installing the Deltacloud client also gives you the
+        <strong>
+          deltacloudc
+        </strong>
+        command line tool. This executable makes use of the Deltacloud client library to speak to the
+        Deltacloud server using the
+        <a href='api.html'>
+          REST API.
+        </a>
+        This allows you to to control your IAAS cloud infrastructure form the command line;
+        even better if you are familiar with linux scripting, you can knock up a bash script in no time
+        to automate your cloud infrastructure tasks.
+        The general usage pattern for deltacloudc is:
+        <br />
+        <br />
+        <pre><code>$ deltacloudc collection operation [options]</code></pre>
+        <ul>
           <li>
-            <a href='libdeltacloud.html'>
-              C library
+            <strong>
+              <em>
+                collection
+              </em>
+            </strong>
+            refers to the Deltacloud object collections, such as Instances,
+            Images, Buckets, Realms etc, as described in greater detail in the
+            <a href='api.html#h1'>
+              REST API
+            </a>
+          </li>
+          <li>
+            <strong>
+              <em>
+                operation
+              </em>
+            </strong>
+            is collection dependant. All collections respond to 'index'
+            and 'show' operations (retrieve details on all objects in a given collection
+            or on a specific object, respectively); some collections respond to 'create' and 'destroy'
+            operations. The instances collection (realised virtual servers) responds to operations
+            for managing the instance lifecycle, such as 'stop', 'reboot' etc.
+          </li>
+          <li>
+            <strong>
+              <em>
+                options
+              </em>
+            </strong>
+            are listed by invoking
+            <strong>deltacloudc -h</strong>
+            One important option is
+            <strong>-u,</strong>
+            with which you specify the API_URL where the Deltacloud server is running. The API_URL
+            takes the form
+            <strong>
+              http://[user]:[password]@[api_url]:[port]/[api]
+            </strong>
+            (examples follow). Alternatively, rather than having to supply the API_URL for every
+            invocation of
+            <strong>
+              deltacloudc
+            </strong>
+            you have the choice of setting the API_URL environment variable
+            (e.g., export API_URL=http://mockuser:mockpassword@localhost:3001/api). A
+            listing of the credentials you need to provide for each back-end cloud provider
+            is available
+            <a href='drivers.html#credentials'>
+              here.
             </a>
           </li>
         </ul>
-        <h1>Usage</h1>
-        <p>
-          The server listens by default on
-          <tt>
-            http://localhost:3001/.
-          </tt>
-          For testing and exploring, the server can be used from a web browser and
-          will return HTML to it. If you want to see XML output from the server in
-          the browser, append
-          <tt>
-            &#x3f;format=xml
-          </tt>
-          to each URL.
-        </p>
-        <p>
-          On Webkit based browsers like Safari, you might need to instruct the
-          server explicitly to
-          <a href='http://www.gethifi.com/blog/webkit-team-admits-accept-header-error'>
-            return HTML
-          </a>
-          &#x2e; Do this by appending
-          <tt>
-            &#x3f;format=html
-          </tt>
-          to each URL.
-        </p>
-        <h2>Logging into the server</h2>
-        <p>
-          Deltacloud uses basic HTTP authentication to receive credentials from the
-          client and passes them through to the backend cloud it is talking to. The
-          credentials always consist of a username and password, and are never
-          stored on the server.  The exact credentials for logging into the server,
-          and where you find them, depends on the backend cloud that the server is
-          talking to.
-        </p>
-        <p>
-          The following table gives details about how to set up the server and what
-          credentials to provide for each of the supported clouds. The entry from
-          the Driver column needs to be passed as the
-          <tt>
-            --driver
-          </tt>
-          option to
-          <tt>
-            deltacloudd.
-          </tt>
-          Note that some of the drivers require additional information, e.g.,
-          API endpoint URL's, be passed through environment variables
-        </p>
-        <table id='providers'>
-          <tr>
-            <th>
-              <strong>Cloud</strong>
-            </th>
-            <th>
-              <strong>Driver</strong>
-            </th>
-            <th>
-              <strong>Username</strong>
-            </th>
-            <th>
-              <strong>Password</strong>
-            </th>
-            <th>
-              <strong>Notes</strong>
-            </th>
-          </tr>
-          <tr>
-            <td>
-              <strong>mock</strong>
-            </td>
-            <td>
-              <tt>mock</tt>
-            </td>
-            <td>
-              <tt>
-                mockuser
-              </tt>
-            </td>
-            <td>
-              <tt>
-                mockpassword
-              </tt>
-            </td>
-            <td>
-              The mock driver doesn't talk to any cloud; it just pretends to be a cloud
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <strong>Amazon EC2/S3</strong>
-            </td>
-            <td>
-              <tt>ec2</tt>
-            </td>
-            <td>
-              Access Key ID
-            </td>
-            <td>
-              Secret Access Key
-            </td>
-            <td>
-              This information can be found on the
-              <a href='http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key'>Security Credentials</a>
-              page in your AWS account
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <strong>Eucalyptus</strong>
-            </td>
-            <td>
-              <tt>eucalyptus</tt>
-            </td>
-            <td>
-              Access Key ID
-            </td>
-            <td>
-              Secret Access Key
-            </td>
-            <td></td>
-          </tr>
-          <tr>
-            <td>
-              <strong>GoGrid</strong>
-            </td>
-            <td>
-              <tt>gogrid</tt>
-            </td>
-            <td>
-              API Key
-            </td>
-            <td>
-              Shared Secret
-            </td>
-            <td>
-              Go to
-              <tt>My Account &gt; API Keys</tt>
-              for
-              <a href='https://my.gogrid.com/gogrid/com.servepath.gogrid.GoGrid/index.html'>your account</a>
-              and click on the key you want to use to find the shared secret.
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <strong>IBM SBC</strong>
-            </td>
-            <td>
-              <tt>sbc</tt>
-            </td>
-            <td>
-              Username
-            </td>
-            <td>
-              Password
-            </td>
-            <td></td>
-          </tr>
-          <tr>
-            <td>
-              <strong>Microsoft Azure (Storage Account only)</strong>
-            </td>
-            <td>
-              <tt>azure</tt>
-            </td>
-            <td>
-              Public Storage Account Name
-            </td>
-            <td>
-              Primary Access Key
-            </td>
-            <td>
-              The Storage Account Name is chosen when you create the service (e.g. name in http://name.blob.core.windows.net/). This and the access key are available from the service control panel.
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <strong>OpenNebula</strong>
-            </td>
-            <td>
-              <tt>opennebula</tt>
-            </td>
-            <td>
-              OpenNebula user
-            </td>
-            <td>
-              OpenNebula password
-            </td>
-            <td>
-              Set the environment variable
-              <tt>OCCI_URL</tt>
-              to the address on which OpenNebula's OCCI server is listening.
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <strong>Rackspace Cloud Servers/Cloud Files</strong>
-            </td>
-            <td>
-              <tt>rackspace</tt>
-            </td>
-            <td>
-              Rackspace user name
-            </td>
-            <td>
-              API Key
-            </td>
-            <td>
-              Obtain the key from the
-              <a href='https://manage.rackspacecloud.com/APIAccess.do'>API Access</a>
-              page in your control panel
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <strong>RHEV-M</strong>
-            </td>
-            <td>
-              <tt>rhevm</tt>
-            </td>
-            <td>
-              <a href='http://markmc.fedorapeople.org/rhevm-api/en-US/html/chap-REST_API_Guide-Authentication.html'>RHEV-M user name plus Windows domain</a>
-              , e.g.,
-              <tt>admin@rhevm.example.com</tt>
-            </td>
-            <td>
-              RHEV-M password
-            </td>
-            <td>
-              Set environment variable
-              <tt>API_PROVIDER</tt>
-              to the URL of the RHEV-M REST API endpoint.
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <strong>Rimuhosting</strong>
-            </td>
-            <td>
-              <tt>rimuhosting</tt>
-            </td>
-            <td>not used (?)</td>
-            <td>API Key</td>
-            <td></td>
-          </tr>
-          <tr>
-            <td>
-              <strong>Terremark</strong>
-            </td>
-            <td>
-              <tt>terremark</tt>
-            </td>
-            <td>
-              Username
-            </td>
-            <td>
-              Password
-            </td>
-            <td></td>
-          </tr>
-        </table>
+        The following examples assume that the Deltacloud server is running on your local machine
+        port 3001 (the
+        <strong>deltacloudd</strong>
+        server daemon defaults to 'localhost:3001') and was started with the 'mock' provider
+        (i.e.
+        <strong>deltacloudd -i mock</strong>
+        ).
+        To list all collections available in the current driver:
+        <br />
+        <br />
+        <pre><code>$ deltacloudc -l -u http://mockuser:mockpassword@localhost:3001/api</code></pre>
+        To get a list of all
+        <strong>images:</strong>
+        <br />
+        <br />
+        <pre><code>$ deltacloudc images index -u http://mockuser:mockpassword@localhost:3001/api</code></pre>
+        To list all operations for the
+        <strong>buckets</strong>
+        collection:
+        <br />
+        <br />
+        <pre><code>$ deltacloudc buckets -l -u http://mockuser:mockpassword@localhost:3001/api</code></pre>
+        To create a new blob in the bucket called 'bucket1':
+        <br />
+        <br />
+        <pre><code>$ deltacloudc blob create -i 'my_new_blob' -b 'bucket1' -f /home/marios/file.txt</code></pre>
+        <br />
+        <br />
+        <hr />
+        <br />
+        <h2>Other HTTP clients - cURL</h2>
+        As interaction with the Deltacloud server is via HTTP calls, you can use any
+        HTTP client to talk to it using the Deltacloud
+        <a href='api.html'>
+          REST API.
+        </a>
+        One popular command line tool available on most modern linux distributions is
+        <a href='http://curl.haxx.se/'>
+          cURL.
+        </a>
+        We give some examples here of how you can use cURL to interact with Deltacloud,
+        demonstrating the flexibility and power of the Deltacloud REST API.
+        The following examples assume the Deltacloud server is running on locahost:3001,
+        and was started with the 'ec2' driver (i.e.,
+        <strong>deltacloudd -i ec2</strong>
+        ).
+        To get a
+        <a href='api.html#list_images'>
+          listing of all images
+        </a>
+        available in the back-end cloud:
+        <br />
+        <br />
+        <pre><code>curl  --user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"&#x000A;"http://localhost:3001/api/images?format=xml"</code></pre>
+        The cURL
+        <strong>--user</strong>
+        option is used to specify the
+        <strong>username:password</strong>
+        <a href='drivers.html#credentials'>
+          credentials
+        </a>
+        for access to the back-end cloud provider (Amazon EC2 in this case).
+        To
+        <a href='api.html#create_instance'>
+          create a new instance
+        </a>
+        from the
+        <a href='api.html#h3_3'>
+          image
+        </a>
+        with id 'ami-f51aff9c', in
+        <a href='api.html#h3_1'>
+          realm
+        </a>
+        'us-east-1c', with the
+        <a href='api.html#h3_2'>
+          hardware profile
+        </a>
+        'c1.medium', in
+        <a href='api.html#h3_7'>
+          firewall
+        </a>
+        'default':
+        <br />
+        <br />
+        <pre><code>curl -X POST -F "keyname=eftah" -F "image_id=ami-f51aff9c"&#x000A;-F "realm_id=us-east-1c" -F "hwp_id=c1.medium" -F "firewalls1=default"&#x000A;--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"&#x000A;"http://localhost:3001/api/instances?format=xml"</code></pre>
+        To
+        <a href='api.html#delete_firewall'>
+          delete a firewall
+        </a>
+        called 'develgroup':
+        <br />
+        <br />
+        <pre><code>curl -X DELETE&#x000A;--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"&#x000A;http://localhost:3001/api/firewalls/develgroup?format=xml</code></pre>
+        To
+        <a href='api.html#create_blob'>
+          create a blob
+        </a>
+        called 'my_new_blob' within the
+        <a href='api.html#h4_3'>
+          bucket
+        </a>
+        'mybucket' from a local file with
+        <strong>
+          <em>
+            HTTP PUT
+          </em>
+        </strong>
+        specifying its content type and setting some some metadata
+        <strong>
+          <em>
+            key:value
+          </em>
+        </strong>
+        pairs:
+        <br />
+        <br />
+        <pre><code>curl -H 'content-type: text/html' -H 'X-Deltacloud-Blobmeta-Name:mariosblob'&#x000A;-H 'X-Deltacloud-Blobmeta-Version:2.1' --upload-file&#x000A;"/home/marios/Desktop/somefile.html"&#x000A;--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"&#x000A;http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml</code></pre>
+        To
+        <a href='api.html#h4_3_10'>
+          retrieve blob metadata
+        </a>
+        for the blob called 'my_new_blob':
+        <br />
+        <br />
+        <pre><code>curl -iv -X HEAD&#x000A;--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"&#x000A;http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml</code></pre>
+        Note the use of the '-iv' flags here which will ensure that cURL displays the
+        request and response headers (blob metadata is reported in the response headers,
+        with an empty response body).
       </div>
     </div>
     <div id='footer-deltacloud'>
diff --git a/site/output/drivers.html b/site/output/drivers.html
index b166e91..af1e931 100644
--- a/site/output/drivers.html
+++ b/site/output/drivers.html
@@ -31,11 +31,14 @@
             <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
           </li>
           <li>
-            <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+            <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
           </li>
           <li>
             <a class='active' href='./documentation.html' title='Project documentation'>Documentation</a>
           </li>
+          <li>
+            <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+          </li>
         </ul>
       </div>
     </div>
@@ -44,7 +47,7 @@
         <ul class='l1'>
           <li>
             <a class='inactive' href='documentation.html'>
-              Overview
+              Installation
             </a>
           </li>
           <li>
@@ -58,11 +61,6 @@
             </a>
           </li>
           <li>
-            <a class='inactive' href='framework.html'>
-              Framework
-            </a>
-          </li>
-          <li>
             <a class='inactive' href='client-ruby.html'>
               Ruby Client
             </a>
@@ -83,79 +81,67 @@
         <!-- = title + '</h1>' -->
         <ul class="toc">
         <li>
-        <a href="#h1">Setting up the code</a>
-        </li>
-        <li>
-        <a href="#h2">Launch the server</a>
+        <a href="#h1">Dynamic driver switching</a>
         </li>
         <li>
-        <a href="#h3">Dynamic driver switching</a>
+        <a href="#h2">Driver functionality and Credentials</a>
         </li>
         <li>
-        <a href="#h4">Notes on specific drivers</a>
+        <a href="#h3">Notes on specific drivers</a>
         <ul>
         <li>
-        <a href="#h4_1">EC2 Driver</a>
+        <a href="#h3_1">EC2 Driver</a>
         </li>
         <li>
-        <a href="#h4_2">Eucalyptus Driver</a>
+        <a href="#h3_2">Eucalyptus Driver</a>
         </li>
         <li>
-        <a href="#h4_3">RHEV-M Driver</a>
+        <a href="#h3_3">RHEV-M Driver</a>
         </li>
         <li>
-        <a href="#h4_4">Rackspace Driver</a>
+        <a href="#h3_4">Rackspace Driver</a>
         </li>
         <li>
-        <a href="#h4_5">RimuHosting</a>
+        <a href="#h3_5">RimuHosting</a>
         </li>
         <li>
-        <a href="#h4_6">OpenNebula</a>
+        <a href="#h3_6">OpenNebula</a>
         </li>
         <li>
-        <a href="#h4_7">IBM Smartcloud Driver</a>
+        <a href="#h3_7">IBM Smartcloud Driver</a>
         </li>
         </ul></li></ul>
         <!-- = rest -->
         
         
-        <p>Deltacloud provides drivers for a growing number of popular clouds. All drivers
-        can handle a set of standard operations, some of them also support a number of
-        optional operations to expose the features of specific clouds more closely. The
-        drivers and their capabilities are:</p>
+        <p>Deltacloud provides drivers for a <a href="drivers.html#providers">growing number</a> of popular
+        IaaS cloud providers. This page contains notes pertinent to specific cloud provider drivers, such
+        as the <a href="drivers.html#credentials">credentials</a> that should be used for a given cloud provider.
+        Furthermore the information here outlines the mechanism through which any API call sent by a
+        given client to a Deltacloud server instance may be routed to a specific driver, regardless
+        of the 'default' driver that the Deltacloud server was invoked for.</p>
         
-        <h2 id="h1">Setting up the code</h2>
+        <hr />
         
-        <p>To set up a Deltacloud core and the drivers, install the
-        <a href="http://rubygems.org/gems/deltacloud-core">deltacloud-core</a> Ruby gem:</p>
+        <h2 id="h1">Dynamic driver switching</h2>
         
-        <pre><code># gem install deltacloud-core&#x000A;</code></pre>
+        <p>When the Deltacloud server is started it is passed a parameter
+        that specifies the <strong>default</strong> driver to be used for API operations:</p>
         
-        <p>RPM package will be available soon.</p>
+        <pre><code>$ deltacloudd -i ec2&#x000A;</code></pre>
         
-        <h2 id="h2">Launch the server</h2>
-        
-        <p>The server is launched with the <code>deltacloudd</code> command and pass it the name
-        of the driver you want to use:</p>
-        
-        <pre><code>$ deltacloudd -i mock&#x000A;</code></pre>
-        
-        <p>This will start a webserver running the mock driver on
-        <code>http://localhost:3001/api</code>; you can simply browse to that URL to get a
-        pretty view of the objects the driver deals with.</p>
-        
-        <h2 id="h3">Dynamic driver switching</h2>
-        
-        <p>The driver specified with the <code>-i</code> switch when <code>deltacloudd</code> is launched is
-        the default driver. Clients can switch drivers for any request. The list of
-        drivers supported by the server can be obtained from the <code>drivers</code>
-        collection.</p>
+        <p>The above for example starts the Detlacloud server with the Amazon EC2 driver. Whilst
+        it is possible to start a number of Deltacloud server instances for each cloud provider
+        that you wish to connect to (e.g., on different ports), a mechanism is provided with which
+        to instruct the server to use a specific driver, regardless of the current default. The
+        Deltacloud API <strong>drivers</strong> colletion (e.g. GET /api/drivers) provides a list of all currently
+        supported cloud provider drivers.</p>
         
         <p>Some drivers also support the notion of a <em>provider</em>. Changing the provider
         makes it possible to use the same driver against different instances of a
         cloud, for example different regions in EC2 or different installations of
         RHEV-M. The possible range of values for the provider is driver-specific,
-        and listed below for each driver.</p>
+        and listed in the notes for each driver below.</p>
         
         <p>The driver and provider can be selected in one of two ways:</p>
         
@@ -168,12 +154,14 @@
         <li>Through the matrix request parameters <code>driver</code> and <code>provider</code> in the
         <code>api</code> component of the server's URL. For example, requesting
         <code>http://localhost:3001/api;driver=ec2;provider=eu-west-1</code> has the same
-        effect as using the two request headers mentioned above.</li>
+        effect as using the two request headers in the example above.</li>
         </ol>
         
         
-        <h2 id="h4">Notes on specific drivers</h2>
-        <h3>Compute Drivers</h3>
+        <hr />
+        
+        <h2 id="h2">Driver functionality and Credentials</h2>
+        <h3>Compute Driver Functionality</h3>
         <table id='providers'>
           <tr>
             <th class='emptycell'>&nbsp;</th>
@@ -356,17 +344,17 @@
             <td class="supported">yes</td>
           </tr>
         </table>
-        <h3>Storage Drivers</h3>
+        <h3>Storage Driver Functionality</h3>
         <table id='providers'>
           <tr>
             <th class='emptycell'>&nbsp;</th>
             <th>
               <strong>Create</strong>
-              new containers
+              new buckets
             </th>
             <th>
               <strong>Update/delete</strong>
-              containers
+              buckets
             </th>
             <th>
               <strong>Create</strong>
@@ -442,30 +430,271 @@
             <td class="not-supported">TBD</td>
           </tr>
         </table>
+        <p>
+          Deltacloud uses basic HTTP
+          <a href='api.html#h1_3'>
+            authentication
+          </a>
+          to receive credentials from the
+          client and passes them through to the backend cloud it is talking to. The
+          credentials always consist of a username and password, and are never
+          stored on the server.  The exact credentials for logging into the server,
+          and where you find them, depends on the backend cloud that the server is
+          talking to.
+        </p>
+        <a name='credentials'></a>
+        <p>
+          The following table gives details about the credentials that must be
+          provided for each of the supported clouds. The entry from
+          the Driver column needs to be passed as the
+          <tt>
+            -i
+          </tt>
+          option to the
+          <tt>
+            deltacloudd
+          </tt>
+          server daemon. Note that some of the drivers require additional information, e.g.,
+          API endpoint URL's, be passed through environment variables, as addressed in the
+          <a href='drivers.html#specific_driver_notes'>
+            Notes
+          </a>
+          for Specific Drivers section below.
+        </p>
+        <h3>Cloud provider credentials</h3>
+        <table id='providers'>
+          <tr>
+            <th>
+              <strong>Cloud</strong>
+            </th>
+            <th>
+              <strong>Driver</strong>
+            </th>
+            <th>
+              <strong>Username</strong>
+            </th>
+            <th>
+              <strong>Password</strong>
+            </th>
+            <th>
+              <strong>Notes</strong>
+            </th>
+          </tr>
+          <tr>
+            <td>
+              <strong>mock</strong>
+            </td>
+            <td>
+              <tt>mock</tt>
+            </td>
+            <td>
+              <tt>
+                mockuser
+              </tt>
+            </td>
+            <td>
+              <tt>
+                mockpassword
+              </tt>
+            </td>
+            <td>
+              The mock driver doesn't talk to any cloud; it just pretends to be a cloud
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <strong>Amazon EC2/S3</strong>
+            </td>
+            <td>
+              <tt>ec2</tt>
+            </td>
+            <td>
+              Access Key ID
+            </td>
+            <td>
+              Secret Access Key
+            </td>
+            <td>
+              This information can be found on the
+              <a href='http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key'>Security Credentials</a>
+              page in your AWS account
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <strong>Eucalyptus</strong>
+            </td>
+            <td>
+              <tt>eucalyptus</tt>
+            </td>
+            <td>
+              Access Key ID
+            </td>
+            <td>
+              Secret Access Key
+            </td>
+            <td></td>
+          </tr>
+          <tr>
+            <td>
+              <strong>GoGrid</strong>
+            </td>
+            <td>
+              <tt>gogrid</tt>
+            </td>
+            <td>
+              API Key
+            </td>
+            <td>
+              Shared Secret
+            </td>
+            <td>
+              Go to
+              <tt>My Account &gt; API Keys</tt>
+              for
+              <a href='https://my.gogrid.com/gogrid/com.servepath.gogrid.GoGrid/index.html'>your account</a>
+              and click on the key you want to use to find the shared secret.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <strong>IBM SBC</strong>
+            </td>
+            <td>
+              <tt>sbc</tt>
+            </td>
+            <td>
+              Username
+            </td>
+            <td>
+              Password
+            </td>
+            <td></td>
+          </tr>
+          <tr>
+            <td>
+              <strong>Microsoft Azure (Storage Account only)</strong>
+            </td>
+            <td>
+              <tt>azure</tt>
+            </td>
+            <td>
+              Public Storage Account Name
+            </td>
+            <td>
+              Primary Access Key
+            </td>
+            <td>
+              The Storage Account Name is chosen when you create the service (e.g. name in http://name.blob.core.windows.net/). This and the access key are available from the service control panel.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <strong>OpenNebula</strong>
+            </td>
+            <td>
+              <tt>opennebula</tt>
+            </td>
+            <td>
+              OpenNebula user
+            </td>
+            <td>
+              OpenNebula password
+            </td>
+            <td>
+              Set the environment variable
+              <tt>OCCI_URL</tt>
+              to the address on which OpenNebula's OCCI server is listening.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <strong>Rackspace Cloud Servers/Cloud Files</strong>
+            </td>
+            <td>
+              <tt>rackspace</tt>
+            </td>
+            <td>
+              Rackspace user name
+            </td>
+            <td>
+              API Key
+            </td>
+            <td>
+              Obtain the key from the
+              <a href='https://manage.rackspacecloud.com/APIAccess.do'>API Access</a>
+              page in your control panel
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <strong>RHEV-M</strong>
+            </td>
+            <td>
+              <tt>rhevm</tt>
+            </td>
+            <td>
+              <a href='http://markmc.fedorapeople.org/rhevm-api/en-US/html/chap-REST_API_Guide-Authentication.html'>RHEV-M user name plus Windows domain</a>
+              , e.g.,
+              <tt>admin@rhevm.example.com</tt>
+            </td>
+            <td>
+              RHEV-M password
+            </td>
+            <td>
+              Set environment variable
+              <tt>API_PROVIDER</tt>
+              to the URL of the RHEV-M REST API endpoint.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <strong>Rimuhosting</strong>
+            </td>
+            <td>
+              <tt>rimuhosting</tt>
+            </td>
+            <td>not used (?)</td>
+            <td>API Key</td>
+            <td></td>
+          </tr>
+          <tr>
+            <td>
+              <strong>Terremark</strong>
+            </td>
+            <td>
+              <tt>terremark</tt>
+            </td>
+            <td>
+              Username
+            </td>
+            <td>
+              Password
+            </td>
+            <td></td>
+          </tr>
+        </table>
         
         
         
-        <h3 id="h4_1">EC2 Driver</h3>
+        <p><a name="providers">.</a></p>
         
-        <p>For the Amazon EC2 you need to install the
-        <a href="https://github.com/appoxy/aws">aws</a> Ruby gem:</p>
+        <hr />
         
-        <pre><code># gem install aws&#x000A;</code></pre>
+        <p><a name="specific_driver_notes"> .</a></p>
         
-        <p>When using the driver for Amazon EC2, the credentials passed in
-        response to the HTTP 401 authentication challenge should be your
-        <em>access_key</em> and <em>secret_access_key</em></p>
+        <h2 id="h3">Notes on specific drivers</h2>
         
-        <p>These credentials may be found on the <a href="http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key">Access Identifiers</a>
-        page at Amazon AWS.</p>
+        <h3 id="h3_1">EC2 Driver</h3>
         
         <p>The providers for the EC2 driver correspond to AWS's regions, and currently
         are <code>us-east-1</code>, <code>us-east-1</code>, <code>eu-west-1</code>, <code>ap-southeast-1</code>.</p>
         
-        <h3 id="h4_2">Eucalyptus Driver</h3>
+        <hr />
         
-        <p>The Eucalyptus driver is based on the EC2 driver, and therefore also
-        requires the <code>aws</code> gem.</p>
+        <h3 id="h3_2">Eucalyptus Driver</h3>
+        
+        <p>The Eucalyptus driver is based on the EC2 driver.</p>
         
         <p>The driver allows selecting the Eucalyptus installation by setting a
         provider in the format</p>
@@ -478,7 +707,9 @@
         
         <pre><code>X-Deltacloud-Driver: eucalyptus&#x000A;X-Deltacloud-Provider: ec2=192.168.1.1:8773;s3=192.168.1.2:8773&#x000A;</code></pre>
         
-        <h3 id="h4_3">RHEV-M Driver</h3>
+        <hr />
+        
+        <h3 id="h3_3">RHEV-M Driver</h3>
         
         <p>The RHEV-M driver needs to be installed on a Windows machine which has the
         RHEV-M Powershell API installed and configured. Assuming the directory
@@ -491,18 +722,24 @@
         the RHEVM.dll.config file which is referenced from the profile.ps1
         file located in My Documents/WindowsPowershell directory</p>
         
-        <h3 id="h4_4">Rackspace Driver</h3>
+        <hr />
+        
+        <h3 id="h3_4">Rackspace Driver</h3>
         
         <p>When using the Rackspace-cloud driver (Rackspace cloud used to be called
         "Mosso") - the password in a HTTP 401 challenge should be your API key, NOT
-        your rackspace account password.  (you can get the API-key, or generate a
-        new one, from the rackspace console).</p>
+        your rackspace account password.  You can get the API-key, or generate a
+        new one, from the rackspace console.</p>
         
-        <h3 id="h4_5">RimuHosting</h3>
+        <hr />
+        
+        <h3 id="h3_5">RimuHosting</h3>
         
         <p>Further details coming soon.</p>
         
-        <h3 id="h4_6">OpenNebula</h3>
+        <hr />
+        
+        <h3 id="h3_6">OpenNebula</h3>
         
         <p>When using the <a href="http://www.opennebula.org/">OpenNebula</a> driver, the
         credentials passed in response to the HTTP 401 authentication challenge
@@ -511,7 +748,9 @@
         <p>The address, on which the OCCI server is listening, needs to be defined in
         an environment variable called OCCI_URL.</p>
         
-        <h3 id="h4_7">IBM Smartcloud Driver</h3>
+        <hr />
+        
+        <h3 id="h3_7">IBM Smartcloud Driver</h3>
         
         <p>When using the IBM SmartCloud driver, the credentials passed in response to
         the HTTP 401 authentication challenge should be your IBM SmartCloud
diff --git a/site/output/framework.html b/site/output/framework.html
deleted file mode 100644
index 2a82f4e..0000000
--- a/site/output/framework.html
+++ /dev/null
@@ -1,357 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-  <head>
-    <title>
-      Deltacloud - Documentation
-    </title>
-    <meta content='' name='keywords' />
-    <meta content='' name='description' />
-    <meta content='text/html; charset=utf-8' http-equiv='Content-Type' />
-    <link href='./styles/favicon.ico' rel='shortcut icon' type='image/x-icon' />
-    <link href='./styles/default.css' rel='StyleSheet' title='Main style' type='text/css' />
-    <link href='./styles/default-debug.css' rel='Alternate StyleSheet' title='Debug main style' type='text/css' />
-  </head>
-  <body>
-    <div id='header'>
-      <div class='container'>
-        <div id='headerLogo' onclick="location.href='index.html';" style='cursor: pointer;'>
-          <h1>
-            Deltacloud - Many clouds. One API. No problem.
-          </h1>
-        </div>
-      </div>
-    </div>
-    <div id='navigation'>
-      <div class='container' id='menu'>
-        <ul class='l0'>
-          <li>
-            <a class='inactive' href='./index.html' title='Deltacloud Home'>Home</a>
-          </li>
-          <li>
-            <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
-          </li>
-          <li>
-            <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
-          </li>
-          <li>
-            <a class='active' href='./documentation.html' title='Project documentation'>Documentation</a>
-          </li>
-        </ul>
-      </div>
-    </div>
-    <div id='subnavigation'>
-      <div class='container' id='submenu'>
-        <ul class='l1'>
-          <li>
-            <a class='inactive' href='documentation.html'>
-              Overview
-            </a>
-          </li>
-          <li>
-            <a class='inactive' href='api.html'>
-              REST API
-            </a>
-          </li>
-          <li>
-            <a class='inactive' href='drivers.html'>
-              Drivers
-            </a>
-          </li>
-          <li>
-            <a class='active' href='framework.html'>
-              Framework
-            </a>
-          </li>
-          <li>
-            <a class='inactive' href='client-ruby.html'>
-              Ruby Client
-            </a>
-          </li>
-          <li>
-            <a class='inactive' href='libdeltacloud.html'>
-              Libdeltacloud
-            </a>
-          </li>
-        </ul>
-      </div>
-    </div>
-    <div id='frontpageHeader'></div>
-    <div id='main'>
-      <div class='container' id='content-deltacloud'>
-        <h1>Writing Deltacloud Drivers</h1>
-        
-        <p><ul class="toc">
-        <li>
-        <a href="#h1">Driver SPI</a>
-        <ul>
-        <li>
-        <a href="#h1_1">Credentials</a>
-        </li>
-        <li>
-        <a href="#h1_2">Object models used by drivers</a>
-        </li>
-        <li>
-        <a href="#h1_3">Driver methods</a>
-        </li>
-        </ul></li></ul></p>
-        
-        <p>The <em>Deltacloud Core framework</em> is provided to assist in creating
-        intermediary <a href="drivers.html">drivers</a> that speak the <a href="api.html">Deltacloud REST
-        API</a> on the front while communicating with cloud providers
-        using their own native APIs on the back.</p>
-        
-        <p><img src="styles/framework.png" alt="Deltacloud framework" /></p>
-        
-        <p>The framework handles all aspects of the REST API, while allowing
-        driver implementors to focus on the specific cloud provider native
-        API.</p>
-        
-        <p>Drivers may be implemented in as little as one Ruby class and plugged
-        into the Deltacloud Core for deployment.</p>
-        
-        <h2 id="h1">Driver SPI</h2>
-        
-        <h3 id="h1_1">Credentials</h3>
-        
-        <p>The framework will collect credentials when the driver indicates they
-        are required by throwing a <code>DeltaCloud::AuthException</code>. Each driver
-        method takes a credentials hash as the first parameter, but unless the
-        client has provided credentials, this hash will be empty.</p>
-        
-        <pre><code>def images(credentials, opts)&#x000A;  if ( credentials[:name].nil? )&#x000A;    throw DeltaCloud::AuthException.new&#x000A;  end&#x000A;  unless ( credentials_valid?( credentials ) )&#x000A;    throw DeltaCloud::AuthException.new&#x000A;  end&#x000A;&#x000A;  # do work&#x000A;&#x000A;end&#x000A;</code></pre>
-        
-        <h3 id="h1_2">Object models used by drivers</h3>
-        
-        <p>To assist driver authors, the framework provides a handful of model
-        classes, representing each resource available through the Deltacloud
-        API. Please see the <a href="api.html">API reference</a> for details about each
-        model. All of these model objects may be initialized with a hash.
-        Every instance <em>must</em> be assigned an <code>id</code> in addition to other
-        attributes it may have. Unless otherwise noted, attributes are text.</p>
-        
-        <p>For example</p>
-        
-        <pre><code>HardwareProfile.new(&#x000A;  :architecture=&gt;'x86_64',&#x000A;  :memory=&gt;4,&#x000A;  :storage=&gt;650,&#x000A;)&#x000A;</code></pre>
-        
-        <p>The <code>base_driver</code> interface and the already implemented drivers are
-        located at <code>server/lib/deltacloud/</code> in the Deltacloud Core repository.</p>
-        
-        <h4><code>HardwareProfile</code></h4>
-        
-        <p>Attributes are</p>
-        
-        <ul>
-        <li><strong><code>id</code></strong></li>
-        <li><strong><code>architecture</code></strong></li>
-        <li><strong><code>memory</code></strong> - Decimal, gigabytes</li>
-        <li><strong><code>storage</code></strong> - Decimal, gigabytes</li>
-        <li><strong><code>cpu</code></strong> - Interger, count</li>
-        </ul>
-        
-        
-        <h4><code>Realm</code></h4>
-        
-        <p>Attributes are</p>
-        
-        <ul>
-        <li><strong><code>id</code></strong></li>
-        <li><strong><code>name</code></strong></li>
-        <li><strong><code>state</code></strong></li>
-        <li><strong><code>limit</code></strong></li>
-        </ul>
-        
-        
-        <h4><code>Image</code></h4>
-        
-        <p>Attributes are</p>
-        
-        <ul>
-        <li><strong><code>id</code></strong></li>
-        <li><strong><code>name</code></strong></li>
-        <li><strong><code>architecture</code></strong></li>
-        <li><strong><code>owner_id</code></strong></li>
-        <li><strong><code>description</code></strong></li>
-        </ul>
-        
-        
-        <h4><code>Instance</code></h4>
-        
-        <p>Attributes are</p>
-        
-        <ul>
-        <li><strong><code>id</code></strong></li>
-        <li><strong><code>name</code></strong></li>
-        <li><strong><code>owner_id</code></strong> - Opaque, external reference</li>
-        <li><strong><code>image</code></strong> - References an image</li>
-        <li><strong><code>realm</code></strong> - References a realm</li>
-        <li><strong><code>state</code></strong> - One of <code>PENDING</code>, <code>RUNNING</code>, <code>SHUTTING_DOWN</code>, <code>STOPPED</code></li>
-        <li><strong><code>actions</code></strong> - Array of applicable actions</li>
-        <li><strong><code>public_addresses</code></strong> - Array of IP addresses or hostnames as text</li>
-        <li><strong><code>private_addresses</code></strong> - Array of IP addresses or hostnames as text</li>
-        </ul>
-        
-        
-        <h3 id="h1_3">Driver methods</h3>
-        
-        <p>The primary methods a driver class must implement are</p>
-        
-        <ul>
-        <li><code>hardware_profiles(credentials, opts=nil)</code></li>
-        <li><code>images(credentials, opts=nil )</code></li>
-        <li><code>realms(credentials, opts=nil)</code></li>
-        <li><code>instances(credentials, opts=nil)</code></li>
-        <li><code>create_instance(credentials, image_id, opts)</code></li>
-        <li><code>reboot_instance(credentials, id)</code></li>
-        <li><code>stop_instance(credentials, id)</code></li>
-        <li><code>destroy_instance(credentials, id)</code></li>
-        </ul>
-        
-        
-        <p>Generally, the <code>BaseDriver</code> handles singular cases while the specific
-        provider driver must implement only the plural cases, along with
-        specific action methods against resources.</p>
-        
-        <p>Additionally, to assist clients in determining what actions may be
-        available without making additional requests, the following must be
-        implemented.</p>
-        
-        <p>While the <code>credentials</code> hash is passed as the first parameter to each
-        method, it <em>may</em> be empty until the driver throws at least one
-        <code>DeltaCloud::AuthException</code>. This exception will indicate to the
-        framework that a normal HTTP authentication challenge should be issued
-        to the client. Depending on the underlying provider the driver is
-        connecting to, the credentials may not be required for some methods.</p>
-        
-        <p>Some methods also allow an optional <code>opts</code> hash, which may be <code>nil</code> or
-        empty if not used for a particular invocation. The <code>BaseDriver</code>
-        provides a method <code>filter_on(...)</code> which may be used to safely filter
-        collections. The <code>filter_on(..)</code> method will be demonstrated below.</p>
-        
-        <p>Each method will be described in more detail below.</p>
-        
-        <h4><code>hardware_profiles(credentials, opts=nil)</code></h4>
-        
-        <p>The <code>hardware_profiles(...)</code> method should return an array of
-        <code>HardwareProfile</code> objects. The <code>opts</code> hash, if present, must be
-        inspected for <code>:id</code> and <code>:architecture</code> keys. If these keys are
-        present, the results should be filtered by the value associated with
-        each key. The <code>filter_on(...)</code> method is useful in this case.</p>
-        
-        <p>For example</p>
-        
-        <pre><code>def hardware_profiles(credentials, opts=nil)&#x000A;  hardware_profiles = fetch_all_hardware_profiles()&#x000A;  hardware_profiles = filter_on( hardware_profiles, :id, opts )&#x000A;  hardware_profiles = filter_on( hardware_profiles, :architecture, opts )&#x000A;  return hardware_profiles&#x000A;end&#x000A;</code></pre>
-        
-        <h4><code>realms(credentials, opts=nil)</code></h4>
-        
-        <p>The <code>realms(...)</code> method should return an array of <code>Realm</code> objects.</p>
-        
-        <h4><code>images(credentials, opts=nil)</code></h4>
-        
-        <p>The <code>images(...)</code> method should return an array of <code>Image</code> objects
-        visible and accessible to the current user, as defined by the
-        <code>credentials</code> hash.</p>
-        
-        <p>The <code>opts</code> hash, if present, must be inspected for <code>:id</code>, <code>:owner_id</code>
-        and <code>:architecture</code> keys. If these keys are present, the results
-        should be filtered by the value assocaited with each key.</p>
-        
-        <h4><code>instances(credentials, opts=nil)</code></h4>
-        
-        <p>The <code>instances(...)</code> method should return an array of <code>Instance</code>
-        objects visible and accessible to the current user, as defined bv the
-        <code>credentials</code> hash. If the <code>opts</code> hash is present and contains an
-        <code>:id</code> key, the results should be filtered by the value associated with
-        the key.</p>
-        
-        <h4><code>create_instance(credentials, image_id, opts)</code></h4>
-        
-        <p>The <code>create_instance(...)</code> method should create within the cloud, a
-        new running instance based from an image identifier. The method should
-        return an <code>Instance</code> object representing the newly-created instance.</p>
-        
-        <p>The <code>image_id</code> parameter must be non-nil. The <code>opts</code> hash may contain
-        keys for <code>hwp_id</code> and <code>realm_id</code>. If they are present, they should be
-        used for the creation of the instance. If they are not present,
-        reasonable defaults should be used. In the case of hardware profile,
-        one compatible with the image should be used as the default.</p>
-        
-        <h4><code>reboot_instance(credentials, id)</code></h4>
-        
-        <p>The <code>reboot_instance(...)</code> method should trigger a running instance to
-        be rebooted. This method should return an <code>Instance</code> object.</p>
-        
-        <h4><code>stop_instance(credentials, id)</code></h4>
-        
-        <p>The <code>stop_instance(...)</code> method should trigger a running instance to be
-        stopped. This method should return an <code>Instance</code> object. A cloud provider
-        may allow restarting an instance, or may not.</p>
-        
-        <h4><code>destroy_instance(credentials, id)</code></h4>
-        
-        <p>The <code>destroy_instance(...)</code> method should remove the instance from the
-        cloud provider, stopping it first, if necessary.</p>
-        
-        <h4><code>instance_states()</code></h4>
-        
-        <p>The <code>instance_states()</code> method should return an array/hash structure
-        representing the finite-state-machine for instances. Each state an
-        instance may be in should be an element in the returned array. Each
-        state itself is also an array with 2 members. The first member is the
-        name of the state, and the second member is a hash indicating valid
-        transitions.</p>
-        
-        <p>The general format for the entire FSM structure is</p>
-        
-        <pre><code>[&#x000A;  [ :origin_state1, {&#x000A;    :destination_state1=&gt;:action1,&#x000A;    :destination_state2=&gt;:action2,&#x000A;  } ],&#x000A;  [ :origin_state2, {&#x000A;    :destination_state3=&gt;:action3,&#x000A;    :destination_state4=&gt;:action4,&#x000A;  } ],&#x000A;]&#x000A;</code></pre>
-        
-        <p>Valid states are</p>
-        
-        <ul>
-        <li><strong><code>:begin</code></strong></li>
-        <li><strong><code>:pending</code></strong></li>
-        <li><strong><code>:running</code></strong></li>
-        <li><strong><code>:shutting_down</code></strong></li>
-        <li><strong><code>:stopped</code></strong></li>
-        <li><strong><code>:end</code></strong></li>
-        </ul>
-        
-        
-        <p>The <code>:begin</code> state is the state an instance is in immediate before
-        being created. The <code>:end</code> state is the state an instance is in
-        immediately after being destroyed.</p>
-        
-        <p>Valid transition actions are</p>
-        
-        <ul>
-        <li><strong><code>:stop</code></strong></li>
-        <li><strong><code>:start</code></strong></li>
-        <li><strong><code>:reboot</code></strong></li>
-        </ul>
-        
-        
-        <p>Additionally, to indicate a transition that may occur <em>without</em> an
-        action being triggered, the action **<code>:_auto_</code> may be used.</p>
-      </div>
-    </div>
-    <div id='footer-deltacloud'>
-      <div class='container'>
-        <p>
-          <a href='http://incubator.apache.org'>
-            <img alt='Apache Incubator Logo' src='http://incubator.apache.org/images/apache-incubator-logo.png' />
-          </a>
-        </p>
-        <p id='disclaimer'>
-          Apache Deltacloud is an effort undergoing incubation at The
-          Apache Software Foundation (ASF), sponsored by the Apache
-          Incubator PMC. Incubation is required of all newly accepted
-          projects until a further review indicates that the
-          infrastructure, communications, and decision making process have
-          stabilized in a manner consistent with other successful ASF
-          projects. While incubation status is not necessarily a reflection
-          of the completeness or stability of the code, it does indicate
-          that the project has yet to be fully endorsed by the ASF.
-        </p>
-      </div>
-    </div>
-  </body>
-</html>
diff --git a/site/output/libdeltacloud.html b/site/output/libdeltacloud.html
index a07028b..3ce4c62 100644
--- a/site/output/libdeltacloud.html
+++ b/site/output/libdeltacloud.html
@@ -31,11 +31,14 @@
             <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
           </li>
           <li>
-            <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+            <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
           </li>
           <li>
             <a class='active' href='./documentation.html' title='Project documentation'>Documentation</a>
           </li>
+          <li>
+            <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+          </li>
         </ul>
       </div>
     </div>
@@ -44,7 +47,7 @@
         <ul class='l1'>
           <li>
             <a class='inactive' href='documentation.html'>
-              Overview
+              Installation
             </a>
           </li>
           <li>
@@ -58,11 +61,6 @@
             </a>
           </li>
           <li>
-            <a class='inactive' href='framework.html'>
-              Framework
-            </a>
-          </li>
-          <li>
             <a class='inactive' href='client-ruby.html'>
               Ruby Client
             </a>
diff --git a/site/output/roadmap.html b/site/output/roadmap.html
index 1c0581c..579ae46 100644
--- a/site/output/roadmap.html
+++ b/site/output/roadmap.html
@@ -31,11 +31,14 @@
             <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
           </li>
           <li>
-            <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+            <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
           </li>
           <li>
             <a class='inactive' href='./documentation.html' title='Project documentation'>Documentation</a>
           </li>
+          <li>
+            <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+          </li>
         </ul>
       </div>
     </div>
@@ -59,9 +62,9 @@
         in order of priority.</p>
         
         <p>If you have anything you'd like to see added to the roadmap, or think that
-        some items should receive more attention, please let us know on the
-        <a href="/contribute.html">mailing list</a>. Of course, the quickest way to get anything into
-        Deltacloud is to <a href="/contribute.html">send us patches</a> &mdash; we will of course take patches
+        some items should receive more attention, please <a href="contact.html">let us know</a>.
+        Of course, the quickest way to get anything into
+        Deltacloud is to send us patches; we will of course take patches
         for anything, regardless of whether they adress items on the roadmap or
         anything else.</p>
         
-- 
1.7.3.4


Mime
View raw message