diff --git a/docs/index.md b/docs/index.md index c7336ddda..553bde448 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,9 +13,168 @@ By coding with fog from the start you avoid vendor lock-in and give yourself mor With a rapidly expanding community and codebase the advantages of fog just keep coming. Join us and together we will realize the future of cloud computing. + +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. + ## Getting Started -fog.io is very much a work in progress. In the meantime there are some great details available in the README. + sudo gem install fog + +Now type 'fog' to try stuff, confident that fog will let you know what to do. Here is an example of wading through server creation for Amazon Elastic Compute Cloud: + + >> server = AWS.servers.create + ArgumentError: image_id is required for this operation + + >> server = AWS.servers.create(:image_id => 'ami-5ee70037') + + + >> server.destroy # cleanup after yourself or regret it, trust me + true + +## 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) + +## 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! + +## 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 + # + +It will return an [excon](http://github.com/geemus/excon) response, which has `body`, `headers` and `status`. Both return nice hashes. + +## Go forth and conquer + +Play around and use the console to explore or check out the [getting started guide](http://wiki.github.com/geemus/fog/getting-started-with-fog) for more details. Once you are reading to start scripting fog, here is a quick hint on how to make connections without the command line thing to help you. + + # create a compute connection + compute = Fog::Compute.new(:provider => 'AWS', :aws_access_key_id => ACCESS_KEY_ID, :aws_secret_access_key => SECRET_ACCESS_KEY) + # compute operations go here + + # create a storage connection + storage = Fog::Storage.new(:provider => 'AWS', :aws_access_key_id => ACCESS_KEY_ID, :aws_secret_access_key => SECRET_ACCESS_KEY) + # storage operations go here + +geemus says: "That should give you everything you need to get started, but let me know if there is anything I can do to help!" + +## Contributing + +* Find something you would like to work on. For suggestions look for the `easy`, `medium` and `hard` tags in the [issues](http://github.com/geemus/fog/issues) +* Fork the project and do your work in a topic branch. +* Add shindo tests to prove your code works and run all the tests using `bundle exec rake`. +* Rebase your branch against geemus/fog to make sure everything is up to date. +* Commit your changes and send a pull request. + +## T-Shirts + +Wonder how you can get a lovely fog shirt? Look no further! + +* Blue shirts go to people who have contributed indirectly, great examples are writing blog posts or giving lightning talks. +* Grey shirts and a follow from @fog go to people who have made it on to the [contributors list](https://github.com/geemus/fog/contributors) by submitting code. +* Black shirts go to people who have made it on to the [collaborators list](https://github.com/api/v2/json/repos/show/geemus/fog/collaborators) by coercing geemus into adding them (geemus is currently the only member of this list). + +## Resources + +Enjoy, and let me know what I can do to continue improving fog! + +* Stay up to date by following [@fog](http://twitter.com/fog) and/or [@geemus](http://twitter.com/geemus) on Twitter. +* Get and give help on the [#ruby-fog](irc://irc.freenode.net/ruby-fog) irc channel on Freenode +* Follow release notes and discussions on the [mailing list](http://groups.google.com/group/ruby-fog) +* Report bugs or find tasks to help with in the [issues](http://github.com/geemus/fog/issues) +* Learn about [contributing](http://github.com/geemus/fog/wiki/contributor-guide) +* See where fog is used and let the world know how you use it [in the wild](http://wiki.github.com/geemus/fog/in-the-wild) +* Check out blog posts and other mentions in the [press](http://wiki.github.com/geemus/fog/press) + +## Sponsorship + +http://www.engineyard.com/images/logo.png + +All new work on fog is sponsored by [Engine Yard](http://engineyard.com) + +## Copyright + +(The MIT License) + +Copyright (c) 2010 [geemus (Wesley Beary)](http://github.com/geemus) + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ## See Also: {% for post in site.posts %}