michiels-fog 1.3.1

data/docs/about/press.markdown

@@ -0,0 +1,52 @@
+---
+layout: default
+title:  Press
+---
+
+Mentions and blog posts from elsewhere in reverse chronological order by day (and alphasorted for same days).
+
+**September 13th, 2011**
+
+* [Libvirt support for fog](http://jedi.be/blog/2011/09/13/libvirt-fog-provider/)
+
+**August 1st, 2011**
+
+* [Using EBS Snapshots with Fog](http://www.mediamolecule.com/lab/article/using_ebs_snapshots_with_fog/)
+
+**June 21st, 2011**
+
+* [Mocking fog When Using It With Carrierwave](http://www.engineyard.com/blog/2011/mocking-fog-when-using-it-with-carrierwave/)
+
+**June 14th, 2011**
+
+* [Backing Up Your Data With Fog](http://larrywright.me/blog/articles/221-backing-up-your-data-with-fog)
+
+**April 7th, 2011**
+
+* [Testing multipart Uploads to S3 with Threads](http://blog.vicecity.co.uk/post/4425574978/multipart-uploads-fog-threads-win)
+
+**March 9th, 2011**
+
+* [Offsite Backups with fog](http://www.engineyard.com/blog/2011/offsite-backups-with-fog/)
+
+**March 2nd, 2011**
+
+* [Better AWS Access Control with IAM and Fog](http://blog.zerosum.org/2011/03/02/better-aws-access-control-with-iam-and-fog.html)
+* [Using Amazon's CloudFormation, cloud-init, chef and fog to automate infrastructure](http://allanfeid.com/content/using-amazons-cloudformation-cloud-init-chef-and-fog-automate-infrastructure)
+
+**January 6th, 2011**
+
+* [Happy New Year (and 0.4.0) from fog!](http://www.engineyard.com/blog/2011/happy-new-year-and-0-4-0-from-fog/)
+
+**November 30th, 2010**
+
+* [Getting Hired: fog Edition](http://www.engineyard.com/blog/2010/getting-hired-fog-edition/)
+
+**October 13, 2010**
+
+* [Engine Yard Announces Formal Support for ‘fog’ to Ensure Application Portability in the Cloud](http://www.engineyard.com/company/press/2010-10-13-engine-yard-announces-formal-support-for-%E2%80%98fog%E2%80%99-to-ensure-application-portability-in-the-cloud)
+* [Wesley Beary and fog Promoted to the Engine Yard Open Source Program](http://www.engineyard.com/blog/2010/wesley-beary-and-fog-promoted-to-the-engine-yard-open-source-program/)
+
+**September 28, 2010**
+
+* [The Curious Tale of the Humble Micro](http://www.engineyard.com/blog/2010/the-curious-tale-of-the-humble-micro/)

data/docs/about/structure.markdown

@@ -0,0 +1,78 @@
+---
+layout: default
+title:  Structure
+---
+
+fog is the Ruby cloud computing library, top to bottom:
+
+* Collections provide a simplified interface, making clouds easier to work with and switch between.
+* Requests allow power users to get the most out of the features of each individual cloud.
+* Mocks make testing and integrating a breeze.
+                                               
+## Collections
+
+A high level interface to each cloud is provided through collections, such as `images` and `servers`.
+You can see a list of available collections by calling `collections` on the connection object. You can try it out using the `fog` command:
+
+    >> AWS.collections
+    [:addresses, :directories, ..., :volumes, :zones]
+
+Some collections are available across multiple providers:
+
+* compute providers have `flavors`, `images` and `servers`
+* dns providers have `zones` and `records`
+* storage providers have `directories` and `files`
+
+Collections share basic CRUD type operations, such as:
+* `all` - fetch every object of that type from the provider.
+* `create` - initialize a new record locally and a remote resource with the provider.
+* `get` - fetch a single object by it's identity from the provider.
+* `new` - initialize a new record locally, but do not create a remote resource with the provider.
+
+As an example, we'll try initializing and persisting a Rackspace Cloud server:
+
+    require 'fog'
+
+    compute = Fog::Compute.new({
+      :provider           => 'Rackspace',
+      :rackspace_api_key  => key,
+      :rackspace_username => username
+    })
+
+    # boot a gentoo server (flavor 1 = 256, image 3 = gentoo 2008.0)
+    server = compute.servers.create(:flavor_id => 1, :image_id => 3, :name => 'my_server')
+    server.wait_for { ready? } # give server time to boot
+
+    # DO STUFF
+
+    server.destroy # cleanup after yourself or regret it, trust me
+
+## Models
+
+Many of the collection methods return individual objects, which also provide common methods:
+* `destroy` - will destroy the persisted object from the provider
+* `save` - persist the object to the provider
+* `wait_for` - takes a block and waits for either the block to return true for the object or for a timeout (defaults to 10 minutes)
+
+## Requests
+
+Requests allow you to dive deeper when the models just can't cut it.
+You can see a list of available requests by calling #requests on the connection object.
+
+For instance, ec2 provides methods related to reserved instances that don't have any models (yet). Here is how you can lookup your reserved instances:
+
+    $ fog
+    >> AWS[:ec2].describe_reserved_instances
+    #<Excon::Response [...]>
+
+It will return an [excon](http://github.com/geemus/excon) response, which has `body`, `headers` and `status`. Both return nice hashes.
+
+## Mocks
+
+As you might imagine, testing code using Fog can be slow and expensive, constantly turning on and and shutting down instances.
+Mocking allows skipping this overhead by providing an in memory representation resources as you make requests.
+Enabling mocking easy to use, before you run other commands, simply run:
+
+    Fog.mock!
+
+Then proceed as usual, if you run into unimplemented mocks fog will raise an error and as always contributions are welcome!

data/docs/about/users.markdown

@@ -0,0 +1,33 @@
+---
+layout: default
+title:  Users
+---
+
+Here lies a listing of projects and products that are using fog.
+
+Please feel free to add your own, just please follow these rules for consistency and readability.
+
+1. Listings should be in alphabetical order and should have a link and list of services used.
+2. Projects that are open source should link to where the source code can be found.
+3. Products that are not open source should link to where more information about the product can be found.
+
+Thanks for following these rules to keep the quality high and and the content useful!
+
+## Projects
+
+* [carrierwave](http://github.com/jnicklas/carrierwave) = AWS => Storage
+* [chef](http://github.com/opscode/chef) = AWS => Compute, Slicehost => Compute, Terremark => vCloud, Rackspace => Compute
+* [deckard](http://github.com/joewilliams/deckard) = AWS => Compute
+* [gaff](http://github.com/joewilliams/gaff) = AWS => Compute, Slicehost => Compute
+* [gemcutter](http://github.com/rubygems/gemcutter) = AWS => Storage
+* [plover](http://github.com/railsmachine/plover) = AWS => Compute
+
+## Products
+
+* [DevStructure](http://devstructure.com/) = AWS => Compute, Rackspace => Compute, Slicehost => Compute
+* [Engine Yard AppCloud](http://www.engineyard.com/cloud) = AWS => \[Compute, Storage\]
+* [iSwifter](http://iswifter.youwebinc.com/) = BlueBox => Compute
+* [OpenFeint](http://openfeint.com) = BlueBox => Compute
+* [PHPFog](https://phpfog.com) = AWS => Compute
+* [RowFeeder](https://rowfeeder.com) = Blue Box Group => Compute
+* [Viximo](http://viximo.com) = AWS => Compute

data/docs/cdn/index.markdown

@@ -0,0 +1,82 @@
+---
+layout: default
+title:  CDN
+---
+
+Faster websites are better. <a href="http://www.websiteoptimization.com/speed/tweak/design-factors/">Better experience</a>, <a href="http://exp-platform.com/Documents/IEEEComputer2007OnlineExperiments.pdf">better sales</a>, <a href="http://www.stevesouders.com/blog/2009/07/27/wikia-fast-pages-retain-users/">you name it</a>. Unfortunately, making a website faster can be tough. Thankfully a content distribution network, or CDN, can give you great performance bang for your buck. A CDN helps speed things up by putting copies of your files closer to your users. It's like the difference between pizza delivery from across the street and pizza delivery from the next town over.
+
+The ease and deliciousness are the good news, but until recently CDN's were only available in the big leagues via 'my business guys will talk to your business guys' deals.  Fortunately for us, Amazon recently updated <a href="http://aws.amazon.com/cloudfront/">CloudFront</a>, their CDN service, to allow us to get these benefits with just a credit card and an API call. So now we'll see how you can spend a few minutes to save your users countless hours of load time.
+
+## Preliminaries
+
+First, make sure you have fog installed:
+
+    gem install fog
+
+Now you'll need to <a href="https://aws-portal.amazon.com/gp/aws/developer/subscription/index.html?productCode=AmazonCloudFront">sign up for Cloudfront</a>. Gather up the credentials your new credentials to initialize a connection to the service:
+
+    require 'fog'
+
+    # create a connection to the service
+    cdn = Fog::CDN.new({
+      :provider               => 'AWS',
+      :aws_access_key_id      => AWS_ACCESS_KEY_ID,
+      :aws_secret_access_key  => AWS_SECRET_ACCESS_KEY
+    }
+
+## Setting Up Your CDN
+
+Now you'll need to create a 'distribution' which represents a mapping from the CDN to your domain. For the examples we'll pretend we are working on 'http://www.example.com', but you can just switch it to your actual domain. Some <a href="http://docs.amazonwebservices.com/AmazonCloudFront/latest/APIReference/CreateDistribution.html">other options</a> are available, but the only other one we need to fill in is OriginProtocolPolicy.  This sets what to do about http vs https. We will use 'match-viewer' which returns the same protocol as the request, but you can also choose 'http-only' which always returns http responses.
+
+    data = cdn.post_distribution({
+      'CustomOrigin' => {
+        'DNSName'               => 'www.example.com',
+        'OriginProtocolPolicy'  => 'match-viewer'
+      }
+    })
+
+    # parse the response for stuff you'll need later
+    distribution_id   = data.body['Id']
+    caller_reference  = data.body['CallerReference']
+    etag              = data.headers['ETag']
+    cdn_domain_name   = data.body['DomainName']
+
+    # wait for the updates to propogate
+    Fog.wait_for {
+      cdn.get_distribution(distribution_id).body['Status'] ## 'Deployed'
+    }
+
+## Getting Served
+
+With the domain name from the distribution in hand you should now be ready to serve content from the edge.  All you need to do is start replacing urls like `http://www.example.com/stylesheets/foo.css` with `#{cdn_domain_name}/stylesheets/foo.css`. Just because you can do something doesn't always mean you should though.  Dynamic pages are not really well suited to CDN storage, since CDN content will be the same for every user.  Fortunately some of your most used content is a great fit.  By just switching over your images, javascripts and stylesheets you can have an impact for each and every one of your users.
+
+Congrats, your site is faster! By default the urls aren't very pretty, something like `http://d1xdx2sah5udd0.cloudfront.net/stylesheets/foo.css`.  Thankfully you can use CNAME config options to utilize something like `http://assets.example.com/stylesheets/foo.css`, if you are interested in learning more about this let me know in the comments.
+
+## Cleaning Up
+
+But, just in case you need to update things I'll run through how you can make changes. In my case I just want to clean up after myself, so I'll use the distribution_id and ETag from before to disable the distribution. We need to use the ETag as well because it provides a way to refer to different versions of the same distribution and ensures we are updating the version that we think we are.
+
+    data = cdn.put_distribution_config(
+      distribution_id,
+      etag,
+      {
+        'CustomOrigin'    => {
+          'DNSName'               => 'www.example.com',
+          'OriginProtocolPolicy'  => 'match-viewer'
+        },
+        'CallerReference' => caller_reference,
+        'Enabled'         => 'false'
+      }
+    )
+
+    # parse the updated etag
+    etag = data.headers['ETag']
+
+Now you just need to wait for the update to happen like before and once its disabled we can delete it:
+
+    Fog.wait_for {
+      cdn.get_distribution(distribution_id).body['Status'] ## 'Deployed'
+    }
+    cdn.delete_distribution(distribution_id, etag)
+
+Thats it, now go forth and speed up some load times!

data/docs/compute/index.markdown

@@ -0,0 +1,122 @@
+---
+layout: default
+title:  Compute
+---
+
+Compute is the lifeblood of the cloud, but with great power comes great complication. Compute opens up huge swaths of potential, but it varies greatly in both capabilities and usage from provider to provider. Thankfully fog helps to abstract these idiosyncrasies to provide a more seamless experience.
+
+## Installing fog
+
+fog is distributed as a RubyGem:
+
+    gem install fog
+
+Or for bundler users, you can add it in your Gemfile:
+
+    gem "fog"
+
+## Using Amazon EC2 and fog
+
+Sign up for an account <a href="http://aws-portal.amazon.com/gp/aws/developer/subscription/index.html?productCode=AmazonEC2">here</a> and copy down your secret access key and access key id from <a href="http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key">here</a>. We are about to get into the code samples, so be sure to fill in anything in ALL_CAPS with your own values!
+
+First, create a connection with your new account:
+
+    require 'rubygems'
+    require 'fog'
+
+    # create a connection
+    connection = Fog::Compute.new({
+      :provider                 => 'AWS',
+      :aws_secret_access_key    => YOUR_SECRET_ACCESS_KEY,
+      :aws_access_key_id        => YOUR_SECRET_ACCESS_KEY_ID
+    })
+
+With that in hand we are ready to start making EC2 calls!
+
+## Servers the EC2 way
+
+Creating a server on EC2 is very easy if you are willing to accept the defaults (the smallest server size, using Ubuntu 10.04 LTS). NOTE: the default EC2 image uses the 'ubuntu' username, rather than 'root' like other services.
+
+    server = connection.servers.create
+
+You can then list your servers to see that it now appears:
+
+    connection.servers
+
+Rather than worrying about the whole list, we can also just get the latest data for just our server:
+
+    server.reload
+
+That can get tedious quickly however, especially when servers can take several minutes to boot.  Fog has `wait_for` for cases like this and `ready?` for checking to see when a server has completed its start up.
+
+    server.wait_for { ready? }
+
+Once we are done with that we can shut it down.
+
+    server.destroy
+
+## Bootstrap: Servers the fog Way
+
+Cycling servers is great, but in order to actually ssh in we need to setup ssh keys and open ports.  But rather than worrying about the nitty gritty, we will utilize `bootstrap`.  NOTE: normally we could leave out username and use the default (root), but the default Ubuntu from Canonical uses the ubuntu username instead.
+
+    server = connection.servers.bootstrap(:private_key_path => '~/.ssh/id_rsa', :public_key_path => '~/.ssh/id_rsa.pub', :username => 'ubuntu')
+
+Bootstrap will create the server, but it will also make sure that port 22 is open for traffic and has ssh keys setup. The ssh key pair you specified will be registered under the name "fog\_default" unless you've set `Fog.credential` to a custom string value. In order to hook everything up `bootstrap` will need the server to be running, so by the time it finishes it will be ready. You can then make commands to it directly:
+
+    server.ssh('pwd')
+    server.ssh(['pwd', 'whoami'])
+
+These return an array of results, where each has stdout, stderr and status values so you can check out what your commands accomplished.  Now just shut it down to make sure you don't continue getting charged.
+
+    server.destroy
+
+
+### Managing multiple ssh key pairs on EC2
+
+The key pair you've specified, will be registered as "fog\_default" after running `bootstrap` for the first time. If you want to use multiple key pairs with the same AWS credentials, you need to set `Fog.credential` to register your other key pairs under different names. Your additional key pair will then be registered as "fog\_#{Fog.credential}":
+
+    Fog.credential = 'my_custom_key'
+    connection.servers.bootstrap(:private_key_path => '~/.ssh/my_custom_key', :public_key_path => '~/.ssh/my_custom_key.pub')
+
+If you've already registered a custom key pair e.g. using `connection.create_key_pair` or `connection.import_key_pair`, you can set your key paths using `Fog.credentials` and pass in the name of this key so `bootstrap` will use it instead of "fog\_default":
+
+    Fog.credentials = Fog.credentials.merge({ :private_key_path => "~/.ssh/my_custom_key", :public_key_path => "~/.ssh/my_custom_key.pub" })
+    connection.import_key_pair('my_custom_key', IO.read('~/.ssh/my_custom_key.pub')) if connection.key_pairs.get('my_custom_key').nil?
+    server = connection.servers.bootstrap(:key_name => 'my_custom_key')
+
+## Rackspace Cloud Servers
+
+Rackspace has <a href="http://www.rackspacecloud.com/cloud_hosting_products/servers">Cloud Servers</a> and you can sign up <a href="https://www.rackspacecloud.com/signup">here</a> and get your credentials <a href="https://manage.rackspacecloud.com/APIAccess.do">here</a>.
+
+    # create a connection
+    connection = Fog::Compute.new({
+      :provider           => 'Rackspace',
+      :rackspace_username => RACKSPACE_USERNAME,
+      :rackspace_api_key  => RACKSPACE_API_KEY
+    })
+
+If you work with the European cloud from Rackspace you have to add the following:
+
+    :rackspace_auth_url => "lon.auth.api.rackspacecloud.com"
+
+We will skip over learning how to do this the 'Rackspace Way' and instead jump right to using bootstrap to get their smallest Ubuntu 10.04 LTS server.
+
+    server = connection.servers.bootstrap
+
+You can run all the same ssh commands and do what you need to, then once again shutdown to ensure you are not charged once you are done.
+
+    server.destroy
+
+## Mocking out Compute
+
+You can also start any of these scripts with `Fog.mock!` or start the fog interactive tool from the command line with `FOG_MOCK=true fog` to run in mock mode. In this mode commands are run as local simulation, so no cloud resources are ever consumed and things operate much faster.
+
+## Cleaning up
+
+To cover your tracks its a good idea to check for running servers and shut them down, here is one way you might do that.
+
+    connection.servers.select {|server| server.ready? && server.destroy}
+
+## Summary
+
+Compute can be tricky, but the abstractions in fog make it much easier to get started.  With your servers up and running you can then focus on the task at hand and get some work done.  Congratulations on adding a new tool to your arsenal and let us know what we can do better.

data/docs/dns/index.markdown

@@ -0,0 +1,79 @@
+---
+layout: default
+title:  DNS
+---
+
+The power and flexibility of the cloud are amazing. But sometimes it can be a pain to chase your resources around and keep everything up to date. This is especially true of keeping track of addresses for DNS, but thankfully more and more API driven options are available, allowing you to automate your DNS to keep up with your hardware changes.
+
+## Setup
+
+First, make sure you have fog installed:
+
+    gem install fog
+
+For this first example we will use Zerigo (see below for how to use other providers). You can signup for Zerigo DNS <a href="https://www.zerigo.com/signup/dns">here</a>. Gather up your new credentials to initialize a connection to the service:
+
+    require 'rubygems'
+    require 'fog'
+
+    # create a connection to the service
+    dns = Fog::DNS.new({
+      :provider     => 'Zerigo',
+      :zerigo_email => ZERIGO_EMAIL,
+      :zerigo_token => ZERIGO_TOKEN
+    })
+
+## Getting in the Zone
+
+The first thing you need to do to prepare for your DNS excursion is create a zone for your domain.  The zone will contain all of the more specific records that you will create later.  You will just need to specify the domain, which should be your url without the 'http' or 'www' parts, and an email address.  Then you can create the zone with your DNS connection:<!--more-->
+
+    zone = @dns.zones.create(
+      :domain => 'example.com',
+      :email  => 'admin@example.com'
+    )
+
+Now that you have a zone you will need to update your registrar to let them know what DNS servers are responsible for your domain.  You can ask the zone what values to use:
+
+    zone.nameservers
+
+## Spinning Records
+
+With your new zone in hand you can add records as needed.  First and foremost you will probably want the 'www' version of your site to point to whatever your ip might be:
+
+    record = @zone.records.create(
+      :value   => '1.2.3.4',
+      :name => 'example.com',
+      :type => 'A'
+    )
+
+Adding other records is similarly easy, for instance if we want 'www.example.com' to go to the same place, we can use a cname record:
+
+    record = @zone.records.create(
+      :value   => 'example.com',
+      :name => 'www',
+      :type => 'CNAME'
+    )
+
+Or, similarly you might want to have your blog elsewhere:
+
+    record = @zone.records.create(
+      :value   => '4.3.2.1',
+      :name => 'blog.example.com',
+      :type => 'A'
+    )
+
+You can add more specifics if you need to, but reasonable defaults make it just that easy.  You can also add any other kind of DNS record you might need for mail or other purposes, you can find a nice overview of record options and types <a href="http://en.wikipedia.org/wiki/Domain_Name_System#DNS_resource_records">on Wikipedia</a>.
+
+## No Zerigo? No Problem
+
+If you already have an account with another service you can just as easily use this same code with different credentials. fog currently supports <a href="http://aws.amazon.com/route53/">AWS Route 53</a>, <a href="http://bluebox.net">Blue Box</a>, <a href="http://dnsimple.com">DNSimple</a>, <a href="http://www.linode.com">Linode</a>, <a href="http://www.rackspace.com">Rackspace</a>, <a href="http://www.slicehost.com">Slicehost</a> and <a href="http://www.zerigo.com/managed-dns">Zerigo</a>; so you can have your pick.  As an example you can connect to AWS instead of Zerigo:
+
+    dns = Fog::DNS.new({
+      :provider               => 'AWS',
+      :aws_access_key_id      => AWS_ACCESS_KEY_ID,
+      :aws_secret_access_key  => AWS_SECRET_ACCESS_KEY
+    })
+
+## Go Forth and Resolve
+
+You can see an example of reusing code like this in the <a href="https://github.com/fog/fog/blob/master/examples/dns_tests.rb">examples folder</a>. Using this makes it easier to give yourself shortcuts to your cloud servers and manage how clients and users access them as well. It is great to have this flexibility so that you can modify your cloud infrastructure as needed while keeping everything ship shape. It also provides a nice way to create custom subdomains for users and just generally round out your cloud solution.